Operators¶

Operators are the building blocks of BEAST programs. They are uniquely identified by an opcode (operator code) each (see this list) and have varying numbers of parameters. In this document, instructions are given for adding new operator, and an overview of what operators are available already.

Adding a new operator¶

To add a new operator to the BEAST library, you will need to follow these steps:

Add a new opcode: Append the new opcode with the next higher hex value in an appropriate category in the enum class OpCode in include/beast/opcodes.hpp:
```
enum class OpCode : int8_t {
  ...
  MyNewOpCode = 0xXX,   // Replace XX with the next higher hex value
  ...
};
```
Add a signature for this opcode: Add a new function signature in include/beast/program.hpp that corresponds to your new opcode. This will allow client programs to add the operator to a program:
```
class Program {
  ...
  void myNewOpCode(int32_t param1, int32_t param2);
  ...
};
```
Add the program implementation: Add the implementation for the new function you added in step 2 in src/program.cpp. Follow the example of existing operators, but in general: Use appendCode1(…) with the opcode you added in step 1, and then add any bytes you deem necessary for your operator:
```
void Program::myNewOpCode(int32_t param1, int32_t param2) {
  appendCode1(OpCode::MyNewOpCode);
  appendData4(param1);
  appendData4(param2);
}
```

Add a VM case for your new opcode: In src/cpu_virtual_machine.cpp, extend the switch statement in the step() function. Add a new case for your new opcode, read all parameters (no need to read the opcode, that’s done automatically), print a debug statement with the operator signature, and call a VmSession function that matches your operator:

void CpuVirtualMachine::step() {
  ...
  case OpCode::MyNewOpCode: {
    const int32_t param1 = session.getData4();
    const int32_t param2 = session.getData4();
    debug("my_new_op_code(" + std::to_string(param1) + ", " + std::to_string(param2) + ")";
    session.myNewOpCode(param1, param2);
  } break;
  ...

Define the VmSession function: If there is no suitable VmSession function, define its signature in include/beast/vm_session.hpp. This is a function that explicitly accepts the parameters for your operator. See the existing ones for how to define them.
Implement the VmSession function: In src/vm_session.cpp, implement the actual logic that should be executed if the VM encounters your operator. Again, see existing operators for how to do it.

Already implemented operators¶

The BEAST byte code is using a defined set of operators that are documented in this OpCodes header file. These available operator codes are organized in … distinct categories:

Variable management¶

These operators are used to manage variables such as declaring variables with index and type, setting variable values, undeclaring variables, copying variable values, and swapping variable values.

beast::Program::declareVariable(int32_t variable_index, VariableType variable_type)¶

Declares a variable at an index and assigns a type.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Declares a numerical variable index, alongside its designated type. A variable type can either be an actual value storage (of type VariableType::Int32) or a link to another variable index (of type VariableType::Link).

Identified by OpCode::DeclareVariable. Represented by 6 bytes.

See

undeclareVariable()

Parameters

variable_index: The index to declare the variable at.
variable_type: The designated type of the variable.

beast::Program::undeclareVariable(int32_t variable_index)¶

Removes a variable declaration at the given index.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The variable declared at the given index is undeclared. The index, type, and value are removed from the variable memory. If at that index no variable is declared, an exception is thrown.

Identified by OpCode::UndeclareVariable. Represented by 5 bytes.

See

declareVariable()

Parameters

variable_index: The index of the variable to undeclare.

beast::Program::setVariable(int32_t variable_index, int32_t content, bool follow_links)¶

Sets the value of a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Sets the value of a variable at the given index to the value content. The variable index needs to be declared prior to this.

Identified by OpCode::SetVariable. Represented by 10 bytes.

See

declareVariable()

Parameters

variable_index: The index of the variable.
content: The value to assign to the variable.
follow_links: Whether to resolve variable links.

beast::Program::copyVariable(int32_t source_variable_index, bool follow_source_links, int32_t destination_variable_index, bool follow_destination_links)¶

Copies the value of one variable into another.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::CopyVariable. Represented by 11 bytes.

Parameters

source_variable_index: The index of the source variable.
follow_source_links: Whether to resolve source variable links.
destination_variable_index: The index of the destination variable.
follow_destination_links: Whether to resolve destination variable links.

beast::Program::swapVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)¶

Swaps the contents of two variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::SwapVariables. Represented by 11 bytes.

Parameters

variable_index_a: The index of the variable.
follow_links_a: Whether to resolve variable links.
variable_index_b: The index of the variable.
follow_links_b: Whether to resolve variable links.

Math¶

These operators perform mathematical operations such as adding or subtracting constants or variables, comparing variables for greater than, less than, or equality, getting the maximum or minimum of variables or constants, and performing modulo operations on variables.

beast::Program::addConstantToVariable(int32_t variable_index, int32_t constant, bool follow_links)¶

Adds a constant value to the value held in a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AddConstantToVariable. Represented by 8 bytes.

Parameters

variable_index: The index of the variable to add the constant to.
constant: The constant value to add to the variable value.
follow_links: Whether to resolve variable links.

beast::Program::addVariableToVariable(int32_t source_variable_index, bool follow_source_links, int32_t destination_variable_index, bool follow_destination_links)¶

Adds the value of one variable to that of another variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The contents of source_variable_index are added to the contents of destination_variable_index. The result is stored in destination_variable_index.

Identified by OpCode::AddVariableToVariable. Represented by 11 bytes.

Parameters

source_variable_index: The index of the source variable.
follow_source_links: Whether to resolve source variable links.
destination_variable_index: The index of the destination variable.
follow_destination_links: Whether to resolve destination variable links.

beast::Program::subtractConstantFromVariable(int32_t variable_index, int32_t constant, bool follow_links)¶

Subtract a constant value from the value held in a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::SubtractConstantFromVariable. Represented by 10 bytes.

Parameters

variable_index: The index of the variable to subtract the constant from.
constant: The constant value to subtract from the variable value.
follow_links: Whether to resolve variable links.

beast::Program::subtractVariableFromVariable(int32_t source_variable_index, bool follow_source_links, int32_t destination_variable_index, bool follow_destination_links)¶

Subtracts the value of one variable from that of another variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The contents of source_variable_index are subtracted from the contents of destination_variable_index. The result is stored in destination_variable_index.

Identified by OpCode::SubtractVariableFromVariable. Represented by 11 bytes.

Parameters

source_variable_index: The index of the variable.
follow_source_links: Whether to resolve variable links.
destination_variable_index: The index of the variable.
follow_destination_links: Whether to resolve variable links.

beast::Program::compareIfVariableGtConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)¶

