rhai/src/api.rs

1548 lines
52 KiB
Rust
Raw Normal View History

2020-03-08 12:54:02 +01:00
//! Module that defines the extern API of `Engine`.
2020-04-12 17:00:06 +02:00
use crate::any::{Dynamic, Variant};
2020-07-04 10:21:15 +02:00
use crate::engine::{make_getter, make_setter, Engine, Imports, State, FN_IDX_GET, FN_IDX_SET};
2020-03-04 15:00:01 +01:00
use crate::error::ParseError;
use crate::fn_call::FuncArgs;
2020-05-21 11:11:01 +02:00
use crate::fn_native::{IteratorFn, SendSync};
2020-03-04 15:00:01 +01:00
use crate::fn_register::RegisterFn;
2020-07-07 16:59:23 +02:00
use crate::module::{FuncReturn, Module};
2020-04-10 06:16:39 +02:00
use crate::optimize::{optimize_into_ast, OptimizationLevel};
2020-06-03 04:44:36 +02:00
use crate::parser::AST;
2020-03-04 15:00:01 +01:00
use crate::result::EvalAltResult;
2020-03-03 08:20:20 +01:00
use crate::scope::Scope;
use crate::token::{lex, Position};
use crate::utils::StaticVec;
#[cfg(not(feature = "no_object"))]
use crate::engine::Map;
2020-07-04 10:21:15 +02:00
#[cfg(not(feature = "no_function"))]
use crate::engine::get_script_function_by_signature;
2020-03-17 19:26:11 +01:00
use crate::stdlib::{
2020-03-10 03:07:44 +01:00
any::{type_name, TypeId},
2020-03-17 19:26:11 +01:00
boxed::Box,
2020-05-05 09:00:10 +02:00
mem,
2020-03-17 19:26:11 +01:00
string::{String, ToString},
2020-03-10 03:07:44 +01:00
};
2020-05-12 10:32:22 +02:00
#[cfg(not(feature = "no_std"))]
2020-06-16 17:47:31 +02:00
#[cfg(not(target_arch = "wasm32"))]
2020-03-17 19:26:11 +01:00
use crate::stdlib::{fs::File, io::prelude::*, path::PathBuf};
2020-04-03 11:17:00 +02:00
/// Engine public API
2020-04-16 17:31:48 +02:00
impl Engine {
2020-07-06 06:06:57 +02:00
/// Register a function of the `Engine`.
2020-07-05 17:08:44 +02:00
///
/// ## WARNING - Low Level API
///
/// This function is very low level. It takes a list of `TypeId`'s indicating the actual types of the parameters.
///
2020-07-07 16:59:23 +02:00
/// Arguments are simply passed in as a mutable array of `&mut Dynamic`,
2020-07-05 17:08:44 +02:00
/// The arguments are guaranteed to be of the correct types matching the `TypeId`'s.
///
2020-07-07 16:59:23 +02:00
/// To access a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::<T>()`
2020-07-05 17:08:44 +02:00
///
2020-07-07 16:59:23 +02:00
/// To access a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::<T>()`.
2020-07-05 17:08:44 +02:00
/// Notice that this will _consume_ the argument, replacing it with `()`.
///
2020-07-07 16:59:23 +02:00
/// To access the first mutable parameter, use `args.get_mut(0).unwrap()`
2020-07-05 17:08:44 +02:00
#[deprecated(note = "this function is volatile and may change")]
2020-07-07 16:59:23 +02:00
pub fn register_raw_fn<T: Variant + Clone>(
2020-07-05 17:08:44 +02:00
&mut self,
name: &str,
2020-07-06 06:06:57 +02:00
arg_types: &[TypeId],
2020-07-07 16:59:23 +02:00
func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn<T> + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self {
2020-07-07 16:59:23 +02:00
self.global_module.set_raw_fn(name, arg_types, func);
2020-07-12 05:46:53 +02:00
self
2020-07-06 06:06:57 +02:00
}
/// Register a function of no parameters with the `Engine`.
///
/// ## WARNING - Low Level API
///
/// This function is very low level.
#[deprecated(note = "this function is volatile and may change")]
2020-07-07 16:59:23 +02:00
pub fn register_raw_fn_0<T: Variant + Clone>(
2020-07-06 06:06:57 +02:00
&mut self,
name: &str,
2020-07-07 16:59:23 +02:00
func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn<T> + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self {
2020-07-07 16:59:23 +02:00
self.global_module.set_raw_fn(name, &[], func);
2020-07-12 05:46:53 +02:00
self
2020-07-06 06:06:57 +02:00
}
/// Register a function of one parameter with the `Engine`.
///
/// ## WARNING - Low Level API
///
/// This function is very low level.
///
2020-07-07 16:59:23 +02:00
/// Arguments are simply passed in as a mutable array of `&mut Dynamic`,
/// which is guaranteed to contain enough arguments of the correct types.
2020-07-06 06:06:57 +02:00
///
2020-07-07 16:59:23 +02:00
/// To access a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::<T>()`
2020-07-06 06:06:57 +02:00
///
2020-07-07 16:59:23 +02:00
/// To access a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::<T>()`.
2020-07-06 06:06:57 +02:00
/// Notice that this will _consume_ the argument, replacing it with `()`.
///
2020-07-07 16:59:23 +02:00
/// To access the first mutable parameter, use `args.get_mut(0).unwrap()`
2020-07-06 06:06:57 +02:00
#[deprecated(note = "this function is volatile and may change")]
2020-07-07 16:59:23 +02:00
pub fn register_raw_fn_1<A: Variant + Clone, T: Variant + Clone>(
2020-07-06 06:06:57 +02:00
&mut self,
name: &str,
2020-07-07 16:59:23 +02:00
func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn<T> + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self {
2020-07-06 06:06:57 +02:00
self.global_module
2020-07-07 16:59:23 +02:00
.set_raw_fn(name, &[TypeId::of::<A>()], func);
2020-07-12 05:46:53 +02:00
self
2020-07-06 06:06:57 +02:00
}
/// Register a function of two parameters with the `Engine`.
///
/// ## WARNING - Low Level API
///
/// This function is very low level.
///
2020-07-07 16:59:23 +02:00
/// Arguments are simply passed in as a mutable array of `&mut Dynamic`,
/// which is guaranteed to contain enough arguments of the correct types.
2020-07-06 06:06:57 +02:00
///
2020-07-07 16:59:23 +02:00
/// To access a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::<T>()`
2020-07-06 06:06:57 +02:00
///
2020-07-07 16:59:23 +02:00
/// To access a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::<T>()`.
2020-07-06 06:06:57 +02:00
/// Notice that this will _consume_ the argument, replacing it with `()`.
///
2020-07-07 16:59:23 +02:00
/// To access the first mutable parameter, use `args.get_mut(0).unwrap()`
2020-07-06 06:06:57 +02:00
#[deprecated(note = "this function is volatile and may change")]
2020-07-07 16:59:23 +02:00
pub fn register_raw_fn_2<A: Variant + Clone, B: Variant + Clone, T: Variant + Clone>(
2020-07-06 06:06:57 +02:00
&mut self,
name: &str,
2020-07-07 16:59:23 +02:00
func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn<T> + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self {
2020-07-06 06:06:57 +02:00
self.global_module
2020-07-07 16:59:23 +02:00
.set_raw_fn(name, &[TypeId::of::<A>(), TypeId::of::<B>()], func);
2020-07-12 05:46:53 +02:00
self
2020-07-06 06:06:57 +02:00
}
/// Register a function of three parameters with the `Engine`.
///
/// ## WARNING - Low Level API
///
/// This function is very low level.
///
2020-07-07 16:59:23 +02:00
/// Arguments are simply passed in as a mutable array of `&mut Dynamic`,
/// which is guaranteed to contain enough arguments of the correct types.
2020-07-06 06:06:57 +02:00
///
2020-07-07 16:59:23 +02:00
/// To access a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::<T>()`
2020-07-06 06:06:57 +02:00
///
2020-07-07 16:59:23 +02:00
/// To access a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::<T>()`.
2020-07-06 06:06:57 +02:00
/// Notice that this will _consume_ the argument, replacing it with `()`.
///
2020-07-07 16:59:23 +02:00
/// To access the first mutable parameter, use `args.get_mut(0).unwrap()`
2020-07-06 06:06:57 +02:00
#[deprecated(note = "this function is volatile and may change")]
2020-07-07 16:59:23 +02:00
pub fn register_raw_fn_3<
A: Variant + Clone,
B: Variant + Clone,
C: Variant + Clone,
T: Variant + Clone,
>(
2020-07-06 06:06:57 +02:00
&mut self,
name: &str,
2020-07-07 16:59:23 +02:00
func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn<T> + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self {
2020-07-07 16:59:23 +02:00
self.global_module.set_raw_fn(
2020-07-06 06:06:57 +02:00
name,
&[TypeId::of::<A>(), TypeId::of::<B>(), TypeId::of::<C>()],
func,
);
2020-07-12 05:46:53 +02:00
self
2020-07-06 06:06:57 +02:00
}
/// Register a function of four parameters with the `Engine`.
///
/// ## WARNING - Low Level API
///
/// This function is very low level.
///
2020-07-07 16:59:23 +02:00
/// Arguments are simply passed in as a mutable array of `&mut Dynamic`,
/// which is guaranteed to contain enough arguments of the correct types.
2020-07-06 06:06:57 +02:00
///
2020-07-07 16:59:23 +02:00
/// To access a primary parameter value (i.e. cloning is cheap), use: `args[n].clone().cast::<T>()`
2020-07-06 06:06:57 +02:00
///
2020-07-07 16:59:23 +02:00
/// To access a parameter value and avoid cloning, use `std::mem::take(args[n]).cast::<T>()`.
2020-07-06 06:06:57 +02:00
/// Notice that this will _consume_ the argument, replacing it with `()`.
///
2020-07-07 16:59:23 +02:00
/// To access the first mutable parameter, use `args.get_mut(0).unwrap()`
2020-07-06 06:06:57 +02:00
#[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,
2020-07-07 16:59:23 +02:00
T: Variant + Clone,
2020-07-06 06:06:57 +02:00
>(
&mut self,
name: &str,
2020-07-07 16:59:23 +02:00
func: impl Fn(&Engine, &Module, &mut [&mut Dynamic]) -> FuncReturn<T> + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self {
2020-07-07 16:59:23 +02:00
self.global_module.set_raw_fn(
2020-07-06 06:06:57 +02:00
name,
&[
TypeId::of::<A>(),
TypeId::of::<B>(),
TypeId::of::<C>(),
TypeId::of::<D>(),
],
func,
);
2020-07-12 05:46:53 +02:00
self
2020-07-05 17:08:44 +02:00
}
2020-03-04 15:00:01 +01:00
/// Register a custom type for use with the `Engine`.
2020-03-19 06:52:10 +01:00
/// The type must implement `Clone`.
///
/// # Example
///
/// ```
2020-03-30 10:10:50 +02:00
/// #[derive(Debug, Clone, Eq, PartialEq)]
2020-03-19 06:52:10 +01:00
/// struct TestStruct {
/// field: i64
/// }
///
/// impl TestStruct {
2020-03-22 03:18:16 +01:00
/// fn new() -> Self { TestStruct { field: 1 } }
/// fn update(&mut self, offset: i64) { self.field += offset; }
2020-03-19 06:52:10 +01:00
/// }
///
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::{Engine, RegisterFn};
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
2020-03-22 03:18:16 +01:00
/// // Use `register_fn` to register methods on the type.
2020-03-19 06:52:10 +01:00
/// engine.register_fn("update", TestStruct::update);
///
/// assert_eq!(
2020-03-30 10:10:50 +02:00
/// engine.eval::<TestStruct>("let x = new_ts(); x.update(41); x")?,
/// TestStruct { field: 42 }
2020-03-19 06:52:10 +01:00
/// );
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
2020-07-12 05:46:53 +02:00
pub fn register_type<T: Variant + Clone>(&mut self) -> &mut Self {
self.register_type_with_name::<T>(type_name::<T>())
2020-03-04 15:00:01 +01:00
}
2020-03-19 06:52:10 +01:00
/// Register a custom type for use with the `Engine`, with a pretty-print name
/// for the `type_of` function. The type must implement `Clone`.
///
/// # Example
///
/// ```
/// #[derive(Clone)]
2020-03-30 10:10:50 +02:00
/// struct TestStruct {
2020-03-19 06:52:10 +01:00
/// field: i64
/// }
///
/// impl TestStruct {
/// fn new() -> Self { TestStruct { field: 1 } }
/// }
///
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::{Engine, RegisterFn};
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// assert_eq!(
/// engine.eval::<String>("let x = new_ts(); type_of(x)")?,
/// "rust_out::TestStruct"
/// );
///
/// // Register the custom type with a name.
/// engine.register_type_with_name::<TestStruct>("Hello");
///
/// // Register methods on the type.
/// engine.register_fn("new_ts", TestStruct::new);
///
/// assert_eq!(
/// engine.eval::<String>("let x = new_ts(); type_of(x)")?,
/// "Hello"
/// );
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
2020-07-12 05:46:53 +02:00
pub fn register_type_with_name<T: Variant + Clone>(&mut self, name: &str) -> &mut Self {
2020-07-05 09:23:51 +02:00
if self.type_names.is_none() {
self.type_names = Some(Default::default());
}
2020-03-04 15:00:01 +01:00
// Add the pretty-print type name into the map
2020-03-08 12:54:02 +01:00
self.type_names
2020-07-05 09:23:51 +02:00
.as_mut()
.unwrap()
2020-03-08 12:54:02 +01:00
.insert(type_name::<T>().to_string(), name.to_string());
2020-07-12 05:46:53 +02:00
self
2020-03-04 15:00:01 +01:00
}
/// Register an iterator adapter for a type with the `Engine`.
2020-03-19 06:52:10 +01:00
/// This is an advanced feature.
2020-07-12 05:46:53 +02:00
pub fn register_iterator<T: Variant + Clone>(&mut self, f: IteratorFn) -> &mut Self {
2020-05-20 13:27:23 +02:00
self.global_module.set_iter(TypeId::of::<T>(), f);
2020-07-12 05:46:53 +02:00
self
2020-03-04 15:00:01 +01:00
}
/// Register a getter function for a member of a registered type with the `Engine`.
2020-03-19 06:52:10 +01:00
///
2020-03-22 03:18:16 +01:00
/// The function signature must start with `&mut self` and not `&self`.
///
2020-03-19 06:52:10 +01:00
/// # Example
///
/// ```
/// #[derive(Clone)]
2020-03-30 10:10:50 +02:00
/// struct TestStruct {
2020-03-19 06:52:10 +01:00
/// field: i64
/// }
///
/// impl TestStruct {
/// fn new() -> Self { TestStruct { field: 1 } }
2020-03-22 03:18:16 +01:00
///
/// // Even a getter must start with `&mut self` and not `&self`.
2020-03-19 06:52:10 +01:00
/// fn get_field(&mut self) -> i64 { self.field }
/// }
///
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::{Engine, RegisterFn};
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register a getter on a property (notice it doesn't have to be the same name).
/// engine.register_get("xyz", TestStruct::get_field);
///
/// assert_eq!(engine.eval::<i64>("let a = new_ts(); a.xyz")?, 1);
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
2020-05-21 11:11:01 +02:00
pub fn register_get<T, U>(
&mut self,
name: &str,
callback: impl Fn(&mut T) -> U + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self
where
2020-04-12 17:00:06 +02:00
T: Variant + Clone,
U: Variant + Clone,
2020-04-03 11:17:00 +02:00
{
2020-07-12 05:46:53 +02:00
self.register_fn(&make_getter(name), callback)
2020-03-04 15:00:01 +01:00
}
/// Register a setter function for a member of a registered type with the `Engine`.
2020-03-19 06:52:10 +01:00
///
/// # Example
///
/// ```
2020-03-30 10:10:50 +02:00
/// #[derive(Debug, Clone, Eq, PartialEq)]
2020-03-19 06:52:10 +01:00
/// struct TestStruct {
/// field: i64
/// }
///
/// impl TestStruct {
/// fn new() -> Self { TestStruct { field: 1 } }
/// fn set_field(&mut self, new_val: i64) { self.field = new_val; }
/// }
///
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::{Engine, RegisterFn};
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register a setter on a property (notice it doesn't have to be the same name)
/// engine.register_set("xyz", TestStruct::set_field);
///
/// // Notice that, with a getter, there is no way to get the property value
2020-03-30 10:10:50 +02:00
/// assert_eq!(
/// engine.eval::<TestStruct>("let a = new_ts(); a.xyz = 42; a")?,
/// TestStruct { field: 42 }
/// );
2020-03-19 06:52:10 +01:00
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
2020-05-21 11:11:01 +02:00
pub fn register_set<T, U>(
&mut self,
name: &str,
callback: impl Fn(&mut T, U) + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self
where
2020-04-12 17:00:06 +02:00
T: Variant + Clone,
U: Variant + Clone,
2020-04-03 11:17:00 +02:00
{
2020-07-12 05:46:53 +02:00
self.register_fn(&make_setter(name), callback)
2020-03-04 15:00:01 +01:00
}
/// Shorthand for registering both getter and setter functions
/// of a registered type with the `Engine`.
2020-03-19 06:52:10 +01:00
///
2020-03-22 03:18:16 +01:00
/// All function signatures must start with `&mut self` and not `&self`.
///
2020-03-19 06:52:10 +01:00
/// # Example
///
/// ```
/// #[derive(Clone)]
/// struct TestStruct {
/// field: i64
/// }
///
/// impl TestStruct {
2020-03-22 03:18:16 +01:00
/// fn new() -> Self { TestStruct { field: 1 } }
2020-03-19 06:52:10 +01:00
/// fn get_field(&mut self) -> i64 { self.field }
2020-03-22 03:18:16 +01:00
/// // Even a getter must start with `&mut self` and not `&self`.
2020-03-19 06:52:10 +01:00
/// fn set_field(&mut self, new_val: i64) { self.field = new_val; }
/// }
///
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::{Engine, RegisterFn};
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register a getter and a setter on a property
/// // (notice it doesn't have to be the same name)
/// engine.register_get_set("xyz", TestStruct::get_field, TestStruct::set_field);
///
/// assert_eq!(engine.eval::<i64>("let a = new_ts(); a.xyz = 42; a.xyz")?, 42);
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
2020-05-21 11:11:01 +02:00
pub fn register_get_set<T, U>(
&mut self,
name: &str,
get_fn: impl Fn(&mut T) -> U + SendSync + 'static,
set_fn: impl Fn(&mut T, U) + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self
where
2020-04-12 17:00:06 +02:00
T: Variant + Clone,
U: Variant + Clone,
2020-04-03 11:17:00 +02:00
{
2020-07-12 05:46:53 +02:00
self.register_get(name, get_fn).register_set(name, set_fn)
2020-03-04 15:00:01 +01:00
}
2020-06-06 07:06:00 +02:00
/// Register an index getter for a registered type with the `Engine`.
2020-05-05 14:38:48 +02:00
///
/// The function signature must start with `&mut self` and not `&self`.
///
/// # Example
///
/// ```
/// #[derive(Clone)]
/// struct TestStruct {
/// fields: Vec<i64>
/// }
///
/// impl TestStruct {
/// fn new() -> Self { TestStruct { fields: vec![1, 2, 3, 4, 5] } }
///
/// // Even a getter must start with `&mut self` and not `&self`.
/// fn get_field(&mut self, index: i64) -> i64 { self.fields[index as usize] }
/// }
///
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// use rhai::{Engine, RegisterFn};
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register an indexer.
2020-06-06 07:06:00 +02:00
/// engine.register_indexer_get(TestStruct::get_field);
2020-05-05 14:38:48 +02:00
///
/// assert_eq!(engine.eval::<i64>("let a = new_ts(); a[2]")?, 3);
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
#[cfg(not(feature = "no_index"))]
2020-06-06 07:06:00 +02:00
pub fn register_indexer_get<T, X, U>(
2020-05-21 11:11:01 +02:00
&mut self,
callback: impl Fn(&mut T, X) -> U + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self
where
2020-05-05 14:38:48 +02:00
T: Variant + Clone,
U: Variant + Clone,
X: Variant + Clone,
{
2020-07-12 05:46:53 +02:00
self.register_fn(FN_IDX_GET, callback)
2020-06-06 07:06:00 +02:00
}
/// Register an index setter for a registered type with the `Engine`.
///
/// # Example
///
/// ```
/// #[derive(Clone)]
/// struct TestStruct {
/// fields: Vec<i64>
/// }
///
/// impl TestStruct {
/// fn new() -> Self { TestStruct { fields: vec![1, 2, 3, 4, 5] } }
/// fn set_field(&mut self, index: i64, value: i64) { self.fields[index as usize] = value; }
/// }
///
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// use rhai::{Engine, RegisterFn};
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register an indexer.
/// engine.register_indexer_set(TestStruct::set_field);
///
/// assert_eq!(
/// engine.eval::<TestStruct>("let a = new_ts(); a[2] = 42; a")?.fields[2],
/// 42
/// );
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
#[cfg(not(feature = "no_index"))]
pub fn register_indexer_set<T, X, U>(
&mut self,
callback: impl Fn(&mut T, X, U) -> () + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self
where
2020-06-06 07:06:00 +02:00
T: Variant + Clone,
U: Variant + Clone,
X: Variant + Clone,
{
2020-07-12 05:46:53 +02:00
self.register_fn(FN_IDX_SET, callback)
2020-06-06 07:06:00 +02:00
}
/// Shorthand for register both index getter and setter functions for a registered type with the `Engine`.
///
/// # Example
///
/// ```
/// #[derive(Clone)]
/// struct TestStruct {
/// fields: Vec<i64>
/// }
///
/// impl TestStruct {
/// fn new() -> Self { TestStruct { fields: vec![1, 2, 3, 4, 5] } }
/// fn get_field(&mut self, index: i64) -> i64 { self.fields[index as usize] }
/// fn set_field(&mut self, index: i64, value: i64) { self.fields[index as usize] = value; }
/// }
///
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// use rhai::{Engine, RegisterFn};
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register an indexer.
/// engine.register_indexer_get_set(TestStruct::get_field, TestStruct::set_field);
///
/// assert_eq!(engine.eval::<i64>("let a = new_ts(); a[2] = 42; a[2]")?, 42);
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
#[cfg(not(feature = "no_index"))]
pub fn register_indexer_get_set<T, X, U>(
&mut self,
getter: impl Fn(&mut T, X) -> U + SendSync + 'static,
setter: impl Fn(&mut T, X, U) -> () + SendSync + 'static,
2020-07-12 05:46:53 +02:00
) -> &mut Self
where
2020-06-06 07:06:00 +02:00
T: Variant + Clone,
U: Variant + Clone,
X: Variant + Clone,
{
2020-07-12 05:46:53 +02:00
self.register_indexer_get(getter)
.register_indexer_set(setter)
2020-05-05 14:38:48 +02:00
}
/// Compile a string into an `AST`, which can be used later for evaluation.
2020-03-19 06:52:10 +01:00
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::Engine;
///
/// let engine = Engine::new();
2020-03-19 06:52:10 +01:00
///
2020-03-19 12:53:42 +01:00
/// // Compile a script to an AST and store it for later evaluation
2020-03-19 06:52:10 +01:00
/// let ast = engine.compile("40 + 2")?;
///
/// for _ in 0..42 {
/// assert_eq!(engine.eval_ast::<i64>(&ast)?, 42);
/// }
/// # Ok(())
/// # }
/// ```
pub fn compile(&self, script: &str) -> Result<AST, ParseError> {
2020-04-08 10:57:15 +02:00
self.compile_with_scope(&Scope::new(), script)
}
/// Compile a string into an `AST` using own scope, which can be used later for evaluation.
2020-05-13 05:57:07 +02:00
///
2020-03-19 12:53:42 +01:00
/// The scope is useful for passing constants into the script for optimization
/// when using `OptimizationLevel::Full`.
2020-03-19 06:52:10 +01:00
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 12:53:42 +01:00
/// # #[cfg(not(feature = "no_optimize"))]
/// # {
/// use rhai::{Engine, Scope, OptimizationLevel};
2020-03-19 06:52:10 +01:00
///
/// let mut engine = Engine::new();
///
2020-03-19 12:53:42 +01:00
/// // Set optimization level to 'Full' so the Engine can fold constants
/// // into function calls and operators.
/// engine.set_optimization_level(OptimizationLevel::Full);
///
2020-03-19 06:52:10 +01:00
/// // Create initialized scope
/// let mut scope = Scope::new();
/// scope.push_constant("x", 42_i64); // 'x' is a constant
///
2020-03-19 12:53:42 +01:00
/// // Compile a script to an AST and store it for later evaluation.
/// // Notice that `Full` optimization is on, so constants are folded
/// // into function calls and operators.
2020-03-19 06:52:10 +01:00
/// let ast = engine.compile_with_scope(&mut scope,
2020-03-19 12:53:42 +01:00
/// "if x > 40 { x } else { 0 }" // all 'x' are replaced with 42
2020-03-19 06:52:10 +01:00
/// )?;
///
2020-03-19 12:53:42 +01:00
/// // Normally this would have failed because no scope is passed into the 'eval_ast'
/// // call and so the variable 'x' does not exist. Here, it passes because the script
/// // has been optimized and all references to 'x' are already gone.
2020-03-19 06:52:10 +01:00
/// assert_eq!(engine.eval_ast::<i64>(&ast)?, 42);
2020-03-19 12:53:42 +01:00
/// # }
2020-03-19 06:52:10 +01:00
/// # Ok(())
/// # }
/// ```
pub fn compile_with_scope(&self, scope: &Scope, script: &str) -> Result<AST, ParseError> {
2020-05-13 05:57:07 +02:00
self.compile_scripts_with_scope(scope, &[script])
}
2020-05-13 05:57:07 +02:00
/// When passed a list of strings, first join the strings into one large script,
/// and then compile them into an `AST` using own scope, which can be used later for evaluation.
2020-05-13 05:57:07 +02:00
///
/// The scope is useful for passing constants into the script for optimization
/// when using `OptimizationLevel::Full`.
///
/// ## Note
///
/// All strings are simply parsed one after another with nothing inserted in between, not even
/// a newline or space.
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// # #[cfg(not(feature = "no_optimize"))]
/// # {
/// use rhai::{Engine, Scope, OptimizationLevel};
///
/// let mut engine = Engine::new();
///
/// // Set optimization level to 'Full' so the Engine can fold constants
/// // into function calls and operators.
/// engine.set_optimization_level(OptimizationLevel::Full);
///
/// // Create initialized scope
/// let mut scope = Scope::new();
/// scope.push_constant("x", 42_i64); // 'x' is a constant
///
/// // Compile a script made up of script segments to an AST and store it for later evaluation.
/// // Notice that `Full` optimization is on, so constants are folded
/// // into function calls and operators.
/// let ast = engine.compile_scripts_with_scope(&mut scope, &[
/// "if x > 40", // all 'x' are replaced with 42
2020-05-13 13:21:42 +02:00
/// "{ x } el",
2020-05-13 05:57:07 +02:00
/// "se { 0 }" // segments do not need to be valid scripts!
/// ])?;
///
/// // Normally this would have failed because no scope is passed into the 'eval_ast'
/// // call and so the variable 'x' does not exist. Here, it passes because the script
/// // has been optimized and all references to 'x' are already gone.
/// assert_eq!(engine.eval_ast::<i64>(&ast)?, 42);
/// # }
/// # Ok(())
/// # }
/// ```
pub fn compile_scripts_with_scope(
&self,
scope: &Scope,
scripts: &[&str],
) -> Result<AST, ParseError> {
2020-05-13 05:57:07 +02:00
self.compile_with_scope_and_optimization_level(scope, scripts, self.optimization_level)
}
/// Join a list of strings and compile into an `AST` using own scope at a specific optimization level.
pub(crate) fn compile_with_scope_and_optimization_level(
&self,
scope: &Scope,
2020-05-13 05:57:07 +02:00
scripts: &[&str],
2020-04-10 06:16:39 +02:00
optimization_level: OptimizationLevel,
) -> Result<AST, ParseError> {
2020-07-05 11:41:45 +02:00
let stream = lex(scripts, self);
2020-06-03 04:44:36 +02:00
self.parse(&mut stream.peekable(), scope, optimization_level)
}
2020-03-19 06:52:10 +01:00
/// Read the contents of a file into a string.
#[cfg(not(feature = "no_std"))]
2020-06-17 03:54:17 +02:00
#[cfg(not(target_arch = "wasm32"))]
fn read_file(path: PathBuf) -> Result<String, Box<EvalAltResult>> {
2020-05-05 18:09:04 +02:00
let mut f = File::open(path.clone()).map_err(|err| {
Box::new(EvalAltResult::ErrorReadingScriptFile(
path.clone(),
Position::none(),
err,
))
})?;
let mut contents = String::new();
2020-05-05 18:09:04 +02:00
f.read_to_string(&mut contents).map_err(|err| {
Box::new(EvalAltResult::ErrorReadingScriptFile(
path.clone(),
Position::none(),
err,
))
})?;
2020-03-30 16:19:37 +02:00
Ok(contents)
}
/// Compile a script file into an `AST`, which can be used later for evaluation.
2020-03-19 06:52:10 +01:00
///
/// # Example
///
/// ```no_run
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::Engine;
///
/// let engine = Engine::new();
2020-03-19 06:52:10 +01:00
///
2020-03-19 12:53:42 +01:00
/// // Compile a script file to an AST and store it for later evaluation.
2020-03-19 06:52:10 +01:00
/// // Notice that a PathBuf is required which can easily be constructed from a string.
/// let ast = engine.compile_file("script.rhai".into())?;
///
/// for _ in 0..42 {
/// engine.eval_ast::<i64>(&ast)?;
/// }
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_std"))]
2020-06-17 03:54:17 +02:00
#[cfg(not(target_arch = "wasm32"))]
pub fn compile_file(&self, path: PathBuf) -> Result<AST, Box<EvalAltResult>> {
2020-03-14 07:33:56 +01:00
self.compile_file_with_scope(&Scope::new(), path)
}
/// Compile a script file into an `AST` using own scope, which can be used later for evaluation.
2020-05-13 05:57:07 +02:00
///
2020-03-19 12:53:42 +01:00
/// The scope is useful for passing constants into the script for optimization
/// when using `OptimizationLevel::Full`.
2020-03-19 06:52:10 +01:00
///
/// # Example
///
/// ```no_run
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 12:53:42 +01:00
/// # #[cfg(not(feature = "no_optimize"))]
/// # {
/// use rhai::{Engine, Scope, OptimizationLevel};
2020-03-19 06:52:10 +01:00
///
/// let mut engine = Engine::new();
///
2020-03-19 12:53:42 +01:00
/// // Set optimization level to 'Full' so the Engine can fold constants.
/// engine.set_optimization_level(OptimizationLevel::Full);
///
2020-03-19 06:52:10 +01:00
/// // Create initialized scope
/// let mut scope = Scope::new();
/// scope.push_constant("x", 42_i64); // 'x' is a constant
///
2020-03-19 12:53:42 +01:00
/// // Compile a script to an AST and store it for later evaluation.
2020-03-19 06:52:10 +01:00
/// // Notice that a PathBuf is required which can easily be constructed from a string.
/// let ast = engine.compile_file_with_scope(&mut scope, "script.rhai".into())?;
///
/// let result = engine.eval_ast::<i64>(&ast)?;
2020-03-19 12:53:42 +01:00
/// # }
2020-03-19 06:52:10 +01:00
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_std"))]
2020-06-17 03:54:17 +02:00
#[cfg(not(target_arch = "wasm32"))]
pub fn compile_file_with_scope(
&self,
scope: &Scope,
2020-03-14 07:33:56 +01:00
path: PathBuf,
) -> Result<AST, Box<EvalAltResult>> {
2020-04-08 10:57:15 +02:00
Self::read_file(path).and_then(|contents| Ok(self.compile_with_scope(scope, &contents)?))
}
2020-04-10 11:14:07 +02:00
/// Parse a JSON string into a map.
///
/// Set `has_null` to `true` in order to map `null` values to `()`.
/// Setting it to `false` will cause a _variable not found_ error during parsing.
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-04-12 17:00:06 +02:00
/// use rhai::Engine;
2020-04-10 11:14:07 +02:00
///
/// let engine = Engine::new();
///
/// let map = engine.parse_json(r#"{"a":123, "b":42, "c":false, "d":null}"#, true)?;
///
/// assert_eq!(map.len(), 4);
/// assert_eq!(map.get("a").cloned().unwrap().cast::<i64>(), 123);
/// assert_eq!(map.get("b").cloned().unwrap().cast::<i64>(), 42);
/// assert_eq!(map.get("c").cloned().unwrap().cast::<bool>(), false);
/// assert_eq!(map.get("d").cloned().unwrap().cast::<()>(), ());
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
pub fn parse_json(&self, json: &str, has_null: bool) -> Result<Map, Box<EvalAltResult>> {
2020-04-10 11:14:07 +02:00
let mut scope = Scope::new();
// Trims the JSON string and add a '#' in front
let scripts = ["#", json.trim()];
2020-07-05 11:41:45 +02:00
let stream = lex(&scripts, self);
2020-06-03 04:44:36 +02:00
let ast =
self.parse_global_expr(&mut stream.peekable(), &scope, OptimizationLevel::None)?;
2020-04-10 11:14:07 +02:00
// Handle null - map to ()
if has_null {
scope.push_constant("null", ());
}
self.eval_ast_with_scope(&mut scope, &ast)
}
/// Compile a string containing an expression into an `AST`,
2020-03-22 14:03:58 +01:00
/// which can be used later for evaluation.
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-22 14:03:58 +01:00
/// use rhai::Engine;
///
/// let engine = Engine::new();
2020-03-22 14:03:58 +01:00
///
/// // Compile a script to an AST and store it for later evaluation
/// let ast = engine.compile_expression("40 + 2")?;
///
/// for _ in 0..42 {
/// assert_eq!(engine.eval_ast::<i64>(&ast)?, 42);
/// }
/// # Ok(())
/// # }
/// ```
pub fn compile_expression(&self, script: &str) -> Result<AST, ParseError> {
2020-04-08 10:57:15 +02:00
self.compile_expression_with_scope(&Scope::new(), script)
2020-03-22 14:03:58 +01:00
}
/// Compile a string containing an expression into an `AST` using own scope,
2020-03-22 14:03:58 +01:00
/// which can be used later for evaluation.
///
/// The scope is useful for passing constants into the script for optimization
/// when using `OptimizationLevel::Full`.
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-22 14:03:58 +01:00
/// # #[cfg(not(feature = "no_optimize"))]
/// # {
/// use rhai::{Engine, Scope, OptimizationLevel};
///
/// let mut engine = Engine::new();
///
/// // Set optimization level to 'Full' so the Engine can fold constants
/// // into function calls and operators.
/// engine.set_optimization_level(OptimizationLevel::Full);
///
/// // Create initialized scope
/// let mut scope = Scope::new();
/// scope.push_constant("x", 10_i64); // 'x' is a constant
///
/// // Compile a script to an AST and store it for later evaluation.
/// // Notice that `Full` optimization is on, so constants are folded
/// // into function calls and operators.
/// let ast = engine.compile_expression_with_scope(&mut scope,
/// "2 + (x + x) * 2" // all 'x' are replaced with 10
/// )?;
///
/// // Normally this would have failed because no scope is passed into the 'eval_ast'
/// // call and so the variable 'x' does not exist. Here, it passes because the script
/// // has been optimized and all references to 'x' are already gone.
/// assert_eq!(engine.eval_ast::<i64>(&ast)?, 42);
/// # }
/// # Ok(())
/// # }
/// ```
pub fn compile_expression_with_scope(
&self,
scope: &Scope,
2020-04-08 10:57:15 +02:00
script: &str,
) -> Result<AST, ParseError> {
2020-04-10 11:14:07 +02:00
let scripts = [script];
2020-07-05 11:41:45 +02:00
let stream = lex(&scripts, self);
2020-05-17 16:19:49 +02:00
{
let mut peekable = stream.peekable();
2020-06-03 04:44:36 +02:00
self.parse_global_expr(&mut peekable, scope, self.optimization_level)
2020-05-17 16:19:49 +02:00
}
2020-03-22 14:03:58 +01:00
}
2020-03-19 06:52:10 +01:00
/// Evaluate a script file.
///
/// # Example
///
/// ```no_run
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::Engine;
///
/// let engine = Engine::new();
2020-03-19 06:52:10 +01:00
///
/// // Notice that a PathBuf is required which can easily be constructed from a string.
/// let result = engine.eval_file::<i64>("script.rhai".into())?;
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_std"))]
2020-06-17 03:54:17 +02:00
#[cfg(not(target_arch = "wasm32"))]
pub fn eval_file<T: Variant + Clone>(&self, path: PathBuf) -> Result<T, Box<EvalAltResult>> {
2020-03-13 11:27:53 +01:00
Self::read_file(path).and_then(|contents| self.eval::<T>(&contents))
}
2020-03-19 06:52:10 +01:00
/// Evaluate a script file with own scope.
///
/// # Example
///
/// ```no_run
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::{Engine, Scope};
///
/// let engine = Engine::new();
2020-03-19 06:52:10 +01:00
///
/// // Create initialized scope
/// let mut scope = Scope::new();
/// scope.push("x", 42_i64);
///
/// // Notice that a PathBuf is required which can easily be constructed from a string.
/// let result = engine.eval_file_with_scope::<i64>(&mut scope, "script.rhai".into())?;
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_std"))]
2020-06-17 03:54:17 +02:00
#[cfg(not(target_arch = "wasm32"))]
2020-04-12 17:00:06 +02:00
pub fn eval_file_with_scope<T: Variant + Clone>(
&self,
scope: &mut Scope,
path: PathBuf,
) -> Result<T, Box<EvalAltResult>> {
Self::read_file(path).and_then(|contents| self.eval_with_scope::<T>(scope, &contents))
}
/// Evaluate a string.
2020-03-19 06:52:10 +01:00
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::Engine;
///
/// let engine = Engine::new();
2020-03-19 06:52:10 +01:00
///
/// assert_eq!(engine.eval::<i64>("40 + 2")?, 42);
/// # Ok(())
/// # }
/// ```
pub fn eval<T: Variant + Clone>(&self, script: &str) -> Result<T, Box<EvalAltResult>> {
2020-04-08 10:57:15 +02:00
self.eval_with_scope(&mut Scope::new(), script)
}
/// Evaluate a string with own scope.
2020-03-19 06:52:10 +01:00
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::{Engine, Scope};
///
/// let engine = Engine::new();
2020-03-19 06:52:10 +01:00
///
/// // Create initialized scope
/// let mut scope = Scope::new();
/// scope.push("x", 40_i64);
///
2020-07-06 10:20:03 +02:00
/// assert_eq!(engine.eval_with_scope::<i64>(&mut scope, "x += 2; x")?, 42);
/// assert_eq!(engine.eval_with_scope::<i64>(&mut scope, "x += 2; x")?, 44);
2020-03-19 06:52:10 +01:00
///
/// // The variable in the scope is modified
/// assert_eq!(scope.get_value::<i64>("x").expect("variable x should exist"), 44);
/// # Ok(())
/// # }
/// ```
2020-04-12 17:00:06 +02:00
pub fn eval_with_scope<T: Variant + Clone>(
&self,
scope: &mut Scope,
2020-04-08 10:57:15 +02:00
script: &str,
) -> Result<T, Box<EvalAltResult>> {
2020-05-13 05:57:07 +02:00
let ast = self.compile_with_scope_and_optimization_level(
scope,
&[script],
2020-05-17 16:19:49 +02:00
self.optimization_level,
2020-05-13 05:57:07 +02:00
)?;
self.eval_ast_with_scope(scope, &ast)
}
2020-03-22 14:03:58 +01:00
/// Evaluate a string containing an expression.
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-22 14:03:58 +01:00
/// use rhai::Engine;
///
/// let engine = Engine::new();
2020-03-22 14:03:58 +01:00
///
/// assert_eq!(engine.eval_expression::<i64>("40 + 2")?, 42);
/// # Ok(())
/// # }
/// ```
pub fn eval_expression<T: Variant + Clone>(
&self,
script: &str,
) -> Result<T, Box<EvalAltResult>> {
2020-04-08 10:57:15 +02:00
self.eval_expression_with_scope(&mut Scope::new(), script)
2020-03-22 14:03:58 +01:00
}
/// Evaluate a string containing an expression with own scope.
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-22 14:03:58 +01:00
/// use rhai::{Engine, Scope};
///
/// let engine = Engine::new();
2020-03-22 14:03:58 +01:00
///
/// // Create initialized scope
/// let mut scope = Scope::new();
/// scope.push("x", 40_i64);
///
/// assert_eq!(engine.eval_expression_with_scope::<i64>(&mut scope, "x + 2")?, 42);
/// # Ok(())
/// # }
/// ```
2020-04-12 17:00:06 +02:00
pub fn eval_expression_with_scope<T: Variant + Clone>(
&self,
2020-03-22 14:03:58 +01:00
scope: &mut Scope,
2020-04-08 10:57:15 +02:00
script: &str,
) -> Result<T, Box<EvalAltResult>> {
2020-04-10 15:02:38 +02:00
let scripts = [script];
2020-07-05 11:41:45 +02:00
let stream = lex(&scripts, self);
// No need to optimize a lone expression
let ast = self.parse_global_expr(&mut stream.peekable(), scope, OptimizationLevel::None)?;
2020-03-22 14:03:58 +01:00
self.eval_ast_with_scope(scope, &ast)
}
/// Evaluate an `AST`.
2020-03-19 06:52:10 +01:00
///
/// # Example
///
2020-03-19 12:53:42 +01:00
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::Engine;
///
/// let engine = Engine::new();
2020-03-19 06:52:10 +01:00
///
2020-03-19 12:53:42 +01:00
/// // Compile a script to an AST and store it for later evaluation
2020-03-19 06:52:10 +01:00
/// let ast = engine.compile("40 + 2")?;
///
/// // Evaluate it
/// assert_eq!(engine.eval_ast::<i64>(&ast)?, 42);
/// # Ok(())
/// # }
/// ```
pub fn eval_ast<T: Variant + Clone>(&self, ast: &AST) -> Result<T, Box<EvalAltResult>> {
2020-03-30 16:19:37 +02:00
self.eval_ast_with_scope(&mut Scope::new(), ast)
}
/// Evaluate an `AST` with own scope.
2020-03-19 06:52:10 +01:00
///
/// # Example
///
2020-03-19 12:53:42 +01:00
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-19 06:52:10 +01:00
/// use rhai::{Engine, Scope};
///
/// let engine = Engine::new();
2020-03-19 06:52:10 +01:00
///
2020-03-19 12:53:42 +01:00
/// // Compile a script to an AST and store it for later evaluation
2020-03-19 06:52:10 +01:00
/// let ast = engine.compile("x + 2")?;
///
/// // Create initialized scope
/// let mut scope = Scope::new();
/// scope.push("x", 40_i64);
///
2020-03-19 12:53:42 +01:00
/// // Compile a script to an AST and store it for later evaluation
2020-07-06 10:20:03 +02:00
/// let ast = engine.compile("x += 2; x")?;
2020-03-19 12:53:42 +01:00
///
2020-03-19 06:52:10 +01:00
/// // Evaluate it
2020-03-19 12:53:42 +01:00
/// assert_eq!(engine.eval_ast_with_scope::<i64>(&mut scope, &ast)?, 42);
/// assert_eq!(engine.eval_ast_with_scope::<i64>(&mut scope, &ast)?, 44);
2020-03-19 06:52:10 +01:00
///
/// // The variable in the scope is modified
/// assert_eq!(scope.get_value::<i64>("x").expect("variable x should exist"), 44);
/// # Ok(())
/// # }
/// ```
2020-04-12 17:00:06 +02:00
pub fn eval_ast_with_scope<T: Variant + Clone>(
&self,
scope: &mut Scope,
ast: &AST,
) -> Result<T, Box<EvalAltResult>> {
let mut mods = Imports::new();
let (result, _) = self.eval_ast_with_scope_raw(scope, &mut mods, ast)?;
2020-07-03 04:45:01 +02:00
let typ = self.map_type_name(result.type_name());
2020-04-13 04:27:08 +02:00
return result.try_cast::<T>().ok_or_else(|| {
Box::new(EvalAltResult::ErrorMismatchOutputType(
2020-07-03 04:45:01 +02:00
self.map_type_name(type_name::<T>()).into(),
typ.into(),
Position::none(),
))
2020-04-13 04:27:08 +02:00
});
2020-03-19 12:53:42 +01:00
}
/// Evaluate an `AST` with own scope.
pub(crate) fn eval_ast_with_scope_raw<'a>(
&self,
2020-03-19 12:53:42 +01:00
scope: &mut Scope,
mods: &mut Imports,
ast: &'a AST,
) -> Result<(Dynamic, u64), Box<EvalAltResult>> {
let mut state = State::new();
2020-04-28 17:05:03 +02:00
2020-05-05 09:00:10 +02:00
ast.statements()
2020-03-30 16:19:37 +02:00
.iter()
.try_fold(().into(), |_, stmt| {
self.eval_stmt(scope, mods, &mut state, ast.lib(), &mut None, stmt, 0)
})
.or_else(|err| match *err {
EvalAltResult::Return(out, _) => Ok(out),
_ => Err(err),
})
.map(|v| (v, state.operations))
}
2020-03-04 15:00:01 +01:00
/// Evaluate a file, but throw away the result and only return error (if any).
/// Useful for when you don't need the result, but still need to keep track of possible errors.
#[cfg(not(feature = "no_std"))]
2020-06-17 03:54:17 +02:00
#[cfg(not(target_arch = "wasm32"))]
pub fn consume_file(&self, path: PathBuf) -> Result<(), Box<EvalAltResult>> {
Self::read_file(path).and_then(|contents| self.consume(&contents))
}
/// Evaluate a file with own scope, but throw away the result and only return error (if any).
/// Useful for when you don't need the result, but still need to keep track of possible errors.
#[cfg(not(feature = "no_std"))]
2020-06-17 03:54:17 +02:00
#[cfg(not(target_arch = "wasm32"))]
pub fn consume_file_with_scope(
&self,
scope: &mut Scope,
path: PathBuf,
) -> Result<(), Box<EvalAltResult>> {
Self::read_file(path).and_then(|contents| self.consume_with_scope(scope, &contents))
}
2020-03-04 15:00:01 +01:00
/// Evaluate a string, but throw away the result and only return error (if any).
/// Useful for when you don't need the result, but still need to keep track of possible errors.
pub fn consume(&self, script: &str) -> Result<(), Box<EvalAltResult>> {
2020-04-08 10:57:15 +02:00
self.consume_with_scope(&mut Scope::new(), script)
}
/// Evaluate a string with own scope, but throw away the result and only return error (if any).
/// Useful for when you don't need the result, but still need to keep track of possible errors.
pub fn consume_with_scope(
&self,
scope: &mut Scope,
script: &str,
) -> Result<(), Box<EvalAltResult>> {
2020-04-10 11:14:07 +02:00
let scripts = [script];
2020-07-05 11:41:45 +02:00
let stream = lex(&scripts, self);
2020-06-03 04:44:36 +02:00
let ast = self.parse(&mut stream.peekable(), scope, self.optimization_level)?;
self.consume_ast_with_scope(scope, &ast)
}
/// Evaluate an AST, but throw away the result and only return error (if any).
/// Useful for when you don't need the result, but still need to keep track of possible errors.
pub fn consume_ast(&self, ast: &AST) -> Result<(), Box<EvalAltResult>> {
self.consume_ast_with_scope(&mut Scope::new(), ast)
}
/// Evaluate an `AST` with own scope, but throw away the result and only return error (if any).
/// Useful for when you don't need the result, but still need to keep track of possible errors.
pub fn consume_ast_with_scope(
&self,
scope: &mut Scope,
ast: &AST,
) -> Result<(), Box<EvalAltResult>> {
let mut state = State::new();
let mut mods = Default::default();
2020-04-28 17:05:03 +02:00
2020-05-05 09:00:10 +02:00
ast.statements()
.iter()
.try_fold(().into(), |_, stmt| {
self.eval_stmt(scope, &mut mods, &mut state, ast.lib(), &mut None, stmt, 0)
})
.map_or_else(
|err| match *err {
EvalAltResult::Return(_, _) => Ok(()),
err => Err(Box::new(err)),
},
|_| Ok(()),
)
}
/// Call a script function defined in an `AST` with multiple arguments.
2020-05-31 06:37:19 +02:00
/// Arguments are passed as a tuple.
2020-03-04 15:00:01 +01:00
///
/// # Example
///
2020-03-19 06:52:10 +01:00
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// # #[cfg(not(feature = "no_function"))]
/// # {
/// use rhai::{Engine, Scope};
2020-03-09 14:57:07 +01:00
///
/// let engine = Engine::new();
2020-03-04 15:00:01 +01:00
///
/// let ast = engine.compile(r"
/// fn add(x, y) { len(x) + y + foo }
/// fn add1(x) { len(x) + 1 + foo }
/// fn bar() { foo/2 }
/// ")?;
///
/// let mut scope = Scope::new();
/// scope.push("foo", 42_i64);
2020-03-04 15:00:01 +01:00
///
2020-03-19 06:52:10 +01:00
/// // Call the script-defined function
/// let result: i64 = engine.call_fn(&mut scope, &ast, "add", ( String::from("abc"), 123_i64 ) )?;
/// assert_eq!(result, 168);
///
/// let result: i64 = engine.call_fn(&mut scope, &ast, "add1", ( String::from("abc"), ) )?;
/// // ^^^^^^^^^^^^^^^^^^^^^^^^ tuple of one
/// assert_eq!(result, 46);
///
/// let result: i64 = engine.call_fn(&mut scope, &ast, "bar", () )?;
/// assert_eq!(result, 21);
/// # }
2020-03-04 15:00:01 +01:00
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_function"))]
2020-04-12 17:00:06 +02:00
pub fn call_fn<A: FuncArgs, T: Variant + Clone>(
&self,
scope: &mut Scope,
ast: &AST,
2020-03-04 15:00:01 +01:00
name: &str,
args: A,
) -> Result<T, Box<EvalAltResult>> {
let mut arg_values = args.into_vec();
2020-07-06 07:01:57 +02:00
let result = self.call_fn_dynamic_raw(scope, ast, name, &mut None, arg_values.as_mut())?;
2020-05-31 06:37:19 +02:00
2020-07-03 04:45:01 +02:00
let typ = self.map_type_name(result.type_name());
2020-05-31 06:37:19 +02:00
return result.try_cast().ok_or_else(|| {
Box::new(EvalAltResult::ErrorMismatchOutputType(
2020-07-03 04:45:01 +02:00
self.map_type_name(type_name::<T>()).into(),
typ.into(),
2020-05-31 06:37:19 +02:00
Position::none(),
))
});
}
/// Call a script function defined in an `AST` with multiple `Dynamic` arguments
2020-07-05 17:08:44 +02:00
/// and optionally a value for binding to the 'this' pointer.
///
/// ## WARNING
///
/// All the arguments are _consumed_, meaning that they're replaced by `()`.
/// This is to avoid unnecessarily cloning the arguments.
/// Do not use the arguments after this call. If they are needed afterwards,
/// clone them _before_ calling this function.
2020-05-31 06:37:19 +02:00
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// # #[cfg(not(feature = "no_function"))]
/// # {
2020-07-05 17:08:44 +02:00
/// use rhai::{Engine, Scope, Dynamic};
2020-05-31 06:37:19 +02:00
///
/// let engine = Engine::new();
///
/// let ast = engine.compile(r"
/// fn add(x, y) { len(x) + y + foo }
/// fn add1(x) { len(x) + 1 + foo }
/// fn bar() { foo/2 }
2020-07-05 17:08:44 +02:00
/// fn action(x) { this += x; } // function using 'this' pointer
2020-05-31 06:37:19 +02:00
/// ")?;
///
/// let mut scope = Scope::new();
/// scope.push("foo", 42_i64);
///
/// // Call the script-defined function
2020-07-06 07:01:57 +02:00
/// let result = engine.call_fn_dynamic(&mut scope, &ast, "add", None, [ String::from("abc").into(), 123_i64.into() ])?;
/// // ^^^^ no 'this' pointer
2020-05-31 06:37:19 +02:00
/// assert_eq!(result.cast::<i64>(), 168);
///
2020-07-06 07:01:57 +02:00
/// let result = engine.call_fn_dynamic(&mut scope, &ast, "add1", None, [ String::from("abc").into() ])?;
2020-05-31 06:37:19 +02:00
/// assert_eq!(result.cast::<i64>(), 46);
///
2020-07-06 07:01:57 +02:00
/// let result = engine.call_fn_dynamic(&mut scope, &ast, "bar", None, [])?;
2020-05-31 06:37:19 +02:00
/// assert_eq!(result.cast::<i64>(), 21);
2020-07-05 17:08:44 +02:00
///
/// let mut value: Dynamic = 1_i64.into();
2020-07-06 07:01:57 +02:00
/// let result = engine.call_fn_dynamic(&mut scope, &ast, "action", Some(&mut value), [ 41_i64.into() ])?;
/// // ^^^^^^^^^^^^^^^^ binding the 'this' pointer
2020-07-05 17:08:44 +02:00
/// assert_eq!(value.as_int().unwrap(), 42);
2020-05-31 06:37:19 +02:00
/// # }
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_function"))]
pub fn call_fn_dynamic(
&self,
scope: &mut Scope,
2020-07-06 07:01:57 +02:00
lib: impl AsRef<Module>,
name: &str,
2020-07-05 17:08:44 +02:00
mut this_ptr: Option<&mut Dynamic>,
mut arg_values: impl AsMut<[Dynamic]>,
2020-07-07 16:59:23 +02:00
) -> FuncReturn<Dynamic> {
self.call_fn_dynamic_raw(scope, lib, name, &mut this_ptr, arg_values.as_mut())
}
/// Call a script function defined in an `AST` with multiple `Dynamic` arguments.
///
/// ## WARNING
///
/// All the arguments are _consumed_, meaning that they're replaced by `()`.
/// This is to avoid unnecessarily cloning the arguments.
/// Do not use the arguments after this call. If they are needed afterwards,
/// clone them _before_ calling this function.
2020-07-04 10:21:15 +02:00
#[cfg(not(feature = "no_function"))]
pub(crate) fn call_fn_dynamic_raw(
2020-05-31 06:37:19 +02:00
&self,
scope: &mut Scope,
2020-07-06 07:01:57 +02:00
lib: impl AsRef<Module>,
2020-05-31 06:37:19 +02:00
name: &str,
2020-07-05 17:08:44 +02:00
this_ptr: &mut Option<&mut Dynamic>,
2020-05-31 06:37:19 +02:00
arg_values: &mut [Dynamic],
2020-07-07 16:59:23 +02:00
) -> FuncReturn<Dynamic> {
2020-07-06 07:01:57 +02:00
let lib = lib.as_ref();
let mut args: StaticVec<_> = arg_values.iter_mut().collect();
let fn_def =
get_script_function_by_signature(lib, name, args.len(), true).ok_or_else(|| {
2020-06-01 09:25:22 +02:00
Box::new(EvalAltResult::ErrorFunctionNotFound(
name.into(),
Position::none(),
))
})?;
2020-04-24 06:39:24 +02:00
let mut state = State::new();
let mut mods = Imports::new();
let args = args.as_mut();
2020-06-26 04:39:18 +02:00
self.call_script_fn(
scope, &mut mods, &mut state, lib, this_ptr, name, fn_def, args, 0,
2020-06-26 04:39:18 +02:00
)
2020-03-04 15:00:01 +01:00
}
/// Optimize the `AST` with constants defined in an external Scope.
/// An optimized copy of the `AST` is returned while the original `AST` is consumed.
///
/// Although optimization is performed by default during compilation, sometimes it is necessary to
/// _re_-optimize an AST. For example, when working with constants that are passed in via an
/// external scope, it will be more efficient to optimize the `AST` once again to take advantage
/// of the new constants.
///
/// With this method, it is no longer necessary to recompile a large script. The script `AST` can be
/// compiled just once. Before evaluation, constants are passed into the `Engine` via an external scope
2020-03-19 06:52:10 +01:00
/// (i.e. with `scope.push_constant(...)`). Then, the `AST is cloned and the copy re-optimized before running.
#[cfg(not(feature = "no_optimize"))]
pub fn optimize_ast(
&self,
scope: &Scope,
2020-05-05 09:00:10 +02:00
mut ast: AST,
optimization_level: OptimizationLevel,
) -> AST {
2020-07-04 10:21:15 +02:00
#[cfg(not(feature = "no_function"))]
let lib = ast
.lib()
.iter_fn()
.filter(|(_, _, _, f)| f.is_script())
.map(|(_, _, _, f)| f.get_fn_def().clone())
2020-04-16 17:58:57 +02:00
.collect();
2020-05-05 09:00:10 +02:00
2020-07-04 10:21:15 +02:00
#[cfg(feature = "no_function")]
let lib = Default::default();
2020-05-05 09:00:10 +02:00
let stmt = mem::take(ast.statements_mut());
optimize_into_ast(self, scope, stmt, lib, optimization_level)
}
/// Register a callback for script evaluation progress.
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// # use std::sync::RwLock;
/// # use std::sync::Arc;
/// use rhai::Engine;
///
/// let result = Arc::new(RwLock::new(0_u64));
/// let logger = result.clone();
///
/// let mut engine = Engine::new();
///
2020-06-02 07:33:16 +02:00
/// engine.on_progress(move |&ops| {
/// if ops > 10000 {
/// false
/// } else if ops % 800 == 0 {
/// *logger.write().unwrap() = ops;
/// true
/// } else {
/// true
/// }
/// });
///
/// engine.consume("for x in range(0, 50000) {}")
/// .expect_err("should error");
///
/// assert_eq!(*result.read().unwrap(), 9600);
///
/// # Ok(())
/// # }
/// ```
2020-07-12 05:46:53 +02:00
pub fn on_progress(
&mut self,
callback: impl Fn(&u64) -> bool + SendSync + 'static,
) -> &mut Self {
self.progress = Some(Box::new(callback));
2020-07-12 05:46:53 +02:00
self
}
2020-03-04 15:00:01 +01:00
/// Override default action of `print` (print to stdout using `println!`)
///
/// # Example
///
2020-03-19 06:52:10 +01:00
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// # use std::sync::RwLock;
2020-04-16 17:31:48 +02:00
/// # use std::sync::Arc;
2020-03-09 14:57:07 +01:00
/// use rhai::Engine;
///
2020-04-16 17:31:48 +02:00
/// let result = Arc::new(RwLock::new(String::from("")));
///
2020-04-16 17:31:48 +02:00
/// let mut engine = Engine::new();
///
/// // Override action of 'print' function
/// let logger = result.clone();
/// engine.on_print(move |s| logger.write().unwrap().push_str(s));
///
/// engine.consume("print(40 + 2);")?;
2020-03-04 15:00:01 +01:00
///
/// assert_eq!(*result.read().unwrap(), "42");
2020-03-09 14:57:07 +01:00
/// # Ok(())
/// # }
2020-03-04 15:00:01 +01:00
/// ```
2020-07-12 05:46:53 +02:00
pub fn on_print(&mut self, callback: impl Fn(&str) + SendSync + 'static) -> &mut Self {
2020-04-27 15:28:31 +02:00
self.print = Box::new(callback);
2020-07-12 05:46:53 +02:00
self
}
2020-03-04 15:00:01 +01:00
/// Override default action of `debug` (print to stdout using `println!`)
///
/// # Example
///
2020-03-19 06:52:10 +01:00
/// ```
2020-04-23 07:22:53 +02:00
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// # use std::sync::RwLock;
2020-04-16 17:31:48 +02:00
/// # use std::sync::Arc;
2020-03-09 14:57:07 +01:00
/// use rhai::Engine;
///
2020-04-16 17:31:48 +02:00
/// let result = Arc::new(RwLock::new(String::from("")));
2020-03-04 15:00:01 +01:00
///
2020-04-16 17:31:48 +02:00
/// let mut engine = Engine::new();
///
/// // Override action of 'print' function
/// let logger = result.clone();
/// engine.on_debug(move |s| logger.write().unwrap().push_str(s));
///
/// engine.consume(r#"debug("hello");"#)?;
///
/// assert_eq!(*result.read().unwrap(), r#""hello""#);
2020-03-09 14:57:07 +01:00
/// # Ok(())
/// # }
2020-03-04 15:00:01 +01:00
/// ```
2020-07-12 05:46:53 +02:00
pub fn on_debug(&mut self, callback: impl Fn(&str) + SendSync + 'static) -> &mut Self {
2020-04-27 15:28:31 +02:00
self.debug = Box::new(callback);
2020-07-12 05:46:53 +02:00
self
}
}