1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
//! Module that defines public event handlers for [`Engine`].
use crate::func::SendSync;
use crate::{Dynamic, Engine, EvalContext, Position, RhaiResultOf};
#[cfg(feature = "no_std")]
use std::prelude::v1::*;
/// Information on a variable definition.
#[non_exhaustive]
pub struct VarDefInfo<'a> {
/// Name of the variable to be defined.
pub name: &'a str,
/// `true` if the statement is `const`, otherwise it is `let`.
pub is_const: bool,
/// The current nesting level, with zero being the global level.
pub nesting_level: usize,
/// Will the variable _shadow_ an existing variable?
pub will_shadow: bool,
}
impl Engine {
/// Provide a callback that will be invoked before each variable access.
///
/// # WARNING - Unstable API
///
/// This API is volatile and may change in the future.
///
/// # Callback Function Signature
///
/// `Fn(name: &str, index: usize, context: EvalContext) -> Result<Option<Dynamic>, Box<EvalAltResult>>`
///
/// where:
/// * `name`: name of the variable.
/// * `index`: an offset from the bottom of the current [`Scope`][crate::Scope] that the
/// variable is supposed to reside. Offsets start from 1, with 1 meaning the last variable in
/// the current [`Scope`][crate::Scope]. Essentially the correct variable is at position
/// `scope.len() - index`. If `index` is zero, then there is no pre-calculated offset position
/// and a search through the current [`Scope`][crate::Scope] must be performed.
/// * `context`: the current [evaluation context][`EvalContext`].
///
/// ## Return value
///
/// * `Ok(None)`: continue with normal variable access.
/// * `Ok(Some(Dynamic))`: the variable's value.
///
/// ## Raising errors
///
/// Return `Err(...)` if there is an error.
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// use rhai::Engine;
///
/// let mut engine = Engine::new();
///
/// // Register a variable resolver.
/// engine.on_var(|name, _, _| {
/// match name {
/// "MYSTIC_NUMBER" => Ok(Some(42_i64.into())),
/// _ => Ok(None)
/// }
/// });
///
/// engine.eval::<i64>("MYSTIC_NUMBER")?;
///
/// # Ok(())
/// # }
/// ```
#[deprecated = "This API is NOT deprecated, but it is considered volatile and may change in the future."]
#[inline(always)]
pub fn on_var(
&mut self,
callback: impl Fn(&str, usize, EvalContext) -> RhaiResultOf<Option<Dynamic>>
+ SendSync
+ 'static,
) -> &mut Self {
self.resolve_var = Some(Box::new(callback));
self
}
/// Provide a callback that will be invoked before the definition of each variable .
///
/// # WARNING - Unstable API
///
/// This API is volatile and may change in the future.
///
/// # Callback Function Signature
///
/// `Fn(is_runtime: bool, info: VarInfo, context: EvalContext) -> Result<bool, Box<EvalAltResult>>`
///
/// where:
/// * `is_runtime`: `true` if the variable definition event happens during runtime, `false` if during compilation.
/// * `info`: information on the variable.
/// * `context`: the current [evaluation context][`EvalContext`].
///
/// ## Return value
///
/// * `Ok(true)`: continue with normal variable definition.
/// * `Ok(false)`: deny the variable definition with an [runtime error][crate::EvalAltResult::ErrorRuntime].
///
/// ## Raising errors
///
/// Return `Err(...)` if there is an error.
///
/// # Example
///
/// ```should_panic
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// use rhai::Engine;
///
/// let mut engine = Engine::new();
///
/// // Register a variable definition filter.
/// engine.on_def_var(|_, info, _| {
/// // Disallow defining MYSTIC_NUMBER as a constant
/// if info.name == "MYSTIC_NUMBER" && info.is_const {
/// Ok(false)
/// } else {
/// Ok(true)
/// }
/// });
///
/// // The following runs fine:
/// engine.eval::<i64>("let MYSTIC_NUMBER = 42;")?;
///
/// // The following will cause an error:
/// engine.eval::<i64>("const MYSTIC_NUMBER = 42;")?;
///
/// # Ok(())
/// # }
/// ```
#[deprecated = "This API is NOT deprecated, but it is considered volatile and may change in the future."]
#[inline(always)]
pub fn on_def_var(
&mut self,
callback: impl Fn(bool, VarDefInfo, EvalContext) -> RhaiResultOf<bool> + SendSync + 'static,
) -> &mut Self {
self.def_var_filter = Some(Box::new(callback));
self
}
/// _(internals)_ Register a callback that will be invoked during parsing to remap certain tokens.
/// Exported under the `internals` feature only.
///
/// # WARNING - Unstable API
///
/// This API is volatile and may change in the future.
///
/// # Callback Function Signature
///
/// `Fn(token: Token, pos: Position, state: &TokenizeState) -> Token`
///
/// where:
/// * [`token`][crate::tokenizer::Token]: current token parsed
/// * [`pos`][`Position`]: location of the token
/// * [`state`][crate::tokenizer::TokenizeState]: current state of the tokenizer
///
/// ## Raising errors
///
/// It is possible to raise a parsing error by returning
/// [`Token::LexError`][crate::tokenizer::Token::LexError] as the mapped token.
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// use rhai::{Engine, Token};
///
/// let mut engine = Engine::new();
///
/// // Register a token mapper.
/// engine.on_parse_token(|token, _, _| {
/// match token {
/// // Convert all integer literals to strings
/// Token::IntegerConstant(n) => Token::StringConstant(n.to_string().into()),
/// // Convert 'begin' .. 'end' to '{' .. '}'
/// Token::Identifier(s) if &*s == "begin" => Token::LeftBrace,
/// Token::Identifier(s) if &*s == "end" => Token::RightBrace,
/// // Pass through all other tokens unchanged
/// _ => token
/// }
/// });
///
/// assert_eq!(engine.eval::<String>("42")?, "42");
/// assert_eq!(engine.eval::<bool>("true")?, true);
/// assert_eq!(engine.eval::<String>("let x = 42; begin let x = 0; end; x")?, "42");
///
/// # Ok(())
/// # }
/// ```
#[deprecated = "This API is NOT deprecated, but it is considered volatile and may change in the future."]
#[cfg(feature = "internals")]
#[inline(always)]
pub fn on_parse_token(
&mut self,
callback: impl Fn(
crate::tokenizer::Token,
Position,
&crate::tokenizer::TokenizeState,
) -> crate::tokenizer::Token
+ SendSync
+ 'static,
) -> &mut Self {
self.token_mapper = Some(Box::new(callback));
self
}
/// Register a callback for script evaluation progress.
///
/// Not available under `unchecked`.
///
/// # Callback Function Signature
///
/// `Fn(counter: u64) -> Option<Dynamic>`
///
/// ## Return value
///
/// * `None`: continue running the script.
/// * `Some(Dynamic)`: terminate the script with the specified exception value.
///
/// # 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();
///
/// engine.on_progress(move |ops| {
/// if ops > 1000 {
/// Some("Over 1,000 operations!".into())
/// } else if ops % 123 == 0 {
/// *logger.write().unwrap() = ops;
/// None
/// } else {
/// None
/// }
/// });
///
/// engine.run("for x in 0..5000 { print(x); }")
/// .expect_err("should error");
///
/// assert_eq!(*result.read().unwrap(), 984);
///
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "unchecked"))]
#[inline(always)]
pub fn on_progress(
&mut self,
callback: impl Fn(u64) -> Option<Dynamic> + SendSync + 'static,
) -> &mut Self {
self.progress = Some(Box::new(callback));
self
}
/// Override default action of `print` (print to stdout using [`println!`])
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// # use std::sync::RwLock;
/// # use std::sync::Arc;
/// use rhai::Engine;
///
/// let result = Arc::new(RwLock::new(String::new()));
///
/// 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.run("print(40 + 2);")?;
///
/// assert_eq!(*result.read().unwrap(), "42");
/// # Ok(())
/// # }
/// ```
#[inline(always)]
pub fn on_print(&mut self, callback: impl Fn(&str) + SendSync + 'static) -> &mut Self {
self.print = Box::new(callback);
self
}
/// Override default action of `debug` (print to stdout using [`println!`])
///
/// # Callback Function Signature
///
/// The callback function signature passed takes the following form:
///
/// `Fn(text: &str, source: Option<&str>, pos: Position)`
///
/// where:
/// * `text`: the text to display
/// * `source`: current source, if any
/// * [`pos`][`Position`]: location of the `debug` call
///
/// # Example
///
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// # use std::sync::RwLock;
/// # use std::sync::Arc;
/// use rhai::Engine;
///
/// let result = Arc::new(RwLock::new(String::new()));
///
/// let mut engine = Engine::new();
///
/// // Override action of 'print' function
/// let logger = result.clone();
/// engine.on_debug(move |s, src, pos| logger.write().unwrap().push_str(
/// &format!("{} @ {:?} > {}", src.unwrap_or("unknown"), pos, s)
/// ));
///
/// let mut ast = engine.compile(r#"let x = "hello"; debug(x);"#)?;
/// ast.set_source("world");
/// engine.run_ast(&ast)?;
///
/// #[cfg(not(feature = "no_position"))]
/// assert_eq!(*result.read().unwrap(), r#"world @ 1:18 > "hello""#);
/// #[cfg(feature = "no_position")]
/// assert_eq!(*result.read().unwrap(), r#"world @ none > "hello""#);
/// # Ok(())
/// # }
/// ```
#[inline(always)]
pub fn on_debug(
&mut self,
callback: impl Fn(&str, Option<&str>, Position) + SendSync + 'static,
) -> &mut Self {
self.debug = Box::new(callback);
self
}
/// _(debugging)_ Register a callback for debugging.
/// Exported under the `debugging` feature only.
///
/// # WARNING - Unstable API
///
/// This API is volatile and may change in the future.
#[deprecated = "This API is NOT deprecated, but it is considered volatile and may change in the future."]
#[cfg(feature = "debugging")]
#[inline(always)]
pub fn register_debugger(
&mut self,
init: impl Fn(&Self) -> Dynamic + SendSync + 'static,
callback: impl Fn(
EvalContext,
crate::eval::DebuggerEvent,
crate::ast::ASTNode,
Option<&str>,
Position,
) -> RhaiResultOf<crate::eval::DebuggerCommand>
+ SendSync
+ 'static,
) -> &mut Self {
self.debugger = Some((Box::new(init), Box::new(callback)));
self
}
}