Compares if a variable is > a given constant.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the variable is greater than the given constant, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableGtConstant. Represented by 15 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
constant: The constant
target_variable_index: The index of the variable.
target_follow_links: Whether to resolve variable links.

beast::Program::compareIfVariableLtConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)¶

Compares if a variable is < a given constant.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the variable is smaller than the given constant, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableLtConstant. Represented by 15 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
constant: The constant
target_variable_index: The index of the variable.
target_follow_links: Whether to resolve variable links.

beast::Program::compareIfVariableEqConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)¶

Compares if a variable is = a given constant.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the variable is equal to the given constant, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableEqConstant. Represented by 15 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
constant: The constant
target_variable_index: The index of the variable.
target_follow_links: Whether to resolve variable links.

beast::Program::compareIfVariableGtVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)¶

Compares if a variable is > another variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If variable a is greater than variable b, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableGtVariable. Represented by 16 bytes.

Parameters

variable_index_a: The index of the variable.
follow_links_a: Whether to resolve variable links.
variable_index_b: The index of the variable.
follow_links_b: Whether to resolve variable links.
target_variable_index: The index of the variable.
target_follow_links: Whether to resolve variable links.

beast::Program::compareIfVariableLtVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)¶

Compares if a variable is < another variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If variable a is smaller than variable b, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableLtVariable. Represented by 16 bytes.

Parameters

variable_index_a: The index of the variable.
follow_links_a: Whether to resolve variable links.
variable_index_b: The index of the variable.
follow_links_b: Whether to resolve variable links.
target_variable_index: The index of the variable.
target_follow_links: Whether to resolve variable links.

beast::Program::compareIfVariableEqVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)¶

Compares if a variable is = another variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If variable a is equal to variable b, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableEqVariable. Represented by 16 bytes.

Parameters

variable_index_a: The index of the variable.
follow_links_a: Whether to resolve variable links.
variable_index_b: The index of the variable.
follow_links_b: Whether to resolve variable links.
target_variable_index: The index of the variable.
target_follow_links: Whether to resolve variable links.

