reorganize module

_archive/rhai_engine/rhaibook/language/print-debug.md

@@ -0,0 +1,92 @@
+`print` and `debug`
+===================
+
+{{#include ../links.md}}
+
+[`Engine::on_print`]: https://docs.rs/rhai/{{version}}/rhai/struct.Engine.html#method.on_print
+[`Engine::on_debug`]: https://docs.rs/rhai/{{version}}/rhai/struct.Engine.html#method.on_debug
+
+
+The `print` and `debug` functions default to printing to `stdout`, with `debug` using standard debug formatting.
+
+```js
+print("hello");         // prints "hello" to stdout
+
+print(1 + 2 + 3);       // prints "6" to stdout
+
+let x = 42;
+
+print(`hello${x}`);     // prints "hello42" to stdout
+
+debug("world!");        // prints "world!" to stdout using debug formatting
+```
+
+
+Override `print` and `debug` with Callback Functions
+----------------------------------------------------
+
+When embedding Rhai into an application, it is usually necessary to trap `print` and `debug` output
+(for logging into a tracking log, for example) with the [`Engine::on_print`] and [`Engine::on_debug`] methods.
+
+```rust
+// Any function or closure that takes an '&str' argument can be used to override 'print'.
+engine.on_print(|x| println!("hello: {x}"));
+
+// Any function or closure that takes a '&str', an 'Option<&str>' and a 'Position' argument
+// can be used to override 'debug'.
+engine.on_debug(|x, src, pos| {
+    let src = src.unwrap_or("unknown");
+    println!("DEBUG of {src} at {pos:?}: {s}")
+});
+
+// Example: quick-'n-dirty logging
+let logbook = Arc::new(RwLock::new(Vec::<String>::new()));
+
+// Redirect print/debug output to 'log'
+let log = logbook.clone();
+engine.on_print(move |s| {
+    let entry = format!("entry: {}", s);
+    log.write().unwrap().push(entry);
+});
+
+let log = logbook.clone();
+engine.on_debug(move |s, src, pos| {
+    let src = src.unwrap_or("unknown");
+    let entry = format!("DEBUG of {src} at {pos:?}: {s}");
+    log.write().unwrap().push(entry);
+});
+
+// Evaluate script
+engine.run(script)?;
+
+// 'logbook' captures all the 'print' and 'debug' output
+for entry in logbook.read().unwrap().iter() {
+    println!("{entry}");
+}
+```
+
+
+`on_debug` Callback Signature
+-----------------------------
+
+The function signature passed to [`Engine::on_debug]` takes the following form.
+
+> ```rust
+> Fn(text: &str, source: Option<&str>, pos: Position)
+> ```
+
+where:
+
+| Parameter |      Type      | Description                                                     |
+| --------- | :------------: | --------------------------------------------------------------- |
+| `text`    |     `&str`     | text to display                                                 |
+| `source`  | `Option<&str>` | source of the current evaluation, if any                        |
+| `pos`     |   `Position`   | position (line number and character offset) of the `debug` call |
+
+The _source_ of a script evaluation is any text string provided to an [`AST`] via `AST::set_source`.
+
+```admonish tip.small
+
+If a [module] is loaded via an [`import`] statement, then the _source_ of functions defined within
+the module will be the module's _path_.
+```