93 lines
2.9 KiB
Markdown
93 lines
2.9 KiB
Markdown
`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_.
|
|
```
|