Struct rhai::Module

pub struct Module { /* private fields */ }

A module which may contain variables, sub-modules, external Rust functions, and/or script-defined functions.

Implementations

impl Module

pub fn with_capacity(_capacity: usize) -> Self

👎Deprecated since 1.12.0: use <code>new</code> instead

Create a new Module with a pre-sized capacity for functions.

Deprecated

This method is deprecated. Use new instead.

This method will be removed in the next major version.

impl Module

pub const fn new() -> Self

Create a new Module.

Example

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

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

Get the ID of the Module, if any.

Example

let mut module = Module::new();
module.set_id("hello");
assert_eq!(module.id(), Some("hello"));

pub fn set_id(&mut self, id: impl Into<ImmutableString>) -> &mut Self

Set the ID of the Module.

If the string is empty, it is equivalent to clearing the ID.

Example

let mut module = Module::new();
module.set_id("hello");
assert_eq!(module.id(), Some("hello"));

pub fn clear_id(&mut self) -> &mut Self

Clear the ID of the Module.

Example

let mut module = Module::new();
module.set_id("hello");
assert_eq!(module.id(), Some("hello"));
module.clear_id();
assert_eq!(module.id(), None);

pub fn doc(&self) -> &str

Get the documentation of the Module, if any. Exported under the metadata feature only.

Example

let mut module = Module::new();
module.set_doc("//! This is my special module.");
assert_eq!(module.doc(), "//! This is my special module.");

pub fn set_doc(&mut self, doc: impl Into<SmartString<LazyCompact>>) -> &mut Self

Set the documentation of the Module. Exported under the metadata feature only.

If the string is empty, it is equivalent to clearing the documentation.

Example

let mut module = Module::new();
module.set_doc("//! This is my special module.");
assert_eq!(module.doc(), "//! This is my special module.");

pub fn clear_doc(&mut self) -> &mut Self

Clear the documentation of the Module.

Example

let mut module = Module::new();
module.set_doc("//! This is my special module.");
assert_eq!(module.doc(), "//! This is my special module.");
module.clear_doc();
assert_eq!(module.doc(), "");

pub fn clear(&mut self)

Clear the Module.

pub fn set_custom_type<T>(&mut self, name: &str) -> &mut Self

Map a custom type to a friendly display name.

Example

#[derive(Clone)]
struct TestStruct;

let name = std::any::type_name::<TestStruct>();

let mut module = Module::new();

module.set_custom_type::<TestStruct>("MyType");

assert_eq!(module.get_custom_type(name), Some("MyType"));

pub fn set_custom_type_raw( &mut self, type_path: impl Into<Identifier>, name: impl Into<Identifier> ) -> &mut Self

Map a custom type to a friendly display name.

#[derive(Clone)]
struct TestStruct;

let name = std::any::type_name::<TestStruct>();

let mut module = Module::new();

module.set_custom_type_raw(name, "MyType");

assert_eq!(module.get_custom_type(name), Some("MyType"));

pub fn get_custom_type(&self, key: &str) -> Option<&str>

Get the display name of a registered custom type.

Example

#[derive(Clone)]
struct TestStruct;

let name = std::any::type_name::<TestStruct>();

let mut module = Module::new();

module.set_custom_type::<TestStruct>("MyType");

assert_eq!(module.get_custom_type(name), Some("MyType"));

pub fn is_empty(&self) -> bool

Returns true if this Module contains no items.

Example

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

pub const fn is_indexed(&self) -> bool

Is the Module indexed?

A module must be indexed before it can be used in an import statement.

Example

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

module.set_native_fn("foo", |x: &mut i64, y: i64| { *x = y; Ok(()) });
assert!(!module.is_indexed());

module.build_index();
assert!(module.is_indexed());

pub fn gen_fn_signatures(&self) -> impl Iterator<Item = String> + '_

(metadata) Generate signatures for all the non-private functions in the Module. Exported under the metadata feature only.

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

Does a variable exist in the Module?

Example

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.

Example

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

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

Get a Module variable as a Dynamic.

