Merge pull request #249 from schungx/master

Finalize 0.19.0.

Cargo.toml

@@ -6,11 +6,11 @@ members = [
 
 [package]
 name = "rhai"
-version = "0.18.3"
+version = "0.19.0"
 edition = "2018"
 authors = ["Jonathan Turner", "Lukáš Hozda", "Stephen Chung", "jhwgh1968"]
 description = "Embedded scripting for Rust"
-homepage = "https://github.com/jonathandturner/rhai"
+homepage = "https://schungx.github.io/rhai"
 repository = "https://github.com/jonathandturner/rhai"
 readme = "README.md"
 license = "MIT OR Apache-2.0"
@@ -27,7 +27,6 @@ smallvec = { version = "1.4.2", default-features = false }
 rhai_codegen = { version = "0.1", path = "codegen" }
 
 [features]
-#default = ["unchecked", "sync", "no_optimize", "no_float", "only_i32", "no_index", "no_object", "no_function", "no_module"]
 default = []
 unchecked = []      # unchecked arithmetic
 sync = []           # restrict to only types that implement Send + Sync

codegen/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 edition = "2018"
 authors = ["jhwgh1968"]
 description = "Proceducral macro support package for Rhai, a scripting language for Rust"
-homepage = "https://github.com/jonathandturner/rhai"
+homepage = "https://schungx.github.io/rhai/plugins/index.html"
 repository = "https://github.com/jonathandturner/rhai"
 license = "MIT OR Apache-2.0"
 

codegen/src/function.rs

@@ -580,7 +580,7 @@ impl ExportedFn {
         );
         quote! {
             pub fn #callable_fn_name() -> CallableFunction {
-                CallableFunction::from_plugin(#token_name())
+                #token_name().into()
             }
         }
     }
