Struct EvalContextFrameGuard 

pub struct EvalContextFrameGuard<'f, 'a, 's, 'ps, 'g, 'c, 't> { /* private fields */ }

A new frame guard for EvalContext, restoring field values upon Drop.

Implementations

impl<'t> EvalContextFrameGuard<'_, '_, '_, '_, '_, '_, 't>

pub fn with_new_caching_layer(self) -> Self

Push a new caching layer for function resolution results.

pub fn rewind_scope(self, enable: bool) -> Self

Rewind the scope.

pub fn with_source(self, source: impl Into<ImmutableString>) -> Self

Modify the current source.

pub fn clear_source(self) -> Self

Clear the current source.

pub fn with_tag(self, tag: Dynamic) -> Self

Modify the custom state.

pub fn clear_tag(self) -> Self

Modify the custom state to Dynamic::UNIT.

Methods from Deref<Target = EvalContext<'a, 's, 'ps, 'g, 'c, 't>>

pub fn engine(&self) -> &'a Engine

The current Engine.

pub fn source(&self) -> Option<&str>

The current source.

pub fn source_mut(&mut self) -> &mut Option<ImmutableString>

Get a mutable reference to the current source.

pub fn scope(&self) -> &Scope<'ps>

The current Scope.

pub fn scope_mut(&mut self) -> &mut Scope<'ps>

Get a mutable reference to the current Scope.

pub fn iter_imports(&self) -> impl Iterator<Item = (&str, &Module)>

Get an iterator over the current set of modules imported via import statements, in reverse order (i.e. modules imported last come first).

pub fn tag(&self) -> &Dynamic

Custom state kept in a Dynamic.

pub fn tag_mut(&mut self) -> &mut Dynamic

Mutable reference to the custom state kept in a Dynamic.

pub fn iter_namespaces(&self) -> impl Iterator<Item = &Module>

Get an iterator over the namespaces containing definition of all script-defined functions.

Not available under no_function.

pub fn this_ptr(&self) -> Option<&Dynamic>

The current bound this pointer, if any.

pub fn this_ptr_mut(&mut self) -> Option<&mut Dynamic>

Mutable reference to the current bound this pointer, if any.

pub fn call_level(&self) -> usize

The current nesting level of function calls.

