rhai/src/scope.rs

464 lines
14 KiB
Rust
Raw Normal View History

2020-03-08 12:54:02 +01:00
//! Module that defines the `Scope` type representing a function call-stack scope.
2020-05-04 17:07:42 +02:00
use crate::any::{Dynamic, Union, Variant};
use crate::module::Module;
use crate::parser::{map_dynamic_to_expr, Expr};
use crate::token::Position;
2020-03-11 04:03:18 +01:00
use crate::stdlib::{borrow::Cow, boxed::Box, iter, string::String, vec::Vec};
2020-03-03 08:20:20 +01:00
2020-03-25 04:27:18 +01:00
/// Type of an entry in the Scope.
2020-03-13 11:12:41 +01:00
#[derive(Debug, Eq, PartialEq, Hash, Copy, Clone)]
2020-03-25 04:27:18 +01:00
pub enum EntryType {
/// Normal value.
2020-03-13 11:12:41 +01:00
Normal,
/// Immutable constant value.
2020-03-13 11:12:41 +01:00
Constant,
2020-05-05 04:39:12 +02:00
/// Name of a module, allowing member access with the :: operator.
/// This is for internal use only.
Module,
2020-03-13 11:12:41 +01:00
}
/// An entry in the Scope.
2020-05-12 12:48:25 +02:00
#[derive(Debug, Clone)]
2020-03-25 04:27:18 +01:00
pub struct Entry<'a> {
/// Name of the entry.
pub name: Cow<'a, str>,
2020-03-25 04:27:18 +01:00
/// Type of the entry.
pub typ: EntryType,
/// Current value of the entry.
2020-04-27 03:36:31 +02:00
pub value: Dynamic,
2020-05-08 10:49:24 +02:00
/// Alias of the entry.
pub alias: Option<Box<String>>,
/// A constant expression if the initial value matches one of the recognized types.
2020-04-27 15:14:34 +02:00
pub expr: Option<Box<Expr>>,
}
2020-05-15 15:40:54 +02:00
/// Type containing information about the current scope.
/// Useful for keeping state between `Engine` evaluation runs.
2020-03-03 08:20:20 +01:00
///
2020-03-04 15:00:01 +01:00
/// # Example
///
2020-03-19 06:52:10 +01:00
/// ```
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
2020-03-03 08:20:20 +01:00
/// use rhai::{Engine, Scope};
///
/// let engine = Engine::new();
2020-03-03 08:20:20 +01:00
/// let mut my_scope = Scope::new();
///
2020-04-05 17:43:40 +02:00
/// my_scope.push("z", 40_i64);
2020-03-09 14:09:53 +01:00
///
2020-04-05 17:43:40 +02:00
/// engine.eval_with_scope::<()>(&mut my_scope, "let x = z + 1; z = 0;")?;
///
/// assert_eq!(engine.eval_with_scope::<i64>(&mut my_scope, "x + 1")?, 42);
///
/// assert_eq!(my_scope.get_value::<i64>("x").unwrap(), 41);
/// assert_eq!(my_scope.get_value::<i64>("z").unwrap(), 0);
2020-03-09 14:09:53 +01:00
/// # Ok(())
/// # }
2020-03-03 08:20:20 +01:00
/// ```
///
2020-03-25 04:27:18 +01:00
/// When searching for entries, newly-added entries are found before similarly-named but older entries,
/// allowing for automatic _shadowing_.
2020-04-03 13:42:01 +02:00
///
/// Currently, `Scope` is neither `Send` nor `Sync`. Turn on the `sync` feature to make it `Send + Sync`.
2020-05-12 12:48:25 +02:00
#[derive(Debug, Clone, Default)]
2020-03-25 04:27:18 +01:00
pub struct Scope<'a>(Vec<Entry<'a>>);
2020-03-03 08:20:20 +01:00
2020-03-07 03:15:42 +01:00
impl<'a> Scope<'a> {
2020-03-03 08:20:20 +01:00
/// Create a new Scope.
2020-04-05 17:43:40 +02:00
///
/// # Examples
///
/// ```
/// use rhai::Scope;
///
/// let mut my_scope = Scope::new();
///
/// my_scope.push("x", 42_i64);
/// assert_eq!(my_scope.get_value::<i64>("x").unwrap(), 42);
/// ```
2020-03-03 08:20:20 +01:00
pub fn new() -> Self {
2020-05-05 09:00:10 +02:00
Default::default()
2020-03-03 08:20:20 +01:00
}
/// Empty the Scope.
2020-04-05 17:43:40 +02:00
///
/// # Examples
///
/// ```
/// use rhai::Scope;
///
/// let mut my_scope = Scope::new();
///
/// my_scope.push("x", 42_i64);
/// assert!(my_scope.contains("x"));
/// assert_eq!(my_scope.len(), 1);
/// assert!(!my_scope.is_empty());
///
/// my_scope.clear();
/// assert!(!my_scope.contains("x"));
/// assert_eq!(my_scope.len(), 0);
/// assert!(my_scope.is_empty());
/// ```
2020-03-03 08:20:20 +01:00
pub fn clear(&mut self) {
self.0.clear();
}
2020-03-25 04:27:18 +01:00
/// Get the number of entries inside the Scope.
2020-04-05 17:43:40 +02:00
///
/// # Examples
///
/// ```
/// use rhai::Scope;
///
/// let mut my_scope = Scope::new();
/// assert_eq!(my_scope.len(), 0);
///
/// my_scope.push("x", 42_i64);
/// assert_eq!(my_scope.len(), 1);
/// ```
2020-03-03 08:20:20 +01:00
pub fn len(&self) -> usize {
self.0.len()
}
2020-03-24 09:57:35 +01:00
/// Is the Scope empty?
2020-04-05 17:43:40 +02:00
///
/// # Examples
///
/// ```
/// use rhai::Scope;
///
/// let mut my_scope = Scope::new();
/// assert!(my_scope.is_empty());
///
/// my_scope.push("x", 42_i64);
/// assert!(!my_scope.is_empty());
/// ```
2020-03-24 09:57:35 +01:00
pub fn is_empty(&self) -> bool {
self.0.len() == 0
}
2020-03-25 04:27:18 +01:00
/// Add (push) a new entry to the Scope.
2020-04-05 17:43:40 +02:00
///
/// # Examples
///
/// ```
/// use rhai::Scope;
///
/// let mut my_scope = Scope::new();
///
/// my_scope.push("x", 42_i64);
/// assert_eq!(my_scope.get_value::<i64>("x").unwrap(), 42);
/// ```
2020-04-12 17:00:06 +02:00
pub fn push<K: Into<Cow<'a, str>>, T: Variant + Clone>(&mut self, name: K, value: T) {
self.push_dynamic_value(name, EntryType::Normal, Dynamic::from(value), false);
2020-03-25 04:27:18 +01:00
}
2020-03-25 04:27:18 +01:00
/// Add (push) a new `Dynamic` entry to the Scope.
2020-04-05 17:43:40 +02:00
///
/// # Examples
///
/// ```
2020-04-12 17:00:06 +02:00
/// use rhai::{Dynamic, Scope};
2020-04-05 17:43:40 +02:00
///
/// let mut my_scope = Scope::new();
///
2020-04-12 17:00:06 +02:00
/// my_scope.push_dynamic("x", Dynamic::from(42_i64));
2020-04-05 17:43:40 +02:00
/// assert_eq!(my_scope.get_value::<i64>("x").unwrap(), 42);
/// ```
2020-03-25 04:27:18 +01:00
pub fn push_dynamic<K: Into<Cow<'a, str>>>(&mut self, name: K, value: Dynamic) {
self.push_dynamic_value(name, EntryType::Normal, value, false);
2020-03-03 08:20:20 +01:00
}
2020-05-05 04:39:12 +02:00
/// Add (push) a new module to the Scope.
2020-05-03 19:19:01 +02:00
///
2020-05-05 04:39:12 +02:00
/// Modules are used for accessing member variables, functions and plugins under a namespace.
#[cfg(not(feature = "no_module"))]
2020-06-02 07:33:16 +02:00
pub fn push_module<K: Into<Cow<'a, str>>>(&mut self, name: K, value: Module) {
self.push_module_internal(name, value);
}
/// Add (push) a new module to the Scope.
///
/// Modules are used for accessing member variables, functions and plugins under a namespace.
pub(crate) fn push_module_internal<K: Into<Cow<'a, str>>>(
&mut self,
name: K,
mut value: Module,
) {
2020-05-09 04:00:59 +02:00
value.index_all_sub_modules();
2020-05-04 17:07:42 +02:00
self.push_dynamic_value(
name,
2020-05-05 04:39:12 +02:00
EntryType::Module,
Dynamic(Union::Module(Box::new(value))),
2020-05-05 09:00:10 +02:00
false,
2020-05-04 17:07:42 +02:00
);
2020-05-03 19:19:01 +02:00
}
2020-03-13 11:12:41 +01:00
/// Add (push) a new constant to the Scope.
///
/// Constants are immutable and cannot be assigned to. Their values never change.
/// Constants propagation is a technique used to optimize an AST.
2020-04-05 17:43:40 +02:00
///
/// However, in order to be used for optimization, constants must be in one of the recognized types:
/// `INT` (default to `i64`, `i32` if `only_i32`), `f64`, `String`, `char` and `bool`.
2020-04-05 17:43:40 +02:00
///
/// # Examples
///
/// ```
/// use rhai::Scope;
///
/// let mut my_scope = Scope::new();
///
/// my_scope.push_constant("x", 42_i64);
/// assert_eq!(my_scope.get_value::<i64>("x").unwrap(), 42);
/// ```
2020-04-12 17:00:06 +02:00
pub fn push_constant<K: Into<Cow<'a, str>>, T: Variant + Clone>(&mut self, name: K, value: T) {
self.push_dynamic_value(name, EntryType::Constant, Dynamic::from(value), true);
2020-03-25 04:27:18 +01:00
}
2020-03-25 04:27:18 +01:00
/// Add (push) a new constant with a `Dynamic` value to the Scope.
///
/// Constants are immutable and cannot be assigned to. Their values never change.
/// Constants propagation is a technique used to optimize an AST.
2020-04-05 17:43:40 +02:00
///
2020-03-25 04:27:18 +01:00
/// However, in order to be used for optimization, the `Dynamic` value must be in one of the
/// recognized types:
/// `INT` (default to `i64`, `i32` if `only_i32`), `f64`, `String`, `char` and `bool`.
2020-04-05 17:43:40 +02:00
///
/// # Examples
///
/// ```
2020-04-12 17:00:06 +02:00
/// use rhai::{Dynamic, Scope};
2020-04-05 17:43:40 +02:00
///
/// let mut my_scope = Scope::new();
///
2020-04-12 17:00:06 +02:00
/// my_scope.push_constant_dynamic("x", Dynamic::from(42_i64));
2020-04-05 17:43:40 +02:00
/// assert_eq!(my_scope.get_value::<i64>("x").unwrap(), 42);
/// ```
2020-03-25 04:27:18 +01:00
pub fn push_constant_dynamic<K: Into<Cow<'a, str>>>(&mut self, name: K, value: Dynamic) {
self.push_dynamic_value(name, EntryType::Constant, value, true);
2020-03-13 11:12:41 +01:00
}
2020-03-25 04:27:18 +01:00
/// Add (push) a new entry with a `Dynamic` value to the Scope.
pub(crate) fn push_dynamic_value<K: Into<Cow<'a, str>>>(
2020-03-13 11:12:41 +01:00
&mut self,
name: K,
2020-03-25 04:27:18 +01:00
entry_type: EntryType,
2020-03-13 11:12:41 +01:00
value: Dynamic,
2020-03-25 04:27:18 +01:00
map_expr: bool,
2020-03-13 11:12:41 +01:00
) {
2020-04-26 12:04:07 +02:00
let expr = if map_expr {
2020-04-27 15:14:34 +02:00
map_dynamic_to_expr(value.clone(), Position::none()).map(Box::new)
2020-04-26 12:04:07 +02:00
} else {
None
};
2020-03-25 04:27:18 +01:00
self.0.push(Entry {
name: name.into(),
2020-03-25 04:27:18 +01:00
typ: entry_type,
2020-05-08 10:49:24 +02:00
alias: None,
2020-04-26 12:04:07 +02:00
value: value.into(),
expr,
});
2020-03-03 08:20:20 +01:00
}
/// Truncate (rewind) the Scope to a previous size.
2020-04-05 17:43:40 +02:00
///
/// # Examples
///
/// ```
/// use rhai::Scope;
///
/// let mut my_scope = Scope::new();
///
/// my_scope.push("x", 42_i64);
/// my_scope.push("y", 123_i64);
/// assert!(my_scope.contains("x"));
/// assert!(my_scope.contains("y"));
/// assert_eq!(my_scope.len(), 2);
///
/// my_scope.rewind(1);
/// assert!(my_scope.contains("x"));
/// assert!(!my_scope.contains("y"));
/// assert_eq!(my_scope.len(), 1);
///
/// my_scope.rewind(0);
/// assert!(!my_scope.contains("x"));
/// assert!(!my_scope.contains("y"));
/// assert_eq!(my_scope.len(), 0);
/// assert!(my_scope.is_empty());
/// ```
2020-03-03 08:20:20 +01:00
pub fn rewind(&mut self, size: usize) {
self.0.truncate(size);
}
2020-03-25 04:27:18 +01:00
/// Does the scope contain the entry?
2020-04-05 17:43:40 +02:00
///
/// # Examples
///
/// ```
/// use rhai::Scope;
///
/// let mut my_scope = Scope::new();
///
/// my_scope.push("x", 42_i64);
/// assert!(my_scope.contains("x"));
/// assert!(!my_scope.contains("y"));
/// ```
pub fn contains(&self, name: &str) -> bool {
2020-03-19 13:55:49 +01:00
self.0
.iter()
.rev() // Always search a Scope in reverse order
2020-05-04 11:43:54 +02:00
.any(|Entry { name: key, typ, .. }| match typ {
EntryType::Normal | EntryType::Constant => name == key,
2020-05-05 04:39:12 +02:00
EntryType::Module => false,
2020-05-04 11:43:54 +02:00
})
2020-03-19 13:55:49 +01:00
}
2020-03-25 04:27:18 +01:00
/// Find an entry in the Scope, starting from the last.
2020-05-04 11:43:54 +02:00
///
2020-05-05 04:39:12 +02:00
/// modules are ignored.
2020-05-04 13:36:58 +02:00
pub(crate) fn get_index(&self, name: &str) -> Option<(usize, EntryType)> {
2020-03-03 08:20:20 +01:00
self.0
.iter()
.enumerate()
2020-03-04 15:00:01 +01:00
.rev() // Always search a Scope in reverse order
2020-05-04 11:43:54 +02:00
.find_map(|(index, Entry { name: key, typ, .. })| match typ {
EntryType::Normal | EntryType::Constant => {
if name == key {
Some((index, *typ))
} else {
None
}
}
2020-05-05 04:39:12 +02:00
EntryType::Module => None,
})
2020-03-03 08:20:20 +01:00
}
2020-05-05 04:39:12 +02:00
/// Find a module in the Scope, starting from the last.
pub(crate) fn get_module_index(&self, name: &str) -> Option<usize> {
2020-05-04 13:36:58 +02:00
self.0
.iter()
.enumerate()
.rev() // Always search a Scope in reverse order
.find_map(|(index, Entry { name: key, typ, .. })| match typ {
2020-05-05 04:39:12 +02:00
EntryType::Module => {
2020-05-04 13:36:58 +02:00
if name == key {
Some(index)
} else {
None
}
}
EntryType::Normal | EntryType::Constant => None,
})
}
2020-05-05 04:39:12 +02:00
/// Find a module in the Scope, starting from the last entry.
#[cfg(not(feature = "no_module"))]
2020-05-05 04:39:12 +02:00
pub fn find_module(&mut self, name: &str) -> Option<&mut Module> {
self.find_module_internal(name)
}
/// Find a module in the Scope, starting from the last entry.
pub(crate) fn find_module_internal(&mut self, name: &str) -> Option<&mut Module> {
2020-05-05 04:39:12 +02:00
let index = self.get_module_index(name)?;
self.get_mut(index).0.downcast_mut::<Module>()
2020-05-03 19:19:01 +02:00
}
2020-03-25 04:27:18 +01:00
/// Get the value of an entry in the Scope, starting from the last.
2020-04-05 17:43:40 +02:00
///
2020-05-05 04:39:12 +02:00
/// modules are ignored.
2020-05-04 11:43:54 +02:00
///
2020-04-05 17:43:40 +02:00
/// # Examples
///
/// ```
/// use rhai::Scope;
///
/// let mut my_scope = Scope::new();
///
/// my_scope.push("x", 42_i64);
/// assert_eq!(my_scope.get_value::<i64>("x").unwrap(), 42);
/// ```
2020-04-12 17:00:06 +02:00
pub fn get_value<T: Variant + Clone>(&self, name: &str) -> Option<T> {
2020-03-03 08:20:20 +01:00
self.0
.iter()
2020-04-05 17:43:40 +02:00
.rev()
2020-05-04 11:43:54 +02:00
.find(|Entry { name: key, typ, .. }| match typ {
EntryType::Normal | EntryType::Constant => name == key,
2020-05-05 04:39:12 +02:00
EntryType::Module => false,
2020-05-04 11:43:54 +02:00
})
2020-04-27 03:36:31 +02:00
.and_then(|Entry { value, .. }| value.downcast_ref::<T>().cloned())
2020-03-03 08:20:20 +01:00
}
2020-04-05 17:43:40 +02:00
/// Update the value of the named entry.
/// Search starts backwards from the last, and only the first entry matching the specified name is updated.
/// If no entry matching the specified name is found, a new one is added.
2020-04-05 13:17:48 +02:00
///
/// # Panics
///
/// Panics when trying to update the value of a constant.
2020-04-05 17:43:40 +02:00
///
/// # Examples
///
/// ```
/// use rhai::Scope;
///
/// let mut my_scope = Scope::new();
///
/// my_scope.push("x", 42_i64);
/// assert_eq!(my_scope.get_value::<i64>("x").unwrap(), 42);
///
/// my_scope.set_value("x", 0_i64);
/// assert_eq!(my_scope.get_value::<i64>("x").unwrap(), 0);
/// ```
2020-04-12 17:00:06 +02:00
pub fn set_value<T: Variant + Clone>(&mut self, name: &'a str, value: T) {
2020-05-04 13:36:58 +02:00
match self.get_index(name) {
2020-05-04 11:43:54 +02:00
None => self.push(name, value),
2020-04-27 16:49:09 +02:00
Some((_, EntryType::Constant)) => panic!("variable {} is constant", name),
Some((index, EntryType::Normal)) => {
self.0.get_mut(index).unwrap().value = Dynamic::from(value)
}
2020-05-05 04:39:12 +02:00
// modules cannot be modified
Some((_, EntryType::Module)) => unreachable!(),
2020-04-05 13:17:48 +02:00
}
}
2020-03-25 04:27:18 +01:00
/// Get a mutable reference to an entry in the Scope.
2020-04-28 17:05:03 +02:00
pub(crate) fn get_mut(&mut self, index: usize) -> (&mut Dynamic, EntryType) {
2020-04-27 16:49:09 +02:00
let entry = self.0.get_mut(index).expect("invalid index in Scope");
2020-04-28 17:05:03 +02:00
(&mut entry.value, entry.typ)
2020-03-03 08:20:20 +01:00
}
2020-05-08 10:49:24 +02:00
/// Update the access type of an entry in the Scope.
pub(crate) fn set_entry_alias(&mut self, index: usize, alias: String) {
let entry = self.0.get_mut(index).expect("invalid index in Scope");
entry.alias = Some(Box::new(alias));
}
2020-05-05 17:57:25 +02:00
/// Get an iterator to entries in the Scope.
pub(crate) fn into_iter(self) -> impl Iterator<Item = Entry<'a>> {
self.0.into_iter()
}
2020-03-25 04:27:18 +01:00
/// Get an iterator to entries in the Scope.
2020-04-28 13:39:28 +02:00
pub(crate) fn iter(&self) -> impl Iterator<Item = &Entry> {
self.0.iter().rev() // Always search a Scope in reverse order
2020-03-03 08:20:20 +01:00
}
}
2020-04-27 14:43:55 +02:00
impl<'a, K: Into<Cow<'a, str>>> iter::Extend<(K, EntryType, Dynamic)> for Scope<'a> {
2020-03-25 04:27:18 +01:00
fn extend<T: IntoIterator<Item = (K, EntryType, Dynamic)>>(&mut self, iter: T) {
self.0
2020-03-25 04:27:18 +01:00
.extend(iter.into_iter().map(|(name, typ, value)| Entry {
name: name.into(),
2020-03-25 04:27:18 +01:00
typ,
2020-05-08 10:49:24 +02:00
alias: None,
2020-04-26 12:04:07 +02:00
value: value.into(),
expr: None,
}));
}
}