Crate rhai[−][src]

Rhai - embedded scripting for Rust

Rhai logo

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+Rust and a simple Rust interface.

A Quick Example

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))

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	Module containing all built-in 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 only.

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 expression. 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`.
FloatWrapper	A type that wraps a `FLOAT` and implements `Hash`.
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.
HashableHashMap	(INTERNALS) A type that wraps a `HashMap` and implements `Hash`. Exported under the `internals` feature only.
Ident	(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

ASTNode	(INTERNALS) An `AST` node, consisting of either an `Expr` or a `Stmt`. Exported under the `internals` feature only.
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.
FuncArgs	Trait that parses arguments to a function call.
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 `NonZeroU64` hash key from a namespace-qualified function name and parameter types. Exported under the `internals` feature only.
calc_script_fn_hash	(INTERNALS) Calculate a `NonZeroU64` 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.