Refine documentation and comments.

README.md

@@ -78,7 +78,7 @@ Running `mdbook build` builds it.
 Playground
 ----------
 
-An [Online Playground](https://alvinhochun.github.io/rhai-demo/) is available with syntax-highlighting editor.
+An [Online Playground](https://rhaiscript.github.io/playground) is available with syntax-highlighting editor.
 Scripts can be evaluated directly from the editor.
 
 

RELEASES.md

@@ -4,6 +4,11 @@ Rhai Release Notes
 Version 0.19.10
 ===============
 
+Bug fixes
+---------
+
+* Bug in `FileModuleResolver::clear_cache_for_path` path mapping fixed.
+
 Breaking changes
 ----------------
 
@@ -15,7 +20,7 @@ Breaking changes
 New features
 ------------
 
-* `Engine::compile_to_self_contained` compiles a script into an `AST` and _eagerly_ resolves all `import` statements with string literal paths. The resolved modules are directly embedded into the `AST`. When the `AST` is later evaluated, `import` statements directly yield the pre-resolved modules without going through the resolution process once again.
+* `Engine::compile_into_self_contained` compiles a script into an `AST` and _eagerly_ resolves all `import` statements with string literal paths. The resolved modules are directly embedded into the `AST`. When the `AST` is later evaluated, `import` statements directly yield the pre-resolved modules without going through the resolution process once again.
 * `AST::walk`, `Stmt::walk` and `Expr::walk` internal API's to recursively walk an `AST`.
 
 Enhancements
@@ -24,6 +29,7 @@ Enhancements
 * Source information is provided when there is an error within a call to a function defined in another module.
 * Source information is provided to the `NativeCallContext` for native Rust functions.
 * `EvalAltResult::clear_position` to clear the position information of an error - useful when only the message is needed and the position doesn't need to be printed out.
+* A new optional function `resolve_ast` is added to the `ModuleResolver` trait for advanced usage.
 
 
 Version 0.19.9

codegen/src/lib.rs

@@ -1,4 +1,4 @@
-//! This crate contains procedural macros to make creating Rhai plugin-modules much easier.
+//! This crate contains procedural macros to make creating Rhai plugin modules much easier.
 //!
 //! # Export an Entire Rust Module to a Rhai `Module`
 //!
@@ -184,7 +184,7 @@ pub fn export_module(
     proc_macro::TokenStream::from(tokens)
 }
 
-/// Macro to generate a Rhai `Module` from a _plugin module_ defined via `#[export_module]`.
+/// Macro to generate a Rhai `Module` from a _plugin module_ defined via [`#[export_module]`][export_module].
 ///
 /// # Usage
 ///
@@ -223,8 +223,8 @@ pub fn exported_module(module_path: proc_macro::TokenStream) -> proc_macro::Toke
 /// Functions and variables in the plugin module overrides any existing similarly-named
 /// functions and variables in the target module.
 ///
-/// This call is intended to be used within the `def_package!` macro to define a custom
+/// This call is intended to be used within the [`def_package!`][crate::def_package] macro to define
-/// package based on a plugin module.
+/// a custom package based on a plugin module.
 ///
 /// All sub-modules, if any, in the plugin module are _flattened_ and their functions/variables
 /// registered at the top level because packages require so.
@@ -269,7 +269,7 @@ pub fn combine_with_exported_module(args: proc_macro::TokenStream) -> proc_macro
     proc_macro::TokenStream::from(tokens)
 }
 
-/// Macro to register a _plugin function_ (defined via `#[export_fn]`) into an `Engine`.
+/// Macro to register a _plugin function_ (defined via [`#[export_fn]`][export_fn]) into an `Engine`.
 ///
 /// # Usage
 ///

src/ast.rs

@@ -295,7 +295,7 @@ impl AST {
     ) -> Option<Shared<crate::module::resolvers::StaticModuleResolver>> {
         self.resolver.clone()
     }
-    /// _(INTERNALS)_ Get the embedded [module resolver][`ModuleResolver`].
+    /// _(INTERNALS)_ Get the embedded [module resolver][crate::ModuleResolver].
     /// Exported under the `internals` feature only.
     #[cfg(not(feature = "no_module"))]
     #[cfg(feature = "internals")]
@@ -318,7 +318,7 @@ impl AST {
     ///
     /// This operation is cheap because functions are shared.
     ///
-    /// Not available under [`no_function`].
+    /// Not available under `no_function`.
     #[cfg(not(feature = "no_function"))]
     #[inline(always)]
     pub fn clone_functions_only(&self) -> Self {
@@ -329,7 +329,7 @@ impl AST {
     ///
     /// This operation is cheap because functions are shared.
     ///
-    /// Not available under [`no_function`].
+    /// Not available under `no_function`.
     #[cfg(not(feature = "no_function"))]
     #[inline(always)]
     pub fn clone_functions_only_filtered(
@@ -614,7 +614,7 @@ impl AST {
     }
     /// Filter out the functions, retaining only some based on a filter predicate.
     ///
-    /// Not available under [`no_function`].
+    /// Not available under `no_function`.
     ///
     /// # Example
     ///
@@ -661,7 +661,7 @@ impl AST {
     }
     /// Iterate through all function definitions.
     ///
-    /// Not available under [`no_function`].
+    /// Not available under `no_function`.
     #[cfg(not(feature = "no_function"))]
     #[inline(always)]
     pub fn iter_functions<'a>(&'a self) -> impl Iterator<Item = ScriptFnMetadata> + 'a {
@@ -671,7 +671,7 @@ impl AST {
     }
     /// Clear all function definitions in the [`AST`].
     ///
-    /// Not available under [`no_function`].
+    /// Not available under `no_function`.
     #[cfg(not(feature = "no_function"))]
     #[inline(always)]
     pub fn clear_functions(&mut self) {

src/dynamic.rs

@@ -266,6 +266,8 @@ impl Dynamic {
         }
     }
     /// Is the value held by this [`Dynamic`] shared?
+    ///
+    /// Always [`false`] under the `no_closure` feature.
     #[inline(always)]
     pub fn is_shared(&self) -> bool {
         match self.0 {

src/module/mod.rs

@@ -221,6 +221,31 @@ impl AsRef<Module> for Module {
     }
 }
 
+impl<M: AsRef<Module>> Add<M> for &Module {
+    type Output = Module;
+
+    fn add(self, rhs: M) -> Self::Output {
+        let mut module = self.clone();
+        module.merge(rhs.as_ref());
+        module
+    }
+}
+
+impl<M: AsRef<Module>> Add<M> for Module {
+    type Output = Self;
+
+    fn add(mut self, rhs: M) -> Self::Output {
+        self.merge(rhs.as_ref());
+        self
+    }
+}
+
+impl<M: Into<Module>> AddAssign<M> for Module {
+    fn add_assign(&mut self, rhs: M) {
+        self.combine(rhs.into());
+    }
+}
+
 impl Module {
     /// Create a new [`Module`].
     ///
@@ -1983,13 +2008,16 @@ impl Module {
 ///
 /// This type is volatile and may change.
 #[derive(Clone, Eq, PartialEq, Default, Hash)]
-pub struct NamespaceRef(Option<NonZeroUsize>, StaticVec<Ident>);
+pub struct NamespaceRef {
+    index: Option<NonZeroUsize>,
+    path: StaticVec<Ident>,
+}
 
 impl fmt::Debug for NamespaceRef {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        fmt::Debug::fmt(&self.1, f)?;
+        fmt::Debug::fmt(&self.path, f)?;
 
-        if let Some(index) = self.0 {
+        if let Some(index) = self.index {
             write!(f, " -> {}", index)
         } else {
             Ok(())
@@ -2001,19 +2029,19 @@ impl Deref for NamespaceRef {
     type Target = StaticVec<Ident>;
 
     fn deref(&self) -> &Self::Target {
-        &self.1
+        &self.path
     }
 }
 
 impl DerefMut for NamespaceRef {
     fn deref_mut(&mut self) -> &mut Self::Target {
-        &mut self.1
+        &mut self.path
     }
 }
 
 impl fmt::Display for NamespaceRef {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        for Ident { name, .. } in self.1.iter() {
+        for Ident { name, .. } in self.path.iter() {
             write!(f, "{}{}", name, Token::DoubleColon.syntax())?;
         }
         Ok(())
@@ -2021,45 +2049,20 @@ impl fmt::Display for NamespaceRef {
 }
 
 impl From<StaticVec<Ident>> for NamespaceRef {
-    fn from(modules: StaticVec<Ident>) -> Self {
+    fn from(path: StaticVec<Ident>) -> Self {
-        Self(None, modules)
+        Self { index: None, path }
-    }
-}
-
-impl<M: AsRef<Module>> Add<M> for &Module {
-    type Output = Module;
-
-    fn add(self, rhs: M) -> Self::Output {
-        let mut module = self.clone();
-        module.merge(rhs.as_ref());
-        module
-    }
-}
-
-impl<M: AsRef<Module>> Add<M> for Module {
-    type Output = Self;
-
-    fn add(mut self, rhs: M) -> Self::Output {
-        self.merge(rhs.as_ref());
-        self
-    }
-}
-
-impl<M: Into<Module>> AddAssign<M> for Module {
-    fn add_assign(&mut self, rhs: M) {
-        self.combine(rhs.into());
     }
 }
 
 impl NamespaceRef {
     /// Get the [`Scope`][crate::Scope] index offset.
     pub(crate) fn index(&self) -> Option<NonZeroUsize> {
-        self.0
+        self.index
     }
     /// Set the [`Scope`][crate::Scope] index offset.
     #[cfg(not(feature = "no_module"))]
     pub(crate) fn set_index(&mut self, index: Option<NonZeroUsize>) {
-        self.0 = index
+        self.index = index
     }
 }
 

src/module/resolvers/collection.rs

@@ -1,7 +1,7 @@
 use crate::stdlib::{boxed::Box, ops::AddAssign, vec::Vec};
 use crate::{Engine, EvalAltResult, Module, ModuleResolver, Position, Shared};
 
-/// [Module] resolution service that holds a collection of [module][Module] resolves,
+/// [Module] resolution service that holds a collection of module resolvers,
 /// to be searched in sequential order.
 ///
 /// # Example

src/module/resolvers/mod.rs

@@ -29,7 +29,7 @@ pub trait ModuleResolver: SendSync {
         pos: Position,
     ) -> Result<Shared<Module>, Box<EvalAltResult>>;
 
-    /// Resolve a module into an `AST` based on a path string.
+    /// Resolve an `AST` based on a path string.
     ///
     /// Returns [`None`] (default) if such resolution is not supported
     /// (e.g. if the module is Rust-based).

src/module/resolvers/stat.rs

@@ -1,7 +1,7 @@
 use crate::stdlib::{boxed::Box, collections::HashMap, ops::AddAssign, string::String};
 use crate::{Engine, EvalAltResult, Module, ModuleResolver, Position, Shared};
 
-/// [Module] resolution service that serves [modules][Module] added into it.
+/// A static [module][Module] resolution service that serves [modules][Module] added into it.
 ///
 /// # Example
 ///

src/packages/mod.rs

@@ -50,7 +50,7 @@ pub trait Package {
     }
 }
 
-/// Macro that makes it easy to define a _package_ (which is basically a shared module)
+/// Macro that makes it easy to define a _package_ (which is basically a shared [module][Module])
 /// and register functions into it.
 ///
 /// Functions can be added to the package using the standard module methods such as
@@ -58,6 +58,8 @@ pub trait Package {
 ///
 /// # Example
 ///
+/// Define a package named `MyPackage` with a single function named `my_add`:
+///
 /// ```
 /// use rhai::{Dynamic, EvalAltResult};
 /// use rhai::def_package;
@@ -70,8 +72,6 @@ pub trait Package {
 ///     lib.set_fn_2("my_add", add);
 /// });
 /// ```
-///
-/// The above defines a package named 'MyPackage' with a single function named 'my_add'.
 #[macro_export]
 macro_rules! def_package {
     ($root:ident : $package:ident : $comment:expr , $lib:ident , $block:stmt) => {