Struct rhai::Module

pub struct Module { /* fields omitted */ }

An imported module, which may contain variables, sub-modules, external Rust functions, and script-defined functions.

Not available under the no_module feature.

Implementations

impl Module

pub fn new() -> Self

Create a new module.

Examples

use rhai::Module;

let mut module = Module::new();
module.set_var("answer", 42_i64);
assert_eq!(module.get_var_value::<i64>("answer").unwrap(), 42);

pub fn new_with_capacity(capacity: usize) -> Self

Create a new module with a specified capacity for native Rust functions.

Examples

use rhai::Module;

let mut module = Module::new();
module.set_var("answer", 42_i64);
assert_eq!(module.get_var_value::<i64>("answer").unwrap(), 42);

pub fn is_empty(&self) -> bool

Is the module empty?

Examples

use rhai::Module;

let module = Module::new();
assert!(module.is_empty());

pub fn contains_var(&self, name: &str) -> bool

Does a variable exist in the module?

Examples

use rhai::Module;

let mut module = Module::new();
module.set_var("answer", 42_i64);
assert!(module.contains_var("answer"));

pub fn get_var_value<T: Variant + Clone>(&self, name: &str) -> Option<T>

Get the value of a module variable.

Examples

use rhai::Module;

let mut module = Module::new();
module.set_var("answer", 42_i64);
assert_eq!(module.get_var_value::<i64>("answer").unwrap(), 42);

pub fn get_var(&self, name: &str) -> Option<Dynamic>

Get a module variable as a Dynamic.

Examples

use rhai::Module;

let mut module = Module::new();
module.set_var("answer", 42_i64);
assert_eq!(module.get_var("answer").unwrap().cast::<i64>(), 42);

pub fn set_var(
    &mut self,
    name: impl Into<String>,
    value: impl Variant + Clone
) -> &mut Self

Set a variable into the module.

If there is an existing variable of the same name, it is replaced.

Examples

use rhai::Module;

let mut module = Module::new();
module.set_var("answer", 42_i64);
assert_eq!(module.get_var_value::<i64>("answer").unwrap(), 42);

pub fn get_script_fn(
    &self,
    name: &str,
    num_params: usize,
    public_only: bool
) -> Option<&Rc<ScriptFnDef>>

Get a script-defined function in the module based on name and number of parameters.

pub fn contains_sub_module(&self, name: &str) -> bool

Does a sub-module exist in the module?

Examples

use rhai::Module;

let mut module = Module::new();
let sub_module = Module::new();
module.set_sub_module("question", sub_module);
assert!(module.contains_sub_module("question"));

pub fn get_sub_module(&self, name: &str) -> Option<&Module>

Get a sub-module.

Examples

use rhai::Module;

let mut module = Module::new();
let sub_module = Module::new();
module.set_sub_module("question", sub_module);
assert!(module.get_sub_module("question").is_some());

pub fn get_sub_module_mut(&mut self, name: &str) -> Option<&mut Module>

Get a mutable reference to a sub-module.

Examples

use rhai::Module;

let mut module = Module::new();
let sub_module = Module::new();
module.set_sub_module("question", sub_module);
assert!(module.get_sub_module_mut("question").is_some());

pub fn set_sub_module(
    &mut self,
    name: impl Into<String>,
    sub_module: Module
) -> &mut Self

Set a sub-module into the module.

If there is an existing sub-module of the same name, it is replaced.

Examples

use rhai::Module;

let mut module = Module::new();
let sub_module = Module::new();
module.set_sub_module("question", sub_module);
assert!(module.get_sub_module("question").is_some());

pub fn contains_fn(&self, hash_fn: u64, public_only: bool) -> bool

Does the particular Rust function exist in the module?

The u64 hash is calculated by the function crate::calc_fn_hash. It is also returned by the set_fn_XXX calls.

Examples

use rhai::Module;

let mut module = Module::new();
let hash = module.set_fn_0("calc", || Ok(42_i64));
assert!(module.contains_fn(hash, true));

pub fn set_fn(
    &mut self,
    name: impl Into<String>,
    access: FnAccess,
    arg_types: &[TypeId],
    func: CallableFunction
) -> u64

Set a Rust function into the module, returning a hash key.

If there is an existing Rust function of the same hash, it is replaced.

WARNING - Low Level API

This function is very low level.

pub fn set_raw_fn<T: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    arg_types: &[TypeId],
    func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust function taking a reference to the scripting Engine, the current set of functions, plus a list of mutable Dynamic references into the module, returning a hash key.

