kjuulh/rhai
1
0
Fork 0
Code Issues 1 Pull Requests 1 Packages Projects Releases Wiki Activity

Refine docs and comments etc.

Browse Source
This commit is contained in:
Stephen Chung
2021-01-02 23:30:10 +08:00
parent 5a3bbaa322
commit ef48f47b74
22 changed files with 352 additions and 296 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
src/module/mod.rs
View File

@@ -125,17 +125,15 @@ impl FuncInfo {
/// A module which may contain variables, sub-modules, external Rust functions,
/// and/or script-defined functions.
///
/// Not available under the `no_module` feature.
#[derive(Clone)]
pub struct Module {
/// ID identifying the module.
id: Option<ImmutableString>,
/// Sub-modules.
modules: HashMap<ImmutableString, Shared<Module>>,
/// Module variables.
/// [`Module`] variables.
variables: HashMap<ImmutableString, Dynamic>,
/// Flattened collection of all module variables, including those in sub-modules.
/// Flattened collection of all [`Module`] variables, including those in sub-modules.
all_variables: HashMap<NonZeroU64, Dynamic, StraightHasherBuilder>,
/// External Rust functions.
functions: HashMap<NonZeroU64, FuncInfo, StraightHasherBuilder>,
@@ -146,7 +144,7 @@ pub struct Module {
type_iterators: HashMap<TypeId, IteratorFn>,
/// Flattened collection of iterator functions, including those in sub-modules.
all_type_iterators: HashMap<TypeId, IteratorFn>,
/// Is the module indexed?
/// Is the [`Module`] indexed?
indexed: bool,
}
@@ -203,7 +201,7 @@ impl AsRef<Module> for Module {
}
impl Module {
/// Create a new module.
/// Create a new [`Module`].
///
/// # Example
///
@@ -219,7 +217,7 @@ impl Module {
Default::default()
}
/// Create a new module with a specified capacity for native Rust functions.
/// Create a new [`Module`] with a specified capacity for native Rust functions.
///
/// # Example
///
@@ -238,7 +236,7 @@ impl Module {
}
}
/// Get the ID of the module, if any.
/// Get the ID of the [`Module`], if any.
///
/// # Example
///
@@ -253,12 +251,12 @@ impl Module {
self.id.as_ref().map(|s| s.as_str())
}
/// Get the ID of the module, if any.
/// Get the ID of the [`Module`], if any.
pub(crate) fn id_raw(&self) -> &Option<ImmutableString> {
&self.id
}
/// Set the ID of the module.
/// Set the ID of the [`Module`].
///
/// # Example
///
@@ -273,7 +271,7 @@ impl Module {
self.id = id.map(|s| s.into());
}
/// Is the module empty?
/// Is the [`Module`] empty?
///
/// # Example
///
@@ -294,7 +292,7 @@ impl Module {
&& self.all_type_iterators.is_empty()
}
/// Is the module indexed?
/// Is the [`Module`] indexed?
///
/// # Example
///
@@ -314,7 +312,7 @@ impl Module {
self.indexed
}
/// Generate signatures for all the functions in the module.
/// Generate signatures for all the functions in the [`Module`].
pub fn gen_fn_signatures<'a>(&'a self) -> impl Iterator<Item = String> + 'a {
self.functions
.values()
@@ -322,7 +320,7 @@ impl Module {
.map(FuncInfo::gen_signature)
}
/// Does a variable exist in the module?
/// Does a variable exist in the [`Module`]?
///
/// # Example
///
@@ -338,7 +336,7 @@ impl Module {
self.variables.contains_key(name)
}
/// Get the value of a module variable.
/// Get the value of a [`Module`] variable.
///
/// # Example
///
@@ -354,7 +352,7 @@ impl Module {
self.get_var(name).and_then(Dynamic::try_cast::<T>)
}
/// Get a module variable as a [`Dynamic`].
/// Get a [`Module`] variable as a [`Dynamic`].
///
/// # Example
///
@@ -370,7 +368,7 @@ impl Module {
self.variables.get(name).cloned()
}
/// Set a variable into the module.
/// Set a variable into the [`Module`].
///
/// If there is an existing variable of the same name, it is replaced.
///
@@ -397,7 +395,7 @@ impl Module {
/// Get a reference to a namespace-qualified variable.
/// Name and Position in [`EvalAltResult`] are [`None`] and [`NONE`][Position::NONE] and must be set afterwards.
///
/// The [`NonZeroU64`] hash is calculated by the function [`crate::calc_native_fn_hash`].
/// The [`NonZeroU64`] hash is calculated by the function [`calc_native_fn_hash`][crate::calc_native_fn_hash].
#[inline(always)]
pub(crate) fn get_qualified_var(
&self,
@@ -408,7 +406,7 @@ impl Module {
})
}
/// Set a script-defined function into the module.
/// 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.
#[cfg(not(feature = "no_function"))]
@@ -437,7 +435,7 @@ impl Module {
hash_script
}
/// Get a script-defined function in the module based on name and number of parameters.
/// Get a script-defined function in the [`Module`] based on name and number of parameters.
#[cfg(not(feature = "no_function"))]
#[inline(always)]
pub fn get_script_fn(
@@ -465,10 +463,10 @@ impl Module {
/// Get a mutable reference to the underlying [`HashMap`] of sub-modules.
///
/// ## Warning
/// # WARNING
///
/// By taking a mutable reference, it is assumed that some sub-modules will be modified.
/// Thus the module is automatically set to be non-indexed.
/// Thus the [`Module`] is automatically set to be non-indexed.
#[cfg(not(feature = "no_module"))]
#[inline(always)]
pub(crate) fn sub_modules_mut(&mut self) -> &mut HashMap<ImmutableString, Shared<Module>> {
@@ -482,7 +480,7 @@ impl Module {
&mut self.modules
}
/// Does a sub-module exist in the module?
/// Does a sub-module exist in the [`Module`]?
///
/// # Example
///
@@ -499,7 +497,7 @@ impl Module {
self.modules.contains_key(name)
}
/// Get a sub-module.
/// Get a sub-module in the [`Module`].
///
/// # Example
///
@@ -516,7 +514,7 @@ impl Module {
self.modules.get(name).map(|m| m.as_ref())
}
/// Set a sub-module into the module.
/// Set a sub-module into the [`Module`].
///
/// If there is an existing sub-module of the same name, it is replaced.
///
@@ -541,9 +539,9 @@ impl Module {
self
}
/// Does the particular Rust function exist in the module?
/// Does the particular Rust function exist in the [`Module`]?
///
/// The [`NonZeroU64`] hash is calculated by the function [`crate::calc_native_fn_hash`].
/// The [`NonZeroU64`] hash is calculated by the function [`calc_native_fn_hash`][crate::calc_native_fn_hash].
/// It is also returned by the `set_fn_XXX` calls.
///
/// # Example
@@ -569,12 +567,17 @@ impl Module {
/// Update the metadata (parameter names/types and return type) of a registered function.
///
/// The [`NonZeroU64`] hash is calculated either by the function [`crate::calc_native_fn_hash`] or
/// the function [`crate::calc_script_fn_hash`].
/// The [`NonZeroU64`] hash is calculated either by the function
/// [`calc_native_fn_hash`][crate::calc_native_fn_hash] or the function
/// [`calc_script_fn_hash`][crate::calc_script_fn_hash].
///
/// ## Parameter Names and Types
///
/// Each parameter name/type pair should be a single string of the format: `var_name: type`.
///
/// The last entry in the list should be the return type of the function.
/// ## 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<'a>(
&mut self,
@@ -589,8 +592,9 @@ impl Module {
/// Update the namespace of a registered function.
///
/// The [`NonZeroU64`] hash is calculated either by the function [`crate::calc_native_fn_hash`] or
/// the function [`crate::calc_script_fn_hash`].
/// The [`NonZeroU64`] hash is calculated either by the function
/// [`calc_native_fn_hash`][crate::calc_native_fn_hash] or the function
/// [`calc_script_fn_hash`][crate::calc_script_fn_hash].
pub fn update_fn_namespace(
&mut self,
hash_fn: NonZeroU64,
@@ -603,11 +607,11 @@ impl Module {
self
}
/// Set a Rust function into the module, returning a hash key.
/// 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
/// # WARNING - Low Level API
///
/// This function is very low level.
pub fn set_fn(
@@ -660,7 +664,7 @@ impl Module {
/// Set a Rust function taking a reference to the scripting [`Engine`][crate::Engine],
/// the current set of functions, plus a list of mutable [`Dynamic`] references
/// into the module, returning a hash key.
/// into the [`Module`], returning a hash key.
///
/// Use this to register a built-in function which must reference settings on the scripting
/// [`Engine`][crate::Engine] (e.g. to prevent growing an array beyond the allowed maximum size),
@@ -668,13 +672,13 @@ impl Module {
///
/// If there is a similar existing Rust function, it is replaced.
///
/// ## WARNING - Low Level API
/// # 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`],
/// Arguments are simply passed in as a mutable array of [`&mut Dynamic`][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.
@@ -746,7 +750,7 @@ impl Module {
)
}
/// Set a Rust function taking no parameters into the module, returning a hash key.
/// 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.
///
@@ -781,7 +785,7 @@ impl Module {
)
}
/// Set a Rust function taking one parameter into the module, returning a hash key.
/// 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.
///
@@ -818,7 +822,7 @@ impl Module {
)
}
/// Set a Rust function taking one mutable parameter into the module, returning a hash key.
/// 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.
///
@@ -890,7 +894,7 @@ impl Module {
)
}
/// Set a Rust function taking two parameters into the module, returning a hash key.
/// 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.
///
@@ -932,7 +936,7 @@ impl Module {
)
}
/// Set a Rust function taking two parameters (the first one mutable) into the module,
/// 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.
@@ -979,7 +983,7 @@ impl Module {
)
}
/// Set a Rust setter function taking two parameters (the first one mutable) into the module,
/// Set a Rust setter function taking two parameters (the first one mutable) into the [`Module`],
/// returning a hash key.
/// This function is automatically exposed to the global namespace.
///
@@ -1015,7 +1019,7 @@ impl Module {
)
}
/// Set a Rust index getter taking two parameters (the first one mutable) into the module,
/// Set a Rust index getter taking two parameters (the first one mutable) into the [`Module`],
/// returning a hash key.
/// This function is automatically exposed to the global namespace.
///
@@ -1064,7 +1068,7 @@ impl Module {
self.set_fn_2_mut(crate::engine::FN_IDX_GET, FnNamespace::Global, func)
}
/// Set a Rust function taking three parameters into the module, returning a hash key.
/// 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.
///
@@ -1112,7 +1116,7 @@ impl Module {
)
}
/// Set a Rust function taking three parameters (the first one mutable) into the module,
/// 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.
@@ -1165,7 +1169,7 @@ impl Module {
)
}
/// Set a Rust index setter taking three parameters (the first one mutable) into the module,
/// Set a Rust index setter taking three parameters (the first one mutable) into the [`Module`],
/// returning a hash key.
/// This function is automatically exposed to the global namespace.
///
@@ -1276,7 +1280,7 @@ impl Module {
)
}
/// Set a Rust function taking four parameters into the module, returning a hash key.
/// 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.
///
@@ -1331,7 +1335,7 @@ impl Module {
)
}
/// Set a Rust function taking four parameters (the first one mutable) into the module,
/// 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.
@@ -1393,7 +1397,7 @@ impl Module {
/// Get a Rust function.
///
/// The [`NonZeroU64`] hash is calculated by the function [`crate::calc_native_fn_hash`].
/// The [`NonZeroU64`] hash is calculated by the function [`calc_native_fn_hash`][crate::calc_native_fn_hash].
/// It is also returned by the `set_fn_XXX` calls.
#[inline(always)]
pub(crate) fn get_fn(
@@ -1410,9 +1414,10 @@ impl Module {
})
}
/// Does the particular namespace-qualified function exist in the module?
/// Does the particular namespace-qualified function exist in the [`Module`]?
///
/// The [`NonZeroU64`] hash is calculated by the function [`crate::calc_native_fn_hash`] and must match
/// The [`NonZeroU64`] hash is calculated by the function
/// [`calc_native_fn_hash`][crate::calc_native_fn_hash] and must match
/// the hash calculated by [`build_index`][Module::build_index].
#[inline(always)]
pub fn contains_qualified_fn(&self, hash_fn: NonZeroU64) -> bool {
@@ -1421,7 +1426,8 @@ impl Module {
/// Get a namespace-qualified function.
///
/// The [`NonZeroU64`] hash is calculated by the function [`crate::calc_native_fn_hash`] and must match
/// The [`NonZeroU64`] hash is calculated by the function
/// [`calc_native_fn_hash`][crate::calc_native_fn_hash] and must match
/// the hash calculated by [`build_index`][Module::build_index].
#[inline(always)]
pub(crate) fn get_qualified_fn(
@@ -1431,8 +1437,8 @@ impl Module {
self.all_functions.get(&hash_qualified_fn)
}
/// Combine another module into this module.
/// The other module is consumed to merge into this module.
/// Combine another [`Module`] into this [`Module`].
/// The other [`Module`] is _consumed_ to merge into this [`Module`].
#[inline]
pub fn combine(&mut self, other: Self) -> &mut Self {
self.modules.extend(other.modules.into_iter());
@@ -1446,9 +1452,9 @@ impl Module {
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.
/// 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.
#[inline]
pub fn combine_flatten(&mut self, other: Self) -> &mut Self {
other.modules.into_iter().for_each(|(_, m)| {
@@ -1464,8 +1470,8 @@ impl Module {
self
}
/// Poly-fill this module with another module.
/// Only items not existing in this module are added.
/// Polyfill this [`Module`] with another [`Module`].
/// Only items not existing in this [`Module`] are added.
#[inline]
pub fn fill_with(&mut self, other: &Self) -> &mut Self {
other.modules.iter().for_each(|(k, v)| {
@@ -1491,13 +1497,13 @@ impl Module {
self
}
/// Merge another module into this module.
/// Merge another [`Module`] into this [`Module`].
#[inline(always)]
pub fn merge(&mut self, other: &Self) -> &mut Self {
self.merge_filtered(other, &mut |_, _, _, _, _| true)
}
/// Merge another module into this module based on a filter predicate.
/// Merge another [`Module`] into this [`Module`] based on a filter predicate.
pub(crate) fn merge_filtered(
&mut self,
other: &Self,
@@ -1583,7 +1589,7 @@ impl Module {
self
}
/// Get the number of variables, functions and type iterators in the module.
/// Get the number of variables, functions and type iterators in the [`Module`].
#[inline(always)]
pub fn count(&self) -> (usize, usize, usize) {
(
@@ -1593,19 +1599,19 @@ impl Module {
)
}
/// Get an iterator to the sub-modules in the module.
/// Get an iterator to the sub-modules in the [`Module`].
#[inline(always)]
pub fn iter_sub_modules(&self) -> impl Iterator<Item = (&str, Shared<Module>)> {
self.modules.iter().map(|(k, m)| (k.as_str(), m.clone()))
}
/// Get an iterator to the variables in the module.
/// Get an iterator to the variables in the [`Module`].
#[inline(always)]
pub fn iter_var(&self) -> impl Iterator<Item = (&str, &Dynamic)> {
self.variables.iter().map(|(k, v)| (k.as_str(), v))
}
/// Get an iterator to the functions in the module.
/// Get an iterator to the functions in the [`Module`].
#[cfg(not(feature = "no_optimize"))]
#[cfg(not(feature = "no_function"))]
#[inline(always)]
@@ -1613,7 +1619,7 @@ impl Module {
self.functions.values()
}
/// Get an iterator over all script-defined functions in the module.
/// Get an iterator over all script-defined functions in the [`Module`].
///
/// Function metadata includes:
/// 1) Namespace ([`FnNamespace::Global`] or [`FnNamespace::Internal`]).
@@ -1646,7 +1652,7 @@ impl Module {
)
}
/// Get an iterator over all script-defined functions in the module.
/// Get an iterator over all script-defined functions in the [`Module`].
///
/// Function metadata includes:
/// 1) Namespace ([`FnNamespace::Global`] or [`FnNamespace::Internal`]).
@@ -1670,7 +1676,7 @@ impl Module {
)
}
/// Get an iterator over all script-defined functions in the module.
/// Get an iterator over all script-defined functions in the [`Module`].
///
/// Function metadata includes:
/// 1) Namespace ([`FnNamespace::Global`] or [`FnNamespace::Internal`]).
@@ -1688,11 +1694,11 @@ impl Module {
self.iter_script_fn()
}
/// Create a new module by evaluating an [`AST`][crate::AST].
/// Create a new [`Module`] by evaluating an [`AST`][crate::AST].
///
/// The entire [`AST`][crate::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.
/// defined in the [`Module`], are _merged_ into a _unified_ namespace before each call.
/// Therefore, all functions will be found.
///
/// # Example
@@ -1765,10 +1771,10 @@ impl Module {
Ok(module)
}
/// Scan through all the sub-modules in the module and build a hash index of all
/// 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.
/// If the [`Module`] is already indexed, this method has no effect.
pub fn build_index(&mut self) -> &mut Self {
// Collect a particular module.
fn index_module<'a>(
@@ -1886,14 +1892,14 @@ impl Module {
self.type_iterators.contains_key(&id)
}
/// Set a type iterator into the module.
/// Set a type iterator into the [`Module`].
pub fn set_iter(&mut self, typ: TypeId, func: IteratorFn) -> &mut Self {
self.type_iterators.insert(typ, func);
self.indexed = false;
self
}
/// Set a type iterator into the module.
/// Set a type iterator into the [`Module`].
pub fn set_iterable<T>(&mut self) -> &mut Self
where
T: Variant + Clone + IntoIterator,
@@ -1904,7 +1910,7 @@ impl Module {
})
}
/// Set an iterator type into the module as a type iterator.
/// Set an iterator type into the [`Module`] as a type iterator.
pub fn set_iterator<T>(&mut self) -> &mut Self
where
T: Variant + Clone + Iterator,
@@ -1934,7 +1940,7 @@ impl Module {
/// A [`StaticVec`] is used because most namespace-qualified access contains only one level,
/// and it is wasteful to always allocate a [`Vec`] with one element.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Clone, Eq, PartialEq, Default, Hash)]
@@ -2018,10 +2024,9 @@ impl NamespaceRef {
}
}
/// Re-export module resolver trait.
#[cfg(not(feature = "no_module"))]
pub use resolvers::ModuleResolver;
/// Re-export module resolvers.
/// Module containing all built-in [module resolvers][ModuleResolver].
#[cfg(not(feature = "no_module"))]
pub mod resolvers;