2021-11-20 14:57:21 +08:00
|
|
|
//! Module that defines the public evaluation API of [`Engine`].
|
|
|
|
|
2022-04-16 16:36:53 +08:00
|
|
|
use crate::eval::{Caches, GlobalRuntimeState};
|
2021-11-20 14:57:21 +08:00
|
|
|
use crate::parser::ParseState;
|
2022-11-07 16:18:59 +08:00
|
|
|
use crate::{Engine, RhaiResultOf, Scope, AST};
|
2021-11-20 14:57:21 +08:00
|
|
|
#[cfg(feature = "no_std")]
|
|
|
|
use std::prelude::v1::*;
|
|
|
|
|
|
|
|
impl Engine {
|
2022-08-08 09:10:15 +08:00
|
|
|
/// Evaluate a string as a script.
|
|
|
|
///
|
|
|
|
/// # Example
|
|
|
|
///
|
|
|
|
/// ```
|
|
|
|
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
|
|
|
|
/// use rhai::Engine;
|
|
|
|
///
|
|
|
|
/// let engine = Engine::new();
|
|
|
|
///
|
2022-08-09 17:24:24 +08:00
|
|
|
/// engine.run("print(40 + 2);")?;
|
2022-08-08 09:10:15 +08:00
|
|
|
/// # Ok(())
|
|
|
|
/// # }
|
|
|
|
/// ```
|
2021-11-20 15:43:55 +08:00
|
|
|
#[inline(always)]
|
2021-12-25 23:49:14 +08:00
|
|
|
pub fn run(&self, script: &str) -> RhaiResultOf<()> {
|
2021-11-20 15:43:55 +08:00
|
|
|
self.run_with_scope(&mut Scope::new(), script)
|
|
|
|
}
|
2022-08-08 09:10:15 +08:00
|
|
|
/// Evaluate a string as a script with own scope.
|
2021-11-20 14:57:21 +08:00
|
|
|
///
|
|
|
|
/// ## Constants Propagation
|
|
|
|
///
|
2021-11-20 21:29:36 +08:00
|
|
|
/// If not [`OptimizationLevel::None`][crate::OptimizationLevel::None], constants defined within
|
2022-08-08 09:10:15 +08:00
|
|
|
/// the scope are propagated throughout the script _including_ functions.
|
|
|
|
///
|
|
|
|
/// This allows functions to be optimized based on dynamic global constants.
|
|
|
|
///
|
|
|
|
/// # Example
|
|
|
|
///
|
|
|
|
/// ```
|
|
|
|
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
|
|
|
|
/// use rhai::{Engine, Scope};
|
|
|
|
///
|
|
|
|
/// let engine = Engine::new();
|
|
|
|
///
|
|
|
|
/// // Create initialized scope
|
|
|
|
/// let mut scope = Scope::new();
|
|
|
|
/// scope.push("x", 40_i64);
|
|
|
|
///
|
|
|
|
/// engine.run_with_scope(&mut scope, "x += 2; print(x);")?;
|
|
|
|
///
|
|
|
|
/// // The variable in the scope is modified
|
2022-08-09 17:24:24 +08:00
|
|
|
/// assert_eq!(scope.get_value::<i64>("x").expect("variable x should exist"), 42);
|
2022-08-08 09:10:15 +08:00
|
|
|
/// # Ok(())
|
|
|
|
/// # }
|
|
|
|
/// ```
|
2021-11-20 14:57:21 +08:00
|
|
|
#[inline]
|
2021-12-25 23:49:14 +08:00
|
|
|
pub fn run_with_scope(&self, scope: &mut Scope, script: &str) -> RhaiResultOf<()> {
|
2021-11-20 14:57:21 +08:00
|
|
|
let scripts = [script];
|
|
|
|
let (stream, tokenizer_control) =
|
2022-07-05 16:26:38 +08:00
|
|
|
self.lex_raw(&scripts, self.token_mapper.as_ref().map(<_>::as_ref));
|
2022-08-12 16:34:57 +08:00
|
|
|
let mut state = ParseState::new(self, scope, Default::default(), tokenizer_control);
|
2022-05-21 22:13:02 +08:00
|
|
|
let ast = self.parse(&mut stream.peekable(), &mut state, self.optimization_level)?;
|
2021-11-20 14:57:21 +08:00
|
|
|
self.run_ast_with_scope(scope, &ast)
|
|
|
|
}
|
2022-08-08 09:10:15 +08:00
|
|
|
/// Evaluate an [`AST`].
|
|
|
|
///
|
|
|
|
/// # Example
|
|
|
|
///
|
|
|
|
/// ```
|
|
|
|
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
|
|
|
|
/// use rhai::Engine;
|
|
|
|
///
|
|
|
|
/// let engine = Engine::new();
|
|
|
|
///
|
|
|
|
/// // Compile a script to an AST and store it for later evaluation
|
|
|
|
/// let ast = engine.compile("print(40 + 2);")?;
|
|
|
|
///
|
|
|
|
/// // Evaluate it
|
|
|
|
/// engine.run_ast(&ast)?;
|
|
|
|
/// # Ok(())
|
|
|
|
/// # }
|
|
|
|
/// ```
|
2021-11-20 14:57:21 +08:00
|
|
|
#[inline(always)]
|
2021-12-25 23:49:14 +08:00
|
|
|
pub fn run_ast(&self, ast: &AST) -> RhaiResultOf<()> {
|
2021-11-20 14:57:21 +08:00
|
|
|
self.run_ast_with_scope(&mut Scope::new(), ast)
|
|
|
|
}
|
2022-08-08 09:10:15 +08:00
|
|
|
/// Evaluate an [`AST`] with own scope.
|
|
|
|
///
|
|
|
|
/// # Example
|
|
|
|
///
|
|
|
|
/// ```
|
|
|
|
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
|
|
|
|
/// use rhai::{Engine, Scope};
|
|
|
|
///
|
|
|
|
/// let engine = Engine::new();
|
|
|
|
///
|
|
|
|
/// // Create initialized scope
|
|
|
|
/// let mut scope = Scope::new();
|
|
|
|
/// scope.push("x", 40_i64);
|
|
|
|
///
|
|
|
|
/// // Compile a script to an AST and store it for later evaluation
|
|
|
|
/// let ast = engine.compile("x += 2; x")?;
|
|
|
|
///
|
|
|
|
/// // Evaluate it
|
|
|
|
/// engine.run_ast_with_scope(&mut scope, &ast)?;
|
|
|
|
///
|
|
|
|
/// // The variable in the scope is modified
|
2022-08-09 17:24:24 +08:00
|
|
|
/// assert_eq!(scope.get_value::<i64>("x").expect("variable x should exist"), 42);
|
2022-08-08 09:10:15 +08:00
|
|
|
/// # Ok(())
|
|
|
|
/// # }
|
|
|
|
/// ```
|
2021-11-20 14:57:21 +08:00
|
|
|
#[inline]
|
2021-12-25 23:49:14 +08:00
|
|
|
pub fn run_ast_with_scope(&self, scope: &mut Scope, ast: &AST) -> RhaiResultOf<()> {
|
2022-04-16 16:36:53 +08:00
|
|
|
let caches = &mut Caches::new();
|
2022-01-28 18:59:18 +08:00
|
|
|
let global = &mut GlobalRuntimeState::new(self);
|
2022-10-29 14:12:18 +08:00
|
|
|
global.source = ast.source_raw().cloned();
|
2022-01-01 17:20:00 +08:00
|
|
|
|
2021-11-20 14:57:21 +08:00
|
|
|
#[cfg(not(feature = "no_module"))]
|
|
|
|
{
|
2021-12-27 23:03:30 +08:00
|
|
|
global.embedded_module_resolver = ast.resolver().cloned();
|
2021-11-20 14:57:21 +08:00
|
|
|
}
|
|
|
|
|
|
|
|
let statements = ast.statements();
|
|
|
|
if !statements.is_empty() {
|
2021-11-29 09:43:35 +08:00
|
|
|
let lib = [
|
|
|
|
#[cfg(not(feature = "no_function"))]
|
2022-11-07 16:18:59 +08:00
|
|
|
AsRef::<crate::Shared<_>>::as_ref(ast).clone(),
|
2021-11-29 09:43:35 +08:00
|
|
|
];
|
2022-11-07 16:18:59 +08:00
|
|
|
let lib = if lib.first().map_or(true, |m| m.is_empty()) {
|
2021-11-29 09:43:35 +08:00
|
|
|
&lib[0..0]
|
|
|
|
} else {
|
|
|
|
&lib
|
|
|
|
};
|
2022-11-04 21:47:09 +08:00
|
|
|
self.eval_global_statements(global, caches, lib, 0, scope, statements)?;
|
2021-11-20 14:57:21 +08:00
|
|
|
}
|
2022-04-26 16:36:24 +08:00
|
|
|
|
|
|
|
#[cfg(feature = "debugging")]
|
|
|
|
if self.debugger.is_some() {
|
|
|
|
global.debugger.status = crate::eval::DebuggerStatus::Terminate;
|
2022-04-26 18:32:43 +08:00
|
|
|
let lib = &[
|
|
|
|
#[cfg(not(feature = "no_function"))]
|
2022-11-07 16:18:59 +08:00
|
|
|
AsRef::<crate::Shared<_>>::as_ref(ast).clone(),
|
2022-04-26 18:32:43 +08:00
|
|
|
];
|
2022-04-26 16:36:24 +08:00
|
|
|
let node = &crate::ast::Stmt::Noop(crate::Position::NONE);
|
2022-11-04 21:47:09 +08:00
|
|
|
self.run_debugger(global, caches, lib, 0, scope, &mut None, node)?;
|
2022-04-26 16:36:24 +08:00
|
|
|
}
|
|
|
|
|
2021-11-20 14:57:21 +08:00
|
|
|
Ok(())
|
|
|
|
}
|
|
|
|
}
|
2022-08-08 09:10:15 +08:00
|
|
|
|
|
|
|
/// Evaluate a string as a script.
|
|
|
|
///
|
|
|
|
/// # Example
|
|
|
|
///
|
|
|
|
/// ```
|
|
|
|
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
|
|
|
|
/// rhai::run("print(40 + 2);")?;
|
|
|
|
/// # Ok(())
|
|
|
|
/// # }
|
|
|
|
/// ```
|
|
|
|
#[inline(always)]
|
|
|
|
pub fn run(script: &str) -> RhaiResultOf<()> {
|
|
|
|
Engine::new().run(script)
|
|
|
|
}
|