Mycelium/hyphae/instructions.toml

description = """
HyphaeVM is a bytecode VM that aims to provide a simplified instruction set to
language implementors and other programmers who wish to use higher level
features without making too many compromises on overhead or performance.

The simplified instruction set greatly reduces the work in language design and
allows for simpler compilers overall. Meanwhile, the VM still meets performance
needs for modern application development.

HyphaeVM contains an instruction set, instruction set implementation, garbage
collection (reference counting), error handling, dynamic number package, vector
based data types, cons cell based dynamic data types, and trap functions that
are programmatically extendable.
"""

[[data_types]]
name = "number"
description = """
"""

[[data_types]]
name = "string"
description = """
"""

[[data_types]]
name = "bool"
description = """
"""

[[data_types]]
name = "cons"
description = """
"""

[[data_types]]
name = "symbol"
description = """
"""

[[data_types]]
name = "char"
description = "a single byte"

[[data_types]]
name = "vector"
description = """
"""

[[data_types]]
name = "ByteVector"
description = "a vector that only contains single bytes"

# TODO: add the following info
#   - info on error handling
#   - info on traps
#   - info on numbers
#   - info on symtable (and its uses)
#   - multiline descriptions for each instruction

[[addressing_modes]]
name = "expr"
mutable = true
symbol = "$expr"
example = "inc $expr"
description = "The expression register is used as a default output, or input by many instructions."

[[addressing_modes]]
name = "operand"
mutable = true
symbol = "$oper<N>"
example = "add $oper1, $oper2"
description = "There are four operand registers N=(0, 1, 2, 3, and 4). They are for storing mutable data."

[[addressing_modes]]
name = "stack"
mutable = false
symbol = "%N"
example = "dupl %0, $expr"
description = "Stack addressing mode takes an index in to the stack to read from."

[[addressing_modes]]
name = "instruction"
mutable = false
symbol = "@N"
example = "jmp @100"
description = "Instruction addressing mode indexes by instruction into the program."

[[addressing_modes]]
name = "numeric"
mutable = false
symbol = "N"
example = "const $expr, 100"
description = "Numeric addressing mode provides read only integer constants to instructions"

[[addressing_modes]]
name = "char"
mutable = false
symbol = "'N'"
example = "const $expr, 'c'"
description = "Char addressing mode provides read only character constants to instructions"

[[addressing_modes]]
name = "boolean"
mutable = false
symbol = "{true|false}"
example = "const $expr, true"
description = "Boolean addressing mode provides read only booleans to instructions"

[[instructions]]
name = "trap"
args = ["index"]
output = "result of function"
description = "triggers callback in trap vector at index"

[[instructions]]
name = "bind"
args = ["name", "operand"]
output = ""
description = "map name to operand in sym table."

[[instructions]]
name = "unbind"
args = ["name"]
output = ""
description = "remove name mapping from sym table."

[[instructions]]
name = "bound"
args = ["name"]
output = "expr = true if name is bound"
description = "test if a name is already bound"

[[instructions]]
name = "push"
args = ["operand"]
output = ""
description = "pushes deep copy of operand onto stack."

[[instructions]]
name = "pop"
args = []
output = ""
description = "removes element at top of stack."

[[instructions]]
name = "enter"
args = []
output = ""
description = "create new stack frame"

[[instructions]]
name = "exit"
args = []
output = ""
description = "delete current stack frame"

[[instructions]]
name = "link"
args = ["src", "dest"]
output = ""
description = "shallow copies src into dest"

[[instructions]]
name = "dupl"
args = ["src", "dest"]
output = ""
description = "deep copies src into dest"

[[instructions]]
name = "clear"
args = ["dest"]
output = ""
description = "clears dest"

[[instructions]]
name = "nop"
args = []
output = ""
description = "no operation"

[[instructions]]
name = "halt"
args = []
output = ""
description = "halts the VM"

[[instructions]]
name = "panic"
args = ["error"]
output = ""
description = "sets error state and halts VM"

[[instructions]]
name = "jmp"
args = ["addr"]
output = ""
description = "sets ictr register to addr"

[[instructions]]
name = "jmpif"
args = ["addr"]
output = ""
description = "if expr register holds true, sets ictr to addr"

[[instructions]]
name = "eq"
args = ["a", "b"]
output = "a == b"
description = "equality test"

[[instructions]]
name = "lt"
args = ["a", "b"]
output = "a < b"
description = "less than test"

[[instructions]]
name = "gt"
args = ["a", "b"]
output = "a > b"
description = "greater than test"