beast::Program::getMaxOfVariableAndConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)¶

Compare a variable to a constant and store the larger value.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This operator compares the value stored in a variable against a constant. The larger value is stored in the target variable.

Identifier by OpCode::GetMaxOfVariableAndConstant. Represented by 15 bytes.

See

getMinOfVariableAndConstant(), getMaxOfVariableAndVariable(), getMinOfVariableAndVariable()

Parameters

variable_index: The index of the variable used for the comparison.
follow_links: Whether to follow variable links for the comparison variable.
constant: The constant to compare the variable against.
target_variable_index: The index of the variable to store the result in.
target_follow_links: whether to follow variable links for the target variable.

beast::Program::getMinOfVariableAndConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)¶

Compare a variable to a constant and store the smaller value.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This operator compares the value stored in a variable against a constant. The smaller value is stored in the target variable.

Identifier by OpCode::GetMinOfVariableAndConstant. Represented by 15 bytes.

See

getMaxOfVariableAndConstant(), getMaxOfVariableAndVariable(), getMinOfVariableAndVariable()

Parameters

variable_index: The index of the variable used for the comparison.
follow_links: Whether to follow variable links for the comparison variable.
constant: The constant to compare the variable against.
target_variable_index: The index of the variable to store the result in.
target_follow_links: whether to follow variable links for the target variable.

beast::Program::getMaxOfVariableAndVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)¶

Compare a variable to another variable and store the larger value.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This operator compares the value stored in one variable against the value stored in another variable. The larger value is stored in the target variable.

Identifier by OpCode::GetMaxOfVariableAndVariable. Represented by 16 bytes.

See

getMaxOfVariableAndConstant(), getMinOfVariableAndConstant(), getMinOfVariableAndVariable()

Parameters

variable_index_a: The index of the first variable used for the comparison.
follow_links_a: Whether to follow the first variable’s links for the comparison variable.
variable_index_b: The index of the second variable used for the comparison.
follow_links_b: Whether to follow the second variable’s links for the comparison variable.
target_variable_index: The index of the variable to store the result in.
target_follow_links: whether to follow variable links for the target variable.

beast::Program::getMinOfVariableAndVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)¶

Compare a variable to another variable and store the smaller value.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This operator compares the value stored in one variable against the value stored in another variable. The smaller value is stored in the target variable.

Identifier by OpCode::GetMinOfVariableAndVariable. Represented by 16 bytes.

See

getMaxOfVariableAndConstant(), getMinOfVariableAndConstant(), getMaxOfVariableAndVariable()

Parameters

variable_index_a: The index of the first variable used for the comparison.
follow_links_a: Whether to follow the first variable’s links for the comparison variable.
variable_index_b: The index of the second variable used for the comparison.
follow_links_b: Whether to follow the second variable’s links for the comparison variable.
target_variable_index: The index of the variable to store the result in.
target_follow_links: whether to follow variable links for the target variable.

beast::Program::moduloVariableByConstant(int32_t variable_index, bool follow_links, int32_t modulo_constant)¶

Performs a constant modulo operation on a variable and stores the result.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The given constant will be modulo’ed onto the given variable. The result will be stored in the same variable.

variable = variable % constant

Identified by OpCode::ModuloVariableByConstant. Represented by 11 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
modulo_constant: The constant to modulo onto the variable.

beast::Program::moduloVariableByVariable(int32_t variable_index, bool follow_links, int32_t modulo_variable_index, bool modulo_follow_links)¶

Performs a variable modulo operation on a variable and stores the result.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The modulo variable’s value will be modulo’ed onto the given variable. The result will be stored in the first variable.

variable = variable % modulo_variable

Identified by OpCode::ModuloVariableByVariable. Represented by 11 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
modulo_variable_index: The index of the modulo variable.
modulo_follow_links: Whether to resolve the modulo variable’s links.

Bit manipulation¶

These operators perform bit manipulation operations on variables such as bit shifting left or right, bitwise AND, OR, and NOT operations, and checking bit values.

beast::Program::bitShiftVariableLeft(int32_t variable_index, bool follow_links, int8_t places)¶

Bit-shift a variable to the left.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Bit-shifts the given variable by places bits to the left. The right side will be filled up with zero bits.

Identified by OpCode::BitShiftVariableLeft. Represented by 7 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
places: The amount of places to shift the variable to the left.

