From ff6d205c1dd198c701e8582d2ee3ab0924b9f1c7 Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Tue, 7 Jul 2020 22:59:23 +0800 Subject: [PATCH 1/5] Make Modules::set_raw_fn public. --- RELEASES.md | 4 +- src/api.rs | 136 ++++++++++---------------- src/module.rs | 188 +++++++++++++++++------------------- src/packages/array_basic.rs | 2 +- src/packages/string_more.rs | 2 +- tests/call_fn.rs | 20 ++-- 6 files changed, 158 insertions(+), 194 deletions(-) diff --git a/RELEASES.md b/RELEASES.md index 1818519e..8a17c106 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -24,9 +24,11 @@ New features This is particularly useful when converting a Rust `struct` to a `Dynamic` _object map_ and back. * `Engine::disable_symbol` to surgically disable keywords and/or operators. * `Engine::register_custom_operator` to define a custom operator. -* New low-level API `Engine::register_raw_fn`. +* New low-level API `Engine::register_raw_fn` and `Engine::register_raw_fn_XXX`. +* New low-level API `Module::set_raw_fn` mirroring `Engine::register_raw_fn`. * `AST::clone_functions_only`, `AST::clone_functions_only_filtered` and `AST::clone_statements_only` to clone only part of an `AST`. * The boolean `^` (XOR) operator is added. +* `FnPtr` is exposed as the function pointer type. Version 0.16.1 diff --git a/src/api.rs b/src/api.rs index 5df12aba..a6500443 100644 --- a/src/api.rs +++ b/src/api.rs @@ -6,7 +6,7 @@ use crate::error::ParseError; use crate::fn_call::FuncArgs; use crate::fn_native::{IteratorFn, SendSync}; use crate::fn_register::RegisterFn; -use crate::module::Module; +use crate::module::{FuncReturn, Module}; use crate::optimize::{optimize_into_ast, OptimizationLevel}; use crate::parser::AST; use crate::result::EvalAltResult; @@ -39,30 +39,23 @@ impl Engine { /// /// This function is very low level. It takes a list of `TypeId`'s indicating the actual types of the parameters. /// - /// Arguments are simply passed in as a mutable array of `&mut Dynamic`. + /// Arguments are simply passed in as a mutable array of `&mut Dynamic`, /// The arguments are guaranteed to be of the correct types matching the `TypeId`'s. /// - /// To get access to a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::()` + /// To access a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::()` /// - /// To get access to a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::()`. + /// To access a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::()`. /// Notice that this will _consume_ the argument, replacing it with `()`. /// - /// To get access to the first mutable parameter, use `args.get_mut(0).unwrap()` + /// To access the first mutable parameter, use `args.get_mut(0).unwrap()` #[deprecated(note = "this function is volatile and may change")] - pub fn register_raw_fn( + pub fn register_raw_fn( &mut self, name: &str, arg_types: &[TypeId], - - #[cfg(not(feature = "sync"))] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + 'static, - - #[cfg(feature = "sync")] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + Send - + Sync - + 'static, + func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn + SendSync + 'static, ) { - self.global_module.set_fn_var_args(name, arg_types, func); + self.global_module.set_raw_fn(name, arg_types, func); } /// Register a function of no parameters with the `Engine`. @@ -71,19 +64,12 @@ impl Engine { /// /// This function is very low level. #[deprecated(note = "this function is volatile and may change")] - pub fn register_raw_fn_0( + pub fn register_raw_fn_0( &mut self, name: &str, - - #[cfg(not(feature = "sync"))] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + 'static, - - #[cfg(feature = "sync")] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + Send - + Sync - + 'static, + func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn + SendSync + 'static, ) { - self.global_module.set_fn_var_args(name, &[], func); + self.global_module.set_raw_fn(name, &[], func); } /// Register a function of one parameter with the `Engine`. @@ -92,30 +78,23 @@ impl Engine { /// /// This function is very low level. /// - /// Arguments are simply passed in as a mutable array of `&mut Dynamic`. - /// The argument is guaranteed to be of the correct type. + /// Arguments are simply passed in as a mutable array of `&mut Dynamic`, + /// which is guaranteed to contain enough arguments of the correct types. /// - /// To get access to a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::()` + /// To access a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::()` /// - /// To get access to a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::()`. + /// To access a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::()`. /// Notice that this will _consume_ the argument, replacing it with `()`. /// - /// To get access to the first mutable parameter, use `args.get_mut(0).unwrap()` + /// To access the first mutable parameter, use `args.get_mut(0).unwrap()` #[deprecated(note = "this function is volatile and may change")] - pub fn register_raw_fn_1( + pub fn register_raw_fn_1( &mut self, name: &str, - - #[cfg(not(feature = "sync"))] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + 'static, - - #[cfg(feature = "sync")] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + Send - + Sync - + 'static, + func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn + SendSync + 'static, ) { self.global_module - .set_fn_var_args(name, &[TypeId::of::()], func); + .set_raw_fn(name, &[TypeId::of::()], func); } /// Register a function of two parameters with the `Engine`. @@ -124,30 +103,23 @@ impl Engine { /// /// This function is very low level. /// - /// Arguments are simply passed in as a mutable array of `&mut Dynamic`. - /// The arguments are guaranteed to be of the correct types. + /// Arguments are simply passed in as a mutable array of `&mut Dynamic`, + /// which is guaranteed to contain enough arguments of the correct types. /// - /// To get access to a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::()` + /// To access a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::()` /// - /// To get access to a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::()`. + /// To access a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::()`. /// Notice that this will _consume_ the argument, replacing it with `()`. /// - /// To get access to the first mutable parameter, use `args.get_mut(0).unwrap()` + /// To access the first mutable parameter, use `args.get_mut(0).unwrap()` #[deprecated(note = "this function is volatile and may change")] - pub fn register_raw_fn_2( + pub fn register_raw_fn_2( &mut self, name: &str, - - #[cfg(not(feature = "sync"))] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + 'static, - - #[cfg(feature = "sync")] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + Send - + Sync - + 'static, + func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn + SendSync + 'static, ) { self.global_module - .set_fn_var_args(name, &[TypeId::of::(), TypeId::of::()], func); + .set_raw_fn(name, &[TypeId::of::(), TypeId::of::()], func); } /// Register a function of three parameters with the `Engine`. @@ -156,29 +128,27 @@ impl Engine { /// /// This function is very low level. /// - /// Arguments are simply passed in as a mutable array of `&mut Dynamic`. - /// The arguments are guaranteed to be of the correct types. + /// Arguments are simply passed in as a mutable array of `&mut Dynamic`, + /// which is guaranteed to contain enough arguments of the correct types. /// - /// To get access to a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::()` + /// To access a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::()` /// - /// To get access to a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::()`. + /// To access a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::()`. /// Notice that this will _consume_ the argument, replacing it with `()`. /// - /// To get access to the first mutable parameter, use `args.get_mut(0).unwrap()` + /// To access the first mutable parameter, use `args.get_mut(0).unwrap()` #[deprecated(note = "this function is volatile and may change")] - pub fn register_raw_fn_3( + pub fn register_raw_fn_3< + A: Variant + Clone, + B: Variant + Clone, + C: Variant + Clone, + T: Variant + Clone, + >( &mut self, name: &str, - - #[cfg(not(feature = "sync"))] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + 'static, - - #[cfg(feature = "sync")] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + Send - + Sync - + 'static, + func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn + SendSync + 'static, ) { - self.global_module.set_fn_var_args( + self.global_module.set_raw_fn( name, &[TypeId::of::(), TypeId::of::(), TypeId::of::()], func, @@ -191,34 +161,28 @@ impl Engine { /// /// This function is very low level. /// - /// Arguments are simply passed in as a mutable array of `&mut Dynamic`. - /// The arguments are guaranteed to be of the correct types. + /// Arguments are simply passed in as a mutable array of `&mut Dynamic`, + /// which is guaranteed to contain enough arguments of the correct types. /// - /// To get access to a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::()` + /// To access a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::()` /// - /// To get access to a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::()`. + /// To access a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::()`. /// Notice that this will _consume_ the argument, replacing it with `()`. /// - /// To get access to the first mutable parameter, use `args.get_mut(0).unwrap()` + /// To access the first mutable parameter, use `args.get_mut(0).unwrap()` #[deprecated(note = "this function is volatile and may change")] pub fn register_raw_fn_4< A: Variant + Clone, B: Variant + Clone, C: Variant + Clone, D: Variant + Clone, + T: Variant + Clone, >( &mut self, name: &str, - - #[cfg(not(feature = "sync"))] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + 'static, - - #[cfg(feature = "sync")] func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> Result> - + Send - + Sync - + 'static, + func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn + SendSync + 'static, ) { - self.global_module.set_fn_var_args( + self.global_module.set_raw_fn( name, &[ TypeId::of::(), @@ -1395,7 +1359,7 @@ impl Engine { name: &str, mut this_ptr: Option<&mut Dynamic>, mut arg_values: impl AsMut<[Dynamic]>, - ) -> Result> { + ) -> FuncReturn { self.call_fn_dynamic_raw(scope, lib, name, &mut this_ptr, arg_values.as_mut()) } @@ -1415,7 +1379,7 @@ impl Engine { name: &str, this_ptr: &mut Option<&mut Dynamic>, arg_values: &mut [Dynamic], - ) -> Result> { + ) -> FuncReturn { let lib = lib.as_ref(); let mut args: StaticVec<_> = arg_values.iter_mut().collect(); let fn_def = diff --git a/src/module.rs b/src/module.rs index cd08e5bc..9703552b 100644 --- a/src/module.rs +++ b/src/module.rs @@ -3,7 +3,7 @@ use crate::any::{Dynamic, Variant}; use crate::calc_fn_hash; use crate::engine::{make_getter, make_setter, Engine, Imports, FN_IDX_GET, FN_IDX_SET}; -use crate::fn_native::{CallableFunction, FnCallArgs, IteratorFn, SendSync, Shared}; +use crate::fn_native::{CallableFunction as Func, FnCallArgs, IteratorFn, SendSync, Shared}; use crate::parser::{ FnAccess, FnAccess::{Private, Public}, @@ -49,18 +49,14 @@ pub struct Module { all_variables: HashMap, /// External Rust functions. - functions: HashMap< - u64, - (String, FnAccess, StaticVec, CallableFunction), - StraightHasherBuilder, - >, + functions: HashMap, Func), StraightHasherBuilder>, /// Iterator functions, keyed by the type producing the iterator. type_iterators: HashMap, /// Flattened collection of all external Rust functions, native or scripted, /// including those in sub-modules. - all_functions: HashMap, + all_functions: HashMap, /// Is the module indexed? indexed: bool, @@ -346,18 +342,18 @@ impl Module { /// Set a Rust function into the module, returning a hash key. /// /// If there is an existing Rust function of the same hash, it is replaced. - pub fn set_fn( + pub(crate) fn set_fn( &mut self, name: impl Into, access: FnAccess, - params: &[TypeId], - func: CallableFunction, + arg_types: &[TypeId], + func: Func, ) -> u64 { let name = name.into(); - let hash_fn = calc_fn_hash(empty(), &name, params.len(), params.iter().cloned()); + let hash_fn = calc_fn_hash(empty(), &name, arg_types.len(), arg_types.iter().cloned()); - let params = params.into_iter().cloned().collect(); + let params = arg_types.into_iter().cloned().collect(); self.functions .insert(hash_fn, (name, access, params, func.into())); @@ -367,29 +363,72 @@ impl Module { hash_fn } - /// Set a Rust function taking a reference to the scripting `Engine`, plus a list of - /// mutable `Dynamic` references into the module, returning a hash key. - /// A list of `TypeId`'s is taken as the argument types. + /// Set a Rust function taking a reference to the scripting `Engine`, the current set of functions, + /// plus a list of mutable `Dynamic` references into the module, returning a hash key. /// /// Use this to register a built-in function which must reference settings on the scripting - /// `Engine` (e.g. to prevent growing an array beyond the allowed maximum size). + /// `Engine` (e.g. to prevent growing an array beyond the allowed maximum size), or to call a + /// script-defined function in the current evaluation context. /// /// If there is a similar existing Rust function, it is replaced. - pub(crate) fn set_fn_var_args( + /// + /// ## WARNING - Low Level API + /// + /// This function is very low level. + /// + /// A list of `TypeId`'s is taken as the argument types. + /// + /// Arguments are simply passed in as a mutable array of `&mut Dynamic`, + /// which is guaranteed to contain enough arguments of the correct types. + /// + /// To access a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::()` + /// + /// To access a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::()`. + /// Notice that this will _consume_ the argument, replacing it with `()`. + /// + /// To access the first mutable parameter, use `args.get_mut(0).unwrap()` + /// + /// # Examples + /// + /// ``` + /// use rhai::Module; + /// + /// let mut module = Module::new(); + /// let hash = module.set_raw_fn("double_or_not", + /// // Pass parameter types via a slice with TypeId's + /// &[std::any::TypeId::of::(), std::any::TypeId::of::() ], + /// // Fixed closure signature + /// |engine, lib, args| { + /// // 'args' is guaranteed to be the right length and of the correct types + /// + /// // Get the second parameter by 'consuming' it + /// let double = std::mem::take(args[1]).cast::(); + /// // Since it is a primary type, it can also be cheaply copied + /// let double = args[1].clone().cast::(); + /// // Get a mutable reference to the first argument. + /// let x = args[0].downcast_mut::().unwrap(); + /// + /// let orig = *x; + /// + /// if double { + /// *x *= 2; // the first argument can be mutated + /// } + /// + /// Ok(orig) // return Result> + /// }); + /// + /// assert!(module.contains_fn(hash)); + /// ``` + pub fn set_raw_fn( &mut self, name: impl Into, - args: &[TypeId], + arg_types: &[TypeId], func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn + SendSync + 'static, ) -> u64 { let f = move |engine: &Engine, lib: &Module, args: &mut FnCallArgs| { func(engine, lib, args).map(Dynamic::from) }; - self.set_fn( - name, - Public, - args, - CallableFunction::from_method(Box::new(f)), - ) + self.set_fn(name, Public, arg_types, Func::from_method(Box::new(f))) } /// Set a Rust function taking no parameters into the module, returning a hash key. @@ -411,13 +450,8 @@ impl Module { func: impl Fn() -> FuncReturn + SendSync + 'static, ) -> u64 { let f = move |_: &Engine, _: &Module, _: &mut FnCallArgs| func().map(Dynamic::from); - let args = []; - self.set_fn( - name, - Public, - &args, - CallableFunction::from_pure(Box::new(f)), - ) + let arg_types = []; + self.set_fn(name, Public, &arg_types, Func::from_pure(Box::new(f))) } /// Set a Rust function taking one parameter into the module, returning a hash key. @@ -441,13 +475,8 @@ impl Module { let f = move |_: &Engine, _: &Module, args: &mut FnCallArgs| { func(mem::take(args[0]).cast::()).map(Dynamic::from) }; - let args = [TypeId::of::()]; - self.set_fn( - name, - Public, - &args, - CallableFunction::from_pure(Box::new(f)), - ) + let arg_types = [TypeId::of::()]; + self.set_fn(name, Public, &arg_types, Func::from_pure(Box::new(f))) } /// Set a Rust function taking one mutable parameter into the module, returning a hash key. @@ -471,13 +500,8 @@ impl Module { let f = move |_: &Engine, _: &Module, args: &mut FnCallArgs| { func(args[0].downcast_mut::().unwrap()).map(Dynamic::from) }; - let args = [TypeId::of::()]; - self.set_fn( - name, - Public, - &args, - CallableFunction::from_method(Box::new(f)), - ) + let arg_types = [TypeId::of::()]; + self.set_fn(name, Public, &arg_types, Func::from_method(Box::new(f))) } /// Set a Rust getter function taking one mutable parameter, returning a hash key. @@ -528,13 +552,8 @@ impl Module { func(a, b).map(Dynamic::from) }; - let args = [TypeId::of::(), TypeId::of::()]; - self.set_fn( - name, - Public, - &args, - CallableFunction::from_pure(Box::new(f)), - ) + let arg_types = [TypeId::of::(), TypeId::of::()]; + self.set_fn(name, Public, &arg_types, Func::from_pure(Box::new(f))) } /// Set a Rust function taking two parameters (the first one mutable) into the module, @@ -564,13 +583,8 @@ impl Module { func(a, b).map(Dynamic::from) }; - let args = [TypeId::of::(), TypeId::of::()]; - self.set_fn( - name, - Public, - &args, - CallableFunction::from_method(Box::new(f)), - ) + let arg_types = [TypeId::of::(), TypeId::of::()]; + self.set_fn(name, Public, &arg_types, Func::from_method(Box::new(f))) } /// Set a Rust setter function taking two parameters (the first one mutable) into the module, @@ -656,13 +670,8 @@ impl Module { func(a, b, c).map(Dynamic::from) }; - let args = [TypeId::of::(), TypeId::of::(), TypeId::of::()]; - self.set_fn( - name, - Public, - &args, - CallableFunction::from_pure(Box::new(f)), - ) + let arg_types = [TypeId::of::(), TypeId::of::(), TypeId::of::()]; + self.set_fn(name, Public, &arg_types, Func::from_pure(Box::new(f))) } /// Set a Rust function taking three parameters (the first one mutable) into the module, @@ -698,13 +707,8 @@ impl Module { func(a, b, c).map(Dynamic::from) }; - let args = [TypeId::of::(), TypeId::of::(), TypeId::of::()]; - self.set_fn( - name, - Public, - &args, - CallableFunction::from_method(Box::new(f)), - ) + let arg_types = [TypeId::of::(), TypeId::of::(), TypeId::of::()]; + self.set_fn(name, Public, &arg_types, Func::from_method(Box::new(f))) } /// Set a Rust index setter taking three parameters (the first one mutable) into the module, @@ -735,12 +739,12 @@ impl Module { func(a, b, c).map(Dynamic::from) }; - let args = [TypeId::of::(), TypeId::of::(), TypeId::of::()]; + let arg_types = [TypeId::of::(), TypeId::of::(), TypeId::of::()]; self.set_fn( FN_IDX_SET, Public, - &args, - CallableFunction::from_method(Box::new(f)), + &arg_types, + Func::from_method(Box::new(f)), ) } @@ -778,18 +782,13 @@ impl Module { func(a, b, c, d).map(Dynamic::from) }; - let args = [ + let arg_types = [ TypeId::of::(), TypeId::of::(), TypeId::of::(), TypeId::of::(), ]; - self.set_fn( - name, - Public, - &args, - CallableFunction::from_pure(Box::new(f)), - ) + self.set_fn(name, Public, &arg_types, Func::from_pure(Box::new(f))) } /// Set a Rust function taking four parameters (the first one mutable) into the module, @@ -827,25 +826,20 @@ impl Module { func(a, b, c, d).map(Dynamic::from) }; - let args = [ + let arg_types = [ TypeId::of::(), TypeId::of::(), TypeId::of::(), TypeId::of::(), ]; - self.set_fn( - name, - Public, - &args, - CallableFunction::from_method(Box::new(f)), - ) + self.set_fn(name, Public, &arg_types, Func::from_method(Box::new(f))) } /// Get a Rust function. /// /// The `u64` hash is calculated by the function `crate::calc_fn_hash`. /// It is also returned by the `set_fn_XXX` calls. - pub(crate) fn get_fn(&self, hash_fn: u64) -> Option<&CallableFunction> { + pub(crate) fn get_fn(&self, hash_fn: u64) -> Option<&Func> { self.functions.get(&hash_fn).map(|(_, _, _, v)| v) } @@ -857,7 +851,7 @@ impl Module { pub(crate) fn get_qualified_fn( &mut self, hash_qualified_fn: u64, - ) -> Result<&CallableFunction, Box> { + ) -> Result<&Func, Box> { self.all_functions.get(&hash_qualified_fn).ok_or_else(|| { Box::new(EvalAltResult::ErrorFunctionNotFound( String::new(), @@ -886,9 +880,7 @@ impl Module { .iter() .filter(|(_, (_, _, _, v))| match v { #[cfg(not(feature = "no_function"))] - CallableFunction::Script(ref f) => { - filter(f.access, f.name.as_str(), f.params.len()) - } + Func::Script(ref f) => filter(f.access, f.name.as_str(), f.params.len()), _ => true, }) .map(|(&k, v)| (k, v.clone())), @@ -906,7 +898,7 @@ impl Module { #[cfg(not(feature = "no_function"))] pub(crate) fn retain_functions(&mut self, filter: impl Fn(FnAccess, &str, usize) -> bool) { self.functions.retain(|_, (_, _, _, v)| match v { - CallableFunction::Script(ref f) => filter(f.access, f.name.as_str(), f.params.len()), + Func::Script(ref f) => filter(f.access, f.name.as_str(), f.params.len()), _ => true, }); @@ -936,7 +928,7 @@ impl Module { /// Get an iterator to the functions in the module. pub(crate) fn iter_fn( &self, - ) -> impl Iterator, CallableFunction)> { + ) -> impl Iterator, Func)> { self.functions.values() } @@ -1003,7 +995,7 @@ impl Module { module: &'a Module, qualifiers: &mut Vec<&'a str>, variables: &mut Vec<(u64, Dynamic)>, - functions: &mut Vec<(u64, CallableFunction)>, + functions: &mut Vec<(u64, Func)>, ) { for (name, m) in &module.modules { // Index all the sub-modules first. diff --git a/src/packages/array_basic.rs b/src/packages/array_basic.rs index acaa1132..0a580933 100644 --- a/src/packages/array_basic.rs +++ b/src/packages/array_basic.rs @@ -67,7 +67,7 @@ macro_rules! reg_tri { macro_rules! reg_pad { ($lib:expr, $op:expr, $func:ident, $($par:ty),*) => { $({ - $lib.set_fn_var_args($op, + $lib.set_raw_fn($op, &[TypeId::of::(), TypeId::of::(), TypeId::of::<$par>()], $func::<$par> ); diff --git a/src/packages/string_more.rs b/src/packages/string_more.rs index 5ae39db6..248b0e93 100644 --- a/src/packages/string_more.rs +++ b/src/packages/string_more.rs @@ -223,7 +223,7 @@ def_package!(crate:MoreStringPackage:"Additional string utilities, including str Ok(()) }, ); - lib.set_fn_var_args( + lib.set_raw_fn( "pad", &[TypeId::of::(), TypeId::of::(), TypeId::of::()], |engine: &Engine, _: &Module, args: &mut [&mut Dynamic]| { diff --git a/tests/call_fn.rs b/tests/call_fn.rs index 715fbc87..62291830 100644 --- a/tests/call_fn.rs +++ b/tests/call_fn.rs @@ -1,7 +1,7 @@ #![cfg(not(feature = "no_function"))] use rhai::{ - Dynamic, Engine, EvalAltResult, Func, ImmutableString, Module, ParseError, ParseErrorType, - Scope, INT, + Dynamic, Engine, EvalAltResult, FnPtr, Func, ImmutableString, Module, ParseError, + ParseErrorType, Scope, INT, }; #[test] @@ -122,17 +122,23 @@ fn test_fn_ptr() -> Result<(), Box> { "bar", &[ std::any::TypeId::of::(), - std::any::TypeId::of::(), + std::any::TypeId::of::(), std::any::TypeId::of::(), ], move |engine: &Engine, lib: &Module, args: &mut [&mut Dynamic]| { - let callback = args[1].clone().cast::(); + let fp = std::mem::take(args[1]).cast::(); let value = args[2].clone(); let this_ptr = args.get_mut(0).unwrap(); - engine.call_fn_dynamic(&mut Scope::new(), lib, &callback, Some(this_ptr), [value])?; + engine.call_fn_dynamic( + &mut Scope::new(), + lib, + fp.fn_name(), + Some(this_ptr), + [value], + )?; - Ok(().into()) + Ok(()) }, ); @@ -142,7 +148,7 @@ fn test_fn_ptr() -> Result<(), Box> { fn foo(x) { this += x; } let x = 41; - x.bar("foo", 1); + x.bar(Fn("foo"), 1); x "# )?, From 236ba40784ea39f8d46d57db9c10ec4c4d35e88e Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Tue, 7 Jul 2020 23:44:23 +0800 Subject: [PATCH 2/5] Add ModuleResolversCollection. --- src/module.rs | 87 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 84 insertions(+), 3 deletions(-) diff --git a/src/module.rs b/src/module.rs index 9703552b..9fa9f9a7 100644 --- a/src/module.rs +++ b/src/module.rs @@ -1145,6 +1145,7 @@ pub trait ModuleResolver: SendSync { /// Re-export module resolvers. #[cfg(not(feature = "no_module"))] pub mod resolvers { + pub use super::collection::ModuleResolversCollection; #[cfg(not(feature = "no_std"))] #[cfg(not(target_arch = "wasm32"))] pub use super::file::FileModuleResolver; @@ -1340,9 +1341,6 @@ mod stat { /// Module resolution service that serves modules added into it. /// - /// `StaticModuleResolver` is a smart pointer to a `HashMap`. - /// It can simply be treated as `&HashMap`. - /// /// # Examples /// /// ``` @@ -1436,3 +1434,86 @@ mod stat { } } } + +/// Module resolver collection. +#[cfg(not(feature = "no_module"))] +mod collection { + use super::*; + + /// Module resolution service that holds a collection of module resolves, + /// to be searched in sequential order. + /// + /// # Examples + /// + /// ``` + /// use rhai::{Engine, Module}; + /// use rhai::module_resolvers::{StaticModuleResolver, ModuleResolversCollection}; + /// + /// let mut collection = ModuleResolversCollection::new(); + /// + /// let resolver = StaticModuleResolver::new(); + /// collection.push(resolver); + /// + /// let mut engine = Engine::new(); + /// engine.set_module_resolver(Some(collection)); + /// ``` + #[derive(Default)] + pub struct ModuleResolversCollection(Vec>); + + impl ModuleResolversCollection { + /// Create a new `ModuleResolversCollection`. + /// + /// # Examples + /// + /// ``` + /// use rhai::{Engine, Module}; + /// use rhai::module_resolvers::{StaticModuleResolver, ModuleResolversCollection}; + /// + /// let mut collection = ModuleResolversCollection::new(); + /// + /// let resolver = StaticModuleResolver::new(); + /// collection.push(resolver); + /// + /// let mut engine = Engine::new(); + /// engine.set_module_resolver(Some(collection)); + /// ``` + pub fn new() -> Self { + Default::default() + } + } + + impl ModuleResolversCollection { + /// Add a module keyed by its path. + pub fn push(&mut self, resolver: impl ModuleResolver + 'static) { + self.0.push(Box::new(resolver)); + } + /// Get an iterator of all the module resolvers. + pub fn iter(&self) -> impl Iterator { + self.0.iter().map(|v| v.as_ref()) + } + /// Remove all module resolvers. + pub fn clear(&mut self) { + self.0.clear(); + } + } + + impl ModuleResolver for ModuleResolversCollection { + fn resolve( + &self, + engine: &Engine, + path: &str, + pos: Position, + ) -> Result> { + for resolver in self.0.iter() { + if let Ok(module) = resolver.resolve(engine, path, pos) { + return Ok(module); + } + } + + Err(Box::new(EvalAltResult::ErrorModuleNotFound( + path.into(), + pos, + ))) + } + } +} From 150f02d8b7ffcc990e47bb1faef0f4c323a0ae3b Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Wed, 8 Jul 2020 09:48:25 +0800 Subject: [PATCH 3/5] Update docs regarding modules. --- RELEASES.md | 2 + doc/src/SUMMARY.md | 6 +-- doc/src/language/eval.md | 8 +-- doc/src/language/functions.md | 10 ++-- doc/src/language/modules/export.md | 4 +- doc/src/language/modules/import.md | 1 + doc/src/language/modules/rust.md | 30 ----------- doc/src/language/values-and-types.md | 2 +- doc/src/links.md | 2 +- doc/src/rust/custom.md | 4 +- .../modules/imp-resolver.md | 0 doc/src/rust/modules/index.md | 45 ++++++++++++++++ .../{language => rust}/modules/resolvers.md | 17 ++++-- doc/src/rust/operators.md | 8 +-- doc/src/rust/register-raw.md | 54 +++++++++++++++++-- 15 files changed, 134 insertions(+), 59 deletions(-) delete mode 100644 doc/src/language/modules/rust.md rename doc/src/{language => rust}/modules/imp-resolver.md (100%) create mode 100644 doc/src/rust/modules/index.md rename doc/src/{language => rust}/modules/resolvers.md (55%) diff --git a/RELEASES.md b/RELEASES.md index 8a17c106..4afe903b 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -9,6 +9,7 @@ This version adds: * [`serde`](https://crates.io/crates/serde) support for working with `Dynamic` values (particularly _object maps_). * Ability to surgically disable keywords and/or operators in the language. * Ability to define custom operators (which must be valid identifiers). +* Low-level API to register functions. Breaking changes ---------------- @@ -29,6 +30,7 @@ New features * `AST::clone_functions_only`, `AST::clone_functions_only_filtered` and `AST::clone_statements_only` to clone only part of an `AST`. * The boolean `^` (XOR) operator is added. * `FnPtr` is exposed as the function pointer type. +* `rhai::module_resolvers::ModuleResolversCollection` added to try a list of module resolvers. Version 0.16.1 diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index 6d90df0c..3274e8cb 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -79,10 +79,10 @@ The Rhai Scripting Language 16. [Modules](language/modules/index.md) 1. [Export Variables, Functions and Sub-Modules](language/modules/export.md) 2. [Import Modules](language/modules/import.md) - 3. [Create from Rust](language/modules/rust.md) + 3. [Create from Rust](rust/modules/index.md) 4. [Create from AST](language/modules/ast.md) - 5. [Module Resolvers](language/modules/resolvers.md) - 1. [Implement a Custom Module Resolver](language/modules/imp-resolver.md) + 5. [Module Resolvers](rust/modules/resolvers.md) + 1. [Custom Implementation](rust/modules/imp-resolver.md) 7. [Safety and Protection](safety/index.md) 1. [Checked Arithmetic](safety/checked.md) 2. [Sand-Boxing](safety/sandbox.md) diff --git a/doc/src/language/eval.md b/doc/src/language/eval.md index a7e5b979..0af40142 100644 --- a/doc/src/language/eval.md +++ b/doc/src/language/eval.md @@ -19,14 +19,14 @@ script += "x + y"; let result = eval(script); // <- look, JavaScript, we can also do this! -print("Answer: " + result); // prints 42 +result == 42; -print("x = " + x); // prints 10: functions call arguments are passed by value -print("y = " + y); // prints 32: variables defined in 'eval' persist! +x == 10; // prints 10: functions call arguments are passed by value +y == 32; // prints 32: variables defined in 'eval' persist! eval("{ let z = y }"); // to keep a variable local, use a statement block -print("z = " + z); // <- error: variable 'z' not found +print(z); // <- error: variable 'z' not found "print(42)".eval(); // <- nope... method-call style doesn't work with 'eval' ``` diff --git a/doc/src/language/functions.md b/doc/src/language/functions.md index 72dac0b4..b6c0a85f 100644 --- a/doc/src/language/functions.md +++ b/doc/src/language/functions.md @@ -14,8 +14,9 @@ fn sub(x, y,) { // trailing comma in parameters list is OK return x - y; } -print(add(2, 3)); // prints 5 -print(sub(2, 3,)); // prints -1 - trailing comma in arguments list is OK +add(2, 3) == 5; + +sub(2, 3,) == -1; // trailing comma in arguments list is OK ``` @@ -35,8 +36,9 @@ fn add2(x) { return x + 2; // explicit return } -print(add(2, 3)); // prints 5 -print(add2(42)); // prints 44 +add(2, 3) == 5; + +add2(42) == 44; ``` diff --git a/doc/src/language/modules/export.md b/doc/src/language/modules/export.md index dbb4ddca..f05e008c 100644 --- a/doc/src/language/modules/export.md +++ b/doc/src/language/modules/export.md @@ -22,6 +22,8 @@ The `export` statement, which can only be at global level, exposes selected vari Variables not exported are _private_ and hidden to the outside. +Everything exported from a module is **constant** (**read-only**). + ```rust // This is a module script. @@ -49,8 +51,6 @@ All functions are automatically exported, _unless_ it is explicitly opt-out with Functions declared [`private`] are hidden to the outside. -Everything exported from a module is **constant** (**read-only**). - ```rust // This is a module script. diff --git a/doc/src/language/modules/import.md b/doc/src/language/modules/import.md index 4ede1f52..dc94b5a8 100644 --- a/doc/src/language/modules/import.md +++ b/doc/src/language/modules/import.md @@ -3,6 +3,7 @@ Import a Module {{#include ../../links.md}} + `import` Statement ----------------- diff --git a/doc/src/language/modules/rust.md b/doc/src/language/modules/rust.md deleted file mode 100644 index 74f90896..00000000 --- a/doc/src/language/modules/rust.md +++ /dev/null @@ -1,30 +0,0 @@ -Create a Module from Rust -======================== - -{{#include ../../links.md}} - -To load a custom module (written in Rust) into an [`Engine`], first create a [`Module`] type, -add variables/functions into it, then finally push it into a custom [`Scope`]. - -This has the equivalent effect of putting an [`import`] statement at the beginning of any script run. - -```rust -use rhai::{Engine, Scope, Module, i64}; - -let mut engine = Engine::new(); -let mut scope = Scope::new(); - -let mut module = Module::new(); // new module -module.set_var("answer", 41_i64); // variable 'answer' under module -module.set_fn_1("inc", |x: i64| Ok(x+1)); // use the 'set_fn_XXX' API to add functions - -// Push the module into the custom scope under the name 'question' -// This is equivalent to 'import "..." as question;' -scope.push_module("question", module); - -// Use module-qualified variables -engine.eval_expression_with_scope::(&scope, "question::answer + 1")? == 42; - -// Call module-qualified functions -engine.eval_expression_with_scope::(&scope, "question::inc(question::answer)")? == 42; -``` diff --git a/doc/src/language/values-and-types.md b/doc/src/language/values-and-types.md index 70c276a9..55b03229 100644 --- a/doc/src/language/values-and-types.md +++ b/doc/src/language/values-and-types.md @@ -15,7 +15,7 @@ The following primitive types are supported natively: | **[`Array`]** (disabled with [`no_index`]) | `rhai::Array` | `"array"` | `"[ ?, ?, ? ]"` | | **[Object map]** (disabled with [`no_object`]) | `rhai::Map` | `"map"` | `"#{ "a": 1, "b": 2 }"` | | **[Timestamp]** (implemented in the [`BasicTimePackage`][packages], disabled with [`no_std`]) | `std::time::Instant` ([`instant::Instant`] if not [WASM] build) | `"timestamp"` | _not supported_ | -| **[Function pointer]** | _None_ | `Fn` | `"Fn(foo)"` | +| **[Function pointer]** | `rhai::FnPtr` | `Fn` | `"Fn(foo)"` | | **[`Dynamic`] value** (i.e. can be anything) | `rhai::Dynamic` | _the actual type_ | _actual value_ | | **System integer** (current configuration) | `rhai::INT` (`i32` or `i64`) | `"i32"` or `"i64"` | `"42"`, `"123"` etc. | | **System floating-point** (current configuration, disabled with [`no_float`]) | `rhai::FLOAT` (`f32` or `f64`) | `"f32"` or `"f64"` | `"123.456"` etc. | diff --git a/doc/src/links.md b/doc/src/links.md index a81bfd0c..85561acc 100644 --- a/doc/src/links.md +++ b/doc/src/links.md @@ -82,7 +82,7 @@ [`Module`]: {{rootUrl}}/language/modules/index.md [module]: {{rootUrl}}/language/modules/index.md [modules]: {{rootUrl}}/language/modules/index.md -[module resolver]: {{rootUrl}}/language/modules/imp-resolver.md +[module resolver]: {{rootUrl}}/rust/modules/resolvers.md [`export`]: {{rootUrl}}/language/modules/export.md [`import`]: {{rootUrl}}/language/modules/import.md diff --git a/doc/src/rust/custom.md b/doc/src/rust/custom.md index b87f6409..43837cd5 100644 --- a/doc/src/rust/custom.md +++ b/doc/src/rust/custom.md @@ -136,10 +136,10 @@ with a special "pretty-print" name, [`type_of()`] will return that name instead. engine.register_type::(); engine.register_fn("new_ts", TestStruct::new); let x = new_ts(); -print(x.type_of()); // prints "path::to::module::TestStruct" +x.type_of() == "path::to::module::TestStruct"; engine.register_type_with_name::("Hello"); engine.register_fn("new_ts", TestStruct::new); let x = new_ts(); -print(x.type_of()); // prints "Hello" +x.type_of() == "Hello"; ``` diff --git a/doc/src/language/modules/imp-resolver.md b/doc/src/rust/modules/imp-resolver.md similarity index 100% rename from doc/src/language/modules/imp-resolver.md rename to doc/src/rust/modules/imp-resolver.md diff --git a/doc/src/rust/modules/index.md b/doc/src/rust/modules/index.md new file mode 100644 index 00000000..be6576bb --- /dev/null +++ b/doc/src/rust/modules/index.md @@ -0,0 +1,45 @@ +Create a Module from Rust +======================== + +{{#include ../../links.md}} + +Manually creating a [`Module`] is possible via the `Module` API. + +For the complete `Module` API, refer to the [documentation](https://docs.rs/rhai/{{version}}/rhai/struct.Module.html) online. + + +Make the Module Available to the Engine +-------------------------------------- + +In order to _use_ a custom module, there must be a [module resolver]. + +The easiest way is to use, for example, the [`StaticModuleResolver`][module resolver] to hold such +a custom module. + +```rust +use rhai::{Engine, Scope, Module, i64}; +use rhai::module_resolvers::StaticModuleResolver; + +let mut engine = Engine::new(); +let mut scope = Scope::new(); + +let mut module = Module::new(); // new module +module.set_var("answer", 41_i64); // variable 'answer' under module +module.set_fn_1("inc", |x: i64| Ok(x+1)); // use the 'set_fn_XXX' API to add functions + +// Create the module resolver +let mut resolver = StaticModuleResolver::new(); + +// Add the module into the module resolver under the name 'question' +// They module can then be accessed via: 'import "question" as q;' +resolver.insert("question", module); + +// Set the module resolver into the 'Engine' +engine.set_module_resolver(Some(resolver)); + +// Use module-qualified variables +engine.eval::(&scope, r#"import "question" as q; q::answer + 1"#)? == 42; + +// Call module-qualified functions +engine.eval::(&scope, r#"import "question" as q; q::inc(q::answer)"#)? == 42; +``` diff --git a/doc/src/language/modules/resolvers.md b/doc/src/rust/modules/resolvers.md similarity index 55% rename from doc/src/language/modules/resolvers.md rename to doc/src/rust/modules/resolvers.md index ed2bf54c..4a3b97e7 100644 --- a/doc/src/language/modules/resolvers.md +++ b/doc/src/rust/modules/resolvers.md @@ -7,15 +7,24 @@ When encountering an [`import`] statement, Rhai attempts to _resolve_ the module _Module Resolvers_ are service types that implement the [`ModuleResolver`][traits] trait. + +Built-In Module Resolvers +------------------------ + There are a number of standard resolvers built into Rhai, the default being the `FileModuleResolver` which simply loads a script file based on the path (with `.rhai` extension attached) and execute it to form a module. Built-in module resolvers are grouped under the `rhai::module_resolvers` module namespace. -| Module Resolver | Description | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `FileModuleResolver` | The default module resolution service, not available under [`no_std`] or [WASM] builds. Loads a script file (based off the current directory) with `.rhai` extension.
The base directory can be changed via the `FileModuleResolver::new_with_path()` constructor function.
`FileModuleResolver::create_module()` loads a script file and returns a module. | -| `StaticModuleResolver` | Loads modules that are statically added. This can be used under [`no_std`]. | +| Module Resolver | Description | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `FileModuleResolver` | The default module resolution service, not available under [`no_std`] or [WASM] builds. Loads a script file (based off the current directory) with `.rhai` extension.
The base directory can be changed via the `FileModuleResolver::new_with_path()` constructor function.
`FileModuleResolver::create_module()` loads a script file and returns a module. | +| `StaticModuleResolver` | Loads modules that are statically added. This can be used under [`no_std`]. | +| `ModuleResolversCollection` | A collection of module resolvers. Modules will be resolved from each resolver in sequential order.
This is useful when multiple types of modules are needed simultaneously. | + + +Set into `Engine` +----------------- An [`Engine`]'s module resolver is set via a call to `Engine::set_module_resolver`: diff --git a/doc/src/rust/operators.md b/doc/src/rust/operators.md index 8374bfb4..e4ce9b65 100644 --- a/doc/src/rust/operators.md +++ b/doc/src/rust/operators.md @@ -39,17 +39,19 @@ engine.register_fn("+", strange_add); // overload '+' operator for let result: i64 = engine.eval("1 + 0"); // the overloading version is used -println!("result: {}", result); // prints 42 +result == 42; let result: f64 = engine.eval("1.0 + 0.0"); // '+' operator for two floats not overloaded -println!("result: {}", result); // prints 1.0 +result == 1.0; fn mixed_add(a: i64, b: f64) -> f64 { (a as f64) + b } engine.register_fn("+", mixed_add); // register '+' operator for an integer and a float -let result: i64 = engine.eval("1 + 1.0"); // prints 2.0 (normally an error) +let result: i64 = engine.eval("1 + 1.0"); // <- normally an error... + +result == 2.0; // ... but not now ``` diff --git a/doc/src/rust/register-raw.md b/doc/src/rust/register-raw.md index 429dae4a..6d3f22c5 100644 --- a/doc/src/rust/register-raw.md +++ b/doc/src/rust/register-raw.md @@ -75,15 +75,18 @@ Closure Signature The closure passed to `Engine::register_raw_fn` takes the following form: -`Fn(engine: &Engine, lib: &Module, args: &mut [&mut Dynamic]) -> Result> + 'static` +`Fn(engine: &Engine, lib: &Module, args: &mut [&mut Dynamic]) -> Result> + 'static` where: -* `engine` - a reference to the current [`Engine`], with all configurations and settings. +* `T : Variant + Clone` - return type of the function. -* `lib` - a reference to the current collection of script-defined functions, as a [`Module`]. +* `engine : &Engine` - the current [`Engine`], with all configurations and settings. -* `args` - a reference to a slice containing `&mut` references to [`Dynamic`] values. +* `lib : &Module` - the current global library of script-defined functions, as a [`Module`]. + This is sometimes useful for calling a script-defined function within the same evaluation context using [`Engine::call_fn`][`call_fn`]. + +* `args : &mut [&mut Dynamic]` - a slice containing `&mut` references to [`Dynamic`] values. The slice is guaranteed to contain enough arguments _of the correct types_. Remember, in Rhai, all arguments _except_ the _first_ one are always passed by _value_ (i.e. cloned). @@ -100,13 +103,54 @@ To extract an argument from the `args` parameter (`&mut [&mut Dynamic]`), use th | ------------------------------ | -------------------------------------- | ---------------------------------------------------------- | | [Primary type][standard types] | `args[n].clone().cast::()` | Copy of value. | | Custom type | `args[n].downcast_ref::().unwrap()` | Immutable reference to value. | -| Custom type (consumed) | `mem::take(args[n]).cast::()` | The _consumed_ value.
The original value becomes `()`. | +| Custom type (consumed) | `std::mem::take(args[n]).cast::()` | The _consumed_ value.
The original value becomes `()`. | | `this` object | `args[0].downcast_mut::().unwrap()` | Mutable reference to value. | When there is a mutable reference to the `this` object (i.e. the first argument), there can be no other immutable references to `args`, otherwise the Rust borrow checker will complain. +Example - Passing a Function Pointer to a Rust Function +------------------------------------------------------ + +```rust +use rhai::{Engine, Module, Dynamic, FnPtr}; + +let mut engine = Engine::new(); + +// Register a Rust function +engine.register_raw_fn( + "bar", + &[ + std::any::TypeId::of::(), // parameter types + std::any::TypeId::of::(), + std::any::TypeId::of::(), + ], + move |engine: &Engine, lib: &Module, args: &mut [&mut Dynamic]| { + // 'args' is guaranteed to contain enough arguments of the correct types + + let fp = std::mem::take(args[1]).cast::(); // 2nd argument - function pointer + let value = args[2].clone(); // 3rd argument - function argument + let this_ptr = args.get_mut(0).unwrap(); // 1st argument - this pointer + + // Use 'call_fn_dynamic' to call the function name. + // Pass 'lib' as the current global library of functions. + engine.call_fn_dynamic(&mut Scope::new(), lib, fp.fn_name(), Some(this_ptr), [value])?; + + Ok(()) + }, +); + +let result = engine.eval::(r#" + fn foo(x) { this += x; } // script-defined function 'foo' + + let x = 41; // object + x.bar(Fn("foo"), 1); // pass 'foo' as function pointer + x +"#)?; +``` + + Hold Multiple References ------------------------ From d92a514f48b5f04e2c20ba0c45636146b75855bb Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Wed, 8 Jul 2020 12:09:18 +0800 Subject: [PATCH 4/5] Add reserved symbols. --- doc/src/SUMMARY.md | 2 +- doc/src/appendix/operators.md | 26 +++++- src/token.rs | 164 +++++++++++++++++++--------------- 3 files changed, 118 insertions(+), 74 deletions(-) diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index 3274e8cb..438b4590 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -110,5 +110,5 @@ The Rhai Scripting Language 7. [Eval Statement](language/eval.md) 9. [Appendix](appendix/index.md) 1. [Keywords](appendix/keywords.md) - 2. [Operators](appendix/operators.md) + 2. [Operators and Symbols](appendix/operators.md) 3. [Literals](appendix/literals.md) diff --git a/doc/src/appendix/operators.md b/doc/src/appendix/operators.md index 074205e2..3e895da9 100644 --- a/doc/src/appendix/operators.md +++ b/doc/src/appendix/operators.md @@ -1,8 +1,12 @@ -Operators -========= +Operators and Symbols +==================== {{#include ../links.md}} + +Operators +--------- + | Operator | Description | Binary? | Binding direction | | :---------------: | ------------------------------ | :-----: | :---------------: | | `+` | Add | Yes | Left | @@ -28,3 +32,21 @@ Operators | `!` | Boolean _Not_ | No | Left | | `[` .. `]` | Indexing | Yes | Right | | `.` | Property access, Method call | Yes | Right | + + +Symbols +------- + +| Symbol | Description | +| ------------ | ------------------------ | +| `:` | Property value separator | +| `::` | Module path separator | +| `=>` | _Reserved_ | +| `->` | _Reserved_ | +| `<-` | _Reserved_ | +| `===` | _Reserved_ | +| `!==` | _Reserved_ | +| `:=` | _Reserved_ | +| `::<` .. `>` | _Reserved_ | +| `@` | _Reserved_ | +| `(*` .. `*)` | _Reserved_ | diff --git a/src/token.rs b/src/token.rs index 7eb7100d..fb02f14c 100644 --- a/src/token.rs +++ b/src/token.rs @@ -213,6 +213,7 @@ pub enum Token { As, LexError(Box), Comment(String), + Reserved(String), Custom(String), EOF, } @@ -229,6 +230,7 @@ impl Token { StringConstant(_) => "string".into(), CharConstant(c) => c.to_string().into(), Identifier(s) => s.clone().into(), + Reserved(s) => s.clone().into(), Custom(s) => s.clone().into(), LexError(err) => err.to_string().into(), @@ -339,7 +341,6 @@ impl Token { UnaryMinus | Multiply | Divide | - Colon | Comma | Period | Equals | @@ -750,7 +751,9 @@ fn get_next_token_inner( } } // 0x????, 0o????, 0b???? - ch @ 'x' | ch @ 'X' | ch @ 'o' | ch @ 'O' | ch @ 'b' | ch @ 'B' if c == '0' => { + ch @ 'x' | ch @ 'X' | ch @ 'o' | ch @ 'O' | ch @ 'b' | ch @ 'B' + if c == '0' => + { result.push(next_char); eat_next(stream, pos); @@ -889,42 +892,48 @@ fn get_next_token_inner( } // " - string literal - ('"', _) => return parse_string_literal(stream, state, pos, '"') - .map_or_else( - |err| Some((Token::LexError(Box::new(err.0)), err.1)), - |out| Some((Token::StringConstant(out), start_pos)), - ), + ('"', _) => { + return parse_string_literal(stream, state, pos, '"').map_or_else( + |err| Some((Token::LexError(Box::new(err.0)), err.1)), + |out| Some((Token::StringConstant(out), start_pos)), + ) + } // ' - character literal - ('\'', '\'') => return Some(( - Token::LexError(Box::new(LERR::MalformedChar("".to_string()))), - start_pos, - )), - ('\'', _) => return Some( - parse_string_literal(stream, state, pos, '\'') - .map_or_else( - |err| (Token::LexError(Box::new(err.0)), err.1), - |result| { - let mut chars = result.chars(); - let first = chars.next(); + ('\'', '\'') => { + return Some(( + Token::LexError(Box::new(LERR::MalformedChar("".to_string()))), + start_pos, + )) + } + ('\'', _) => { + return Some(parse_string_literal(stream, state, pos, '\'').map_or_else( + |err| (Token::LexError(Box::new(err.0)), err.1), + |result| { + let mut chars = result.chars(); + let first = chars.next(); - if chars.next().is_some() { - ( - Token::LexError(Box::new(LERR::MalformedChar(result))), - start_pos, - ) - } else { - (Token::CharConstant(first.expect("should be Some")), start_pos) - } - }, - ), - ), + if chars.next().is_some() { + ( + Token::LexError(Box::new(LERR::MalformedChar(result))), + start_pos, + ) + } else { + ( + Token::CharConstant(first.expect("should be Some")), + start_pos, + ) + } + }, + )) + } // Braces ('{', _) => return Some((Token::LeftBrace, start_pos)), ('}', _) => return Some((Token::RightBrace, start_pos)), // Parentheses + ('(', '*') => return Some((Token::Reserved("(*".into()), start_pos)), ('(', _) => return Some((Token::LeftParen, start_pos)), (')', _) => return Some((Token::RightParen, start_pos)), @@ -953,15 +962,11 @@ fn get_next_token_inner( eat_next(stream, pos); return Some((Token::MinusAssign, start_pos)); } - ('-', '>') => return Some(( - Token::LexError(Box::new(LERR::ImproperSymbol( - "'->' is not a valid symbol. This is not C or C++!".to_string(), - ))), - start_pos, - )), + ('-', '>') => return Some((Token::Reserved("->".into()), start_pos)), ('-', _) if !state.non_unary => return Some((Token::UnaryMinus, start_pos)), ('-', _) => return Some((Token::Minus, start_pos)), + ('*', ')') => return Some((Token::Reserved("*)".into()), start_pos)), ('*', '=') => { eat_next(stream, pos); return Some((Token::MultiplyAssign, start_pos)); @@ -1026,49 +1031,31 @@ fn get_next_token_inner( // Warn against `===` if stream.peek_next() == Some('=') { - return Some(( - Token::LexError(Box::new(LERR::ImproperSymbol( - "'===' is not a valid operator. This is not JavaScript! Should it be '=='?" - .to_string(), - ))), - start_pos, - )); + return Some((Token::Reserved("===".into()), start_pos)); } return Some((Token::EqualsTo, start_pos)); } - ('=', '>') => return Some(( - Token::LexError(Box::new(LERR::ImproperSymbol( - "'=>' is not a valid symbol. This is not Rust! Should it be '>='?" - .to_string(), - ))), - start_pos, - )), + ('=', '>') => return Some((Token::Reserved("=>".into()), start_pos)), ('=', _) => return Some((Token::Equals, start_pos)), (':', ':') => { eat_next(stream, pos); + + if stream.peek_next() == Some('<') { + return Some((Token::Reserved("::<".into()), start_pos)); + } + return Some((Token::DoubleColon, start_pos)); } - (':', '=') => return Some(( - Token::LexError(Box::new(LERR::ImproperSymbol( - "':=' is not a valid assignment operator. This is not Pascal! Should it be simply '='?" - .to_string(), - ))), - start_pos, - )), + (':', '=') => return Some((Token::Reserved(":=".into()), start_pos)), (':', _) => return Some((Token::Colon, start_pos)), ('<', '=') => { eat_next(stream, pos); return Some((Token::LessThanEqualsTo, start_pos)); } - ('<', '-') => return Some(( - Token::LexError(Box::new(LERR::ImproperSymbol( - "'<-' is not a valid symbol. Should it be '<='?".to_string(), - ))), - start_pos, - )), + ('<', '-') => return Some((Token::Reserved("<-".into()), start_pos)), ('<', '<') => { eat_next(stream, pos); @@ -1106,15 +1093,8 @@ fn get_next_token_inner( ('!', '=') => { eat_next(stream, pos); - // Warn against `!==` if stream.peek_next() == Some('=') { - return Some(( - Token::LexError(Box::new(LERR::ImproperSymbol( - "'!==' is not a valid operator. This is not JavaScript! Should it be '!='?" - .to_string(), - ))), - start_pos, - )); + return Some((Token::Reserved("!==".into()), start_pos)); } return Some((Token::NotEqualsTo, start_pos)); @@ -1159,10 +1139,17 @@ fn get_next_token_inner( } ('~', _) => return Some((Token::PowerOf, start_pos)), + ('@', _) => return Some((Token::Reserved("@".into()), start_pos)), + ('\0', _) => unreachable!(), (ch, _) if ch.is_whitespace() => (), - (ch, _) => return Some((Token::LexError(Box::new(LERR::UnexpectedInput(ch.to_string()))), start_pos)), + (ch, _) => { + return Some(( + Token::LexError(Box::new(LERR::UnexpectedInput(ch.to_string()))), + start_pos, + )) + } } } @@ -1237,6 +1224,41 @@ impl<'a> Iterator for TokenIterator<'a, '_> { self.engine.custom_keywords.as_ref(), ) { (None, _, _) => None, + (Some((Token::Reserved(s), pos)), None, None) => return Some((match s.as_str() { + "===" => Token::LexError(Box::new(LERR::ImproperSymbol( + "'===' is not a valid operator. This is not JavaScript! Should it be '=='?" + .to_string(), + ))), + "!==" => Token::LexError(Box::new(LERR::ImproperSymbol( + "'!==' is not a valid operator. This is not JavaScript! Should it be '!='?" + .to_string(), + ))), + "->" => Token::LexError(Box::new(LERR::ImproperSymbol( + "'->' is not a valid symbol. This is not C or C++!".to_string(), + ))), + "<-" => Token::LexError(Box::new(LERR::ImproperSymbol( + "'<-' is not a valid symbol. This is not Go! Should it be '<='?".to_string(), + ))), + "=>" => Token::LexError(Box::new(LERR::ImproperSymbol( + "'=>' is not a valid symbol. This is not Rust! Should it be '>='?" + .to_string(), + ))), + ":=" => Token::LexError(Box::new(LERR::ImproperSymbol( + "':=' is not a valid assignment operator. This is not Go! Should it be simply '='?" + .to_string(), + ))), + "::<" => Token::LexError(Box::new(LERR::ImproperSymbol( + "'::<>' is not a valid symbol. This is not Rust! Should it be '::'?" + .to_string(), + ))), + "(*" | "*)" => Token::LexError(Box::new(LERR::ImproperSymbol( + "'(* .. *)' is not a valid comment style. This is not Pascal! Should it be '/* .. */'?" + .to_string(), + ))), + token => Token::LexError(Box::new(LERR::ImproperSymbol( + format!("'{}' is not a valid symbol.", token) + ))), + }, pos)), (r @ Some(_), None, None) => r, (Some((token, pos)), Some(disabled), _) if token.is_operator() && disabled.contains(token.syntax().as_ref()) => From 703cc414b871651d7674941a9fd2a171dd35d9cf Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Wed, 8 Jul 2020 13:06:00 +0800 Subject: [PATCH 5/5] Allow mutating a module-qualified function's first argument if it is a variable. --- src/engine.rs | 168 ++++++++++++++++++++++++++++++++++++----------- src/module.rs | 2 +- tests/modules.rs | 16 +++++ 3 files changed, 145 insertions(+), 41 deletions(-) diff --git a/src/engine.rs b/src/engine.rs index f999235b..297c3906 100644 --- a/src/engine.rs +++ b/src/engine.rs @@ -399,6 +399,39 @@ fn default_print(s: &str) { /// Search for a module within an imports stack. /// Position in `EvalAltResult` is None and must be set afterwards. fn search_imports<'s>( + mods: &'s Imports, + state: &mut State, + modules: &Box, +) -> Result<&'s Module, Box> { + let (root, root_pos) = modules.get(0); + + // Qualified - check if the root module is directly indexed + let index = if state.always_search { + None + } else { + modules.index() + }; + + Ok(if let Some(index) = index { + let offset = mods.len() - index.get(); + &mods.get(offset).unwrap().1 + } else { + mods.iter() + .rev() + .find(|(n, _)| n == root) + .map(|(_, m)| m) + .ok_or_else(|| { + Box::new(EvalAltResult::ErrorModuleNotFound( + root.to_string(), + *root_pos, + )) + })? + }) +} + +/// Search for a module within an imports stack. +/// Position in `EvalAltResult` is None and must be set afterwards. +fn search_imports_mut<'s>( mods: &'s mut Imports, state: &mut State, modules: &Box, @@ -429,15 +462,49 @@ fn search_imports<'s>( }) } -/// Search for a variable within the scope -fn search_scope<'s, 'a>( +/// Search for a variable within the scope and imports +fn search_namespace<'s, 'a>( scope: &'s mut Scope, mods: &'s mut Imports, state: &mut State, this_ptr: &'s mut Option<&mut Dynamic>, expr: &'a Expr, ) -> Result<(&'s mut Dynamic, &'a str, ScopeEntryType, Position), Box> { - let ((name, pos), modules, hash_var, index) = match expr { + match expr { + Expr::Variable(v) => match v.as_ref() { + // Qualified variable + ((name, pos), Some(modules), hash_var, _) => { + let module = search_imports_mut(mods, state, modules)?; + let target = module + .get_qualified_var_mut(*hash_var) + .map_err(|err| match *err { + EvalAltResult::ErrorVariableNotFound(_, _) => { + Box::new(EvalAltResult::ErrorVariableNotFound( + format!("{}{}", modules, name), + *pos, + )) + } + _ => err.new_position(*pos), + })?; + + // Module variables are constant + Ok((target, name, ScopeEntryType::Constant, *pos)) + } + // Normal variable access + _ => search_scope_only(scope, state, this_ptr, expr), + }, + _ => unreachable!(), + } +} + +/// Search for a variable within the scope +fn search_scope_only<'s, 'a>( + scope: &'s mut Scope, + state: &mut State, + this_ptr: &'s mut Option<&mut Dynamic>, + expr: &'a Expr, +) -> Result<(&'s mut Dynamic, &'a str, ScopeEntryType, Position), Box> { + let ((name, pos), _, _, index) = match expr { Expr::Variable(v) => v.as_ref(), _ => unreachable!(), }; @@ -451,37 +518,21 @@ fn search_scope<'s, 'a>( } } - // Check if it is qualified - if let Some(modules) = modules { - let module = search_imports(mods, state, modules)?; - let target = module - .get_qualified_var_mut(*hash_var) - .map_err(|err| match *err { - EvalAltResult::ErrorVariableNotFound(_, _) => Box::new( - EvalAltResult::ErrorVariableNotFound(format!("{}{}", modules, name), *pos), - ), - _ => err.new_position(*pos), - })?; + // Check if it is directly indexed + let index = if state.always_search { None } else { *index }; - // Module variables are constant - Ok((target, name, ScopeEntryType::Constant, *pos)) + let index = if let Some(index) = index { + scope.len() - index.get() } else { - // Unqualified - check if it is directly indexed - let index = if state.always_search { None } else { *index }; + // Find the variable in the scope + scope + .get_index(name) + .ok_or_else(|| Box::new(EvalAltResult::ErrorVariableNotFound(name.into(), *pos)))? + .0 + }; - let index = if let Some(index) = index { - scope.len() - index.get() - } else { - // Find the variable in the scope - scope - .get_index(name) - .ok_or_else(|| Box::new(EvalAltResult::ErrorVariableNotFound(name.into(), *pos)))? - .0 - }; - - let (val, typ) = scope.get_mut(index); - Ok((val, name, typ, *pos)) - } + let (val, typ) = scope.get_mut(index); + Ok((val, name, typ, *pos)) } impl Engine { @@ -1276,7 +1327,8 @@ impl Engine { self.inc_operations(state) .map_err(|err| err.new_position(*var_pos))?; - let (target, _, typ, pos) = search_scope(scope, mods, state, this_ptr, dot_lhs)?; + let (target, _, typ, pos) = + search_namespace(scope, mods, state, this_ptr, dot_lhs)?; // Constants cannot be modified match typ { @@ -1573,7 +1625,7 @@ impl Engine { } } Expr::Variable(_) => { - let (val, _, _, _) = search_scope(scope, mods, state, this_ptr, expr)?; + let (val, _, _, _) = search_namespace(scope, mods, state, this_ptr, expr)?; Ok(val.clone()) } Expr::Property(_) => unreachable!(), @@ -1587,7 +1639,7 @@ impl Engine { let mut rhs_val = self.eval_expr(scope, mods, state, lib, this_ptr, rhs_expr, level)?; let (lhs_ptr, name, typ, pos) = - search_scope(scope, mods, state, this_ptr, lhs_expr)?; + search_namespace(scope, mods, state, this_ptr, lhs_expr)?; self.inc_operations(state) .map_err(|err| err.new_position(pos))?; @@ -1800,7 +1852,7 @@ impl Engine { .collect::>()?; let (target, _, _, pos) = - search_scope(scope, mods, state, this_ptr, lhs)?; + search_namespace(scope, mods, state, this_ptr, lhs)?; self.inc_operations(state) .map_err(|err| err.new_position(pos))?; @@ -1836,12 +1888,48 @@ impl Engine { let ((name, _, pos), modules, hash_script, args_expr, def_val) = x.as_ref(); let modules = modules.as_ref().unwrap(); - let mut arg_values = args_expr - .iter() - .map(|expr| self.eval_expr(scope, mods, state, lib, this_ptr, expr, level)) - .collect::, _>>()?; + let mut arg_values: StaticVec; + let mut args: StaticVec<_>; - let mut args: StaticVec<_> = arg_values.iter_mut().collect(); + if args_expr.is_empty() { + // No arguments + args = Default::default(); + } else { + // See if the first argument is a variable (not module-qualified). + // If so, convert to method-call style in order to leverage potential + // &mut first argument and avoid cloning the value + match args_expr.get(0) { + // func(x, ...) -> x.func(...) + Expr::Variable(x) if x.1.is_none() => { + arg_values = args_expr + .iter() + .skip(1) + .map(|expr| { + self.eval_expr(scope, mods, state, lib, this_ptr, expr, level) + }) + .collect::>()?; + + let (target, _, _, pos) = + search_scope_only(scope, state, this_ptr, args_expr.get(0))?; + + self.inc_operations(state) + .map_err(|err| err.new_position(pos))?; + + args = once(target).chain(arg_values.iter_mut()).collect(); + } + // func(..., ...) or func(mod::x, ...) + _ => { + arg_values = args_expr + .iter() + .map(|expr| { + self.eval_expr(scope, mods, state, lib, this_ptr, expr, level) + }) + .collect::>()?; + + args = arg_values.iter_mut().collect(); + } + } + } let module = search_imports(mods, state, modules)?; diff --git a/src/module.rs b/src/module.rs index 9fa9f9a7..7181e4d7 100644 --- a/src/module.rs +++ b/src/module.rs @@ -849,7 +849,7 @@ impl Module { /// The `u64` hash is calculated by the function `crate::calc_fn_hash` and must match /// the hash calculated by `index_all_sub_modules`. pub(crate) fn get_qualified_fn( - &mut self, + &self, hash_qualified_fn: u64, ) -> Result<&Func, Box> { self.all_functions.get(&hash_qualified_fn).ok_or_else(|| { diff --git a/tests/modules.rs b/tests/modules.rs index 0e1eb3ba..479ec429 100644 --- a/tests/modules.rs +++ b/tests/modules.rs @@ -73,6 +73,10 @@ fn test_module_resolver() -> Result<(), Box> { module.set_fn_4("sum".to_string(), |x: INT, y: INT, z: INT, w: INT| { Ok(x + y + z + w) }); + module.set_fn_1_mut("double".to_string(), |x: &mut INT| { + *x *= 2; + Ok(()) + }); resolver.insert("hello", module); @@ -90,6 +94,18 @@ fn test_module_resolver() -> Result<(), Box> { 42 ); + assert_eq!( + engine.eval::( + r#" + import "hello" as h; + let x = 21; + h::double(x); + x + "# + )?, + 42 + ); + #[cfg(not(feature = "unchecked"))] { engine.set_max_modules(5);