Struct Module

pub struct Module { /* private fields */ }

Expand description

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

Implementations§

§

impl Module

pub const fn with_capacity(_capacity: usize) -> Module

👎Deprecated since 1.12.0: use new 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.

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

👎Deprecated since 1.16.0: use get_custom_type_display_by_name instead

Get the display name of a registered custom type.

§Deprecated

This method is deprecated. Use get_custom_type_display_by_name instead.

This method will be removed in the next major version.

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

👎Deprecated since 1.17.0: use the FuncRegistration API instead

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

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

§Deprecated

This method is deprecated. Use the FuncRegistration API instead.

This method will be removed in the next major version.

§

impl Module

pub const fn new() -> Module

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 Module

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 Module

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

Clear the Module.

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

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_display_by_name(name), Some("MyType"));

pub fn set_custom_type_raw( &mut self, type_name: impl Into<SmartString<LazyCompact>>, display_name: impl Into<SmartString<LazyCompact>>, ) -> &mut Module

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_display_by_name(name), Some("MyType"));

pub fn get_custom_type_display_by_name(&self, type_name: &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_display_by_name(name), Some("MyType"));

pub fn get_custom_type_display<T>(&self) -> 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_display::<TestStruct>(), 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 const fn is_internal(&self) -> bool

Is the Module an internal Rhai system module?

pub const fn is_standard_lib(&self) -> bool

Is the Module a Rhai standard library module?

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>(&self, name: &str) -> Option<T>
where T: Variant + Clone,

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<SmartString<LazyCompact>>, value: impl Variant + Clone, ) -> &mut Module

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 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<SmartString<LazyCompact>>, sub_module: impl Into<Arc<Module>>, ) -> &mut Module

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", |x: i64| Ok(42 + x));
assert!(module.contains_fn(hash));

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

👎Deprecated since 1.17.0: use the FuncRegistration API instead

Update the namespace of a registered function.

§Deprecated

This method is deprecated. Use the FuncRegistration API instead.

This method will be removed in the next major version.

pub fn set_fn_raw_with_options( &mut self, options: FuncRegistration, arg_types: impl AsRef<[TypeId]>, func: RhaiFunc, ) -> &FuncMetadata

Set a native Rust function into the Module based on a FuncRegistration.

§WARNING - Low Level API

This function is very low level. It takes a list of TypeId’s indicating the actual types of the parameters.

pub fn set_native_fn<A, const N: usize, const X: bool, R, FUNC>( &mut self, name: impl Into<SmartString<LazyCompact>>, func: FUNC, ) -> u64
where A: 'static, R: Variant + Clone, FUNC: RhaiNativeFunc<A, N, X, R, true> + SendSync + 'static,

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

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

§Use `FuncRegistration` API

It is recommended that the FuncRegistration API be used instead.

Essentially, this method is a shortcut for:

FuncRegistration::new(name)
    .in_internal_namespace()
    .with_purity(true)
    .with_volatility(false)
    .set_into_module(module, func)
    .hash

§Assumptions

Accessibility: The function namespace is FnNamespace::Internal.
Purity: The function is assumed to be pure unless it is a property setter or an index setter.
Volatility: The function is assumed to be non-volatile – i.e. it guarantees the same result for the same input(s).
Metadata: No metadata for the function is registered.

To change these assumptions, use the FuncRegistration API instead.

§Example

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

pub fn set_getter_fn<A, const X: bool, R, FUNC>( &mut self, name: impl AsRef<str>, func: FUNC, ) -> u64
where A: Variant + Clone, R: Variant + Clone, FUNC: RhaiNativeFunc<(Mut<A>,), 1, X, R, 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.

§Assumptions

Accessibility: The function namespace is FnNamespace::Global.
Purity: The function is assumed to be pure (so it can be called on constants).
Volatility: The function is assumed to be non-volatile – i.e. it guarantees the same result for the same input(s).
Metadata: No metadata for the function is registered.

To change these assumptions, use the FuncRegistration API instead.

§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 X: bool, R, FUNC>( &mut self, name: impl AsRef<str>, func: FUNC, ) -> u64
where A: Variant + Clone, R: Variant + Clone, FUNC: RhaiNativeFunc<(Mut<A>, R), 2, X, (), 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.

