Add internals feature.

Cargo.toml

@@ -33,6 +33,7 @@ no_index = []       # no arrays and indexing
 no_object = []      # no custom objects
 no_function = []    # no script-defined functions
 no_module = []      # no modules
+internals = []      # expose internal data structures
 
 # compiling for no-std
 no_std = [ "num-traits/libm", "hashbrown", "core-error", "libm", "ahash" ]

RELEASES.md

@@ -13,6 +13,7 @@ Enhancements
 ------------
 
 * [The Rhai Book](https://schungx.github.io/rhai) is online.  Most content in the original `README` was transferred to the Book.
+* New feature `internals` to expose internal data structures (e.g. the AST nodes).
 
 
 Version 0.15.1

doc/src/links.md

@@ -10,8 +10,8 @@
 [`no_function`]: {{rootUrl}}/start/features.md
 [`no_module`]: {{rootUrl}}/start/features.md
 [`no_std`]: {{rootUrl}}/start/features.md
-
 [`no-std`]: {{rootUrl}}/start/features.md
+[`internals`]: {{rootUrl}}/start/features.md
 
 [minimal builds]: {{rootUrl}}/start/builds/minimal.md
 [WASM]: {{rootUrl}}/start/builds/wasm.md

doc/src/start/builds/wasm.md

@@ -47,7 +47,8 @@ are typically used for a WASM build:
 
 The following features are typically _not_ used because they don't make sense in a WASM build:
 
-|  Feature   | Why unnecessary                 |
+|    Feature    | Why unnecessary                                                    |
-| :--------: | ------------------------------- |
+| :-----------: | ------------------------------------------------------------------ |
-|  [`sync`]  | WASM is single-threaded.        |
+|   [`sync`]    | WASM is single-threaded.                                           |
-| [`no_std`] | `std` lib works fine with WASM. |
+|  [`no_std`]   | `std` lib works fine with WASM.                                    |
+| [`internals`] | WASM usually doesn't need to access Rhai internal data structures. |

doc/src/start/features.md

@@ -24,6 +24,7 @@ more control over what a script can (or cannot) do.
 | `no_function` | Disable script-defined [functions].                                                                                                                                                                        |
 | `no_module`   | Disable loading external [modules].                                                                                                                                                                        |
 | `no_std`      | Build for `no-std`. Notice that additional dependencies will be pulled in to replace `std` features.                                                                                                       |
+| `internals`   | Expose internal data structures (e.g. `AST` nodes). Beware that Rhai internals are volatile and may change from version to version.                                                                        |
 
 
 Example

src/lib.rs

@@ -63,8 +63,9 @@
 //! | `only_i64`    | Set the system integer type to `i64` and disable all other integer types. `INT` is set to `i64`.                                  |
 //! | `no_std`      | Build for `no-std`. Notice that additional dependencies will be pulled in to replace `std` features.                              |
 //! | `sync`        | Restrict all values types to those that are `Send + Sync`. Under this feature, `Engine`, `Scope` and `AST` are all `Send + Sync`. |
+//! | `internals`   | Expose internal data structures (beware they may be volatile from version to version).                                            |
 //!
-//! See [The Rhai Book](https://schungx.github.io/rhai/) for details on the Rhai script engine and language.
+//! See [The Rhai Book](https://schungx.github.io/rhai) for details on the Rhai script engine and language.
 
 #![cfg_attr(feature = "no_std", no_std)]
 
@@ -125,3 +126,23 @@ pub mod module_resolvers {
 
 #[cfg(not(feature = "no_optimize"))]
 pub use optimize::OptimizationLevel;
+
+// Expose internal data structures.
+
+#[cfg(feature = "internals")]
+pub use token::Token;
+
+#[cfg(feature = "internals")]
+pub use parser::Expr;
+
+#[cfg(feature = "internals")]
+pub use parser::Stmt;
+
+#[cfg(feature = "internals")]
+pub use module::ModuleRef;
+
+#[cfg(feature = "internals")]
+pub use utils::StaticVec;
+
+#[cfg(feature = "internals")]
+pub use parser::ReturnType;

src/parser.rs

@@ -65,20 +65,34 @@ impl AST {
     }
 
     /// Get the statements.
+    #[cfg(not(feature = "internals"))]
     pub(crate) fn statements(&self) -> &Vec<Stmt> {
         &self.0
     }
 
+    /// Get the statements.
+    #[cfg(feature = "internals")]
+    pub fn statements(&self) -> &Vec<Stmt> {
+        &self.0
+    }
+
     /// Get a mutable reference to the statements.
     pub(crate) fn statements_mut(&mut self) -> &mut Vec<Stmt> {
         &mut self.0
     }
 
-    /// Get the script-defined functions.
+    /// Get the internal `Module` containing all script-defined functions.
+    #[cfg(not(feature = "internals"))]
     pub(crate) fn lib(&self) -> &Module {
         &self.1
     }
 
+    /// Get the internal `Module` containing all script-defined functions.
+    #[cfg(feature = "internals")]
+    pub fn lib(&self) -> &Module {
+        &self.1
+    }
+
     /// Merge two `AST` into one.  Both `AST`'s are untouched and a new, merged, version
     /// is returned.
     ///