pub fn eval_expression_tree( &mut self, expr: &Expression<'_>, ) -> Result<Dynamic, Box<EvalAltResult>>

Evaluate an expression tree within this evaluation context.

WARNING - Low Level API

This function is very low level. It evaluates an expression from an AST.

pub fn eval_expression_tree_raw( &mut self, expr: &Expression<'_>, rewind_scope: bool, ) -> Result<Dynamic, Box<EvalAltResult>>

👎Deprecated:

This API is NOT deprecated, but it is considered volatile and may change in the future.

Evaluate an expression tree within this evaluation context.

The following option is available:

• whether to rewind the Scope after evaluation if the expression is a [StmtBlock][crate::ast::StmtBlock]

WARNING - Unstable API

This API is volatile and may change in the future.

WARNING - Low Level API

This function is extremely low level. It evaluates an expression from an AST.

pub fn call_fn<T: Variant + Clone>( &mut self, fn_name: impl AsRef<str>, args: impl FuncArgs, ) -> Result<T, Box<EvalAltResult>>

Call a function inside the evaluation context with the provided arguments.

pub fn call_native_fn<T: Variant + Clone>( &mut self, fn_name: impl AsRef<str>, args: impl FuncArgs, ) -> Result<T, Box<EvalAltResult>>

Call a registered native Rust function inside the evaluation context with the provided arguments.

This is often useful because Rust functions typically only want to cross-call other registered Rust functions and not have to worry about scripted functions hijacking the process unknowingly (or deliberately).

pub fn call_fn_raw( &mut self, fn_name: impl AsRef<str>, is_ref_mut: bool, is_method_call: bool, args: &mut [&mut Dynamic], ) -> Result<Dynamic, Box<EvalAltResult>>

Call a function (native Rust or scripted) inside the evaluation context.

If is_method_call is true, the first argument is assumed to be the this pointer for a script-defined function (or the object of a method call).

WARNING - Low Level API

This function is very low level.

Arguments

All arguments may be consumed, meaning that they may be replaced by (). This is to avoid unnecessarily cloning the arguments.

DO NOT reuse the arguments after this call. If they are needed afterwards, clone them before calling this function.

If is_ref_mut is true, the first argument is assumed to be passed by reference and is not consumed.

pub fn call_native_fn_raw( &mut self, fn_name: impl AsRef<str>, is_ref_mut: bool, args: &mut [&mut Dynamic], ) -> Result<Dynamic, Box<EvalAltResult>>

Call a registered native Rust function inside the evaluation context.

This is often useful because Rust functions typically only want to cross-call other registered Rust functions and not have to worry about scripted functions hijacking the process unknowingly (or deliberately).

WARNING - Low Level API

This function is very low level.

Arguments

All arguments may be consumed, meaning that they may be replaced by (). This is to avoid unnecessarily cloning the arguments.

DO NOT reuse the arguments after this call. If they are needed afterwards, clone them before calling this function.

If is_ref_mut is true, the first argument is assumed to be passed by reference and is not consumed.

pub fn new_frame<'f>( &'f mut self, ) -> EvalContextFrameGuard<'f, 'a, 's, 'ps, 'g, 'c, 't>

Create a new isolated runtime frame guard, restoring field values upon Drop.

The frame guard returned derefs to EvalContext.

Examples

// The following pushes a new, empty, caching layer to make sure that new function resolutions
// do not persist. This is useful if the resolution will be volatile.
let result: i64 = context.new_frame()
                         .with_new_caching_layer()
                         .call_fn("foo", (0_i64,))?;

// In the above example, the resolution to function 'foo' will not be cached outside the frame.
// The next call to 'foo' will be resolved again instead of using the cached resolution,
// even if 'foo' is redefined.

// The following modifies the [`EvalContext`] before using, restoring its state afterwards.
{
    // Modify the context before using...
    let context = context.new_frame()
                         .rewind_scope(true)            // rewinds the scope...
                         .with_source("new source")     // new source...
                         .with_namespace(new_module)    // add new namespace module...
                         .up_call_level();

    // Call a function with the modified context...
    let result: i64 = context.call_fn("foo", (0_i64,))?;

    // ... at end of block, context automatically restored to previous state.
}

Drop behavior

Upon Drop, the following fields will be automatically restored to the previous values:

• the stack of imported modules will be rewound to the original depth if more have been added via [EvalContextFrameGuard::with_import].
• the stack of scripted function modules will be rewound to the original depth if more have been added via [EvalContextFrameGuard::with_namespace].
• the original functions resolution cache will be restored if a new caching layer was created via EvalContextFrameGuard::with_new_caching_layer.
• the original scope will be rewound if EvalContextFrameGuard::rewind_scope was set to true.
• the [source][GlobalRuntimeState::source] will be restored if a new source was set via EvalContextFrameGuard::with_source or cleared via EvalContextFrameGuard::clear_source.
• the current [nesting level][GlobalRuntimeState::level] of function calls will be restored if modified via [EvalContextFrameGuard::up_call_level].
• the current [tag][GlobalRuntimeState::tag] will be restored if modified via EvalContextFrameGuard::with_tag or EvalContextFrameGuard::clear_tag.

Trait Implementations

impl<'a, 's, 'ps, 'g, 'c, 't> Deref for EvalContextFrameGuard<'_, 'a, 's, 'ps, 'g, 'c, 't>

type Target = EvalContext<'a, 's, 'ps, 'g, 'c, 't>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a, 's, 'ps, 'g, 'c, 't> DerefMut for EvalContextFrameGuard<'_, 'a, 's, 'ps, 'g, 'c, 't>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Drop for EvalContextFrameGuard<'_, '_, '_, '_, '_, '_, '_>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.