Rhai Embedded Scripting for Rust

The rhai_codegen crate provides procedural macros used for code generation within the Rhai plugin system. It is designed to facilitate the creation of plugins for the Rhai scripting engine.

Note: This crate is automatically referenced by the main rhai crate. It is recommended that users do not use rhai_codegen directly unless they are specifically developing custom plugins that require these macros.

Rhai provides several command-line tools for working with Rhai scripts. Note that some tools require specific Cargo features to be enabled during compilation or installation.

Rhai is an embedded scripting language and evaluation engine for Rust. It provides a safe and easy way to add scripting capabilities to Rust applications, featuring a syntax similar to JavaScript and Rust with dynamic typing.

Key capabilities include:

• Tight integration with native Rust functions, types, getters/setters, methods, and indexers.
• Passing Rust values into scripts via an external Scope (supports all clonable Rust types).
• Support for common data types: booleans, integers, floating-point numbers (including Decimal), strings, Unicode characters, arrays (including byte arrays), and object maps.
• Ability to call script-defined functions from Rust.
• Optimization via AST compilation and script optimization.
• Custom API development through a plugin system using procedural macros.
• Serialization/deserialization support via serde (requires the serde feature).

To measure the execution speed of Rhai using the provided micro benchmarks, run the benchmark suite using cargo bench with the nightly toolchain.

cargo +nightly bench

Rhai can be heavily customized to serve as a specialized DSL by restricting or extending its language features:

• Disable Features: Disable specific language features like looping.
• Restrict Syntax: Surgically disable specific keywords and operators.
• Extend Syntax: Define custom operators or add custom syntax to the language.
• Custom Operators: Define your own operators within the engine.

Rhai supports all CPU and O/S targets supported by Rust, including:

• WebAssembly (WASM)
• no-std environments

Requirements:

• Minimum Rust version: 1.66.0

Note: stdweb is no longer supported for WASM builds due to changes in getrandom v0.3.

You can install the rhai-run utility directly from the repository using cargo install. This tool is used to execute Rhai scripts.

cargo install --path . --bin rhai-run

To install all Rhai tools with full functionality, use the bin-features feature flag. This flag enables decimal, metadata, serde, debugging, and rustyline support.

To install all tools at once:

cargo install --path . --bins --features bin-features

To install a specific tool (replace sample_app_to_run with the desired binary name):

cargo install --path . --bin sample_app_to_run --features bin-features

If you are working within the repository and want to run a tool using cargo run, ensure you include the bin-features flag to enable all tool-related capabilities.

cargo run --features bin-features --bin sample_app_to_run

To use Rhai, create an Engine instance, register any necessary external functions, and then evaluate your script using eval_file or eval.

Example script (my_script.rhai):

fn factorial(x) {
    if x == 1 { return 1; }
    x * factorial(x - 1)
}

compute(factorial(10))

Rust implementation:

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: bool = engine.eval_file("my_script.rhai".into())?;

    assert_eq!(result, true);

    Ok(())
}