beast::Program::bitShiftVariableRight(int32_t variable_index, bool follow_links, int8_t places)¶

Bit-shift a variable to the right.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Bit-shifts the given variable by places bits to the right. The left side will be filled up with zero bits.

Identified by OpCode::BitShiftVariableRight. Represented by 7 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
places: The amount of places to shift the variable to the right.

beast::Program::bitWiseInvertVariable(int32_t variable_index, bool follow_links)¶

Bit-wise inverts the given variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::BitWiseInvertVariable. Represented by 5 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::bitWiseAndTwoVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)¶

Performs a bit-wise AND operation on two variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The result will be stored in variable_index_b.

Identified by OpCode::BitWiseAndTwoVariables. Represented by 11 bytes.

Parameters

variable_index_a: The index of the first variable.
follow_links_a: Whether to resolve first variable’s links.
variable_index_b: The index of the second variable.
follow_links_b: Whether to resolve second variable’s links.

beast::Program::bitWiseOrTwoVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)¶

Performs a bit-wise OR operation on two variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The result will be stored in variable_index_b.

Identified by OpCode::BitWiseOrTwoVariables. Represented by 11 bytes.

Parameters

variable_index_a: The index of the first variable.
follow_links_a: Whether to resolve first variable’s links.
variable_index_b: The index of the second variable.
follow_links_b: Whether to resolve second variable’s links.

beast::Program::bitWiseXorTwoVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)¶

Performs a bit-wise XOR operation on two variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The result will be stored in variable_index_b.

Identified by OpCode::BitWiseXorTwoVariables. Represented by 11 bytes.

Parameters

variable_index_a: The index of the first variable.
follow_links_a: Whether to resolve first variable’s links.
variable_index_b: The index of the second variable.
follow_links_b: Whether to resolve second variable’s links.

beast::Program::rotateVariableLeft(int32_t variable_index, bool follow_links, int8_t places)¶

Bit-wise rotate the given variable to the left.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Negative values cause a rotation to the right.

Identified by OpCode::RotateVariableLeft. Represented by 7 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
places: How many bits to rotate the variable to the left (can be negative).

beast::Program::rotateVariableRight(int32_t variable_index, bool follow_links, int8_t places)¶

Bit-wise rotate the given variable to the left.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Negative values cause a rotation to the left.

Identified by OpCode::RotateVariableRight. Represented by 7 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
places: How many bits to rotate the variable to the right (can be negative).

beast::Program::variableBitShiftVariableLeft(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool follow_links_places)¶

Bit-shifts a variable to the left by a variable amount of places.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::VariableBitShiftVariableLeft. Represented by 11 bytes.

See

bitShiftVariableLeft()

Parameters

variable_index: The target variable that should be bit-shifted
follow_links: Whether to resolve the target variable’s links
places_variable_index: The variable holding the amount to shift by
follow_links_places: Whether to resolve the amount variable’s links

beast::Program::variableBitShiftVariableRight(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool follow_links_places)¶

Bit-shifts a variable to the right by a variable amount of places.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::VariableBitShiftVariableRight. Represented by 11 bytes.

See

bitShiftVariableRight()

Parameters

variable_index: The target variable that should be bit-shifted
follow_links: Whether to resolve the target variable’s links
places_variable_index: The variable holding the amount to shift by
follow_links_places: Whether to resolve the amount variable’s links

beast::Program::variableRotateVariableLeft(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool follow_links_places)¶

Rotates a variable to the left by a variable amount of places.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::VariableRotateVariableLeft. Represented by 11 bytes.

Parameters

variable_index: The target variable that should be rotated
follow_links: Whether to resolve the target variable’s links
places_variable_index: The variable holding the amount to rotate by
follow_links_places: Whether to resolve the amount variable’s links

beast::Program::variableRotateVariableRight(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool follow_links_places)¶

Rotates a variable to the right by a variable amount of places.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::VariableRotateVariableRight. Represented by 11 bytes.

Parameters

variable_index: The target variable that should be rotated
follow_links: Whether to resolve the target variable’s links
places_variable_index: The variable holding the amount to rotate by
follow_links_places: Whether to resolve the amount variable’s links

Stacks¶

These operators manage the content of virtual stacks used for storing and retrieving data items in a specific order.

beast::Program::pushVariableOnStack(int32_t stack_variable_index, bool follow_links_stack, int32_t variable_index, bool follow_links)¶

