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 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 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) -> 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));

pub fn set_fn(
    &mut self,
    name: impl Into<String>,
    access: FnAccess,
    arg_types: &[TypeId],
    func: Func
) -> 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.

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 x = args[0].downcast_mut::<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));

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));

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));

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));

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));

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));

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));

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));

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.

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));

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));

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));

pub fn set_indexer_set_fn<A: Variant + Clone, B: Variant + Clone>(
    &mut self,
    func: impl Fn(&mut A, B, A) -> 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.

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));

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));

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));

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

Merge another module into this module.

pub fn num_var(&self) -> usize

Get the number of variables in the module.

pub fn num_fn(&self) -> usize

Get the number of functions in the module.

pub fn num_iter(&self) -> usize

Get the number of 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<'a>(
    &'a self
) -> impl Iterator<Item = Rc<ScriptFnDef>> + 'a

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

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

Create a new Module by evaluating an AST.

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: IteratorFn) -> &mut Self

Set a type iterator into the module.

Trait Implementations

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.