Use this to register a built-in function which must reference settings on the scripting Engine (e.g. to prevent growing an array beyond the allowed maximum size), or to call a script-defined function in the current evaluation context.

If there is a similar existing Rust function, it is replaced.

WARNING - Low Level API

This function is very low level.

A list of TypeId’s is taken as the argument types.

Arguments are simply passed in as a mutable array of &mut Dynamic, which is guaranteed to contain enough arguments of the correct types.

The function is assumed to be a method, meaning that the first argument should not be consumed. All other arguments can be consumed.

To access a primary parameter value (i.e. cloning is cheap), use: args[n].clone().cast::<T>()

To access a parameter value and avoid cloning, use std::mem::take(args[n]).cast::<T>(). Notice that this will consume the argument, replacing it with ().

To access the first mutable parameter, use args.get_mut(0).unwrap()

Examples

use rhai::Module;

let mut module = Module::new();
let hash = module.set_raw_fn("double_or_not",
                // Pass parameter types via a slice with TypeId's
                &[std::any::TypeId::of::<i64>(), std::any::TypeId::of::<bool>()],
                // Fixed closure signature
                |engine, lib, args| {
                    // 'args' is guaranteed to be the right length and of the correct types

                    // Get the second parameter by 'consuming' it
                    let double = std::mem::take(args[1]).cast::<bool>();
                    // Since it is a primary type, it can also be cheaply copied
                    let double = args[1].clone().cast::<bool>();
                    // Get a mutable reference to the first argument.
                    let mut x = args[0].write_lock::<i64>().unwrap();

                    let orig = *x;

                    if double {
                        *x *= 2;            // the first argument can be mutated
                    }

                    Ok(orig)                // return Result<T, Box<EvalAltResult>>
                });

assert!(module.contains_fn(hash, true));

pub fn set_fn_0<T: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    func: impl Fn() -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust function taking no parameters into the module, returning a hash key.

If there is a similar existing Rust function, it is replaced.

Examples

use rhai::Module;

let mut module = Module::new();
let hash = module.set_fn_0("calc", || Ok(42_i64));
assert!(module.contains_fn(hash, true));

pub fn set_fn_1<A: Variant + Clone, T: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    func: impl Fn(A) -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust function taking one parameter into the module, returning a hash key.

If there is a similar existing Rust function, it is replaced.

Examples

use rhai::Module;

let mut module = Module::new();
let hash = module.set_fn_1("calc", |x: i64| Ok(x + 1));
assert!(module.contains_fn(hash, true));

pub fn set_fn_1_mut<A: Variant + Clone, T: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    func: impl Fn(&mut A) -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust function taking one mutable parameter into the module, returning a hash key.

If there is a similar existing Rust function, it is replaced.

Examples

use rhai::Module;

let mut module = Module::new();
let hash = module.set_fn_1_mut("calc", |x: &mut i64| { *x += 1; Ok(*x) });
assert!(module.contains_fn(hash, true));

pub fn set_getter_fn<A: Variant + Clone, T: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    func: impl Fn(&mut A) -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust getter function taking one mutable parameter, returning a hash key.

If there is a similar existing Rust getter function, it is replaced.

Examples

use rhai::Module;

let mut module = Module::new();
let hash = module.set_getter_fn("value", |x: &mut i64| { Ok(*x) });
assert!(module.contains_fn(hash, true));

pub fn set_fn_2<A: Variant + Clone, B: Variant + Clone, T: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    func: impl Fn(A, B) -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust function taking two parameters into the module, returning a hash key.

If there is a similar existing Rust function, it is replaced.

Examples

use rhai::{Module, ImmutableString};

let mut module = Module::new();
let hash = module.set_fn_2("calc", |x: i64, y: ImmutableString| {
    Ok(x + y.len() as i64)
});
assert!(module.contains_fn(hash, true));

pub fn set_fn_2_mut<A: Variant + Clone, B: Variant + Clone, T: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    func: impl Fn(&mut A, B) -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust function taking two parameters (the first one mutable) into the module, returning a hash key.

If there is a similar existing Rust function, it is replaced.

Examples

use rhai::{Module, ImmutableString};

let mut module = Module::new();
let hash = module.set_fn_2_mut("calc", |x: &mut i64, y: ImmutableString| {
    *x += y.len() as i64; Ok(*x)
});
assert!(module.contains_fn(hash, true));

