Struct rhai::AST

pub struct AST(_, _);

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

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

Implementations

impl AST

pub fn new(statements: Vec<Stmt>, lib: Module) -> Self

Create a new AST.

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

👎 Deprecated:

this method is volatile and may change

[INTERNALS] Get the statements.

pub fn lib(&self) -> &Module

👎 Deprecated:

this method is volatile and may change

[INTERNALS] Get the internal Module containing all script-defined functions.

pub fn clone_functions_only(&self) -> Self

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

This operation is cheap because functions are shared.

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

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

This operation is cheap because functions are shared.

pub fn clone_statements_only(&self) -> Self

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

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

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

The second AST is 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(r#"
                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 merge_filtered(
    &self,
    other: &Self,
    filter: impl Fn(FnAccess, &str, usize) -> bool
) -> Self

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

The second AST is 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(r#"
                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, |_, name, params| 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 retain_functions(
    &mut self,
    filter: impl Fn(FnAccess, &str, usize) -> bool
)

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

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 clear_functions(&mut self)

Clear all function definitions in the AST.

pub fn clear_statements(&mut self)

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

Trait Implementations

impl<'_> Add<&'_ AST> for &'_ AST

type Output = AST

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl AsRef<[Stmt]> for AST

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

Performs the conversion.

impl AsRef<Module> for AST

fn as_ref(&self) -> &Module

Performs the conversion.

impl Clone for AST

fn clone(&self) -> AST

Returns a copy 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

Formats the value using the given formatter.

impl Default for AST

fn default() -> AST

Returns the "default value" for a type.