Struct AST 

pub struct AST { /* private fields */ }

Available on crate feature rhai only.

Compiled AST (abstract syntax tree) of a Rhai script.

Thread Safety

Currently, AST is neither Send nor Sync. Turn on the sync feature to make it Send + Sync.

Implementations

impl AST

pub fn lib(&self) -> &Module

👎Deprecated since 1.3.0:

use shared_lib instead

Available on crate feature internals and non-crate feature no_function only.

(internals) Get the internal Module containing all script-defined functions. Exported under the internals feature only.

Not available under no_function.

Deprecated

This method is deprecated. Use shared_lib instead.

This method will be removed in the next major version.

impl AST

pub fn new( statements: impl IntoIterator<Item = Stmt>, functions: impl Into<Arc<Module>>, ) -> AST

Available on crate feature internals only.

(internals) Create a new AST. Exported under the internals feature only.

pub fn new_with_source( statements: impl IntoIterator<Item = Stmt>, functions: impl Into<Arc<Module>>, source: impl Into<ImmutableString>, ) -> AST

Available on crate feature internals only.

(internals) Create a new AST with a source name. Exported under the internals feature only.

pub fn new_from_module(module: impl Into<Arc<Module>>) -> AST

Available on non-crate feature no_function only.

Create a new AST from a shared Module.

pub fn empty() -> AST

Create an empty AST.

pub fn source(&self) -> Option<&str>

Get the source, if any.

pub fn set_source(&mut self, source: impl Into<ImmutableString>) -> &mut AST

Set the source.

pub fn clear_source(&mut self) -> &mut AST

Clear the source.

pub fn statements(&self) -> &[Stmt]

Available on crate feature internals only.

(internals) Get the statements. Exported under the internals feature only.

pub fn has_functions(&self) -> bool

Available on non-crate feature no_function only.

Does this AST contain script-defined functions?

Not available under no_function.

pub const fn shared_lib(&self) -> &Arc<Module>

Available on crate feature internals only.

(internals) Get the internal shared Module containing all script-defined functions. Exported under the internals feature only.

Not available under no_function.

pub const fn resolver(&self) -> Option<&Arc<StaticModuleResolver>>

Available on crate feature internals and non-crate feature no_module only.

(internals) Get the embedded module resolver. Exported under the internals feature only.

Not available under no_module.

pub fn clone_functions_only(&self) -> AST

Available on non-crate feature no_function only.

Clone the AST’s functions into a new AST. No statements are cloned.

Not available under no_function.

This operation is cheap because functions are shared.

pub fn clone_functions_only_filtered( &self, filter: impl Fn(FnNamespace, FnAccess, bool, &str, usize) -> bool, ) -> AST

Available on non-crate feature no_function only.

Clone the AST’s functions into a new AST based on a filter predicate. No statements are cloned.

Not available under no_function.

This operation is cheap because functions are shared.

pub fn clone_statements_only(&self) -> AST

Clone the AST’s script statements into a new AST. No functions are cloned.

pub fn merge(&self, other: &AST) -> AST

Merge two AST into one. Both AST’s are untouched and a new, merged, version is returned.

Statements in the second AST are simply appended to the end of the first without any processing. Thus, the return value of the first AST (if using expression-statement syntax) is buried. Of course, if the first AST uses a return statement at the end, then the second AST will essentially be dead code.

All script-defined functions in the second AST overwrite similarly-named functions in the first AST with the same number of parameters.

Example

use rhai::Engine;

let engine = Engine::new();