Pushes the content of a variable onto a stack.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

A stack is identified by a variable holding the current size of the stack, and a number of declared variables after it. This operator increases the current size of the stack by 1, and copies the value of the passed in variable into the variable index that is at stack_variable_index + previous_size + 1.

Identified by OpCode::PushVariableOnStack. Represented by 11 bytes.

See

pushConstantOnStack(), popVariableFromStack(), popTopItemFromStack(), checkIfStackIsEmpty()

Parameters

stack_variable_index: The index of the stack variable.
follow_links_stack: Whether to resolve the stack variable’s links.
variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::pushConstantOnStack(int32_t stack_variable_index, bool follow_links_stack, int32_t constant)¶

Pushes a constant value onto a stack.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Similar to pushVariableOnStack, but pushes a constant value passed to this operand onto the stack rather than reading the value from a variable.

Identified by OpCode::PushConstantOnStack. Represented by 10 bytes.

See

pushVariableOnStack(), popVariableFromStack(), popTopItemFromStack(), checkIfStackIsEmpty()

Parameters

stack_variable_index: The index of the variable.
follow_links_stack: Whether to resolve variable links.
constant: tbd

beast::Program::popVariableFromStack(int32_t stack_variable_index, bool follow_links_stack, int32_t variable_index, bool follow_links)¶

Removes the top item from the stack and stores it in a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Removes the top item from the stack, reducing the stack size by 1. The value of the removed item will be stored in variable_index. Throws if the stack was empty before.

Identified by OpCode::PopVariableFromStack. Represented by 11 bytes.

See

pushVariableOnStack(), pushConstantOnStack(), popTopItemFromStack(), checkIfStackIsEmpty()

Parameters

stack_variable_index: The index of the variable.
follow_links_stack: Whether to resolve variable links.
variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::popTopItemFromStack(int32_t stack_variable_index, bool follow_links_stack)¶

Removes the top item from the stack.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Effectively, the stack size will be reduced by 1. The top item will be discarded. Throws if the stack was empty before.

Identified by OpCode::PopTopItemFromStack. Represented by 6 bytes.

See

popVariableFromStack(), popVariableFromStack(), checkIfStackIsEmpty()

See

pushVariableOnStack(), pushConstantOnStack(), popVariableFromStack(), checkIfStackIsEmpty()

Parameters

stack_variable_index: The index of the variable.
follow_links_stack: Whether to resolve variable links.

beast::Program::checkIfStackIsEmpty(int32_t stack_variable_index, bool follow_links_stack, int32_t variable_index, bool follow_links)¶

Checks whether there are no items on a stack.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the stack at variable stack_variable_index contains no items, the variable at variable_index will be set to 0x1, and 0x0 if there is at least one item on the stack.

Identified by OpCode::CheckIfStackIsEmpty. Represented by 11 bytes.

See

pushConstantOnStack(), pushVariableOnStack(), pushConstantOnStack(), popTopItemFromStack()

Parameters

stack_variable_index: The index of the variable.
follow_links_stack: Whether to resolve variable links.
variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

Jumps¶

These operators control the flow of a program such as performing absolute and relative jumps optionally based on various different conditions.

beast::Program::relativeJumpToVariableAddressIfVariableGreaterThanZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address_variable_index, bool follow_addr_links)¶

Performs a relative jump to a variable address if a variable is > 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpToVariableAddressIfVariableGt0. Represented by 11 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
relative_jump_address_variable_index: The variable containing the absolute jump address.
follow_addr_links: Whether to follow links in the address variable.

beast::Program::relativeJumpToVariableAddressIfVariableLessThanZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address_variable_index, bool follow_addr_links)¶

Performs a relative jump to a variable address if a variable is < 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpToVariableAddressIfVariableLt0. Represented by 11 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
relative_jump_address_variable_index: The variable containing the absolute jump address.
follow_addr_links: Whether to follow links in the address variable.

beast::Program::relativeJumpToVariableAddressIfVariableEqualsZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address_variable_index, bool follow_addr_links)¶

Performs a relative jump to a variable address if a variable is = 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpToVariableAddressIfVariableEq0. Represented by 11 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
relative_jump_address_variable_index: The variable containing the absolute jump address.
follow_addr_links: Whether to follow links in the address variable.

