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 JavaScript 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_module	Disable loading external modules 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.
internals	Expose internal data structures (beware they may be volatile from version to version).

See The Rhai Book for details on the Rhai script engine and 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.
FnAccess	A type representing the access mode of a scripted function.
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.
IteratorFn	A standard function that gets an iterator from a type.
Map	Hash map of Dynamic values with String keys.