New packages API.

CHANGELOG.md

@@ -44,6 +44,11 @@ New features
 
 * A new volatile API, `Engine::build_type`, enables registration of the entire API of a custom type in one go, provided that the custom type implements the `CustomType` trait (which uses `TypeBuilder` to register the API functions).
 
+### Simpler Package API
+
+* It is now easier to register packages via the `Package::register_into_engine` and `Package::register_into_engine_as` API.
+* Defining a custom package with base packages is also much easier with a new syntax - put the new base packages after a colon.
+
 Enhancements
 ------------
 

benches/engine.rs

@@ -23,7 +23,7 @@ fn bench_engine_new_raw_core(bench: &mut Bencher) {
 
     bench.iter(|| {
         let mut engine = Engine::new_raw();
-        engine.register_global_module(package.as_shared_module());
+        package.register_into_engine(&mut engine);
     });
 }
 

src/packages/mod.rs

@@ -1,6 +1,6 @@
 //! Module containing all built-in _packages_ available to Rhai, plus facilities to define custom packages.
 
-use crate::{Module, Shared};
+use crate::{Engine, Module, Shared};
 
 pub(crate) mod arithmetic;
 pub(crate) mod array_basic;
@@ -47,6 +47,48 @@ pub trait Package {
     /// Functions should be registered into `module` here.
     fn init(module: &mut Module);
 
+    /// Initialize the package with an [`Engine`].
+    ///
+    /// Perform tasks such as registering custom operators/syntax.
+    #[allow(unused_variables)]
+    fn init_engine(engine: &mut Engine) {}
+
+    /// Register the package with an [`Engine`].
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use rhai::Engine;
+    /// # use rhai::packages::{Package, CorePackage};
+    /// let mut engine = Engine::new_raw();
+    /// let package = CorePackage::new();
+    ///
+    /// package.register_into_engine(&mut engine);
+    /// ```
+    fn register_into_engine(&self, engine: &mut Engine) -> &Self {
+        Self::init_engine(engine);
+        engine.register_global_module(self.as_shared_module());
+        self
+    }
+
+    /// Register the package with an [`Engine`] under a static namespace.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use rhai::Engine;
+    /// # use rhai::packages::{Package, CorePackage};
+    /// let mut engine = Engine::new_raw();
+    /// let package = CorePackage::new();
+    ///
+    /// package.register_into_engine_as(&mut engine, "core");
+    /// ```
+    fn register_into_engine_as(&self, engine: &mut Engine, name: &str) -> &Self {
+        Self::init_engine(engine);
+        engine.register_static_module(name, self.as_shared_module());
+        self
+    }
+
     /// Get a reference to a shared module from this package.
     #[must_use]
     fn as_shared_module(&self) -> Shared<Module>;
@@ -70,27 +112,49 @@ pub trait Package {
 /// def_package! {
 ///     /// My super-duper package.
 ///     pub MyPackage(module) {
-///         // Load a binary function with all value parameters.
+///         // Load a native Rust function.
 ///         module.set_native_fn("my_add", add);
 ///     }
 /// }
 /// ```
 #[macro_export]
 macro_rules! def_package {
-    ($($(#[$outer:meta])* $mod:vis $package:ident($lib:ident) $block:block)+) => { $(
+    ($($(#[$outer:meta])* $mod:vis $package:ident($lib:ident)
+                $( : $($(#[$base_meta:meta])* $base_pkg:ty),+ )?
+                $block:block
+                $( |> | $engine:ident | $init_engine:block )?
+    )+) => { $(
         $(#[$outer])*
         $mod struct $package($crate::Shared<$crate::Module>);
 
         impl $crate::packages::Package for $package {
+            #[inline(always)]
             fn as_shared_module(&self) -> $crate::Shared<$crate::Module> {
                 self.0.clone()
             }
+            #[inline]
             fn init($lib: &mut $crate::Module) {
+                $($(
+                    $(#[$base_meta])* { <$base_pkg>::init($lib); }
+                )*)*
+
                 $block
             }
+            #[inline]
+            fn init_engine(_engine: &mut $crate::Engine) {
+                $($(
+                    $(#[$base_meta])* { <$base_pkg>::init_engine(_engine); }
+                )*)*
+
+                $(
+                    let $engine = _engine;
+                    $init_engine
+                )*
+            }
         }
 
         impl Default for $package {
+            #[inline(always)]
             fn default() -> Self {
                 Self::new()
             }
@@ -98,6 +162,7 @@ macro_rules! def_package {
 
         impl $package {
             #[doc=concat!("Create a new `", stringify!($package), "`")]
+            #[inline]
             #[must_use]
             pub fn new() -> Self {
                 let mut module = $crate::Module::new();

src/packages/pkg_core.rs

@@ -1,6 +1,7 @@
 #[cfg(feature = "no_std")]
 use std::prelude::v1::*;
 
+use super::*;
 use crate::def_package;
 
 def_package! {
@@ -14,15 +15,14 @@ def_package! {
     /// * [`BasicIteratorPackage`][super::BasicIteratorPackage]
     /// * [`BasicFnPackage`][super::BasicFnPackage]
     /// * [`DebuggingPackage`][super::DebuggingPackage]
-    pub CorePackage(lib) {
+    pub CorePackage(lib) :
+            LanguageCorePackage,
+            ArithmeticPackage,
+            BasicStringPackage,
+            BasicIteratorPackage,
+            BasicFnPackage,
+            #[cfg(feature = "debugging")] DebuggingPackage
+        {
         lib.standard = true;
-
-        super::LanguageCorePackage::init(lib);
-        super::ArithmeticPackage::init(lib);
-        super::BasicStringPackage::init(lib);
-        super::BasicIteratorPackage::init(lib);
-        super::BasicFnPackage::init(lib);
-        #[cfg(feature = "debugging")]
-        super::DebuggingPackage::init(lib);
     }
 }

src/packages/pkg_std.rs

@@ -1,6 +1,7 @@
 #[cfg(feature = "no_std")]
 use std::prelude::v1::*;
 
+use super::*;
 use crate::def_package;
 
 def_package! {
@@ -17,21 +18,17 @@ def_package! {
     /// * [`BasicMapPackage`][super::BasicMapPackage]
     /// * [`BasicTimePackage`][super::BasicTimePackage]
     /// * [`MoreStringPackage`][super::MoreStringPackage]
-    pub StandardPackage(lib) {
+    pub StandardPackage(lib) :
+            CorePackage,
+            BitFieldPackage,
+            LogicPackage,
+            BasicMathPackage,
+            #[cfg(not(feature = "no_index"))] BasicArrayPackage,
+            #[cfg(not(feature = "no_index"))] BasicBlobPackage,
+            #[cfg(not(feature = "no_object"))] BasicMapPackage,
+            #[cfg(not(feature = "no_std"))] BasicTimePackage,
+            MoreStringPackage
+    {
         lib.standard = true;
-
-        super::CorePackage::init(lib);
-        super::BitFieldPackage::init(lib);
-        super::LogicPackage::init(lib);
-        super::BasicMathPackage::init(lib);
-        #[cfg(not(feature = "no_index"))]
-        super::BasicArrayPackage::init(lib);
-        #[cfg(not(feature = "no_index"))]
-        super::BasicBlobPackage::init(lib);
-        #[cfg(not(feature = "no_object"))]
-        super::BasicMapPackage::init(lib);
-        #[cfg(not(feature = "no_std"))]
-        super::BasicTimePackage::init(lib);
-        super::MoreStringPackage::init(lib);
     }
 }

tests/packages.rs

@@ -1,18 +1,27 @@
-use rhai::packages::{Package, StandardPackage};
+use rhai::packages::{Package, StandardPackage as SSS};
-use rhai::{Engine, EvalAltResult, Module, Scope, INT};
+use rhai::{def_package, Engine, EvalAltResult, Module, Scope, INT};
+
+def_package! {
+    /// My custom package.
+    MyPackage(m) : SSS {
+        m.set_native_fn("hello", |x: INT| Ok(x + 1));
+        m.set_native_fn("@", |x: INT, y: INT| Ok(x * x + y * y));
+    } |> |engine| {
+        engine.register_custom_operator("@", 160).unwrap();
+    }
+}
 
 #[test]
 fn test_packages() -> Result<(), Box<EvalAltResult>> {
-    let engine = Engine::new();
+    let pkg = MyPackage::new();
-    let ast = engine.compile("x")?;
-    let std_pkg = StandardPackage::new();
 
     let make_call = |x: INT| -> Result<INT, Box<EvalAltResult>> {
         // Create a raw Engine - extremely cheap.
         let mut engine = Engine::new_raw();
 
         // Register packages - cheap.
-        engine.register_global_module(std_pkg.as_shared_module());
+        pkg.register_into_engine(&mut engine);
+        pkg.register_into_engine_as(&mut engine, "foo");
 
         // Create custom scope - cheap.
         let mut scope = Scope::new();
@@ -21,10 +30,10 @@ fn test_packages() -> Result<(), Box<EvalAltResult>> {
         scope.push("x", x);
 
         // Evaluate script.
-        engine.eval_ast_with_scope::<INT>(&mut scope, &ast)
+        engine.eval_with_scope::<INT>(&mut scope, "hello(x) @ foo::hello(x)")
     };
 
-    assert_eq!(make_call(42)?, 42);
+    assert_eq!(make_call(42)?, 3698);
 
     Ok(())
 }