beast::Program::absoluteJumpToVariableAddressIfVariableGreaterThanZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address_variable_index, bool follow_addr_links)¶

Performs an absolute jump to a variable address if a variable is > 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpToVariableAddressIfVariableGt0. Represented by 11 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
absolute_jump_address_variable_index: The variable containing the absolute jump address.
follow_addr_links: Whether to follow links in the address variable.

beast::Program::absoluteJumpToVariableAddressIfVariableLessThanZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address_variable_index, bool follow_addr_links)¶

Performs an absolute jump to a variable address if a variable is < 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpToVariableAddressIfVariableLt0. Represented by 11 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
absolute_jump_address_variable_index: The variable containing the absolute jump address.
follow_addr_links: Whether to follow links in the address variable.

beast::Program::absoluteJumpToVariableAddressIfVariableEqualsZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address_variable_index, bool follow_addr_links)¶

Performs an absolute jump to a variable address if a variable is = 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpToVariableAddressIfVariableEq0. Represented by 11 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
absolute_jump_address_variable_index: The variable containing the absolute jump address.
follow_addr_links: Whether to follow links in the address variable.

beast::Program::relativeJumpToAddressIfVariableGreaterThanZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address)¶

Performs a relative jump to a fixed address if a variable is > 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpIfVariableGt0. Represented by 10 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
relative_jump_address: The relative address to jump to.

beast::Program::relativeJumpToAddressIfVariableLessThanZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address)¶

Performs a relative jump to a fixed address if a variable is < 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpIfVariableLt0. Represented by 10 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
relative_jump_address: The relative address to jump to.

beast::Program::relativeJumpToAddressIfVariableEqualsZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address)¶

Performs a relative jump to a fixed address if a variable is = 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpIfVariableEq0. Represented by 10 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
relative_jump_address: The relative address to jump to.

beast::Program::absoluteJumpToAddressIfVariableGreaterThanZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address)¶

Performs an absolute jump to a fixed address if a variable is > 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpIfVariableGt0. Represented by 10 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
absolute_jump_address: The absolute address to jump to.

beast::Program::absoluteJumpToAddressIfVariableLessThanZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address)¶

Performs an absolute jump to a fixed address if a variable is < 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpIfVariableLt0. Represented by 10 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
absolute_jump_address: The absolute address to jump to.

beast::Program::absoluteJumpToAddressIfVariableEqualsZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address)¶

Performs an absolute jump to a fixed address if a variable is = 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpIfVariableEq0. Represented by 10 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
absolute_jump_address: The absolute address to jump to.

beast::Program::unconditionalJumpToAbsoluteAddress(int32_t addr)¶

Jumps to the given absolute address.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::UnconditionalJumpToAbsoluteAddress. Represented by 5 bytes.

Parameters

addr: The absolute address to jump to.

beast::Program::unconditionalJumpToAbsoluteVariableAddress(int32_t variable_index, bool follow_links)¶

Jumps to an absolute address stored in a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::UnconditionalJumpToAbsoluteVariableAddress. Represented by 6 bytes.

Parameters

variable_index: The index of the variable holding the absolute address to jump to.
follow_links: Whether to resolve variable links.

beast::Program::unconditionalJumpToRelativeAddress(int32_t addr)¶

Jumps to the given relative address.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::UnconditionalJumpToRelativeAddress. Represented by 5 bytes.

Parameters

addr: The relativeaddress to jump to.

beast::Program::unconditionalJumpToRelativeVariableAddress(int32_t variable_index, bool follow_links)¶

Jumps to a relative address stored in a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::UnconditionalJumpToRelativeVariableAddress. Represented by 6 bytes.

Parameters

variable_index: The index of the variable holding the relative address to jump to.
follow_links: Whether to resolve variable links.

I/O¶

These operators handle input and output operations such as identifying input/output characteristics of variables, and finding out which and how many I/O variables there are.

beast::Program::checkIfVariableIsInput(int32_t source_variable_index, bool follow_source_links, int32_t destination_variable_index, bool follow_destination_links)¶

Check if a variable is defined as an input.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the variable source_variable_index is defined as having the VariableIoBehavior::Input, set the value of the variable destination_variable_index to 0x1, else set it to 0x0.

Identified by OpCode::CheckIfVariableIsInput. Represented by 11 bytes.

Parameters

