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+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};

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

    // Evaluate the script, expecting a 'bool' result
    let result = engine.eval_file::<bool>("my_script.rhai".into())?;

    assert_eq!(result, true);

    Ok(())
}

Documentation

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

Modules

debugger

(debugging) Module containing types for debugging. Exported under the debugging feature only.

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.

reify

Macro to cast an identifier or expression to another type with type checks.

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.

ASTFlags

(internals) A type that holds a configuration option with bit-flags. Exported under the internals feature only.

BinaryExpr

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

Caches

(internals) A type containing system-wide caches. Exported under the internals feature only.

ConditionalStmtBlock

A statements block with a condition.

CustomExpr

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

Dynamic

Dynamic type containing any value.

DynamicReadLock

(internals) Lock guard for reading a Dynamic. Exported under the internals feature only.

DynamicWriteLock

(internals) Lock guard for writing a Dynamic. Exported under the internals feature only.

EncapsulatedEnviron

(internals) Encapsulated AST environment. Exported under the internals feature only.

Engine

Rhai main scripting engine.

EvalContext

Context of a script evaluation process.

Expression

An expression sub-tree in an AST.

FloatWrapper

A type that wraps a floating-point number and implements Hash.

FnCallExpr

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

FnCallHashes

(internals) A set of function call hashes. 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.

FnResolutionCacheEntry

(internals) An entry in a function resolution cache. Exported under the internals feature only.

GlobalRuntimeState

(internals) Global runtime states. Exported under the internals feature only.

Ident

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

ImmutableString

The system immutable string type.

Instant

A measurement of a monotonically nondecreasing clock. Opaque and useful only with Duration.

Locked

Alias to RefCell or RwLock depending on the sync feature flag. A mutable memory location with dynamically checked borrow rules

Module

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

MultiInputsStream

(internals) A type that implements the InputStream trait. Exported under the internals feature only.

Namespace

(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.

OpAssignment

(internals) An op-assignment operator. Exported under the internals feature only.

ParseError

Error when parsing a script.

ParseState

(internals) A type that encapsulates the current state of the parser. Exported under the internals feature only.

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 script-defined function. Exported under the internals feature only.

ScriptFnMetadata

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

Shared

Alias to Rc or Arc depending on the sync feature flag. A single-threaded reference-counting pointer. ‘Rc’ stands for ‘Reference Counted’.

Span

(internals) A span consisting of a starting and an ending positions. Exported under the internals feature only.

StmtBlock

(internals) A scoped block of statements. Exported under the internals feature only.

StringsInterner

(internals) A factory of identifiers from text strings. Exported under the internals feature only.

SwitchCases

(internals) A type containing all cases for a switch statement. Exported under the internals feature only.

TokenIterator

(internals) An iterator on a Token stream. Exported under the internals feature only.

TokenizeState

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

TokenizerControlBlock

(internals) A type containing commands to control the tokenizer.

TryCatchBlock

(internals) A try-catch block. Exported under the internals feature only.

VarDefInfo

Information on a variable definition.

Enums

ASTNode

(internals) An AST node, consisting of either an Expr or a Stmt. Exported under the internals feature only.

AccessMode

(internals) Modes of access. 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

Error encountered when tokenizing the script text.

OptimizationLevel

Level of optimization performed.

ParseErrorType

Error encountered when parsing a script.

Stmt

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

Token

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

Constants

OP_CONTAINS

Standard containment testing function.

OP_EQUALS

Standard equality comparison operator.

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.

RegisterNativeFunction

Trait to register custom Rust functions.

Variant

(internals) Trait to represent any type. Exported under the internals feature only.

Functions

format_map_as_json

Return the JSON representation of an object map.

get_next_token

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

parse_string_literal

(internals) Parse a string literal ended by a specified termination character. Exported under the internals feature only.

Type Definitions

Array

Variable-sized array of Dynamic values.

Blob

Variable-sized array of u8 values (byte array).

FLOAT

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

FnResolutionCache

(internals) A function resolution cache. Exported under the internals feature only.

INT

The system integer type. It is defined as i64.

Identifier

An identifier in Rhai. SmartString is used because most identifiers are ASCII and short, fewer than 23 characters, so they can be stored inline.

Map

A dictionary of Dynamic values with string keys.

StaticVec

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

TokenizerControl

(internals) A shared object that allows control of the tokenizer from outside.

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.