2020-03-08 12:54:02 +01:00
|
|
|
//! Module which defines the function registration mechanism.
|
2016-02-29 22:43:45 +01:00
|
|
|
|
2020-03-18 05:04:26 +01:00
|
|
|
#![allow(non_snake_case)]
|
|
|
|
|
2020-04-12 17:00:06 +02:00
|
|
|
use crate::any::{Dynamic, Variant};
|
2020-04-20 06:43:34 +02:00
|
|
|
use crate::engine::{calc_fn_spec, Engine, FnCallArgs};
|
2020-03-04 15:00:01 +01:00
|
|
|
use crate::result::EvalAltResult;
|
2020-04-15 16:21:23 +02:00
|
|
|
use crate::token::Position;
|
2020-03-18 15:03:50 +01:00
|
|
|
|
2020-04-20 06:43:34 +02:00
|
|
|
use crate::stdlib::{any::TypeId, boxed::Box, string::ToString};
|
2016-02-29 22:43:45 +01:00
|
|
|
|
2020-03-04 15:00:01 +01:00
|
|
|
/// A trait to register custom functions with the `Engine`.
|
2017-12-20 12:16:14 +01:00
|
|
|
pub trait RegisterFn<FN, ARGS, RET> {
|
2020-03-04 15:00:01 +01:00
|
|
|
/// Register a custom function with the `Engine`.
|
2020-03-19 06:52:10 +01:00
|
|
|
///
|
|
|
|
/// # Example
|
|
|
|
///
|
|
|
|
/// ```
|
|
|
|
/// # fn main() -> Result<(), rhai::EvalAltResult> {
|
|
|
|
/// use rhai::{Engine, RegisterFn};
|
|
|
|
///
|
|
|
|
/// // Normal function
|
|
|
|
/// fn add(x: i64, y: i64) -> i64 {
|
|
|
|
/// x + y
|
|
|
|
/// }
|
|
|
|
///
|
|
|
|
/// let mut engine = Engine::new();
|
|
|
|
///
|
|
|
|
/// // You must use the trait rhai::RegisterFn to get this method.
|
|
|
|
/// engine.register_fn("add", add);
|
|
|
|
///
|
|
|
|
/// assert_eq!(engine.eval::<i64>("add(40, 2)")?, 42);
|
|
|
|
///
|
|
|
|
/// // You can also register a closure.
|
|
|
|
/// engine.register_fn("sub", |x: i64, y: i64| x - y );
|
|
|
|
///
|
|
|
|
/// assert_eq!(engine.eval::<i64>("sub(44, 2)")?, 42);
|
|
|
|
/// # Ok(())
|
|
|
|
/// # }
|
|
|
|
/// ```
|
2017-12-20 12:16:14 +01:00
|
|
|
fn register_fn(&mut self, name: &str, f: FN);
|
2016-02-29 22:43:45 +01:00
|
|
|
}
|
2020-03-04 15:00:01 +01:00
|
|
|
|
|
|
|
/// A trait to register custom functions that return `Dynamic` values with the `Engine`.
|
2020-02-28 16:38:39 +01:00
|
|
|
pub trait RegisterDynamicFn<FN, ARGS> {
|
2020-03-04 15:00:01 +01:00
|
|
|
/// Register a custom function returning `Dynamic` values with the `Engine`.
|
2020-03-19 06:52:10 +01:00
|
|
|
///
|
|
|
|
/// # Example
|
|
|
|
///
|
|
|
|
/// ```
|
|
|
|
/// # fn main() -> Result<(), rhai::EvalAltResult> {
|
|
|
|
/// use rhai::{Engine, Dynamic, RegisterDynamicFn};
|
|
|
|
///
|
|
|
|
/// // Function that returns a Dynamic value
|
|
|
|
/// fn return_the_same_as_dynamic(x: i64) -> Dynamic {
|
2020-04-12 17:00:06 +02:00
|
|
|
/// Dynamic::from(x)
|
2020-03-19 06:52:10 +01:00
|
|
|
/// }
|
|
|
|
///
|
|
|
|
/// let mut engine = Engine::new();
|
|
|
|
///
|
|
|
|
/// // You must use the trait rhai::RegisterDynamicFn to get this method.
|
|
|
|
/// engine.register_dynamic_fn("get_any_number", return_the_same_as_dynamic);
|
|
|
|
///
|
|
|
|
/// assert_eq!(engine.eval::<i64>("get_any_number(42)")?, 42);
|
|
|
|
/// # Ok(())
|
|
|
|
/// # }
|
|
|
|
/// ```
|
2020-02-25 08:02:27 +01:00
|
|
|
fn register_dynamic_fn(&mut self, name: &str, f: FN);
|
2020-02-23 15:48:46 +01:00
|
|
|
}
|
2016-02-29 22:43:45 +01:00
|
|
|
|
2020-03-08 15:47:13 +01:00
|
|
|
/// A trait to register fallible custom functions returning Result<_, EvalAltResult> with the `Engine`.
|
|
|
|
pub trait RegisterResultFn<FN, ARGS, RET> {
|
2020-03-19 06:52:10 +01:00
|
|
|
/// Register a custom fallible function with the `Engine`.
|
|
|
|
///
|
|
|
|
/// # Example
|
|
|
|
///
|
|
|
|
/// ```
|
|
|
|
/// use rhai::{Engine, RegisterResultFn, EvalAltResult};
|
|
|
|
///
|
|
|
|
/// // Normal function
|
|
|
|
/// fn div(x: i64, y: i64) -> Result<i64, EvalAltResult> {
|
|
|
|
/// if y == 0 {
|
2020-03-25 04:24:06 +01:00
|
|
|
/// // '.into()' automatically converts to 'EvalAltResult::ErrorRuntime'
|
|
|
|
/// Err("division by zero!".into())
|
2020-03-19 06:52:10 +01:00
|
|
|
/// } else {
|
|
|
|
/// Ok(x / y)
|
|
|
|
/// }
|
|
|
|
/// }
|
|
|
|
///
|
|
|
|
/// let mut engine = Engine::new();
|
|
|
|
///
|
|
|
|
/// // You must use the trait rhai::RegisterResultFn to get this method.
|
|
|
|
/// engine.register_result_fn("div", div);
|
|
|
|
///
|
|
|
|
/// engine.eval::<i64>("div(42, 0)")
|
|
|
|
/// .expect_err("expecting division by zero error!");
|
|
|
|
/// ```
|
2020-03-08 15:47:13 +01:00
|
|
|
fn register_result_fn(&mut self, name: &str, f: FN);
|
|
|
|
}
|
|
|
|
|
2020-03-25 04:24:06 +01:00
|
|
|
// These types are used to build a unique _marker_ tuple type for each combination
|
|
|
|
// of function parameter types in order to make each trait implementation unique.
|
2020-03-25 10:21:58 +01:00
|
|
|
// That is because stable Rust currently does not allow distinguishing implementations
|
|
|
|
// based purely on parameter types of traits (Fn, FnOnce and FnMut).
|
2020-03-25 04:24:06 +01:00
|
|
|
//
|
|
|
|
// For example:
|
|
|
|
//
|
|
|
|
// `RegisterFn<FN, (Mut<A>, B, Ref<C>), R>`
|
|
|
|
//
|
|
|
|
// will have the function prototype constraint to:
|
|
|
|
//
|
|
|
|
// `FN: (&mut A, B, &C) -> R`
|
|
|
|
//
|
|
|
|
// These types are not actually used anywhere.
|
2020-03-25 10:21:58 +01:00
|
|
|
pub struct Mut<T>(T);
|
|
|
|
//pub struct Ref<T>(T);
|
2016-04-17 04:32:18 +02:00
|
|
|
|
2020-03-25 04:24:06 +01:00
|
|
|
/// Identity dereferencing function.
|
2020-03-24 09:57:35 +01:00
|
|
|
#[inline]
|
2020-04-20 18:11:25 +02:00
|
|
|
pub fn identity<T>(data: &mut T) -> &mut T {
|
2020-03-24 09:57:35 +01:00
|
|
|
data
|
|
|
|
}
|
|
|
|
|
2020-04-20 18:11:25 +02:00
|
|
|
/// Clone dereferencing function.
|
|
|
|
#[inline]
|
|
|
|
pub fn cloned<T: Clone>(data: &mut T) -> T {
|
|
|
|
data.clone()
|
|
|
|
}
|
|
|
|
|
2020-03-25 04:24:06 +01:00
|
|
|
/// This macro counts the number of arguments via recursion.
|
2017-12-20 12:16:14 +01:00
|
|
|
macro_rules! count_args {
|
2020-03-04 16:06:05 +01:00
|
|
|
() => { 0_usize };
|
|
|
|
( $head:ident $($tail:ident)* ) => { 1_usize + count_args!($($tail)*) };
|
2016-03-02 16:49:24 +01:00
|
|
|
}
|
|
|
|
|
2020-04-19 16:58:44 +02:00
|
|
|
/// This macro creates a closure wrapping a registered function.
|
|
|
|
macro_rules! make_func {
|
|
|
|
($fn_name:ident : $fn:ident : $map:expr ; $($par:ident => $clone:expr),*) => {
|
|
|
|
// ^ function name
|
|
|
|
// ^ function pointer
|
|
|
|
// ^ result mapping function
|
|
|
|
// ^ function parameter generic type name (A, B, C etc.)
|
|
|
|
// ^ dereferencing function
|
|
|
|
|
|
|
|
move |args: &mut FnCallArgs, pos: Position| {
|
|
|
|
// Check for length at the beginning to avoid per-element bound checks.
|
|
|
|
const NUM_ARGS: usize = count_args!($($par)*);
|
|
|
|
|
|
|
|
if args.len() != NUM_ARGS {
|
|
|
|
return Err(Box::new(EvalAltResult::ErrorFunctionArgsMismatch($fn_name.clone(), NUM_ARGS, args.len(), pos)));
|
|
|
|
}
|
|
|
|
|
|
|
|
#[allow(unused_variables, unused_mut)]
|
|
|
|
let mut drain = args.iter_mut();
|
|
|
|
$(
|
|
|
|
// Downcast every element, return in case of a type mismatch
|
|
|
|
let $par: &mut $par = drain.next().unwrap().downcast_mut().unwrap();
|
|
|
|
)*
|
|
|
|
|
|
|
|
// Call the user-supplied function using ($clone) to
|
|
|
|
// potentially clone the value, otherwise pass the reference.
|
|
|
|
let r = $fn($(($clone)($par)),*);
|
|
|
|
$map(r, pos)
|
|
|
|
};
|
|
|
|
};
|
|
|
|
}
|
|
|
|
|
|
|
|
/// To Dynamic mapping function.
|
|
|
|
#[inline]
|
2020-04-20 06:43:34 +02:00
|
|
|
pub fn map_dynamic<T: Variant + Clone>(
|
|
|
|
data: T,
|
|
|
|
_pos: Position,
|
|
|
|
) -> Result<Dynamic, Box<EvalAltResult>> {
|
2020-04-19 16:58:44 +02:00
|
|
|
Ok(data.into_dynamic())
|
|
|
|
}
|
|
|
|
|
|
|
|
/// To Dynamic mapping function.
|
|
|
|
#[inline]
|
2020-04-20 06:43:34 +02:00
|
|
|
pub fn map_identity(data: Dynamic, _pos: Position) -> Result<Dynamic, Box<EvalAltResult>> {
|
2020-04-19 16:58:44 +02:00
|
|
|
Ok(data)
|
|
|
|
}
|
|
|
|
|
|
|
|
/// To Result<Dynamic, EvalAltResult> mapping function.
|
|
|
|
#[inline]
|
2020-04-20 06:43:34 +02:00
|
|
|
pub fn map_result<T: Variant + Clone>(
|
2020-04-19 16:58:44 +02:00
|
|
|
data: Result<T, EvalAltResult>,
|
|
|
|
pos: Position,
|
|
|
|
) -> Result<Dynamic, Box<EvalAltResult>> {
|
|
|
|
data.map(|v| v.into_dynamic())
|
|
|
|
.map_err(|err| Box::new(err.set_position(pos)))
|
|
|
|
}
|
|
|
|
|
2017-12-20 12:16:14 +01:00
|
|
|
macro_rules! def_register {
|
|
|
|
() => {
|
|
|
|
def_register!(imp);
|
|
|
|
};
|
|
|
|
(imp $($par:ident => $mark:ty => $param:ty => $clone:expr),*) => {
|
2020-04-09 12:45:49 +02:00
|
|
|
// ^ function parameter generic type name (A, B, C etc.)
|
2020-03-25 10:21:58 +01:00
|
|
|
// ^ function parameter marker type (T, Ref<T> or Mut<T>)
|
2020-04-09 12:45:49 +02:00
|
|
|
// ^ function parameter actual type (T, &T or &mut T)
|
2020-03-25 04:24:06 +01:00
|
|
|
// ^ dereferencing function
|
2020-02-25 08:02:27 +01:00
|
|
|
impl<
|
2020-04-12 17:00:06 +02:00
|
|
|
$($par: Variant + Clone,)*
|
2020-04-03 11:17:00 +02:00
|
|
|
|
|
|
|
#[cfg(feature = "sync")]
|
|
|
|
FN: Fn($($param),*) -> RET + Send + Sync + 'static,
|
|
|
|
|
|
|
|
#[cfg(not(feature = "sync"))]
|
2017-12-20 12:16:14 +01:00
|
|
|
FN: Fn($($param),*) -> RET + 'static,
|
2020-04-03 11:17:00 +02:00
|
|
|
|
2020-04-12 17:00:06 +02:00
|
|
|
RET: Variant + Clone
|
2020-04-16 17:31:48 +02:00
|
|
|
> RegisterFn<FN, ($($mark,)*), RET> for Engine
|
2017-12-20 12:16:14 +01:00
|
|
|
{
|
|
|
|
fn register_fn(&mut self, name: &str, f: FN) {
|
2020-03-02 05:08:03 +01:00
|
|
|
let fn_name = name.to_string();
|
2020-04-19 16:58:44 +02:00
|
|
|
let func = make_func!(fn_name : f : map_dynamic ; $($par => $clone),*);
|
2020-04-20 06:43:34 +02:00
|
|
|
let hash = calc_fn_spec(name, [$(TypeId::of::<$par>()),*].iter().cloned());
|
|
|
|
self.functions.insert(hash, Box::new(func));
|
2020-02-23 15:48:46 +01:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2020-02-25 08:02:27 +01:00
|
|
|
impl<
|
2020-04-12 17:00:06 +02:00
|
|
|
$($par: Variant + Clone,)*
|
2020-04-03 11:17:00 +02:00
|
|
|
|
|
|
|
#[cfg(feature = "sync")]
|
|
|
|
FN: Fn($($param),*) -> Dynamic + Send + Sync + 'static,
|
|
|
|
|
|
|
|
#[cfg(not(feature = "sync"))]
|
2020-02-25 08:02:27 +01:00
|
|
|
FN: Fn($($param),*) -> Dynamic + 'static,
|
2020-04-16 17:31:48 +02:00
|
|
|
> RegisterDynamicFn<FN, ($($mark,)*)> for Engine
|
2020-02-23 15:48:46 +01:00
|
|
|
{
|
2020-02-25 08:02:27 +01:00
|
|
|
fn register_dynamic_fn(&mut self, name: &str, f: FN) {
|
2020-03-02 05:08:03 +01:00
|
|
|
let fn_name = name.to_string();
|
2020-04-19 16:58:44 +02:00
|
|
|
let func = make_func!(fn_name : f : map_identity ; $($par => $clone),*);
|
2020-04-20 06:43:34 +02:00
|
|
|
let hash = calc_fn_spec(name, [$(TypeId::of::<$par>()),*].iter().cloned());
|
|
|
|
self.functions.insert(hash, Box::new(func));
|
2017-12-20 12:16:14 +01:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2020-03-08 15:47:13 +01:00
|
|
|
impl<
|
2020-04-12 17:00:06 +02:00
|
|
|
$($par: Variant + Clone,)*
|
2020-04-03 11:17:00 +02:00
|
|
|
|
|
|
|
#[cfg(feature = "sync")]
|
|
|
|
FN: Fn($($param),*) -> Result<RET, EvalAltResult> + Send + Sync + 'static,
|
|
|
|
#[cfg(not(feature = "sync"))]
|
2020-03-08 15:47:13 +01:00
|
|
|
FN: Fn($($param),*) -> Result<RET, EvalAltResult> + 'static,
|
2020-04-03 11:17:00 +02:00
|
|
|
|
2020-04-12 17:00:06 +02:00
|
|
|
RET: Variant + Clone
|
2020-04-16 17:31:48 +02:00
|
|
|
> RegisterResultFn<FN, ($($mark,)*), RET> for Engine
|
2020-03-08 15:47:13 +01:00
|
|
|
{
|
|
|
|
fn register_result_fn(&mut self, name: &str, f: FN) {
|
|
|
|
let fn_name = name.to_string();
|
2020-04-19 16:58:44 +02:00
|
|
|
let func = make_func!(fn_name : f : map_result ; $($par => $clone),*);
|
2020-04-20 06:43:34 +02:00
|
|
|
let hash = calc_fn_spec(name, [$(TypeId::of::<$par>()),*].iter().cloned());
|
|
|
|
self.functions.insert(hash, Box::new(func));
|
2020-03-08 15:47:13 +01:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2017-12-20 12:16:14 +01:00
|
|
|
//def_register!(imp_pop $($par => $mark => $param),*);
|
|
|
|
};
|
|
|
|
($p0:ident $(, $p:ident)*) => {
|
2020-04-20 18:11:25 +02:00
|
|
|
def_register!(imp $p0 => $p0 => $p0 => cloned $(, $p => $p => $p => cloned)*);
|
|
|
|
def_register!(imp $p0 => Mut<$p0> => &mut $p0 => identity $(, $p => $p => $p => cloned)*);
|
2020-03-25 04:24:06 +01:00
|
|
|
// handle the first parameter ^ first parameter passed through
|
2020-04-09 12:45:49 +02:00
|
|
|
// ^ others passed by value (cloned)
|
2017-12-20 12:16:14 +01:00
|
|
|
|
2020-04-09 12:45:49 +02:00
|
|
|
// Currently does not support first argument which is a reference, as there will be
|
|
|
|
// conflicting implementations since &T: Any and T: Any cannot be distinguished
|
2020-03-25 10:21:58 +01:00
|
|
|
//def_register!(imp $p0 => Ref<$p0> => &$p0 => identity $(, $p => $p => $p => Clone::clone)*);
|
|
|
|
|
2017-12-20 12:16:14 +01:00
|
|
|
def_register!($($p),*);
|
|
|
|
};
|
2016-03-02 16:49:24 +01:00
|
|
|
}
|
|
|
|
|
2020-03-24 09:57:35 +01:00
|
|
|
#[rustfmt::skip]
|
2020-03-25 10:21:58 +01:00
|
|
|
def_register!(A, B, C, D, E, F, G, H, J, K, L, M, N, P, Q, R, S, T, U, V);
|