@@ -628,7 +628,7 @@ impl ExportedFn {
                         arg_type.span()=> &mut args[0usize].write_lock::<#arg_type>().unwrap());
                     unpack_stmts.push(
                         syn::parse2::<syn::Stmt>(quote! {
-                            let #var: &mut _ = #downcast_span;
+                            let #var = #downcast_span;
                         })
                         .unwrap(),
                     );
@@ -757,7 +757,7 @@ impl ExportedFn {
                 }
 
                 fn is_method_call(&self) -> bool { #is_method_call }
-                fn is_varadic(&self) -> bool { false }
+                fn is_variadic(&self) -> bool { false }
                 fn clone_boxed(&self) -> Box<dyn PluginFunction> { Box::new(#type_name()) }
                 fn input_types(&self) -> Box<[TypeId]> {
                     new_vec![#(#input_type_exprs),*].into_boxed_slice()

codegen/src/lib.rs

@@ -1,17 +1,14 @@
+//! This crate contains procedural macros to make creating Rhai plugin-modules much easier.
 //!
-//! This crate contains procedural macros to make creating Rhai modules much easier.
-//!
-//! # Exporting a Macro to Rhai
+//! # Export an Entire Rust Module to a Rhai `Module`
 //!
 //! ```
 //! use rhai::{EvalAltResult, FLOAT};
 //! use rhai::plugin::*;
 //! use rhai::module_resolvers::*;
 //!
-//! #[rhai::export_module]
-//! pub mod advanced_math {
-//!     use rhai::FLOAT;
-//!
+//! #[export_module]
+//! mod advanced_math {
 //!     pub const MYSTIC_NUMBER: FLOAT = 42.0 as FLOAT;
 //!
 //!     pub fn euclidean_distance(x1: FLOAT, y1: FLOAT, x2: FLOAT, y2: FLOAT) -> FLOAT {
@@ -35,15 +32,15 @@
 //! }
 //! ```
 //!
-//! # Exporting a Function to a Rhai Module
+//! # Register a Rust Function with a Rhai `Module`
 //!
 //! ```
 //! use rhai::{EvalAltResult, FLOAT, Module, RegisterFn};
 //! use rhai::plugin::*;
 //! use rhai::module_resolvers::*;
 //!
-//! #[rhai::export_fn]
-//! pub fn distance_function(x1: FLOAT, y1: FLOAT, x2: FLOAT, y2: FLOAT) -> FLOAT {
+//! #[export_fn]
+//! fn distance_function(x1: FLOAT, y1: FLOAT, x2: FLOAT, y2: FLOAT) -> FLOAT {
 //!     ((y2 - y1).abs().powf(2.0) + (x2 -x1).abs().powf(2.0)).sqrt()
 //! }
 //!
@@ -66,7 +63,7 @@
 //! }
 //! ```
 //!
-//! # Exporting a Function to an Engine
+//! # Register a Plugin Function with an `Engine`
 //!
 //! ```
 //! use rhai::{EvalAltResult, FLOAT, Module, RegisterFn};
@@ -105,6 +102,18 @@ mod rhai_module;
 #[cfg(test)]
 mod test;
 
+/// Attribute, when put on a Rust function, turns it into a _plugin function_.
+///
+/// # Usage
+///
+/// ```,ignore
+/// use rhai::plugin::*;
+///
+/// #[export_fn]
+/// fn my_plugin_function(...) {
+///   ...
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn export_fn(
     args: proc_macro::TokenStream,
@@ -125,6 +134,18 @@ pub fn export_fn(
     proc_macro::TokenStream::from(output)
 }
 
+/// Attribute, when put on a Rust module, turns it into a _plugin module_.
+///
+/// # Usage
+///
+/// ```,ignore
+/// use rhai::plugin::*;
+///
+/// #[export_module]
+/// mod my_plugin_module {
+///   ...
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn export_module(
     args: proc_macro::TokenStream,
@@ -143,6 +164,20 @@ pub fn export_module(
     proc_macro::TokenStream::from(tokens)
 }
 
+/// Macro to generate a Rhai `Module` from a _plugin module_.
+///
+/// # Usage
+///
+/// ```,ignore
+/// use rhai::plugin::*;
+///
+/// #[export_module]
+/// mod my_plugin_module {
+///   ...
+/// }
+///
+/// let module = exported_module!(my_plugin_module);
+/// ```
 #[proc_macro]
 pub fn exported_module(module_path: proc_macro::TokenStream) -> proc_macro::TokenStream {
     let module_path = parse_macro_input!(module_path as syn::Path);
@@ -152,6 +187,34 @@ pub fn exported_module(module_path: proc_macro::TokenStream) -> proc_macro::Toke
     proc_macro::TokenStream::from(tokens)
 }
 
+/// Macro to combine a _plugin module_ into an existing module.
+///
+/// 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
+/// 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.
+///
+/// The text string name in the second parameter can be anything and is reserved for future use;
+/// it is recommended to be an ID string that uniquely identifies the plugin module.
+///
+/// # Usage
+///
+/// ```,ignore
+/// use rhai::plugin::*;
+///
+/// #[export_module]
+/// mod my_plugin_module {
+///   ...
+/// }
+///
+/// let mut module = Module::new();
+///
+/// combine_with_exported_module!(&mut module, "my_plugin_module_ID", my_plugin_module);
+/// ```
 #[proc_macro]
 pub fn combine_with_exported_module(args: proc_macro::TokenStream) -> proc_macro::TokenStream {
     let (module_expr, _export_name, module_path) = match crate::register::parse_register_macro(args)
@@ -165,6 +228,22 @@ pub fn combine_with_exported_module(args: proc_macro::TokenStream) -> proc_macro
     proc_macro::TokenStream::from(tokens)
 }
 
+/// Macro to register a _plugin function_ into an `Engine`.
+///
+/// # Usage
+///
+/// ```,ignore
+/// use rhai::plugin::*;
+///
+/// #[export_fn]
+/// fn my_plugin_function(...) {
+///   ...
+/// }
+///
+/// let mut engine = Engine::new();
+///
+/// register_exported_fn!(engine, "calc", my_plugin_function);
+/// ```
 #[proc_macro]
 pub fn register_exported_fn(args: proc_macro::TokenStream) -> proc_macro::TokenStream {
     let (engine_expr, export_name, rust_modpath) = match crate::register::parse_register_macro(args)
@@ -179,6 +258,22 @@ pub fn register_exported_fn(args: proc_macro::TokenStream) -> proc_macro::TokenS
     proc_macro::TokenStream::from(tokens)
 }
 
+/// Macro to register a _plugin function_ into a Rhai `Module`.
+///
+/// # Usage
+///
+/// ```,ignore
+/// use rhai::plugin::*;
+///
+/// #[export_fn]
+/// fn my_plugin_function(...) {
+///   ...
+/// }
+///
+/// let mut module = Module::new();
+///
+/// set_exported_fn!(module, "calc", my_plugin_function);
+/// ```
 #[proc_macro]
 pub fn set_exported_fn(args: proc_macro::TokenStream) -> proc_macro::TokenStream {
     let (module_expr, export_name, rust_modpath) = match crate::register::parse_register_macro(args)

codegen/src/rhai_module.rs

@@ -126,7 +126,7 @@ pub(crate) fn generate_body(
             set_fn_stmts.push(
                 syn::parse2::<syn::Stmt>(quote! {
                     m.set_fn(#fn_literal, FnAccess::Public, &[#(#fn_input_types),*],
-                             CallableFunction::from_plugin(#fn_token_name()));
+                             #fn_token_name().into());
                 })
                 .unwrap(),
             );

codegen/src/test/function.rs

@@ -283,14 +283,14 @@ mod generate_tests {
                     }
 
                     fn is_method_call(&self) -> bool { false }
-                    fn is_varadic(&self) -> bool { false }
+                    fn is_variadic(&self) -> bool { false }
                     fn clone_boxed(&self) -> Box<dyn PluginFunction> { Box::new(Token()) }
                     fn input_types(&self) -> Box<[TypeId]> {
                         new_vec![].into_boxed_slice()
                     }
                 }
                 pub fn token_callable() -> CallableFunction {
-                    CallableFunction::from_plugin(Token())
+                    Token().into()
                 }
                 pub fn token_input_types() -> Box<[TypeId]> {
                     Token().input_types()
@@ -328,14 +328,14 @@ mod generate_tests {
                     }
 
                     fn is_method_call(&self) -> bool { false }
-                    fn is_varadic(&self) -> bool { false }
+                    fn is_variadic(&self) -> bool { false }
                     fn clone_boxed(&self) -> Box<dyn PluginFunction> { Box::new(Token()) }
                     fn input_types(&self) -> Box<[TypeId]> {
                         new_vec![TypeId::of::<usize>()].into_boxed_slice()
                     }
                 }
                 pub fn token_callable() -> CallableFunction {
-                    CallableFunction::from_plugin(Token())
+                    Token().into()
                 }
                 pub fn token_input_types() -> Box<[TypeId]> {
                     Token().input_types()
@@ -369,7 +369,7 @@ mod generate_tests {
                 }
 
                 fn is_method_call(&self) -> bool { false }
-                fn is_varadic(&self) -> bool { false }
+                fn is_variadic(&self) -> bool { false }
                 fn clone_boxed(&self) -> Box<dyn PluginFunction> { Box::new(MyType()) }
                 fn input_types(&self) -> Box<[TypeId]> {
                     new_vec![TypeId::of::<usize>()].into_boxed_slice()
@@ -404,15 +404,15 @@ mod generate_tests {
                     }
 
                     fn is_method_call(&self) -> bool { false }
-                    fn is_varadic(&self) -> bool { false }
+                    fn is_variadic(&self) -> bool { false }
                     fn clone_boxed(&self) -> Box<dyn PluginFunction> { Box::new(Token()) }
                     fn input_types(&self) -> Box<[TypeId]> {
                         new_vec![TypeId::of::<usize>(),
                              TypeId::of::<usize>()].into_boxed_slice()
                     }
                 }
                 pub fn token_callable() -> CallableFunction {
-                    CallableFunction::from_plugin(Token())
+                    Token().into()
                 }
                 pub fn token_input_types() -> Box<[TypeId]> {
                     Token().input_types()
@@ -446,20 +446,20 @@ mod generate_tests {
                         debug_assert_eq!(args.len(), 2usize,
                                     "wrong arg count: {} != {}", args.len(), 2usize);
                         let arg1 = mem::take(args[1usize]).cast::<usize>();
-                        let arg0: &mut _ = &mut args[0usize].write_lock::<usize>().unwrap();
+                        let arg0 = &mut args[0usize].write_lock::<usize>().unwrap();
                         Ok(Dynamic::from(increment(arg0, arg1)))
                     }
 
                     fn is_method_call(&self) -> bool { true }
-                    fn is_varadic(&self) -> bool { false }
+                    fn is_variadic(&self) -> bool { false }
                     fn clone_boxed(&self) -> Box<dyn PluginFunction> { Box::new(Token()) }
                     fn input_types(&self) -> Box<[TypeId]> {
                         new_vec![TypeId::of::<usize>(),
                              TypeId::of::<usize>()].into_boxed_slice()
                     }
                 }
                 pub fn token_callable() -> CallableFunction {
-                    CallableFunction::from_plugin(Token())
+                    Token().into()
                 }
                 pub fn token_input_types() -> Box<[TypeId]> {
                     Token().input_types()
@@ -498,14 +498,14 @@ mod generate_tests {
                     }
 
                     fn is_method_call(&self) -> bool { false }
-                    fn is_varadic(&self) -> bool { false }
+                    fn is_variadic(&self) -> bool { false }
                     fn clone_boxed(&self) -> Box<dyn PluginFunction> { Box::new(Token()) }
                     fn input_types(&self) -> Box<[TypeId]> {
                         new_vec![TypeId::of::<ImmutableString>()].into_boxed_slice()
                     }
                 }
                 pub fn token_callable() -> CallableFunction {
-                    CallableFunction::from_plugin(Token())
+                    Token().into()
                 }
                 pub fn token_input_types() -> Box<[TypeId]> {
                     Token().input_types()