source_variable_index: The index of the source variable.
follow_source_links: Whether to resolve source variable links.
destination_variable_index: The index of the destination variable.
follow_destination_links: Whether to resolve destination variable links.

beast::Program::checkIfVariableIsOutput(int32_t source_variable_index, bool follow_source_links, int32_t destination_variable_index, bool follow_destination_links)¶

Check if a variable is defined as an output.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the variable source_variable_index is defined as having the VariableIoBehavior::Output, set the value of the variable destination_variable_index to 0x1, else set it to 0x0.

Identified by OpCode::CheckIfVariableIsOutput. Represented by 11 bytes.

Parameters

source_variable_index: The index of the source variable.
follow_source_links: Whether to resolve source variable links.
destination_variable_index: The index of the destination variable.
follow_destination_links: Whether to resolve destination variable links.

beast::Program::loadInputCountIntoVariable(int32_t variable_index, bool follow_links)¶

Load the number of registered input variables into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadInputCountIntoVariable. Represented by 6 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::loadOutputCountIntoVariable(int32_t variable_index, bool follow_links)¶

Load the number of registered output variables into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadOutputCountIntoVariable. Represented by 6 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::checkIfInputWasSet(int32_t variable_index, bool follow_links, int32_t destination_variable_index, bool follow_destination_links)¶

Determine whether an input variable was written to since the last read operation.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If since the last read operation the given variable at variable_index was written to, store the value 0x1 in the variable at destination_variable_index. Store 0x0 otherwise.

For details on I/O behaviors, also see VmSession::setVariableBehavior.

Identified by OpCode::CheckIfInputWasSet. Represented by 11 bytes.

See

VmSession::setVariableBehavior()

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
destination_variable_index: The index of the destination variable.
follow_destination_links: Whether to resolve destination variable links.

Printing and string table¶

These operators produce screen output and manage the content of the string table, such as storing or retrieving items, but also providing information about them and the string table in general.

beast::Program::printVariable(int32_t variable_index, bool follow_links, bool as_char)¶

Print the value of a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The value stored in the variable variable_index will be printed. If as_char is true, then the variable’s least significant byte will be printed as an ASCII character instead.

Identified by OpCode::PrintVariable. Represented by 7 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.
as_char: If true, print least significant byte as char.

beast::Program::setStringTableEntry(int32_t string_table_index, const std::string &string)¶

Set the content of an entry in the string table.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Sets the value that is stored for a specified entry in the string table.

Identified by OpCode::SetStringTableEntry. Represented by 7 + string length bytes.

Parameters

string_table_index: The string table index to set.
string: The content to store in the string table.

beast::Program::printStringFromStringTable(int32_t string_table_index)¶

Prints a string from the string table.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::PrintStringFromStringTable. Represented by 5 bytes.

Parameters

string_table_index: The string stored at this index will be printed.

beast::Program::loadStringTableLimitIntoVariable(int32_t variable_index, bool follow_links)¶

Loads the maximum number of items in the string table into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This is equivalent to the number of possible string items an associated VmSession provides.

Identified by OpCode::LoadStringTableLimitIntoVariable. Represented by 6 bytes.

Parameters

variable_index: The index of the variable to load the limit into.
follow_links: Whether to resolve variable links.

beast::Program::loadStringTableItemLengthLimitIntoVariable(int32_t variable_index, bool follow_links)¶

Load the maximum length of string table items into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This is the limit imposed on the Program by the VmSession associated to it during execution.

Identified by OpCode::LoadStringTableItemLengthLimitIntoVariable. Represented by 6 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::setVariableStringTableEntry(int32_t variable_index, bool follow_links, const std::string &string)¶

Sets an entry in the string table at a variable index.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::SetVariableStringTableEntry. Represented by 8 + string length bytes.

See

setStringTableEntry()

Parameters

variable_index: The index of the variable to read the string table index from.
follow_links: Whether to resolve variable links.
string: The string to store in the string table

beast::Program::printVariableStringFromStringTable(int32_t variable_index, bool follow_links)¶

Prints an entry from the string table from a variable index.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::PrintVariableStringFromStringTable. Represented by 6 bytes.

See

printStringFromStringTable()

Parameters

variable_index: The index of the variable to read the string table index from.
follow_links: Whether to resolve variable links.

beast::Program::loadVariableStringItemLengthIntoVariable(int32_t string_item_variable_index, bool follow_links_string_item, int32_t variable_index, bool follow_links)¶