Example

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

pub fn set_var( &mut self, name: impl Into<Identifier>, 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.

Example

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

pub fn set_script_fn(&mut self, fn_def: impl Into<Shared<ScriptFnDef>>) -> u64

Set a script-defined function into the Module.

If there is an existing function of the same name and number of arguments, it is replaced.

pub fn get_script_fn( &self, name: impl AsRef<str>, num_params: usize ) -> Option<&Shared<ScriptFnDef>>

Get a shared reference to the 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?

Example

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 in the Module.

Example

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 set_sub_module( &mut self, name: impl Into<Identifier>, sub_module: impl Into<Shared<Module>> ) -> &mut Self

Set a sub-module into the Module.

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

Example

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 returned by the set_native_fn call.

Example

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

pub fn update_fn_metadata<S: Into<Identifier>>( &mut self, hash_fn: u64, arg_names: impl IntoIterator<Item = S> ) -> &mut Self

(metadata) Update the metadata (parameter names/types and return type) of a registered function. Exported under the metadata feature only.

The u64 hash is returned by the set_native_fn call.

Parameter Names and Types

Each parameter name/type pair should be a single string of the format: var_name: type.

Return Type

The last entry in the list should be the return type of the function. In other words, the number of entries should be one larger than the number of parameters.

pub fn update_fn_metadata_with_comments<A: Into<Identifier>, C: Into<Identifier>>( &mut self, hash_fn: u64, arg_names: impl IntoIterator<Item = A>, comments: impl IntoIterator<Item = C> ) -> &mut Self

(metadata) Update the metadata (parameter names/types, return type and doc-comments) of a registered function. Exported under the metadata feature only.

The u64 hash is returned by the set_native_fn call.

Parameter Names and Types

Each parameter name/type pair should be a single string of the format: var_name: type.

Return Type

The last entry in the list should be the return type of the function. In other words, the number of entries should be one larger than the number of parameters.

Comments

Block doc-comments should be kept in a separate string slice.

Line doc-comments should be merged, with line-breaks, into a single string slice without a final termination line-break.

Leading white-spaces should be stripped, and each string slice always starts with the corresponding doc-comment leader: /// or /**.

Each line in non-block doc-comments should start with ///.

pub fn update_fn_namespace( &mut self, hash_fn: u64, namespace: FnNamespace ) -> &mut Self

Update the namespace of a registered function.

The u64 hash is returned by the set_native_fn call.

pub fn set_fn( &mut self, name: impl AsRef<str>, namespace: FnNamespace, access: FnAccess, arg_names: Option<&[&str]>, arg_types: impl AsRef<[TypeId]>, func: CallableFunction ) -> u64

Set a Rust function into the Module, returning a u64 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.

Parameter Names and Types

Each parameter name/type pair should be a single string of the format: var_name: type.

Return Type

The last entry in the list should be the return type of the function. In other words, the number of entries should be one larger than the number of parameters.

pub fn set_fn_with_comments<S: AsRef<str>>( &mut self, name: impl AsRef<str>, namespace: FnNamespace, access: FnAccess, arg_names: Option<&[&str]>, arg_types: impl AsRef<[TypeId]>, comments: impl IntoIterator<Item = S>, func: CallableFunction ) -> u64

(metadata) Set a Rust function into the Module, returning a u64 hash key. Exported under the metadata feature only.

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

WARNING - Low Level API

This function is very low level.

Parameter Names and Types

Each parameter name/type pair should be a single string of the format: var_name: type.

Return Type

The last entry in the list should be the return type of the function. In other words, the number of entries should be one larger than the number of parameters.

Comments

Block doc-comments should be kept in a separate string slice.

Line doc-comments should be merged, with line-breaks, into a single string slice without a final termination line-break.

Leading white-spaces should be stripped, and each string slice always starts with the corresponding doc-comment leader: /// or /**.

Each line in non-block doc-comments should start with ///.

pub fn set_raw_fn<T: Variant + Clone>( &mut self, name: impl AsRef<str>, namespace: FnNamespace, access: FnAccess, arg_types: impl AsRef<[TypeId]>, func: impl Fn(NativeCallContext<'_>, &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 u64 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.

Arguments

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 argument value (i.e. cloning is cheap), use: args[n].as_xxx().unwrap()

To access an argument 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 argument, use args.get_mut(0).unwrap()

Function Metadata

No metadata for the function is registered. Use update_fn_metadata to add metadata.

Example

use rhai::{Module, FnNamespace, FnAccess};

let mut module = Module::new();
let hash = module.set_raw_fn("double_or_not", FnNamespace::Internal, FnAccess::Public,
                // Pass parameter types via a slice with TypeId's
                &[std::any::TypeId::of::<i64>(), std::any::TypeId::of::<bool>()],
                // Fixed closure signature
                |context, 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 RhaiResult<T>
                });

assert!(module.contains_fn(hash));

pub fn set_native_fn<A: 'static, const N: usize, const C: bool, T, F>( &mut self, name: impl AsRef<str> + Into<Identifier>, func: F ) -> u64where T: Variant + Clone, F: RegisterNativeFunction<A, N, C, T, true>,

Set a Rust function into the Module, returning a u64 hash key.

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

Function Namespace

The default function namespace is FnNamespace::Internal. Use update_fn_namespace to change it.

Function Metadata

No metadata for the function is registered. Use update_fn_metadata to add metadata.

Example

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

pub fn set_getter_fn<A, const C: bool, T, F>( &mut self, name: impl AsRef<str>, func: F ) -> u64where A: Variant + Clone, T: Variant + Clone, F: RegisterNativeFunction<(Mut<A>,), 1, C, T, true> + SendSync + 'static,

Set a Rust getter function taking one mutable parameter, returning a u64 hash key. This function is automatically exposed to the global namespace.

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

Function Metadata

No metadata for the function is registered. Use update_fn_metadata to add metadata.

Example

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_setter_fn<A, const C: bool, T, F>( &mut self, name: impl AsRef<str>, func: F ) -> u64where A: Variant + Clone, T: Variant + Clone, F: RegisterNativeFunction<(Mut<A>, T), 2, C, (), true> + SendSync + 'static,

Set a Rust setter function taking two parameters (the first one mutable) into the Module, returning a u64 hash key. This function is automatically exposed to the global namespace.

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

Function Metadata

No metadata for the function is registered. Use update_fn_metadata to add metadata.

Example

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_getter_setter_fn<A: Variant + Clone, const C1: bool, const C2: bool, T: Variant + Clone>( &mut self, name: impl AsRef<str>, getter: impl RegisterNativeFunction<(Mut<A>,), 1, C1, T, true> + SendSync + 'static, setter: impl RegisterNativeFunction<(Mut<A>, T), 2, C2, (), true> + SendSync + 'static ) -> (u64, u64)

Set a pair of Rust getter and setter functions into the Module, returning both u64 hash keys. This is a short-hand for set_getter_fn and set_setter_fn.

These function are automatically exposed to the global namespace.

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

Function Metadata

No metadata for the function is registered. Use update_fn_metadata to add metadata.

Example

use rhai::{Module, ImmutableString};

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

pub fn set_indexer_get_fn<A, B, const C: bool, T, F>(&mut self, func: F) -> u64where A: Variant + Clone, B: Variant + Clone, T: Variant + Clone, F: RegisterNativeFunction<(Mut<A>, B), 2, C, T, true> + SendSync + 'static,

Set a Rust index getter taking two parameters (the first one mutable) into the Module, returning a u64 hash key. This function is automatically exposed to the global namespace.

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.

Function Metadata

No metadata for the function is registered. Use update_fn_metadata to add metadata.

Example

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_indexer_set_fn<A, B, const C: bool, T, F>(&mut self, func: F) -> u64where A: Variant + Clone, B: Variant + Clone, T: Variant + Clone, F: RegisterNativeFunction<(Mut<A>, B, T), 3, C, (), true> + SendSync + 'static,

Set a Rust index setter taking three parameters (the first one mutable) into the Module, returning a u64 hash key. This function is automatically exposed to the global namespace.

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.

Function Metadata

No metadata for the function is registered. Use update_fn_metadata to add metadata.

Example

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_indexer_get_set_fn<A: Variant + Clone, B: Variant + Clone, const C1: bool, const C2: bool, T: Variant + Clone>( &mut self, get_fn: impl RegisterNativeFunction<(Mut<A>, B), 2, C1, T, true> + SendSync + 'static, set_fn: impl RegisterNativeFunction<(Mut<A>, B, T), 3, C2, (), true> + SendSync + 'static ) -> (u64, u64)

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

These functions are automatically exposed to the global namespace.

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.

Function Metadata

No metadata for the function is registered. Use update_fn_metadata to add metadata.

Example

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));
assert!(module.contains_fn(hash_set));

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

