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 quad_compat_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);
assert_eq!(
// Evaluate the script, expects a 'bool' return
engine.eval_file::<bool>("my_script.rhai".into())?,
true
);
Ok(())
}
§Documentation
See The Rhai Book for details on the Rhai scripting engine and language.
Modules§
- module_
resolvers - Module containing all built-in module resolvers available to Rhai. 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 theserde
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 anEngine
. - 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.
- Binary
Expr - (internals) A binary expression.
Exported under the
internals
feature only. - Custom
Expr - (internals) A custom syntax expression.
Exported under the
internals
feature only. - Dynamic
- Dynamic type containing any value.
- Dynamic
Read Lock - (internals) Lock guard for reading a
Dynamic
. Exported under theinternals
feature only. - Dynamic
Write Lock - (internals) Lock guard for writing a
Dynamic
. Exported under theinternals
feature only. - Engine
- Rhai main scripting engine.
- Eval
Context - Context of a script evaluation process.
- Eval
State - (internals) A type that holds all the current states of the
Engine
. Exported under theinternals
feature only. - Expression
- An expression sub-tree in an
AST
. - Float
Wrapper - A type that wraps a floating-point number and implements
Hash
. - FnCall
Expr - (internals) A function call.
Exported under the
internals
feature only. - FnCall
Hashes - (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.
- FnResolution
Cache Entry - (internals) An entry in a function resolution cache.
Exported under the
internals
feature only. - Ident
- (internals) An identifier containing a name and a position.
Exported under the
internals
feature only. - Identifier
Builder - (internals) A factory of identifiers from text strings.
Exported under the
internals
feature only. - Immutable
String - The system immutable string type.
- Imports
- (internals) A stack of imported modules plus mutable runtime global states.
Exported under the
internals
feature only. - Locked
- Alias to
RefCell
orRwLock
depending on thesync
feature flag. Synchronized shared object. 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.
- Multi
Inputs Stream - (internals) A type that implements the
InputStream
trait. Exported under theinternals
feature only. - Namespace
Ref - (internals) A chain of module names to namespace-qualify a variable or function call.
Exported under the
internals
feature only. - Native
Call Context - Context of a native Rust function call.
- OpAssignment
- (internals) An op-assignment operator.
Exported under the
internals
feature only. - Option
Flags - A type that holds a configuration option with bit-flags.
Exported under the
internals
feature only. - Parse
Error - Error when parsing a script.
- Parse
State - (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. - Script
FnDef - (internals) A type containing information on a scripted function.
Exported under the
internals
feature only. - Script
FnMetadata - A type containing the metadata of a script-defined function.
- Shared
- Alias to
Rc
orArc
depending on thesync
feature flag. Immutable reference-counted container. A single-threaded reference-counting pointer. ‘Rc’ stands for ‘Reference Counted’. - Stmt
Block - (internals) A scoped block of statements.
Exported under the
internals
feature only. - Token
Iterator - (internals) An iterator on a
Token
stream. Exported under theinternals
feature only. - Tokenize
State - (internals) State of the tokenizer.
Exported under the
internals
feature only. - Tokenizer
Control Block - (internals) A type containing commands to control the tokenizer.
Enums§
- ASTNode
- (internals) An
AST
node, consisting of either anExpr
or aStmt
. Exported under theinternals
feature only. - Access
Mode - (internals) Modes of access.
Exported under the
internals
feature only. - Eval
AltResult - 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
- (internals) Error encountered when tokenizing the script text.
Exported under the
internals
feature only. - Optimization
Level - Level of optimization performed.
- Parse
Error Type - Type of 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§
- AST_
OPTION_ BREAK_ OUT - (internals) The
AST
node breaks out of normal control flow. Exported under theinternals
feature only. - AST_
OPTION_ CONSTANT - (internals) The
AST
node is constant. Exported under theinternals
feature only. - AST_
OPTION_ NEGATED - (internals) The
AST
node is in negated mode. Exported under theinternals
feature only. - AST_
OPTION_ NONE - (internals) No options for the
AST
node. Exported under theinternals
feature only. - AST_
OPTION_ PUBLIC - (internals) The
AST
node is public. Exported under theinternals
feature only. - OP_
CONTAINS - Standard method function for containment testing.
The
in
operator is implemented as a call to this method. - OP_
EQUALS - Standard equality comparison operator.
- OP_
EXCLUSIVE_ RANGE - Standard exclusive range operator.
- OP_
INCLUSIVE_ RANGE - Standard inclusive range operator.
Traits§
- Func
- Trait to create a Rust closure from a script.
- Func
Args - Trait that parses arguments to a function call.
- Input
Stream - (internals) Trait that encapsulates a peekable character input stream.
Exported under the
internals
feature only. - Module
Resolver - Trait that encapsulates a module resolution service.
- Register
Native Function - Trait to register custom Rust functions.
- Variant
- (internals) Trait to represent any type.
Exported under the
internals
feature only.
Functions§
- get_
next_ token - (internals) Get the next token from the
stream
. Exported under theinternals
feature only. - parse_
string_ literal - (internals) Parse a string literal ended by
termination_char
. Exported under theinternals
feature only.
Type Aliases§
- Array
- Variable-sized array of
Dynamic
values. Not available underno_index
. - Blob
- Variable-sized array of
u8
values (byte array). Not available underno_index
. - Exclusive
Range - FLOAT
- The system floating-point type. It is defined as
f64
. Not available underno_float
. - FnResolution
Cache - (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. - Inclusive
Range - Map
- Hash map of
Dynamic
values withSmartString
keys. Not available underno_object
. - Static
Vec - (internals) Alias to
smallvec::SmallVec<[T; 3]>
, which is aVec
backed by a small, inline, fixed-size array when there are ≤ 3 items stored. Exported under theinternals
feature only. - Tokenizer
Control - (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.