From 83589be58e00bf5fd47f193bbff23cd742856b5c Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Thu, 18 Aug 2022 17:22:56 +0800 Subject: [PATCH] New packages API. --- CHANGELOG.md | 5 +++ benches/engine.rs | 2 +- src/packages/mod.rs | 71 ++++++++++++++++++++++++++++++++++++++-- src/packages/pkg_core.rs | 18 +++++----- src/packages/pkg_std.rs | 27 +++++++-------- tests/packages.rs | 25 +++++++++----- 6 files changed, 112 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 93232d95..fbe3f96b 100644 --- a/CHANGELOG.md +++ b/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 ------------ diff --git a/benches/engine.rs b/benches/engine.rs index 70643a08..d725699a 100644 --- a/benches/engine.rs +++ b/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); }); } diff --git a/src/packages/mod.rs b/src/packages/mod.rs index ef59ae26..c41c721d 100644 --- a/src/packages/mod.rs +++ b/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; @@ -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(); diff --git a/src/packages/pkg_core.rs b/src/packages/pkg_core.rs index 1603bcb8..547274cd 100644 --- a/src/packages/pkg_core.rs +++ b/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); } } diff --git a/src/packages/pkg_std.rs b/src/packages/pkg_std.rs index cd8f29db..e7d4f1ff 100644 --- a/src/packages/pkg_std.rs +++ b/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); } } diff --git a/tests/packages.rs b/tests/packages.rs index 528eaf1d..75537721 100644 --- a/tests/packages.rs +++ b/tests/packages.rs @@ -1,18 +1,27 @@ -use rhai::packages::{Package, StandardPackage}; -use rhai::{Engine, EvalAltResult, Module, Scope, INT}; +use rhai::packages::{Package, StandardPackage as SSS}; +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> { - let engine = Engine::new(); - let ast = engine.compile("x")?; - let std_pkg = StandardPackage::new(); + let pkg = MyPackage::new(); let make_call = |x: INT| -> Result> { // 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> { scope.push("x", x); // Evaluate script. - engine.eval_ast_with_scope::(&mut scope, &ast) + engine.eval_with_scope::(&mut scope, "hello(x) @ foo::hello(x)") }; - assert_eq!(make_call(42)?, 42); + assert_eq!(make_call(42)?, 3698); Ok(()) }