Manage AST
’s
When compiling a Rhai script to an AST
, the following data are packaged together as a single unit:
Data | Type | Description | Requires feature | Access API |
---|---|---|---|---|
Source name | ImmutableString | optional text name to identify the source of the script | source(&self) ,clone_source(&self) ,set_source(&mut self, source) ,clear_source(&mut self) | |
Statements | Vec<Stmt> | list of script statements at global level | internals | statements(&self) ,statements_mut(&mut self) |
Functions | Shared<Module> | functions defined in the script | internals ,not no_function | shared_lib(&self) |
Embedded module resolver | StaticModuleResolver | embedded module resolver for self-contained AST | internals ,not no_module | resolver(&self) |
Most of the AST
API is available only under the internals
feature.
Use the source name to identify the source script in errors – useful when multiple [modules]
are imported recursively.
For the complete [`AST`] API, refer to the [documentation](https://docs.rs/rhai/{{version}}/rhai/struct.AST.html) online.
Extract Only Functions
The following methods, not available under no_function
, allow manipulation of the functions
encapsulated within an AST
:
Method | Description |
---|---|
clone_functions_only(&self) | clone the AST into a new AST with only functions, excluding statements |
clone_functions_only_filtered(&self, filter) | clone the AST into a new AST with only functions that pass the filter predicate, excluding statements |
retain_functions(&mut self, filter) | remove all functions in the AST that do not pass a particular predicate filter; statements are untouched |
iter_functions(&self) | return an iterator on all the functions in the AST |
clear_functions(&mut self) | remove all functions from the AST , leaving only statements |
Extract Only Statements
The following methods allow manipulation of the statements in an AST
:
Method | Description |
---|---|
clone_statements_only(&self) | clone the AST into a new AST with only the statements, excluding functions |
clear_statements(&mut self) | remove all statements from the AST , leaving only functions |
iter_literal_variables(&self, constants, variables) | return an iterator on all top-level literal constant and/or variable definitions in the AST |
Merge and Combine AST’s
The following methods merge one AST
with another:
Method | Description |
---|---|
merge(&self, &ast) ,+ operator | append the second AST to this AST , yielding a new AST that is a combination of the two; statements are simply appended, functions in the second AST of the same name and arity override similar functions in this AST |
merge_filtered(&self, &ast, filter) | append the second AST (but only functions that pass the predicate filter) to this AST , yielding a new AST that is a combination of the two; statements are simply appended, functions in the second AST of the same name and arity override similar functions in this AST |
combine(&mut self, ast) ,+= operator | append the second AST to this AST ; statements are simply appended, functions in the second AST of the same name and arity override similar functions in this AST |
combine_filtered(&mut self, ast, filter) | append the second AST (but only functions that pass the predicate filter) to this AST ; statements are simply appended, functions in the second AST of the same name and arity override similar functions in this AST |
When statements are appended, beware that this may change the semantics of the script.
// First script
let ast1 = engine.compile(
"
fn foo(x) { 42 + x }
foo(1)
")?;
// Second script
let ast2 = engine.compile(
"
fn foo(n) { `hello${n}` }
foo("!")
")?;
// Merge them
let merged = ast1.merge(&ast2);
// Notice that using the '+' operator also works:
let merged = &ast1 + &ast2;
merged
in the above example essentially contains the following script program:
fn foo(n) { `hello${n}` } // <- definition of first 'foo' is overwritten
foo(1) // <- notice this will be "hello1" instead of 43,
// but it is no longer the return value
foo("!") // <- returns "hello!"
Walk an AST
The internals
feature allows access to internal Rhai data structures, particularly the nodes
that make up the AST
.
AST node types
There are a few useful types when walking an AST
:
Type | Description |
---|---|
ASTNode | an enum with two variants: Expr or Stmt |
Expr | an expression |
Stmt | a statement |
BinaryExpr | a sub-type containing the LHS and RHS of a binary expression |
FnCallExpr | a sub-type containing information on a function call |
CustomExpr | a sub-type containing information on a custom syntax expression |
The AST::walk
method takes a callback function and recursively walks the AST
in depth-first
manner, with the parent node visited before its children.
Callback function signature
The signature of the callback function takes the following form.
FnMut(&[ASTNode]) -> bool
The single argument passed to the method contains a slice of ASTNode
types representing the path
from the current node to the root of the AST
.
Return true
to continue walking the AST
, or false
to terminate.
Children visit order
The order of visits to the children of each node type:
Node type | Children visit order |
---|---|
if statement |
|
switch statement |
|
while , do , loop statement |
|
for statement |
|
return statement | return value expression |
throw statement | exception value expression |
try … catch statement |
|
import statement | path expression |
Array literal | each of the element expressions, in order |
Object map literal | each of the element expressions, in order |
Interpolated string | each of the string/expression segments, in order |
Indexing |
|
Field access/method call |
|
&& , || , ?? |
|
Function call, operator expression | each of the argument expressions, in order |
let , const statement | value expression |
Assignment statement |
|
Statements block | each of the statements, in order |
Custom syntax expression | each of the inputs stream, in order |
All others | single child (if any) |