Expand description
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: bool = engine.eval_file("my_script.rhai".into())?;
assert_eq!(result, true);
Ok(())
}
Documentation
See The Rhai Book for details on the Rhai scripting engine and language.
Modules
(debugging) Module containing types for debugging.
Exported under the
debugging
feature only.Module containing all built-in module resolvers.
Module containing all built-in packages available to Rhai, plus facilities to define custom packages.
Module defining macros for developing plugins.
Macros
Macro to combine a plugin module into an existing module.
Macro that makes it easy to define a package (which is basically a shared module)
and register functions into it.
Macro to generate a Rhai
Module
from a plugin module defined via #[export_module]
.Macro to register a plugin function (defined via
#[export_fn]
) into an Engine
.Macro to cast an identifier or expression to another type with type checks.
Macro to register a plugin function into a Rhai
Module
.Macro to register a plugin function into a Rhai
Module
and expose it globally.Structs
Compiled AST (abstract syntax tree) of a Rhai script.
(internals) Bit-flags containing
AST
node configuration options.
Exported under the internals
feature only.(internals) A binary expression.
Exported under the
internals
feature only.(internals) A type containing system-wide caches.
Exported under the
internals
feature only.An expression with a condition.
(internals) A custom syntax expression.
Exported under the
internals
feature only.(metadata, internals) Definitions helper type to generate definition files based on the
contents of an
Engine
.
Exported under the internals
and metadata
feature only.Dynamic type containing any value.
(internals) Lock guard for reading a
Dynamic
.
Exported under the internals
feature only.(internals) Lock guard for writing a
Dynamic
.
Exported under the internals
feature only.(internals) Encapsulated AST environment.
Exported under the
internals
feature only.Rhai main scripting engine.
Context of a script evaluation process.
An expression sub-tree in an
AST
.A type that wraps a floating-point number and implements
Hash
.(internals) A function call.
Exported under the
internals
feature only.(internals) A set of function call hashes. Exported under the
internals
feature only.A general function pointer, which may carry additional (i.e. curried) argument values
to be passed onto a function during a call.
(internals) A function resolution cache with a bloom filter.
Exported under the
internals
feature only.(internals) An entry in a function resolution cache.
Exported under the
internals
feature only.(internals) Global runtime states.
Exported under the
internals
feature only.(internals) An identifier containing a name and a position.
Exported under the
internals
feature only.The system immutable string type.
A module which may contain variables, sub-modules, external Rust functions,
and/or script-defined functions.
(internals) A type that implements the
InputStream
trait.
Exported under the internals
feature only.(internals) A chain of module names to namespace-qualify a variable or function call.
Exported under the
internals
feature only.Context of a native Rust function call.
(internals) An op-assignment operator.
Exported under the
internals
feature only.Error when parsing a script.
(internals) A type that encapsulates the current state of the parser.
Exported under the
internals
feature only.A location (line number + character position) in the input script.
Type containing information about the current scope. Useful for keeping state between
Engine
evaluation runs.(internals) A type containing information on a script-defined function.
Exported under the
internals
feature only.A type containing the metadata of a script-defined function.
(internals) A span consisting of a starting and an ending positions.
Exported under the
internals
feature only.(internals) A scoped block of statements.
Exported under the
internals
feature only.(internals) A factory of identifiers from text strings.
Exported under the
internals
feature only.(internals) A type containing all cases for a
switch
statement.
Exported under the internals
feature only.(internals) An iterator on a
Token
stream.
Exported under the internals
feature only.(internals) State of the tokenizer.
Exported under the
internals
feature only.(internals) A type containing commands to control the tokenizer.
(internals) A
try-catch
block.
Exported under the internals
feature only.TypeBuilderDeprecated
Builder to build the API of a custom type for use with an
Engine
.Information on a variable definition.
Enums
(internals) Modes of access.
Exported under the
internals
feature only.Evaluation result.
(internals) An expression sub-tree.
Exported under the
internals
feature only.A type representing the access mode of a function.
A type representing the namespace of a function.
Error encountered when tokenizing the script text.
Level of optimization performed.
Error encountered when parsing a script.
(internals) A type containing a range case for a
switch
statement.
Exported under the internals
feature only.(internals) A statement.
Exported under the
internals
feature only.(internals) A Rhai language token.
Exported under the
internals
feature only.Constants
Standard containment testing function.
Standard equality comparison operator.
Traits
CustomTypeDeprecated
Trait to build the API of a custom type for use with an
Engine
(i.e. register the type and its getters, setters, methods, etc.).Trait to create a Rust closure from a script.
Trait that parses arguments to a function call.
(internals) Trait that encapsulates a peekable character input stream.
Exported under the
internals
feature only.Trait that encapsulates a module resolution service.
Trait to register custom Rust functions.
(internals) Trait to represent any type.
Exported under the
internals
feature only.Functions
Evaluate a string as a script, returning the result value or an error.
Evaluate a script file, returning the result value or an error.
Return the JSON representation of an object map.
(internals) Get the next token from the input stream.
Exported under the
internals
feature only.(internals) Is a text string a valid script-defined function name?
Exported under the
internals
feature only.(internals) Is a text string a valid identifier?
Exported under the
internals
feature only.(internals) Parse a string literal ended by a specified termination character.
Exported under the
internals
feature only.Evaluate a string as a script.
Evaluate a file.
Type Definitions
An identifier in Rhai.
SmartString
is used because most
identifiers are ASCII and short, fewer than 23 characters, so they can be stored inline.(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.(internals) A shared object that allows control of the tokenizer from outside.
Attribute Macros
Attribute, when put on a Rust function, turns it into a plugin function.
Attribute, when put on a Rust module, turns it into a plugin module.