69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
Register a Rust Function
|
|
========================
|
|
|
|
{{#include ../links.md}}
|
|
|
|
Rhai's scripting engine is very lightweight. It gets most of its abilities from functions.
|
|
|
|
To call these functions, they need to be _registered_ with the [`Engine`] using `Engine::register_fn`
|
|
(in the `RegisterFn` trait) and `Engine::register_result_fn` (in the `RegisterResultFn` trait,
|
|
see [fallible functions]({{rootUrl}}/rust/fallible.md)).
|
|
|
|
```rust
|
|
use rhai::{Dynamic, Engine, EvalAltResult, ImmutableString};
|
|
use rhai::RegisterFn; // use 'RegisterFn' trait for 'register_fn'
|
|
use rhai::RegisterResultFn; // use 'RegisterResultFn' trait for 'register_result_fn'
|
|
|
|
// Normal function that returns a standard type
|
|
// Remember to use 'ImmutableString' and not 'String'
|
|
fn add_len(x: i64, s: ImmutableString) -> i64 {
|
|
x + s.len()
|
|
}
|
|
// Alternatively, '&str' maps directly to 'ImmutableString'
|
|
fn add_len_str(x: i64, s: &str) -> i64 {
|
|
x + s.len()
|
|
}
|
|
|
|
// Function that returns a 'Dynamic' value - must return a 'Result'
|
|
fn get_any_value() -> Result<Dynamic, Box<EvalAltResult>> {
|
|
Ok((42_i64).into()) // standard types can use 'into()'
|
|
}
|
|
|
|
let mut engine = Engine::new();
|
|
|
|
engine.register_fn("add", add_len);
|
|
engine.register_fn("add_str", add_len_str);
|
|
|
|
let result = engine.eval::<i64>(r#"add(40, "xx")"#)?;
|
|
|
|
println!("Answer: {}", result); // prints 42
|
|
|
|
let result = engine.eval::<i64>(r#"add_str(40, "xx")"#)?;
|
|
|
|
println!("Answer: {}", result); // prints 42
|
|
|
|
// Functions that return Dynamic values must use register_result_fn()
|
|
engine.register_result_fn("get_any_value", get_any_value);
|
|
|
|
let result = engine.eval::<i64>("get_any_value()")?;
|
|
|
|
println!("Answer: {}", result); // prints 42
|
|
```
|
|
|
|
To create a [`Dynamic`] value, use the `Dynamic::from` method.
|
|
[Standard types] in Rhai can also use `into()`.
|
|
|
|
```rust
|
|
use rhai::Dynamic;
|
|
|
|
let x = (42_i64).into(); // 'into()' works for standard types
|
|
|
|
let y = Dynamic::from("hello!".to_string()); // remember &str is not supported by Rhai
|
|
```
|
|
|
|
Functions registered with the [`Engine`] can be _overloaded_ as long as the _signature_ is unique,
|
|
i.e. different functions can have the same name as long as their parameters are of different types
|
|
and/or different number.
|
|
|
|
New definitions _overwrite_ previous definitions of the same name and same number/types of parameters.
|