let ast1 = engine.compile("
    fn foo(x) { 42 + x }
    foo(1)
")?;

let ast2 = engine.compile(r#"
    fn foo(n) { `hello${n}` }
    foo("!")
"#)?;

let ast = ast1.merge(&ast2);    // Merge 'ast2' into 'ast1'

// Notice that using the '+' operator also works:
// let ast = &ast1 + &ast2;

// 'ast' is essentially:
//
//    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!"

// Evaluate it
assert_eq!(engine.eval_ast::<String>(&ast)?, "hello!");

pub fn combine(&mut self, other: AST) -> &mut AST

Combine one AST with another. The second AST is consumed.

Statements in the second AST are simply appended to the end of the first without any processing. Thus, the return value of the first AST (if using expression-statement syntax) is buried. Of course, if the first AST uses a return statement at the end, then the second AST will essentially be dead code.

All script-defined functions in the second AST overwrite similarly-named functions in the first AST with the same number of parameters.

Example

use rhai::Engine;

let engine = Engine::new();

let mut ast1 = engine.compile("
    fn foo(x) { 42 + x }
    foo(1)
")?;

let ast2 = engine.compile(r#"
    fn foo(n) { `hello${n}` }
    foo("!")
"#)?;

ast1.combine(ast2);    // Combine 'ast2' into 'ast1'

// Notice that using the '+=' operator also works:
// ast1 += ast2;

// 'ast1' is essentially:
//
//    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!"

// Evaluate it
assert_eq!(engine.eval_ast::<String>(&ast1)?, "hello!");

pub fn merge_filtered( &self, other: &AST, filter: impl Fn(FnNamespace, FnAccess, bool, &str, usize) -> bool, ) -> AST

Available on non-crate feature no_function only.

Merge two AST into one. Both AST’s are untouched and a new, merged, version is returned.

Not available under no_function.

Statements in the second AST are simply appended to the end of the first without any processing. Thus, the return value of the first AST (if using expression-statement syntax) is buried. Of course, if the first AST uses a return statement at the end, then the second AST will essentially be dead code.

All script-defined functions in the second AST are first selected based on a filter predicate, then overwrite similarly-named functions in the first AST with the same number of parameters.

Example

use rhai::Engine;

let engine = Engine::new();

let ast1 = engine.compile("
    fn foo(x) { 42 + x }
    foo(1)
")?;

let ast2 = engine.compile(r#"
    fn foo(n) { `hello${n}` }
    fn error() { 0 }
    foo("!")
"#)?;

// Merge 'ast2', picking only 'error()' but not 'foo(..)', into 'ast1'
let ast = ast1.merge_filtered(&ast2, |_, _, script, name, params|
                                script && name == "error" && params == 0);

// 'ast' is essentially:
//
//    fn foo(n) { 42 + n }      // <- definition of 'ast1::foo' is not overwritten
//                              //    because 'ast2::foo' is filtered away
//    foo(1)                    // <- notice this will be 43 instead of "hello1",
//                              //    but it is no longer the return value
//    fn error() { 0 }          // <- this function passes the filter and is merged
//    foo("!")                  // <- returns "42!"

// Evaluate it
assert_eq!(engine.eval_ast::<String>(&ast)?, "42!");

pub fn combine_filtered( &mut self, other: AST, filter: impl Fn(FnNamespace, FnAccess, bool, &str, usize) -> bool, ) -> &mut AST

Available on non-crate feature no_function only.

Combine one AST with another. The second AST is consumed.

Not available under no_function.

Statements in the second AST are simply appended to the end of the first without any processing. Thus, the return value of the first AST (if using expression-statement syntax) is buried. Of course, if the first AST uses a return statement at the end, then the second AST will essentially be dead code.

All script-defined functions in the second AST are first selected based on a filter predicate, then overwrite similarly-named functions in the first AST with the same number of parameters.

Example

use rhai::Engine;

let engine = Engine::new();

let mut ast1 = engine.compile("
    fn foo(x) { 42 + x }
    foo(1)
")?;

let ast2 = engine.compile(r#"
    fn foo(n) { `hello${n}` }
    fn error() { 0 }
    foo("!")
"#)?;

// Combine 'ast2', picking only 'error()' but not 'foo(..)', into 'ast1'
ast1.combine_filtered(ast2, |_, _, script, name, params|
                                script && name == "error" && params == 0);

// 'ast1' is essentially:
//
//    fn foo(n) { 42 + n }      // <- definition of 'ast1::foo' is not overwritten
//                              //    because 'ast2::foo' is filtered away
//    foo(1)                    // <- notice this will be 43 instead of "hello1",
//                              //    but it is no longer the return value
//    fn error() { 0 }          // <- this function passes the filter and is merged
//    foo("!")                  // <- returns "42!"

// Evaluate it
assert_eq!(engine.eval_ast::<String>(&ast1)?, "42!");

pub fn retain_functions( &mut self, filter: impl Fn(FnNamespace, FnAccess, &str, usize) -> bool, ) -> &mut AST

Available on non-crate feature no_function only.

Filter out the functions, retaining only some based on a filter predicate.

Not available under no_function.

Example

use rhai::Engine;

let engine = Engine::new();

let mut ast = engine.compile(r#"
    fn foo(n) { n + 1 }
    fn bar() { print("hello"); }
"#)?;

// Remove all functions except 'foo(..)'
ast.retain_functions(|_, _, name, params| name == "foo" && params == 1);

pub fn iter_fn_def(&self) -> impl Iterator<Item = &Arc<ScriptFuncDef>>

Available on crate feature internals only.

(internals) Iterate through all function definitions. Exported under the internals feature only.

Not available under no_function.

pub fn iter_functions(&self) -> impl Iterator<Item = ScriptFnMetadata<'_>>

Available on non-crate feature no_function only.

Iterate through all function definitions.

Not available under no_function.

pub fn clear_functions(&mut self) -> &mut AST

Available on non-crate feature no_function only.

Clear all function definitions in the AST.

Not available under no_function.

pub fn clear_statements(&mut self) -> &mut AST

Clear all statements in the AST, leaving only function definitions.

pub fn iter_literal_variables( &self, include_constants: bool, include_variables: bool, ) -> impl Iterator<Item = (&str, bool, Dynamic)>

Extract all top-level literal constant and/or variable definitions. This is useful for extracting all global constants from a script without actually running it.

A literal constant/variable definition takes the form of: const VAR = value; and let VAR = value; where value is a literal expression or will be optimized into a literal.

Example

use rhai::{Engine, Scope};

let engine = Engine::new();

let ast = engine.compile(
"
    const A = 40 + 2;   // constant that optimizes into a literal
    let b = 123;        // literal variable
    const B = b * A;    // non-literal constant
    const C = 999;      // literal constant
    b = A + C;          // expression

    {                   // <- new block scope
        const Z = 0;    // <- literal constant not at top-level

        print(Z);       // make sure the block is not optimized away
    }
")?;

let mut iter = ast.iter_literal_variables(true, false)
                  .map(|(name, is_const, value)| (name, is_const, value.as_int().unwrap()));

assert_eq!(iter.next(), Some(("A", true, 42)));
assert_eq!(iter.next(), Some(("C", true, 999)));
assert_eq!(iter.next(), None);

let mut iter = ast.iter_literal_variables(false, true)
                  .map(|(name, is_const, value)| (name, is_const, value.as_int().unwrap()));

assert_eq!(iter.next(), Some(("b", false, 123)));
assert_eq!(iter.next(), None);

let mut iter = ast.iter_literal_variables(true, true)
                  .map(|(name, is_const, value)| (name, is_const, value.as_int().unwrap()));

assert_eq!(iter.next(), Some(("A", true, 42)));
assert_eq!(iter.next(), Some(("b", false, 123)));
assert_eq!(iter.next(), Some(("C", true, 999)));
assert_eq!(iter.next(), None);

let scope: Scope = ast.iter_literal_variables(true, false).collect();

assert_eq!(scope.len(), 2);

Ok(())

pub fn walk( &self, on_node: &mut (impl FnMut(&[ASTNode<'_>]) -> bool + ?Sized), ) -> bool

Available on crate feature internals only.

(internals) Recursively walk the AST, including function bodies (if any). Return false from the callback to terminate the walk. Exported under the internals feature only.

Trait Implementations

impl<A> Add<A> for &AST

where A: AsRef<AST>,

type Output = AST

The resulting type after applying the + operator.

fn add(self, rhs: A) -> <&AST as Add<A>>::Output

Performs the + operation.

impl<A> AddAssign<A> for AST

where A: Into<AST>,

fn add_assign(&mut self, rhs: A)

Performs the += operation.

impl AsRef<Arc<Module>> for AST

Available on non-crate feature no_function only.

fn as_ref(&self) -> &Arc<Module>

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Module> for AST

Available on non-crate feature no_function only.

fn as_ref(&self) -> &Module

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<[Stmt]> for AST

fn as_ref(&self) -> &[Stmt]

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<Arc<Module>> for AST

Available on non-crate feature no_function only.

fn borrow(&self) -> &Arc<Module>

Immutably borrows from an owned value.

impl Borrow<Module> for AST

Available on non-crate feature no_function only.

fn borrow(&self) -> &Module

Immutably borrows from an owned value.

impl Borrow<[Stmt]> for AST

fn borrow(&self) -> &[Stmt]

Immutably borrows from an owned value.

impl Clone for AST

fn clone(&self) -> AST

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AST

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for AST

fn default() -> AST

Returns the “default value” for a type.