What's on your stack ?

rust_multistackvm is a Rust crate that implements a Virtual Machine operating on top of a two-dimensional stack rather than a single stack and registers. This two-dimensional stack structure, defined in the rust_multistack crate, offers functionality for the Rust programming language. It can contain dynamically typed values provided by the rust_dynamic crate, organized in a stack of stacks structure. This approach assists in achieving data isolation and control. At its core is a circular ring buffer of references on the stacks. The actual data stacks could be anonymous or named. Users can define and manipulate stacks and perform data manipulation through callbacks.

Show me the code!

let mut vm = VM::new();
vm.apply(Value::from(42.0).unwrap()).unwrap();
let val = vm.stack.pull().expect("No pull() happens");
assert_eq!(val.cast_float().unwrap(), 42.0 as f64);

After creating a Virtual Machine, we assigned it a number. The MultistackVM's default behavior is to push data to the current stack. If the passed value is a type of CALL, it executes the requested function. It's as simple as that. We retrieve data from the current stack upon evaluating the number, confirming its value as 42.0.

let mut vm = VM::new();
vm.apply(Value::call("list".to_string(), Vec::new())).unwrap();
vm.apply(Value::call(":".to_string(), Vec::new())).unwrap();
vm.apply(Value::from(42.0).unwrap()).unwrap();
vm.apply(Value::call(";".to_string(), Vec::new())).unwrap();
let val = vm.stack.pull().expect("No pull() happens");
let list_val = val.cast_list().unwrap();
assert_eq!(list_val[0].cast_float().unwrap(), 42.0 as f64);

This snippet demonstrated two important concepts:

• Execution of the VM functions;
• Autoadd feature.

When we pass Value::call("list".to_string(), Vec::new()) to VM::apply(), the default behavior is to execute the VM function or command or lambda. Function list is defined as a VM inline function, and this function puts an empty Value::list to the current stack.

What is auto-add?

When working with a VM, you may need to create a list or define a lambda and store some content. By default, the VM stores values on the stack or executes commands. The VM command : changes this behavior, bringing the VM into automated mode. In this mode, when the VM evaluates the data, instead of pushing the value to the stack, it pushes the data to the LIST or LAMBDA value on top of the current stack. For example, the Value::from(42.0) doesn't go to the stack but to the LIST stored earlier. The VM command ; resets the VM behavior to the default. When casting LIST to Vector and checking an element in the list, we can verify that the autoadd feature is working.

How to control VM

All virtual machine (VM) controls are accessed through methods implemented within the VM struct. Data processing is carried out using inline functions defined for either the VM or stack TS structures. The TS inline functions primarily handle stack management, while the VM inline functions are dedicated to overall logic and data processing. A VM inline function is a self-contained function that takes a reference to the VM as a parameter and returns a Result<> containing a reference to the same VM or an Error. Here is an example of VM inline function implementation.

pub fn stdlib_print_inline(vm: &mut VM) -> Result<&mut VM, Error> {
    if vm.stack.current_stack_len() < 1 {
        bail!("Stack is too shallow for inline clear_in()");
    }
    match vm.stack.pull() {
        Some(value) => {
            print!("{}", &value);
        }
        None => {
            bail!("PRINT returns: NO DATA");
        }
    }
    Ok(vm)
}

In this straightforward example, each inline function clearly defines how it consumes data from the stack and outlines the expected behavior of that data. And here is an example of how you register new inline function.

let _ = vm.register_inline("print".to_string(), stdlib_print_inline);

Methods of VM struct

Inline functions of Multistack VM

These inline functions are defined for the VM, with additional inline functions specifically defined for the stack. All of these are documented in the rust_multistack crate.

Example of the format function

41 42     // For format variables a
          // and b, a = 42, b = 41 since they are
          // resolved as allocated
"Answer is {a}, but not {b}. It is really {a}!" format

This snippet will leave foollowing string on the stack:

"Answer is 42, but not 41. It is really 42!"

Group of functions for boolean logic operations

Group of function for comparing values on the stack. Returns a boolean value

1 0 <     // Will return TRUE on stack

Here is group of functions that is doing a conditional move of data in stack and workbench

Here is some example

42.0              // Put some value to the stack
{ dup > 0 } ?.    // Check if value is more than 0
                  // Since logical operator consumes 
                  // value from stack, we duplicate it inside lambda
                  // If test return TRUE, word "?." will move next value
                  // To workbench

The outcome of this snippet is value 42.0 stored in workbench if only this value is greater than 0

Here is the group of functions to work with application-defined anonymous and named functions

// First, let's define function and register it with name "FortyTwo"
:FortyTwo {
  42
} register
// And then let's execute it
FortyTwo

Here is the group of functions covering the application logic

Examples of use IF conditional functions

true
{
  // This code will be executed
}
if

true
{
  // This code will not be executed
}
?false

:main
{
  // This code will be executed only if name of the current stack is "main"
}
if.stack

Example of use LOOP function

[ 42 ] { . } loop

Example of WHILE function

true
{
  42.0 . false
}
while

After single loop over lambda, condition is met and number 42.0 is in workbench

Example of FOR function

{
  "This lambda function will be executed at least once " println
  false
} for

After single loop over lambda, condition is met.

Example of TIMES. function

0       // Send an initial value
3 .     // Send a counter to workbench
{
  +     // Perform math operation in lambda
} times.

Example of MAP function

[ "Hello World!"]   // First, let's define data
{ :string.upper } map

This snipper will return following value on the list [ "HELLO WORLD!"]

This snippet will execute lambda function three times and leave number 3 on top of the stack.

In this example, we are pushing content of the list to stack and evaluate lambda after each push. This code will push integer 42 to workbench.

And here is functions that is working with dictionaries

// We create an empty dictionary
dict
  // Then provide a key-value
  :ANSWER
  42.0
  // And set the value. Dictionary is on top of stack
  set
  // Set the key and get the Value
  :ANSWER
  get
// This snippet shall render 42.0 on top of the stack

There are number of internal libraries for multistackvm

Math library

String library

Conversion library

Conversion library support both stack and workbench operations. For the word operating with workbench add "." to name. For example, the word convert.to_int. will perform conversion in workbench.

Time library

VM control functions

Default aliases

Alias is basically another name for the function or lambda. Here is an example, where I am calling function "." that is an alias for inline function "return".

let mut vm = VM::new();
vm.apply(Value::from(42.0).unwrap()).unwrap();
vm.call(".".to_string()).unwrap();
let val = vm.stack.pull_from_workbench().unwrap();
assert_eq!(val.cast_float().unwrap(), 42.0 as f64);

This alias was previously defined in stdlib/create aliases.rs as

let _ = vm.register_alias(".".to_string(), "return".to_string());

First, I am appying a Value::float to VM, that is pushed this value to the stack. Then I am calling for function "." Alias is getting resolved and inline function "return" defined in TS is called. As expected, we can pull the value from vm.stack Workbench.