pub fn set_setter_fn<A: Variant + Clone, B: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    func: impl Fn(&mut A, B) -> Result<(), Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust setter function taking two parameters (the first one mutable) into the module, returning a hash key.

If there is a similar existing setter Rust function, it is replaced.

Examples

use rhai::{Module, ImmutableString};

let mut module = Module::new();
let hash = module.set_setter_fn("value", |x: &mut i64, y: ImmutableString| {
    *x = y.len() as i64;
    Ok(())
});
assert!(module.contains_fn(hash, true));

pub fn set_indexer_get_fn<A: Variant + Clone, B: Variant + Clone, T: Variant + Clone>(
    &mut self,
    func: impl Fn(&mut A, B) -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust index getter taking two parameters (the first one mutable) into the module, returning a hash key.

If there is a similar existing setter Rust function, it is replaced.

Panics

Panics if the type is Array or Map. Indexers for arrays, object maps and strings cannot be registered.

Examples

use rhai::{Module, ImmutableString};

let mut module = Module::new();
let hash = module.set_indexer_get_fn(|x: &mut i64, y: ImmutableString| {
    Ok(*x + y.len() as i64)
});
assert!(module.contains_fn(hash, true));

pub fn set_fn_3<A: Variant + Clone, B: Variant + Clone, C: Variant + Clone, T: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    func: impl Fn(A, B, C) -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust function taking three parameters into the module, returning a hash key.

If there is a similar existing Rust function, it is replaced.

Examples

use rhai::{Module, ImmutableString};

let mut module = Module::new();
let hash = module.set_fn_3("calc", |x: i64, y: ImmutableString, z: i64| {
    Ok(x + y.len() as i64 + z)
});
assert!(module.contains_fn(hash, true));

pub fn set_fn_3_mut<A: Variant + Clone, B: Variant + Clone, C: Variant + Clone, T: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    func: impl Fn(&mut A, B, C) -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust function taking three parameters (the first one mutable) into the module, returning a hash key.

If there is a similar existing Rust function, it is replaced.

Examples

use rhai::{Module, ImmutableString};

let mut module = Module::new();
let hash = module.set_fn_3_mut("calc", |x: &mut i64, y: ImmutableString, z: i64| {
    *x += y.len() as i64 + z; Ok(*x)
});
assert!(module.contains_fn(hash, true));

pub fn set_indexer_set_fn<A: Variant + Clone, B: Variant + Clone, C: Variant + Clone>(
    &mut self,
    func: impl Fn(&mut A, B, C) -> Result<(), Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust index setter taking three parameters (the first one mutable) into the module, returning a hash key.

If there is a similar existing Rust function, it is replaced.

Panics

Panics if the type is Array or Map. Indexers for arrays, object maps and strings cannot be registered.

Examples

use rhai::{Module, ImmutableString};

let mut module = Module::new();
let hash = module.set_indexer_set_fn(|x: &mut i64, y: ImmutableString, value: i64| {
    *x = y.len() as i64 + value;
    Ok(())
});
assert!(module.contains_fn(hash, true));

pub fn set_indexer_get_set_fn<A: Variant + Clone, B: Variant + Clone, T: Variant + Clone>(
    &mut self,
    getter: impl Fn(&mut A, B) -> Result<T, Box<EvalAltResult>> + SendSync + 'static,
    setter: impl Fn(&mut A, B, T) -> Result<(), Box<EvalAltResult>> + SendSync + 'static
) -> (u64, u64)

Set a pair of Rust index getter and setter functions, returning both hash keys. This is a short-hand for set_indexer_get_fn and set_indexer_set_fn.

If there are similar existing Rust functions, they are replaced.

Panics

Panics if the type is Array or Map. Indexers for arrays, object maps and strings cannot be registered.

Examples

use rhai::{Module, ImmutableString};

let mut module = Module::new();
let (hash_get, hash_set) = module.set_indexer_get_set_fn(
    |x: &mut i64, y: ImmutableString| {
        Ok(*x + y.len() as i64)
    },
    |x: &mut i64, y: ImmutableString, value: i64| {
        *x = y.len() as i64 + value;
        Ok(())
    }
);
assert!(module.contains_fn(hash_get, true));
assert!(module.contains_fn(hash_set, true));

pub fn set_fn_4<A: Variant + Clone, B: Variant + Clone, C: Variant + Clone, D: Variant + Clone, T: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    func: impl Fn(A, B, C, D) -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust function taking four parameters into the module, returning a hash key.

If there is a similar existing Rust function, it is replaced.

Examples

use rhai::{Module, ImmutableString};

let mut module = Module::new();
let hash = module.set_fn_4("calc", |x: i64, y: ImmutableString, z: i64, _w: ()| {
    Ok(x + y.len() as i64 + z)
});
assert!(module.contains_fn(hash, true));

pub fn set_fn_4_mut<A: Variant + Clone, B: Variant + Clone, C: Variant + Clone, D: Variant + Clone, T: Variant + Clone>(
    &mut self,
    name: impl Into<String>,
    func: impl Fn(&mut A, B, C, D) -> Result<T, Box<EvalAltResult>> + SendSync + 'static
) -> u64

Set a Rust function taking four parameters (the first one mutable) into the module, returning a hash key.

If there is a similar existing Rust function, it is replaced.

Examples

use rhai::{Module, ImmutableString};

let mut module = Module::new();
let hash = module.set_fn_4_mut("calc", |x: &mut i64, y: ImmutableString, z: i64, _w: ()| {
    *x += y.len() as i64 + z; Ok(*x)
});
assert!(module.contains_fn(hash, true));

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

Combine another module into this module. The other module is consumed to merge into this module.

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

Combine another module into this module. The other module is consumed to merge into this module. Sub-modules are flattened onto the root module, with higher level overriding lower level.

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

Merge another module into this module.

pub fn count(&self) -> (usize, usize, usize)

Get the number of variables, functions and type iterators in the module.

pub fn iter_var(&self) -> impl Iterator<Item = (&String, &Dynamic)>

Get an iterator to the variables in the module.

pub fn iter_script_fn_info(
    &self
) -> impl Iterator<Item = (FnAccess, &str, usize, Rc<ScriptFnDef>)>

Get an iterator over all script-defined functions in the module.

Function metadata includes:

1. Access mode (FnAccess::Public or FnAccess::Private).
2. Function name (as string slice).
3. Number of parameters.
4. [INTERNALS] Shared reference to function definition ScriptFnDef. Exported under the internals feature only.

pub fn eval_ast_as_new(
    scope: Scope<'_>,
    ast: &AST,
    engine: &Engine
) -> Result<Self, Box<EvalAltResult>>

Create a new Module by evaluating an AST.

The entire AST is encapsulated into each function, allowing functions to cross-call each other. Functions in the global namespace, plus all functions defined in the module, are merged into a unified namespace before each call. Therefore, all functions will be found.

Examples

use rhai::{Engine, Module, Scope};

let engine = Engine::new();
let ast = engine.compile("let answer = 42; export answer;")?;
let module = Module::eval_ast_as_new(Scope::new(), &ast, &engine)?;
assert!(module.contains_var("answer"));
assert_eq!(module.get_var_value::<i64>("answer").unwrap(), 42);

pub fn contains_iter(&self, id: TypeId) -> bool

Does a type iterator exist in the module?

pub fn set_iter(
    &mut self,
    typ: TypeId,
    func: fn(_: Dynamic) -> Box<dyn Iterator<Item = Dynamic>>
) -> &mut Self

Set a type iterator into the module.

pub fn set_iterable<T>(&mut self) -> &mut Self where
    T: Variant + Clone + IntoIterator,
    <T as IntoIterator>::Item: Variant + Clone, 

Set a type iterator into the module.

pub fn set_iterator<T>(&mut self) -> &mut Self where
    T: Variant + Clone + Iterator,
    <T as Iterator>::Item: Variant + Clone, 

Set an iterator type into the module as a type iterator.

Trait Implementations

impl<M: AsRef<Module>> Add<M> for &Module

type Output = Module

The resulting type after applying the + operator.

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

Performs the + operation.

impl<M: AsRef<Module>> Add<M> for Module

type Output = Self

The resulting type after applying the + operator.

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

Performs the + operation.

impl<M: Into<Module>> AddAssign<M> for Module

fn add_assign(&mut self, rhs: M)

Performs the += operation.

impl AsRef<Module> for Module

fn as_ref(&self) -> &Module

Performs the conversion.

impl AsRef<Module> for AST

fn as_ref(&self) -> &Module

Performs the conversion.

impl Clone for Module

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Module

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

Formats the value using the given formatter.

impl Default for Module

fn default() -> Module

Returns the “default value” for a type.