§Assumptions

Accessibility: The function namespace is FnNamespace::Global.
Purity: The function is assumed to be non-pure (so it cannot be called on constants).
Volatility: The function is assumed to be non-volatile – i.e. it guarantees the same result for the same input(s).
Metadata: No metadata for the function is registered.

To change these assumptions, use the FuncRegistration API instead.

§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, const X1: bool, const X2: bool, R>( &mut self, name: impl AsRef<str>, getter: impl RhaiNativeFunc<(Mut<A>,), 1, X1, R, true> + SendSync + 'static, setter: impl RhaiNativeFunc<(Mut<A>, R), 2, X2, (), true> + SendSync + 'static, ) -> (u64, u64)
where A: Variant + Clone, R: Variant + Clone,

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.

To change these assumptions, use the FuncRegistration API instead.

§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 X: bool, R, FUNC>( &mut self, func: FUNC, ) -> u64
where A: Variant + Clone, B: Variant + Clone, R: Variant + Clone, FUNC: RhaiNativeFunc<(Mut<A>, B), 2, X, R, 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.

§Assumptions

Accessibility: The function namespace is FnNamespace::Global.
Purity: The function is assumed to be pure (so it can be called on constants).
Volatility: The function is assumed to be non-volatile – i.e. it guarantees the same result for the same input(s).
Metadata: No metadata for the function is registered.

To change these assumptions, use the FuncRegistration API instead.

§Panics

Panics if the type is Array, Map, String, ImmutableString, &str or INT.

Indexers for arrays, object maps, strings and integers cannot be registered.

§Example

use rhai::{Module, ImmutableString};

#[derive(Clone)]
struct TestStruct(i64);

let mut module = Module::new();

let hash = module.set_indexer_get_fn(
                |x: &mut TestStruct, y: ImmutableString| Ok(x.0 + y.len() as i64)
           );

assert!(module.contains_fn(hash));

pub fn set_indexer_set_fn<A, B, const X: bool, R, FUNC>( &mut self, func: FUNC, ) -> u64
where A: Variant + Clone, B: Variant + Clone, R: Variant + Clone, FUNC: RhaiNativeFunc<(Mut<A>, B, R), 3, X, (), 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.

§Assumptions

Accessibility: The function namespace is FnNamespace::Global.
Purity: The function is assumed to be non-pure (so it cannot be called on constants).
Volatility: The function is assumed to be non-volatile – i.e. it guarantees the same result for the same input(s).

§Panics

Panics if the type is Array, Map, String, ImmutableString, &str or INT.

Indexers for arrays, object maps, strings and integers cannot be registered.

§Example

use rhai::{Module, ImmutableString};

#[derive(Clone)]
struct TestStruct(i64);

let mut module = Module::new();

let hash = module.set_indexer_set_fn(|x: &mut TestStruct, y: ImmutableString, value: i64| {
                        *x = TestStruct(y.len() as i64 + value);
                        Ok(())
           });

assert!(module.contains_fn(hash));

pub fn set_indexer_get_set_fn<A, B, const X1: bool, const X2: bool, R>( &mut self, get_fn: impl RhaiNativeFunc<(Mut<A>, B), 2, X1, R, true> + SendSync + 'static, set_fn: impl RhaiNativeFunc<(Mut<A>, B, R), 3, X2, (), true> + SendSync + 'static, ) -> (u64, u64)
where A: Variant + Clone, B: Variant + Clone, R: Variant + Clone,

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, Map, String, ImmutableString, &str or INT.

Indexers for arrays, object maps, strings and integers cannot be registered.

§Example

use rhai::{Module, ImmutableString};

#[derive(Clone)]
struct TestStruct(i64);

let mut module = Module::new();

let (hash_get, hash_set) = module.set_indexer_get_set_fn(
    |x: &mut TestStruct, y: ImmutableString| Ok(x.0 + y.len() as i64),
    |x: &mut TestStruct, y: ImmutableString, value: i64| { *x = TestStruct(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: Module) -> &mut Module

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

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

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.