Loads the length of a variable string table index into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadVariableStringItemLengthIntoVariable. Represented by 11 bytes.

Parameters

string_item_variable_index: The index of the variable to read the string table index from
follow_links_string_item: Whether to resolve the string table index variable’s links
variable_index: The index of the variable to store the length in
follow_links: Whether to resolve the target variable’s links

beast::Program::loadVariableStringItemIntoVariables(int32_t string_item_variable_index, bool follow_links_string_item, int32_t variable_index, bool follow_links)¶

Loads a variable item from the string table into consecutive variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

See loadStringItemLengthIntoVariable for details. The string table index is not fixed in this variant, but is read from the string_item_variable_index variable.

Identified by OpCode::LoadVariableStringItemIntoVariables. Represented by 11 bytes.

See

loadStringItemLengthIntoVariable()

Parameters

string_item_variable_index: The index of the variable.
follow_links_string_item: Whether to resolve variable links.
variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::loadStringItemLengthIntoVariable(int32_t string_table_index, int32_t variable_index, bool follow_links)¶

Load the actual length of a string table item into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadStringItemLengthIntoVariable. Represented by 10 bytes.

Parameters

string_table_index: The string table item’s index to read the length from.
variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::loadStringItemIntoVariables(int32_t string_table_index, int32_t start_variable_index, bool follow_links)¶

Loads an item from the string table into consecutive variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The item at the string table index string_table_index will be stored in the variables starting at index start_variable_index, consecutively. Each variable stores the character value from the respective string table item. Example:

String table item: Entry

start_variable_index + 0 = E
start_variable_index + 1 = n
start_variable_index + 2 = t
start_variable_index + 3 = r
start_variable_index + 4 = y

The follow_links parameter will be applied to every index separately.

Identified by OpCode::LoadStringItemIntoVariables. Represented by 10 bytes.

See

loadVariableStringItemLengthIntoVariable()

Parameters

string_table_index: The string table item to read character from.
start_variable_index: The index of the start variable.
follow_links: Whether to resolve variable links.

Misc¶

These operators perform general-purpose actions such as loading memory size into a variable, loading the current execution pointer address into a variable, terminating the program with a fixed or variable return code, performing system calls, and loading random values into variables.

beast::Program::noop()¶

Adds a NoOp operation to the program.

A NoOp operation performs no operation when executed.

Identified by OpCode::NoOp. Represented by 1 byte.

beast::Program::loadMemorySizeIntoVariable(int32_t variable_index, bool follow_links)¶

Loads the maximum number of VmSession variables into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadMemorySizeIntoVariable. Represented by 6 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::loadCurrentAddressIntoVariable(int32_t variable_index, bool follow_links)¶

Load the current program execution pointer value into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadCurrentAddressIntoVariable. Represented by 6 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::terminate(int8_t return_code)¶

Immediately terminates the program.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

No further program operators will be executes. The program’s return code will be set to the value of the parameter return_code.

Identified by OpCode::Terminate. Represented by 2 bytes.

Parameters

return_code: The return code of the program after termination.

beast::Program::terminateWithVariableReturnCode(int32_t variable_index, bool follow_links)¶

Immediately terminates the program, returning a variable return code.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

No further program operators will be executes. The program’s return code will be set to the value of the value of the variable_index variable.

Identified by OpCode::TerminateWithVariableReturnCode. Represented by 6 bytes.

Parameters

variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::performSystemCall(int8_t major_code, int8_t minor_code, int32_t variable_index, bool follow_links)¶

Performs a system call according to its parameters.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Performs system calls for different purposes. The currently implemented set of functionalities and valid parameter ranges can be found in VmSession::performSystemCall.

Identified by OpCode::PerformSystemCall. Represented by 8 bytes.

See

VmSession::performSystemCall()

Parameters

major_code: The major code of the system call to perform
minor_code: The minor code of the system call to perform
variable_index: The index of the variable.
follow_links: Whether to resolve variable links.

beast::Program::loadRandomValueIntoVariable(int32_t variable_index, bool follow_links)¶

Stores a random value into the given variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

A random numeric value will be stored in the variable variable_index. It is drawn from the full range of the data type int32_t.

Identified by OpCode::LoadRandomValueIntoVariable. Represented by 6 bytes.

Parameters

variable_index: The index of the variable to store the random value in.
follow_links: Whether to resolve variable links.