Crate rhai

Rhai - embedded scripting for Rust

Rhai is a tiny, simple and 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(())
}

Documentation

See The Rhai Book for details on the Rhai scripting engine and language.

Modules

module_resolvers

Re-export module resolvers.

packages

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

plugin

Module defining macros for developing plugins.

serde

(SERDE) Serialization and deserialization support for serde. Exported under the serde feature.

Macros

combine_with_exported_module

Macro to combine a plugin module into an existing module.

def_package

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

exported_module

Macro to generate a Rhai Module from a plugin module defined via #[export_module].

register_exported_fn

Macro to register a plugin function (defined via #[export_fn]) into an Engine.

set_exported_fn

Macro to register a plugin function into a Rhai Module.

set_exported_global_fn

Macro to register a plugin function into a Rhai Module and expose it globally.

Structs

AST

Compiled AST (abstract syntax tree) of a Rhai script.

BinaryExpr

(INTERNALS) A binary expression. Exported under the internals feature only.

CustomExpr

(INTERNALS) A custom syntax definition. Exported under the internals feature only.

Dynamic

Dynamic type containing any value.

Engine

Rhai main scripting engine.

EvalContext

Context of a script evaluation process.

EvalState

(INTERNALS) A type that holds all the current states of the Engine. Exported under the internals feature only.

Expression

An expression sub-tree in an AST.

FnCallExpr

(INTERNALS) A function call. Exported under the internals feature only.

FnPtr

A general function pointer, which may carry additional (i.e. curried) argument values to be passed onto a function during a call.

Ident

(INTERNALS) An identifier containing a string name and a position. Exported under the internals feature only.

IdentX

(INTERNALS) An identifier containing an immutable string name and a position. Exported under the internals feature only.

ImmutableString

The system immutable string type.

Imports

(INTERNALS) A stack of imported modules. Exported under the internals feature only.

Limits

(INTERNALS) A type containing all the limits imposed by the Engine. Exported under the internals feature only.

Module

A module which may contain variables, sub-modules, external Rust functions, and/or script-defined functions.

NamespaceRef

(INTERNALS) A chain of module names to namespace-qualify a variable or function call. Exported under the internals feature only.

NativeCallContext

Context of a native Rust function call.

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.

ScriptFnDef

(INTERNALS) A type containing information on a scripted function. Exported under the internals feature only.

ScriptFnMetadata

A type containing the metadata of a script-defined function.

TokenizeState

(INTERNALS) State of the tokenizer. Exported under the internals feature only.

Enums

EvalAltResult

Evaluation result.

Expr

(INTERNALS) An expression sub-tree. Exported under the internals feature only.

FnAccess

A type representing the access mode of a function.

FnNamespace

A type representing the namespace of a function.

LexError

(INTERNALS) Error encountered when tokenizing the script text. Exported under the internals feature only.

OptimizationLevel

Level of optimization performed.

ParseErrorType

Type of error encountered when parsing a script.

ReturnType

(INTERNALS) A type encapsulating the mode of a return/throw statement. Exported under the internals feature only.

Stmt

(INTERNALS) A statement. Exported under the internals feature only.

Token

(INTERNALS) A Rhai language token. Exported under the internals feature only.

Traits

Func

Trait to create a Rust closure from a script.

InputStream

(INTERNALS) Trait that encapsulates a peekable character input stream. Exported under the internals feature only.

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_native_fn_hash

(INTERNALS) Calculate a u64 hash key from a namespace-qualified function name and parameter types. Exported under the internals feature only.

calc_script_fn_hash

(INTERNALS) Calculate a u64 hash key from a namespace-qualified function name and the number of parameters, but no parameter types. Exported under the internals feature only.

get_next_token

(INTERNALS) Get the next token from the stream. Exported under the internals feature only.

parse_string_literal

(INTERNALS) Parse a string literal wrapped by enclosing_char. Exported under the internals feature only.

Type Definitions

Array

Variable-sized array of Dynamic values.

FLOAT

The system floating-point type. It is defined as f64.

INT

The system integer type. It is defined as i64.

Map

Hash map of Dynamic values with ImmutableString keys.

Shared

Immutable reference-counted container.

StaticVec

(INTERNALS) Alias to smallvec::SmallVec<[T; 4]>, which is a specialized Vec backed by a small, fixed-size array when there are <= 4 items stored. Exported under the internals feature only.

Attribute Macros

export_fn

Attribute, when put on a Rust function, turns it into a plugin function.

export_module

Attribute, when put on a Rust module, turns it into a plugin module.