[[instructions]]
name = "lte"
args = ["a", "b"]
output = "a <= b"
description = "less than equals test"

[[instructions]]
name = "gte"
args = ["a", "b"]
output = "a >= b"
description = "greater than equals test"

[[instructions]]
name = "bool_not"
args = []
output = "expr = !expr"
description = "boolean not"

[[instructions]]
name = "bool_and"
args = ["a", "b"]
output = "a && b"
description = "boolean and"

[[instructions]]
name = "bool_or"
args = ["a", "b"]
output = "a || b"
description = "boolean or"

[[instructions]]
name = "byte_and"
args = ["a", "b"]
output = "a & b"
description = "bitwise and"

[[instructions]]
name = "byte_or"
args = ["a", "b"]
output = "a | b"
description = "bitwise or"

[[instructions]]
name = "xor"
args = ["a", "b"]
output = "a xor b"
description = "bitwise exclusive or"

[[instructions]]
name = "byte_not"
args = []
output = "expr = !expr"
description = "bitwise not"

[[instructions]]
name = "add"
args = ["a", "b"]
output = "a + b"
description = "numeric addition"

[[instructions]]
name = "sub"
args = ["a", "b"]
output = "a - b"
description = "numeric subtraction"

[[instructions]]
name = "mul"
args = ["a", "b"]
output = "a * b"
description = "numeric multiplication"

[[instructions]]
name = "fdiv"
args = ["a", "b"]
output = "a / b"
description = "numeric FLOAT division"

[[instructions]]
name = "idiv"
args = ["a", "b"]
output = "a / b"
description = "numeric INTEGER division"

[[instructions]]
name = "pow"
args = ["a", "b"]
output = "a ^ b"
description = "numeric operation to raise a to the power of b"

[[instructions]]
name = "modulo"
args = ["a", "b"]
output = "a % b"
description = "numeric modulo operation"

[[instructions]]
name = "rem"
args = ["a", "b"]
output = "remainder from a / b"
description = "remainder from integer division"

[[instructions]]
name = "inc"
args = ["src"]
output = ""
description = "increments number at source"

[[instructions]]
name = "dec"
args = ["src"]
output = ""
description = "decrements number at source"

[[instructions]]
name = "ctos"
args = ["src"]
output = ""
description = "mutates a char datum into a string datum"

[[instructions]]
name = "cton"
args = ["src"]
output = ""
description = "mutates a char datum into a number datum"

[[instructions]]
name = "ntoc"
args = ["src"]
output = ""
description = "mutates a number datum into a char datum"

[[instructions]]
name = "ntoi"
args = ["src"]
output = ""
description = "mutates a number datum into its exact form"

[[instructions]]
name = "ntoe"
args = ["src"]
output = ""
description = "mutates a number datum into its inexact form"

[[instructions]]
name = "const"
args = ["dst", "data"]
output = ""
description = "sets dst location to constant integer data"

[[instructions]]
name = "mkvec"
args = []
output = "a blank vector"
description = "creates a new vector"

[[instructions]]
name = "mkbvec"
args = []
output = "a blank bytevector"
description = "creates a blank bytevector"

[[instructions]]
name = "mkstr"
args = []
output = "an empty string"
description = "creates a new empty string"

[[instructions]]
name = "index"
args = ["collection", "index"]
output = "collection[index]"
description = "extracts element from collection at index"

[[instructions]]
name = "length"
args = ["collection"]
output = "length of collection"
description = "calculates length of collection"

[[instructions]]
name = "subsl"
args = ["collection", "start", "end"]
output = "collection[start:end]"
description = "returns a subset from collection denoted by start and end indexes"

[[instructions]]
name = "inser"
args = ["collection", "elem", "idx"]
output = ""
description = "inserts an element at specified index into a collection"

[[instructions]]
name = "cons"
args = ["left", "right"]
output = "resulting collection"
description = "either append right to left or make new list from both"

[[instructions]]
name = "car"
args = ["list"]
output = "returns first element in cons cell"
description = "takes an AST and returns first element in top level cons cell"

[[instructions]]
name = "cdr"
args = ["list"]
output = "returns last element in cons cell"
description = "takes an AST and returns last element in top level cons cell"

[[instructions]]
name = "concat"
args = ["string_l", "string_r"]
output = "string_l+string_r"
description = "concatenates string r to string l and returns a new string"

[[instructions]]
name = "s_append"
args = ["parent", "child"]
output = ""
description = "append in place child character into parent string"