Struct Eval 

pub struct Eval {
    pub operand_stack: OperandStack,
    pub memory: Memory,
    /* private fields */
}

The ongoing evaluation of a script

This, alongside Script is one of the main entry points into this library’s API. To evaluate a script, first initialize an Eval instance using Eval::new, then use Eval::run or Eval::step to advance the evaluation.

Example

use stack_assembly::{Eval, Script};

let script = Script::compile("1 2 +");

let mut eval = Eval::new();
eval.run(&script);

assert_eq!(eval.operand_stack.to_i32_slice(), &[3]);

Fields

operand_stack: OperandStack

The operand stack

StackAssembly’s evaluation model is based on an implicit stack which stores all operands. An operator’s output is pushed to that stack, and any of its inputs are popped from there.

Alongside memory, this field is the primary channel for communication between script and host.

Most hosts should restrict modifications to this field to when the script triggers Effect::Yield, and then only do so in a well-reasoned and documented manner. Anything else might make reasoning about the script’s behavior very difficult.

None the less, the host has full access to this field, as to not restrict any experimental or non-standard use cases.

memory: Memory

The memory

StackAssembly provides a linear memory that is freely addressable per word.

Alongside operand_stack, this field is the primary channel for communication between script and host.

Most hosts should restrict modifications to this field to when the script triggers Effect::Yield, and then only do so in a well-reasoned and documented manner. Anything else might make reasoning about the script’s behavior very difficult.

None the less, the host has full access to this field, as to not restrict any experimental or non-standard use cases.

Implementations

impl Eval

pub fn new() -> Self

Construct a new instance of Eval

To evaluate a script using the returned instance, you must call Eval::run or Eval::step.

pub fn call_stack(&self) -> impl Iterator<Item = OperatorIndex>

Access the current call stack

The returned iterator yields operator indices on the call stack, starting with the top-most one.

The yielded operator indices identify the operators where evaluation will continue after evaluating a return operator; not the operators that were the source of a call.

pub fn run(&mut self, script: &Script) -> (Effect, OperatorIndex)

Advance the evaluation until it triggers an effect

If an effect is currently active, do nothing and return immediately. Otherwise, keep evaluating operators until one triggers an effect.

The operator index returned alongside the effect identifies the operator that triggered the effect.

If you need more control over the evaluation, consider using Eval::step instead.

pub fn step(&mut self, script: &Script) -> Option<(Effect, OperatorIndex)>

Advance the evaluation by one step

If an effect is currently active, do nothing and return immediately. Otherwise, evaluate the next operator. If that triggers an effect, return that.

The operator index returned alongside the effect identifies the operator that triggered the effect.

This function may be used for advancing the evaluation of the script in a controlled manner. If you just want to keep evaluating until the next effect triggers, consider using Eval::run instead.

pub fn clear_effect(&mut self) -> Option<(Effect, OperatorIndex)>

Clear the active effect, if any

If no effect is active, this call does nothing. If an effect has been cleared, return that.

The operator index returned alongside the effect identifies the operator that triggered the effect.

Trait Implementations

impl Debug for Eval

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Eval

fn default() -> Eval

Returns the “default value” for a type.