Rhai - Embedded Scripting for Rust

Rhai is an embedded scripting language and evaluation engine for Rust that gives a safe and easy way to add scripting to any application.

Targets and builds

• All CPU and O/S targets supported by Rust, including:

  • WebAssembly (WASM)
  • no-std

• Minimum Rust version 1.66.0

Standard features

• Simple language similar to JavaScript+Rust with dynamic typing.

• Fairly efficient evaluation (1 million iterations in 0.14 sec on a single-core 2.6 GHz Linux VM).

• Tight integration with native Rust functions and types, including getters/setters, methods and indexers.

• Freely pass Rust values into a script as variables/constants via an external Scope - all clonable Rust types are supported; no need to implement any special trait. Or tap directly into the variable resolution process.

• Built-in support for most common data types including booleans, integers, floating-point numbers (including Decimal), strings, Unicode characters, arrays (including packed byte arrays) and object maps.

• Easily call a script-defined function from Rust.

• Relatively little unsafe code (yes there are some for performance reasons).

• Few dependencies - currently only smallvec, thin-vec, num-traits, once_cell, ahash, bitflags and smartstring.

• Re-entrant scripting engine can be made Send + Sync (via the sync feature).

• Compile once to AST form for repeated evaluations.

• Scripts are optimized (useful for template-based machine-generated scripts).

• Easy custom API development via plugins system powered by procedural macros.

• Function overloading and operator overloading.

• Dynamic dispatch via function pointers with additional support for currying.

• Closures (anonymous functions) that can capture shared values.

• Some syntactic support for object-oriented programming (OOP).

• Organize code base with dynamically-loadable modules, optionally overriding the resolution process.

• Serialization/deserialization support via serde (requires the serde feature).

• Support for minimal builds by excluding unneeded language features.

• A debugging interface.

Protected against attacks

• Don't Panic guarantee - Any panic is a bug. Rhai subscribes to the motto that a library should never panic the host system, and is coded with this in mind.

• Sand-boxed - the scripting engine, if declared immutable, cannot mutate the containing environment unless explicitly permitted.

• Rugged - protected against malicious attacks (such as stack-overflow, over-sized data, and runaway scripts etc.) that may come from untrusted third-party user-land scripts.

• Track script evaluation progress and manually terminate a script run.

• Passes Miri.

For those who actually want their own language

• Use as a DSL.

• Disable certain language features such as looping.

• Further restrict the language by surgically disabling keywords and operators.

• Define custom operators.

• Extend the language with custom syntax.

Example

The scripts subdirectory contains sample Rhai scripts.

Below is the standard Fibonacci example for scripting languages:

// This Rhai script calculates the n-th Fibonacci number using a
// really dumb algorithm to test the speed of the scripting engine.

const TARGET = 28;
const REPEAT = 5;
const ANSWER = 317_811;

fn fib(n) {
    if n < 2 {
        n
    } else {
        fib(n-1) + fib(n-2)
    }
}

print(`Running Fibonacci(${TARGET}) x ${REPEAT} times...`);
print("Ready... Go!");

let result;
let now = timestamp();

for n in 0..REPEAT {
    result = fib(TARGET);
}

print(`Finished. Run time = ${now.elapsed} seconds.`);

print(`Fibonacci number #${TARGET} = ${result}`);

if result != ANSWER {
    print(`The answer is WRONG! Should be ${ANSWER}!`);
}

Project Site

rhai.rs

Documentation

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

Playground

An Online Playground is available with syntax-highlighting editor, powered by WebAssembly.

Scripts can be evaluated directly from the editor.

License

Licensed under either of the following, at your choice:

• Apache License, Version 2.0, or
• MIT license

Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion in this crate, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.