Crate rhai

Rhai - embedded scripting for Rust

Rhai is a tiny, simple and very fast embedded scripting language for Rust that gives you a safe and easy way to add scripting to your applications. It provides a familiar syntax based on JS and Rust and a simple Rust interface. Here is a quick example.

First, the contents of my_script.rhai:

// Brute force factorial function
fn factorial(x) {
    if x == 1 { return 1; }
    x * factorial(x - 1)
}

// Calling an external function 'compute'
compute(factorial(10))

And the Rust part:

use rhai::{Engine, EvalAltResult, RegisterFn};

fn main() -> Result<(), Box<EvalAltResult>>
{
    // Define external function
    fn compute_something(x: i64) -> bool {
        (x % 40) == 0
    }

    // Create scripting engine
    let mut engine = Engine::new();

    // Register external function as 'compute'
    engine.register_fn("compute", compute_something);

    assert_eq!(
        // Evaluate the script, expects a 'bool' return
        engine.eval_file::<bool>("my_script.rhai".into())?,
        true
    );

    Ok(())
}

Optional features

Feature	Description
unchecked	Exclude arithmetic checking (such as overflows and division by zero). Beware that a bad script may panic the entire system!
no_function	Disable script-defined functions if not needed.
no_index	Disable arrays and indexing features if not needed.
no_object	Disable support for custom types and objects.
no_float	Disable floating-point numbers and math if not needed.
no_optimize	Disable the script optimizer.
only_i32	Set the system integer type to i32 and disable all other integer types. INT is set to i32.
only_i64	Set the system integer type to i64 and disable all other integer types. INT is set to i64.
no_std	Build for no-std. Notice that additional dependencies will be pulled in to replace std features.
sync	Restrict all values types to those that are Send + Sync. Under this feature, Engine, Scope and AST are all Send + Sync.

Check out the README on GitHub for details on the Rhai language!

Modules

module_resolvers	Module containing all built-in module resolvers available to Rhai.
packages	Module containing all built-in packages available to Rhai, plus facilities to define custom packages.

Macros

def_package

Macro that makes it easy to define a package (which is basically a shared module) and register functions into it.

Structs

AST	Compiled AST (abstract syntax tree) of a Rhai script.
Dynamic	Dynamic type containing any value.
Engine	Rhai main scripting engine.
ImmutableString	The system immutable string type.
Module	An imported module, which may contain variables, sub-modules, external Rust functions, and script-defined functions.
ParseError	Error when parsing a script.
Position	A location (line number + character position) in the input script.
Scope	Type containing information about the current scope. Useful for keeping state between Engine evaluation runs.

Enums

EvalAltResult	Evaluation result.
OptimizationLevel	Level of optimization performed.
ParseErrorType	Type of error encountered when parsing a script.

Traits

Func	Trait to create a Rust anonymous function from a script.
ModuleResolver	Trait that encapsulates a module resolution service.
RegisterFn	Trait to register custom functions with the Engine.
RegisterResultFn	Trait to register fallible custom functions returning Result<Dynamic, Box<EvalAltResult>> with the Engine.

Functions

calc_fn_hash

Calculate a u64 hash key from a module-qualified function name and parameter types.

Type Definitions

Array	Variable-sized array of Dynamic values.
FLOAT	The system floating-point type.
INT	The system integer type.
Map	Hash map of Dynamic values with String keys.