Repository files navigation

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

• All CPU and O/S targets supported by Rust, including:
  • WebAssembly (WASM)
  • no-std
• Minimum Rust version 1.66.0

• Simple language similar to JavaScript+Rust withdynamic typing.
• Fairly efficient evaluation - 1 million iterations in 0.14 sec on a single-core 2.6 GHz Linux VM runningthis script.
• Tight integration with native Rustfunctions andtypes, includinggetters/setters,methods andindexers.
• Freely pass Rust values into a script asvariables/constants via an externalScope - all clonable Rust types are supported; no need to implement any special trait. Or tap directly into thevariable resolution process.
• Built-in support for most commondata types including booleans,integers,floating-point numbers (includingDecimal),strings,Unicode characters,arrays (including packedbyte arrays) andobject maps.
• Easilycall a script-defined function from Rust.
• Relatively littleunsafe code (yes there are some for performance reasons).
• Few dependencies - currently onlysmallvec,thin-vec,num-traits,once_cell,ahash,bitflags andsmartstring.
• Re-entrant scripting engine can be madeSend + Sync (via thesync feature).
• Compile once toAST form for repeated evaluations.
• Scripts areoptimized (useful for template-based machine-generated scripts).
• Easy custom API development viaplugins system powered by procedural macros.
• Function overloading andoperator overloading.
• Dynamic dispatch viafunction pointers with additional support forcurrying.
• Closures (anonymous functions) that can capture shared values.
• Some syntactic support forobject-oriented programming (OOP).
• Organize code base with dynamically-loadablemodules, optionallyoverriding the resolution process.
• Serialization/deserialization support viaserde (requires theserde feature).
• Support forminimal builds by excluding unneeded languagefeatures.
• Adebugging interface.

• 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 unlessexplicitly permitted.
• Rugged - protected against malicious attacks (such asstack-overflow,over-sized data, andrunaway scripts etc.) that may come from untrusted third-party user-land scripts.
• Track script evaluationprogress and manually terminate a script run.
• Passes Miri.

• Use as aDSL.
• Disable certainlanguage features such aslooping.
• Further restrict the language by surgicallydisabling keywords and operators.
• Definecustom operators.
• Extend the language withcustom syntax.

Thescripts subdirectory contains sample Rhai scripts.

Below is the standardFibonacci 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.constTARGET=28;constREPEAT=5;constANSWER=317_811;fnfib(n){ifn<2{n}else{fib(n-1)+fib(n-2)}}print(`Running Fibonacci(${TARGET}) x${REPEAT} times...`);print("Ready... Go!");letresult;letnow=timestamp();fornin0..REPEAT{result=fib(TARGET);}print(`Finished. Run time =${now.elapsed} seconds.`);print(`Fibonacci number #${TARGET} =${result}`);ifresult!=ANSWER{print(`The answer is WRONG! Should be${ANSWER}!`);}

rhai.rs

SeeThe Rhai Book for details on the Rhai scripting engine and language.

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

Scripts can be evaluated directly from the editor.

Licensed under either of the following, at your choice:

• Apache License, Version 2.0, or
• MIT license

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