//! Module that defines the extern API of `Engine`. use crate::any::{Any, AnyExt, Dynamic}; use crate::call::FuncArgs; use crate::engine::{Engine, FnAny, FnCallArgs, FnIntExt, FnSpec}; use crate::error::ParseError; use crate::fn_register::RegisterFn; use crate::parser::{lex, parse, Position, AST}; use crate::result::EvalAltResult; use crate::scope::Scope; use std::{ any::{type_name, TypeId}, fs::File, io::prelude::*, sync::Arc, }; impl<'e> Engine<'e> { pub(crate) fn register_fn_raw( &mut self, fn_name: &str, args: Option>, f: Box, ) { debug_println!( "Register function: {} with {}", fn_name, if let Some(a) = &args { format!( "{} parameter{}", a.len(), if a.len() > 1 { "s" } else { "" } ) } else { "no parameter".to_string() } ); let spec = FnSpec { name: fn_name.to_string().into(), args, }; self.ext_functions.insert(spec, Arc::new(FnIntExt::Ext(f))); } /// Register a custom type for use with the `Engine`. /// The type must be `Clone`. pub fn register_type(&mut self) { self.register_type_with_name::(type_name::()); } /// Register a custom type for use with the `Engine` with a name for the `type_of` function. /// The type must be `Clone`. pub fn register_type_with_name(&mut self, name: &str) { // Add the pretty-print type name into the map self.type_names .insert(type_name::().to_string(), name.to_string()); } /// Register an iterator adapter for a type with the `Engine`. pub fn register_iterator(&mut self, f: F) where F: Fn(&Dynamic) -> Box> + 'static, { self.type_iterators.insert(TypeId::of::(), Arc::new(f)); } /// Register a getter function for a member of a registered type with the `Engine`. pub fn register_get( &mut self, name: &str, callback: impl Fn(&mut T) -> U + 'static, ) { let get_name = "get$".to_string() + name; self.register_fn(&get_name, callback); } /// Register a setter function for a member of a registered type with the `Engine`. pub fn register_set( &mut self, name: &str, callback: impl Fn(&mut T, U) -> () + 'static, ) { let set_name = "set$".to_string() + name; self.register_fn(&set_name, callback); } /// Shorthand for registering both getter and setter functions /// of a registered type with the `Engine`. pub fn register_get_set( &mut self, name: &str, get_fn: impl Fn(&mut T) -> U + 'static, set_fn: impl Fn(&mut T, U) -> () + 'static, ) { self.register_get(name, get_fn); self.register_set(name, set_fn); } /// Compile a string into an AST. pub fn compile(&self, input: &str) -> Result { let tokens = lex(input); parse(&mut tokens.peekable(), self.optimize) } fn read_file(filename: &str) -> Result { let mut f = File::open(filename) .map_err(|err| EvalAltResult::ErrorReadingScriptFile(filename.into(), err))?; let mut contents = String::new(); f.read_to_string(&mut contents) .map_err(|err| EvalAltResult::ErrorReadingScriptFile(filename.into(), err)) .map(|_| contents) } /// Compile a file into an AST. pub fn compile_file(&self, filename: &str) -> Result { Self::read_file(filename) .and_then(|contents| self.compile(&contents).map_err(|err| err.into())) } /// Evaluate a file. pub fn eval_file(&mut self, filename: &str) -> Result { Self::read_file(filename).and_then(|contents| self.eval::(&contents)) } /// Evaluate a string. pub fn eval(&mut self, input: &str) -> Result { let mut scope = Scope::new(); self.eval_with_scope(&mut scope, false, input) } /// Evaluate a string with own scope. /// /// Note - if `retain_functions` is set to `true`, functions defined by previous scripts are _retained_ /// and not cleared from run to run. pub fn eval_with_scope( &mut self, scope: &mut Scope, retain_functions: bool, input: &str, ) -> Result { let ast = self.compile(input).map_err(EvalAltResult::ErrorParsing)?; self.eval_ast_with_scope(scope, retain_functions, &ast) } /// Evaluate an AST. pub fn eval_ast(&mut self, ast: &AST) -> Result { let mut scope = Scope::new(); self.eval_ast_with_scope(&mut scope, false, ast) } /// Evaluate an AST with own scope. /// /// Note - if `retain_functions` is set to `true`, functions defined by previous scripts are _retained_ /// and not cleared from run to run. pub fn eval_ast_with_scope( &mut self, scope: &mut Scope, retain_functions: bool, ast: &AST, ) -> Result { fn eval_ast_internal( engine: &mut Engine, scope: &mut Scope, retain_functions: bool, ast: &AST, ) -> Result { let AST(statements, functions) = ast; functions.iter().for_each(|f| { engine.script_functions.insert( FnSpec { name: f.name.clone().into(), args: None, }, Arc::new(FnIntExt::Int(f.clone())), ); }); let result = statements .iter() .try_fold(().into_dynamic(), |_, stmt| engine.eval_stmt(scope, stmt)); if !retain_functions { engine.clear_functions(); } result } match eval_ast_internal(self, scope, retain_functions, ast) { Err(EvalAltResult::Return(out, pos)) => out.downcast::().map(|v| *v).map_err(|a| { EvalAltResult::ErrorMismatchOutputType( self.map_type_name((*a).type_name()).to_string(), pos, ) }), Ok(out) => out.downcast::().map(|v| *v).map_err(|a| { EvalAltResult::ErrorMismatchOutputType( self.map_type_name((*a).type_name()).to_string(), Position::eof(), ) }), Err(err) => Err(err), } } /// 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. pub fn consume_file(&mut self, filename: &str) -> Result<(), EvalAltResult> { let mut f = File::open(filename) .map_err(|err| EvalAltResult::ErrorReadingScriptFile(filename.into(), err))?; let mut contents = String::new(); f.read_to_string(&mut contents) .map_err(|err| EvalAltResult::ErrorReadingScriptFile(filename.into(), err)) .and_then(|_| self.consume(&contents)) } /// 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(&mut self, input: &str) -> Result<(), EvalAltResult> { self.consume_with_scope(&mut Scope::new(), false, input) } /// 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. /// /// Note - if `retain_functions` is set to `true`, functions defined by previous scripts are _retained_ /// and not cleared from run to run. pub fn consume_with_scope( &mut self, scope: &mut Scope, retain_functions: bool, input: &str, ) -> Result<(), EvalAltResult> { let tokens = lex(input); parse(&mut tokens.peekable(), self.optimize) .map_err(|err| EvalAltResult::ErrorParsing(err)) .and_then(|AST(ref statements, ref functions)| { for f in functions { self.script_functions.insert( FnSpec { name: f.name.clone().into(), args: None, }, Arc::new(FnIntExt::Int(f.clone())), ); } let val = statements .iter() .try_fold(().into_dynamic(), |_, o| self.eval_stmt(scope, o)) .map(|_| ()); if !retain_functions { self.clear_functions(); } val }) } /// Call a script function defined in a compiled AST. /// /// # Example /// /// ```rust /// # fn main() -> Result<(), rhai::EvalAltResult> { /// # #[cfg(not(feature = "no_stdlib"))] /// # { /// use rhai::Engine; /// /// let mut engine = Engine::new(); /// /// let ast = engine.compile("fn add(x, y) { x.len() + y }")?; /// /// let result: i64 = engine.call_fn("add", &ast, (String::from("abc"), 123_i64))?; /// /// assert_eq!(result, 126); /// # } /// # Ok(()) /// # } /// ``` pub fn call_fn( &mut self, name: &str, ast: &AST, args: A, ) -> Result { fn call_fn_internal( engine: &mut Engine, name: &str, ast: &AST, args: FnCallArgs, ) -> Result { ast.1.iter().for_each(|f| { engine.script_functions.insert( FnSpec { name: f.name.clone().into(), args: None, }, Arc::new(FnIntExt::Int(f.clone())), ); }); let result = engine.call_fn_raw(name, args, None, Position::none()); engine.clear_functions(); result } let mut arg_values = args.into_vec(); call_fn_internal( self, name, ast, arg_values.iter_mut().map(|v| v.as_mut()).collect(), ) .and_then(|b| { b.downcast().map(|b| *b).map_err(|a| { EvalAltResult::ErrorMismatchOutputType( self.map_type_name((*a).type_name()).into(), Position::none(), ) }) }) } /// Override default action of `print` (print to stdout using `println!`) /// /// # Example /// /// ```rust /// # fn main() -> Result<(), rhai::EvalAltResult> { /// use rhai::Engine; /// /// let mut result = String::from(""); /// { /// let mut engine = Engine::new(); /// /// // Override action of 'print' function /// engine.on_print(|s| result.push_str(s)); /// engine.consume("print(40 + 2);")?; /// } /// assert_eq!(result, "42"); /// # Ok(()) /// # } /// ``` pub fn on_print(&mut self, callback: impl FnMut(&str) + 'e) { self.on_print = Box::new(callback); } /// Override default action of `debug` (print to stdout using `println!`) /// /// # Example /// /// ```rust /// # fn main() -> Result<(), rhai::EvalAltResult> { /// use rhai::Engine; /// /// let mut result = String::from(""); /// { /// let mut engine = Engine::new(); /// /// // Override action of 'debug' function /// engine.on_debug(|s| result.push_str(s)); /// engine.consume(r#"debug("hello");"#)?; /// } /// assert_eq!(result, "\"hello\""); /// # Ok(()) /// # } /// ``` pub fn on_debug(&mut self, callback: impl FnMut(&str) + 'e) { self.on_debug = Box::new(callback); } }