Does the particular namespace-qualified function exist in the Module?

The u64 hash is calculated by build_index.

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 fill_with(&mut self, other: &Self) -> &mut Self

Polyfill this Module with another Module. Only items not existing in this Module are added.

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_sub_modules(&self) -> impl Iterator<Item = (&str, &Shared<Module>)>

Get an iterator to the sub-modules in the Module.

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

Get an iterator to the variables in the Module.

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

(internals) Get an iterator over all script-defined functions in the Module. Exported under the internals feature only.

Function metadata includes:

1. Namespace (FnNamespace::Global or FnNamespace::Internal).
2. Access mode (FnAccess::Public or FnAccess::Private).
3. Function name (as string slice).
4. Number of parameters.
5. (internals) Shared reference to function definition ScriptFnDef.

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.

Example

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").expect("answer should exist"), 42);

pub fn eval_ast_as_new_raw( engine: &Engine, scope: &mut Scope<'_>, global: &mut GlobalRuntimeState, ast: &AST ) -> 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.

WARNING - Low Level API

This function is very low level.

In particular, the global parameter allows the entire calling environment to be encapsulated, including automatic global constants.

pub fn contains_indexed_global_functions(&self) -> bool

Does the Module contain indexed functions that have been exposed to the global namespace?

Panics

Panics if the Module is not yet indexed via build_index.

pub fn build_index(&mut self) -> &mut Self

Scan through all the sub-modules in the Module and build a hash index of all variables and functions as one flattened namespace.

If the Module is already indexed, this method has no effect.

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

Does a type iterator exist in the entire module tree?

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

Does a type iterator exist in the module?

pub fn set_iter( &mut self, type_id: TypeId, func: impl Fn(Dynamic) -> Box<dyn Iterator<Item = Dynamic>> + SendSync + 'static ) -> &mut Self

Set a type iterator into the Module.

pub fn set_iter_result( &mut self, type_id: TypeId, func: impl Fn(Dynamic) -> Box<dyn Iterator<Item = Result<Dynamic, Box<EvalAltResult>>>> + SendSync + 'static ) -> &mut Self

Set a fallible type iterator into the Module.

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

Set a type iterator into the Module.

pub fn set_iterable_result<T, X>(&mut self) -> &mut Selfwhere T: Variant + Clone + IntoIterator<Item = Result<X, Box<EvalAltResult>>>, X: Variant + Clone,

Set a fallible type iterator into the Module.

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

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

pub fn set_iterator_result<T, X>(&mut self) -> &mut Selfwhere T: Variant + Clone + Iterator<Item = Result<X, Box<EvalAltResult>>>, X: Variant + Clone,

Set a iterator type into the Module as a fallible 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 = Module

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 AST

fn as_ref(&self) -> &Module

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

impl Borrow<Module> for AST

fn borrow(&self) -> &Module

Immutably borrows from an owned value.

impl Clone for Module

fn clone(&self) -> Module

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() -> Self

Returns the “default value” for a type.

impl<T: IntoIterator<Item = Shared<ScriptFnDef>>> From<T> for Module

fn from(iter: T) -> Self

Converts to this type from the input type.