rhai/api/
run.rs

1//! Module that defines the public evaluation API of [`Engine`].
2
3use crate::eval::Caches;
4use crate::parser::ParseState;
5use crate::{Engine, RhaiResultOf, Scope, AST};
6#[cfg(feature = "no_std")]
7use std::prelude::v1::*;
8
9impl Engine {
10    /// Evaluate a string as a script.
11    ///
12    /// # Example
13    ///
14    /// ```
15    /// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
16    /// use rhai::Engine;
17    ///
18    /// let engine = Engine::new();
19    ///
20    /// engine.run("print(40 + 2);")?;
21    /// # Ok(())
22    /// # }
23    /// ```
24    #[inline(always)]
25    pub fn run(&self, script: &str) -> RhaiResultOf<()> {
26        self.run_with_scope(&mut Scope::new(), script)
27    }
28    /// Evaluate a string as a script with own scope.
29    ///
30    /// ## Constants Propagation
31    ///
32    /// If not [`OptimizationLevel::None`][crate::OptimizationLevel::None], constants defined within
33    /// the scope are propagated throughout the script _including_ functions.
34    ///
35    /// This allows functions to be optimized based on dynamic global constants.
36    ///
37    /// # Example
38    ///
39    /// ```
40    /// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
41    /// use rhai::{Engine, Scope};
42    ///
43    /// let engine = Engine::new();
44    ///
45    /// // Create initialized scope
46    /// let mut scope = Scope::new();
47    /// scope.push("x", 40_i64);
48    ///
49    /// engine.run_with_scope(&mut scope, "x += 2; print(x);")?;
50    ///
51    /// // The variable in the scope is modified
52    /// assert_eq!(scope.get_value::<i64>("x").expect("variable x should exist"), 42);
53    /// # Ok(())
54    /// # }
55    /// ```
56    #[inline]
57    pub fn run_with_scope(&self, scope: &mut Scope, script: &str) -> RhaiResultOf<()> {
58        let scripts = [script];
59        let ast = {
60            let (stream, tc) = self.lex(&scripts);
61
62            let input = &mut stream.peekable();
63            let lib = &mut <_>::default();
64            let state = ParseState::new(Some(scope), input, tc, lib);
65
66            self.parse(
67                state,
68                #[cfg(not(feature = "no_optimize"))]
69                self.optimization_level,
70            )?
71        };
72        self.run_ast_with_scope(scope, &ast)
73    }
74    /// Evaluate an [`AST`].
75    ///
76    /// # Example
77    ///
78    /// ```
79    /// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
80    /// use rhai::Engine;
81    ///
82    /// let engine = Engine::new();
83    ///
84    /// // Compile a script to an AST and store it for later evaluation
85    /// let ast = engine.compile("print(40 + 2);")?;
86    ///
87    /// // Evaluate it
88    /// engine.run_ast(&ast)?;
89    /// # Ok(())
90    /// # }
91    /// ```
92    #[inline(always)]
93    pub fn run_ast(&self, ast: &AST) -> RhaiResultOf<()> {
94        self.run_ast_with_scope(&mut Scope::new(), ast)
95    }
96    /// Evaluate an [`AST`] with own scope.
97    ///
98    /// # Example
99    ///
100    /// ```
101    /// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
102    /// use rhai::{Engine, Scope};
103    ///
104    /// let engine = Engine::new();
105    ///
106    /// // Create initialized scope
107    /// let mut scope = Scope::new();
108    /// scope.push("x", 40_i64);
109    ///
110    /// // Compile a script to an AST and store it for later evaluation
111    /// let ast = engine.compile("x += 2; x")?;
112    ///
113    /// // Evaluate it
114    /// engine.run_ast_with_scope(&mut scope, &ast)?;
115    ///
116    /// // The variable in the scope is modified
117    /// assert_eq!(scope.get_value::<i64>("x").expect("variable x should exist"), 42);
118    /// # Ok(())
119    /// # }
120    /// ```
121    #[inline]
122    pub fn run_ast_with_scope(&self, scope: &mut Scope, ast: &AST) -> RhaiResultOf<()> {
123        let caches = &mut Caches::new();
124        let global = &mut self.new_global_runtime_state();
125        global.source = ast.source_raw().cloned();
126
127        #[cfg(not(feature = "no_function"))]
128        global.lib.push(ast.shared_lib().clone());
129
130        #[cfg(not(feature = "no_module"))]
131        global.embedded_module_resolver.clone_from(&ast.resolver);
132
133        let _ = self.eval_global_statements(global, caches, scope, ast.statements(), true)?;
134
135        #[cfg(feature = "debugging")]
136        if self.is_debugger_registered() {
137            global.debugger_mut().status = crate::eval::DebuggerStatus::Terminate;
138            let node = &crate::ast::Stmt::Noop(crate::Position::NONE);
139            self.dbg(global, caches, scope, None, node)?;
140        }
141
142        Ok(())
143    }
144}
145
146/// Evaluate a string as a script.
147///
148/// # Example
149///
150/// ```
151/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
152/// rhai::run("print(40 + 2);")?;
153/// # Ok(())
154/// # }
155/// ```
156#[inline(always)]
157pub fn run(script: &str) -> RhaiResultOf<()> {
158    Engine::new().run(script)
159}
rhai/api/run.rs

rhai/api/
run.rs
