Struct scriptful::core::machine::Machine

pub struct Machine<'a, Op> { /* fields omitted */ }

A convenient wrapper around Stack providing multiple operation methods, i.e. xecuting scripts by evaluating operators and pushing values into the stack.

This is the preferred way to interact with Stacks, as they do not support operators, Items, and other abstractions.

Methods

impl<'a, Op> Machine<'a, Op> where
    Op: Debug + Eq, 

pub fn new(op_sys: &'a dyn Fn(&mut Stack, &Op)) -> Self

A simple factory that helps constructing a Machine around a existing operator system, be it user defined or any of the ones in the op_systems module.

This method initializes the internal stack to be empty.

Examples

use scriptful::prelude::*;
use scriptful::op_systems::simple_math::simple_math_op_sys;

// Instantiate the machine with a reference to your operator system, or any of the ones in
// the `op_systems` module.
let machine = Machine::new(&simple_math_op_sys);

// Make sure the stack is initialized to be empty.
assert_eq!(machine.stack_length(), 0);

pub fn operate(&mut self, item: &Item<Op>) -> &Value

The simplest way to make a Machine evaluate a single Item, be it a Value or Operator.

Note that the preferred way to evaluate multiple Items at once is through the run_script method, which instead of single Items takes a Script, i.e. an array of Items.

Panics

Operating on a Machine that has an empty Stack can cause a panic if the Item is an operator that tries to pop from it.

Examples

use scriptful::prelude::*;
use scriptful::prelude::Value::*;
use scriptful::op_systems::simple_math::*;

// Instantiate the machine with a reference to your operator system, or any of the ones in
// the `op_systems` module.    
let mut machine = Machine::new(&simple_math_op_sys);

// Operating a `Value::Integer(1)` should simply push it into the stack.
let result = machine.operate(&Item::Value(Integer(1)));
// Make sure the value gets pushed.
assert_eq!(result, &Integer(1));
// The length of the stack should be 1.
assert_eq!(machine.stack_length(), 1);

// Operating a `Value::Integer(2)` should simply push it into the stack.
let result = machine.operate(&Item::Value(Integer(2)));
// Make sure the value gets pushed.
assert_eq!(result, &Integer(2));
// The length of the stack should be 2.
assert_eq!(machine.stack_length(), 2);

// Operating an `OpCode::Add` should pop the two topmost values in the stack, add them
// together, and push the result back into the stack.
let result = machine.operate(&Item::Operator(OpCode::Add));
// Make sure the result is 3.
assert_eq!(result, &Integer(3));
// The final length of the stack should be 1 again.
assert_eq!(machine.stack_length(), 1);

pub fn run_script(&mut self, script: &Script<Op>) -> &Value

Evaluates a Script in the context of a Machine.

Panics

Operating on a Machine that has an empty Stack can cause a panic if any of the Items in the Script is an operator that tries to pop from it.

Examples

use scriptful::prelude::*;
use scriptful::prelude::Value::*;
use scriptful::op_systems::simple_math::*;

// Instantiate the machine with a reference to your operator system, or any of the ones in
// the `op_systems` module.
let mut machine = Machine::new(&simple_math_op_sys);

// Run a script that simply adds 1 and 2.
let result = machine.run_script(&[
   Item::Value(Integer(1)),
   Item::Value(Integer(2)),
   Item::Operator(OpCode::Add),
]);

// The result should unsurprisingly be 3.
assert_eq!(result, &Integer(3));
// The final length of the stack should be 1.
assert_eq!(machine.stack_length(), 1);

pub fn stack_length(&self) -> usize

Returns the number of Values currently in the Stack.

Examples

use scriptful::prelude::*;
use scriptful::prelude::Value::*;
use scriptful::op_systems::simple_math::*;

// Instantiate the machine with a reference to your operator system, or any of the ones in
// the `op_systems` module.
let mut machine = Machine::new(&simple_math_op_sys);

// Run a script that simply pushes 4 values into the stack.
machine.run_script(&[
    Item::Value(Boolean(true)),
    Item::Value(Float(3.141592)),
    Item::Value(Integer(1337)),
    Item::Value(String("foo"))
]);

// The final length of the stack should be 4.
assert_eq!(machine.stack_length(), 4);

Trait Implementations

impl<'a, Op> Debug for Machine<'a, Op>

Debugging of Machine only shows the internal Stack, but not the operator system.

The explanation for this is straightforward: how do you print a dynamic reference to a function?

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

Formats the value using the given formatter.