spo_rhai/packages/
mod.rs

1//! Module containing all built-in _packages_ available to Rhai, plus facilities to define custom packages.
2
3use crate::{Engine, Module, SharedModule};
4
5pub(crate) mod arithmetic;
6pub(crate) mod array_basic;
7pub(crate) mod bit_field;
8pub(crate) mod blob_basic;
9pub(crate) mod debugging;
10pub(crate) mod fn_basic;
11pub(crate) mod iter_basic;
12pub(crate) mod lang_core;
13pub(crate) mod logic;
14pub(crate) mod map_basic;
15pub(crate) mod math_basic;
16pub(crate) mod pkg_core;
17pub(crate) mod pkg_std;
18pub(crate) mod string_basic;
19pub(crate) mod string_more;
20pub(crate) mod time_basic;
21
22pub use arithmetic::ArithmeticPackage;
23#[cfg(not(feature = "no_index"))]
24pub use array_basic::BasicArrayPackage;
25pub use bit_field::BitFieldPackage;
26#[cfg(not(feature = "no_index"))]
27pub use blob_basic::BasicBlobPackage;
28#[cfg(feature = "debugging")]
29pub use debugging::DebuggingPackage;
30pub use fn_basic::BasicFnPackage;
31pub use iter_basic::BasicIteratorPackage;
32pub use lang_core::LanguageCorePackage;
33pub use logic::LogicPackage;
34#[cfg(not(feature = "no_object"))]
35pub use map_basic::BasicMapPackage;
36pub use math_basic::BasicMathPackage;
37pub use pkg_core::CorePackage;
38pub use pkg_std::StandardPackage;
39pub use string_basic::BasicStringPackage;
40pub use string_more::MoreStringPackage;
41#[cfg(not(feature = "no_time"))]
42pub use time_basic::BasicTimePackage;
43
44/// Trait that all packages must implement.
45pub trait Package {
46    /// Initialize the package.
47    /// Functions should be registered into `module` here.
48    #[cold]
49    fn init(module: &mut Module);
50
51    /// Initialize the package with an [`Engine`].
52    ///
53    /// Perform tasks such as registering custom operators/syntax.
54    #[cold]
55    #[inline]
56    #[allow(unused_variables)]
57    fn init_engine(engine: &mut Engine) {}
58
59    /// Register the package with an [`Engine`].
60    ///
61    /// # Example
62    ///
63    /// ```rust
64    /// # use rhai::Engine;
65    /// # use rhai::packages::{Package, CorePackage};
66    /// let mut engine = Engine::new_raw();
67    /// let package = CorePackage::new();
68    ///
69    /// package.register_into_engine(&mut engine);
70    /// ```
71    #[cold]
72    #[inline]
73    fn register_into_engine(&self, engine: &mut Engine) -> &Self {
74        Self::init_engine(engine);
75        engine.register_global_module(self.as_shared_module());
76        self
77    }
78
79    /// Register the package with an [`Engine`] under a static namespace.
80    ///
81    /// # Example
82    ///
83    /// ```rust
84    /// # use rhai::Engine;
85    /// # use rhai::packages::{Package, CorePackage};
86    /// let mut engine = Engine::new_raw();
87    /// let package = CorePackage::new();
88    ///
89    /// package.register_into_engine_as(&mut engine, "core");
90    /// ```
91    #[cfg(not(feature = "no_module"))]
92    #[cold]
93    #[inline]
94    fn register_into_engine_as(&self, engine: &mut Engine, name: &str) -> &Self {
95        Self::init_engine(engine);
96        engine.register_static_module(name, self.as_shared_module());
97        self
98    }
99
100    /// Get a reference to a shared module from this package.
101    #[must_use]
102    fn as_shared_module(&self) -> SharedModule;
103}
104
105/// Macro that makes it easy to define a _package_ (which is basically a shared [module][Module])
106/// and register functions into it.
107///
108/// Functions can be added to the package using [`Module::set_native_fn`].
109///
110/// # Example
111///
112/// Define a package named `MyPackage` with a single function named `my_add`:
113///
114/// ```
115/// use rhai::{Dynamic, EvalAltResult};
116/// use rhai::def_package;
117///
118/// fn add(x: i64, y: i64) -> Result<i64, Box<EvalAltResult>> { Ok(x + y) }
119///
120/// def_package! {
121///     /// My super-duper package.
122///     pub MyPackage(module) {
123///         // Load a native Rust function.
124///         module.set_native_fn("my_add", add);
125///     }
126/// }
127/// ```
128#[macro_export]
129macro_rules! def_package {
130    ($($(#[$outer:meta])* $mod:vis $package:ident($lib:ident)
131                $( : $($(#[$base_meta:meta])* $base_pkg:ty),+ )?
132                $block:block
133                $( |> | $engine:ident | $init_engine:block )?
134    )+) => { $(
135        $(#[$outer])*
136        $mod struct $package($crate::Shared<$crate::Module>);
137
138        impl $crate::packages::Package for $package {
139            #[inline(always)]
140            fn as_shared_module(&self) -> $crate::Shared<$crate::Module> {
141                self.0.clone()
142            }
143            fn init($lib: &mut $crate::Module) {
144                $($(
145                    $(#[$base_meta])* { <$base_pkg>::init($lib); }
146                )*)*
147
148                $block
149            }
150            fn init_engine(_engine: &mut $crate::Engine) {
151                $($(
152                    $(#[$base_meta])* { <$base_pkg>::init_engine(_engine); }
153                )*)*
154
155                $(
156                    let $engine = _engine;
157                    $init_engine
158                )*
159            }
160        }
161
162        impl Default for $package {
163            #[inline(always)]
164            #[must_use]
165            fn default() -> Self {
166                Self::new()
167            }
168        }
169
170        impl $package {
171            #[doc=concat!("Create a new `", stringify!($package), "`")]
172            #[inline]
173            #[must_use]
174            pub fn new() -> Self {
175                let mut module = $crate::Module::new();
176                <Self as $crate::packages::Package>::init(&mut module);
177                module.build_index();
178                Self(module.into())
179            }
180        }
181    )* };
182    ($($(#[$outer:meta])* $root:ident :: $package:ident => | $lib:ident | $block:block)+) => { $(
183        $(#[$outer])*
184        /// # Deprecated
185        ///
186        /// This old syntax of `def_package!` is deprecated. Use the new syntax instead.
187        ///
188        /// This syntax will be removed in the next major version.
189        #[deprecated(since = "1.5.0", note = "this is an old syntax of `def_package!` and is deprecated; use the new syntax of `def_package!` instead")]
190        pub struct $package($root::Shared<$root::Module>);
191
192        impl $root::packages::Package for $package {
193            fn as_shared_module(&self) -> $root::Shared<$root::Module> {
194                self.0.clone()
195            }
196            fn init($lib: &mut $root::Module) {
197                $block
198            }
199        }
200
201        impl Default for $package {
202            #[inline(always)]
203            #[must_use]
204            fn default() -> Self {
205                Self::new()
206            }
207        }
208
209        impl $package {
210            #[inline]
211            #[must_use]
212            pub fn new() -> Self {
213                let mut module = $root::Module::new();
214                <Self as $root::packages::Package>::init(&mut module);
215                module.build_index();
216                Self(module.into())
217            }
218        }
219    )* };
220    ($root:ident : $package:ident : $comment:expr , $lib:ident , $block:stmt) => {
221        #[doc=$comment]
222        ///
223        /// # Deprecated
224        ///
225        /// This old syntax of `def_package!` is deprecated. Use the new syntax instead.
226        ///
227        /// This syntax will be removed in the next major version.
228        #[deprecated(since = "1.4.0", note = "this is an old syntax of `def_package!` and is deprecated; use the new syntax of `def_package!` instead")]
229        pub struct $package($root::Shared<$root::Module>);
230
231        impl $root::packages::Package for $package {
232            fn as_shared_module(&self) -> $root::Shared<$root::Module> {
233                #[allow(deprecated)]
234                self.0.clone()
235            }
236            fn init($lib: &mut $root::Module) {
237                $block
238            }
239        }
240
241        impl Default for $package {
242            #[inline(always)]
243            #[must_use]
244            fn default() -> Self {
245                Self::new()
246            }
247        }
248
249        impl $package {
250            #[inline]
251            #[must_use]
252            pub fn new() -> Self {
253                let mut module = $root::Module::new();
254                <Self as $root::packages::Package>::init(&mut module);
255                module.build_index();
256                Self(module.into())
257            }
258        }
259    };
260}
spo_rhai/packages/mod.rs

spo_rhai/packages/
mod.rs
