Scope – Maintaining State

By default, Rhai treats each Engine invocation as a fresh one, persisting only the functions that have been registered but no global state.

This gives each evaluation a clean starting slate.

In order to continue using the same global state from one invocation to the next, such a state (a Scope) must be manually created and passed in.

All Scope variables and constants have values that are Dynamic, meaning they can store values of any type.

Under sync, however, only types that are Send + Sync are supported, and the entire Scope itself will also be Send + Sync. This is extremely useful in multi-threaded applications.

Scope API

MethodDescription
new instance methodcreate a new empty Scope
lennumber of variables/constants currently within the Scope
rewindrewind (i.e. reset) the Scope to a particular number of variables/constants
clearremove all variables/constants from the Scope, making it empty
is_emptyis the Scope empty?
push, push_constantadd a new variable/constant into the Scope with a specified value
push_dynamic, push_constant_dynamicadd a new variable/constant into the Scope with a Dynamic value
containsdoes the particular variable or constant exist in the Scope?
get_value<T>, get_mut<T>get the value of a variable within the Scope
set_value<T>set the value of a variable within the Scope, panics if it is constant
is_constantis the particular variable in the Scope a constant?
set_or_push<T>set the value of a variable within the Scope if it exists and is not constant; add a new variable into the Scope otherwise
iter, iter_raw, IntoIterator::into_iterget an iterator to the variables/constants within the Scope
Extend::extendadd variables/constants to the Scope

For details on the Scope API, refer to the documentation online.

Shadowing

A newly-added variable or constant shadows previous ones of the same name.

In other words, all versions are kept for variables and constants, but only the latest ones can be accessed via get_value<T>, get_mut<T> and set_value<T>.

Essentially, a Scope is always searched in reverse order.

Example

In the following example, a Scope is created with a few initialized variables, then it is threaded through multiple evaluations.


#![allow(unused)]
fn main() {
use rhai::{Engine, Scope, EvalAltResult};

let engine = Engine::new();

// First create the state
let mut scope = Scope::new();

// Then push (i.e. add) some initialized variables into the state.
// Remember the system number types in Rhai are i64 (i32 if 'only_i32')
// and f64 (f32 if 'f32_float').
// Better stick to them or it gets hard working with the script.
scope.push("y", 42_i64)
     .push("z", 999_i64)
     .push_constant("MY_NUMBER", 123_i64)       // constants can also be added
     .set_value("s", "hello, world!");          // 'set_value' adds a variable when one doesn't exist

// First invocation
engine.run_with_scope(&mut scope, 
"
    let x = 4 + 5 - y + z + MY_NUMBER + s.len;
    y = 1;
")?;

// Second invocation using the same state
let result = engine.eval_with_scope::<i64>(&mut scope, "x")?;

println!("result: {}", result);                 // prints 1102

// Variable y is changed in the script - read it with 'get_value'
assert_eq!(scope.get_value::<i64>("y").expect("variable y should exist"), 1);

// We can modify scope variables directly with 'set_value'
scope.set_value("y", 42_i64);
assert_eq!(scope.get_value::<i64>("y").expect("variable y should exist"), 42);
}

Scope Lifetime Parameter

The Scope has a lifetime parameter, in the vast majority of cases it can be omitted and automatically inferred to be 'static.

Currently, that lifetime parameter is not used. It is there to maintain backwards compatibility as well as for possible future expansion when references can also be put into the Scope.

The lifetime parameter is not guaranteed to remain unused for future versions.

In order to put a Scope into a struct, use Scope<'static>.