# Pitmachine
A pitmachine is an abstract register machine for executing pitcode.

The pitmachine assembly language is JSON. The instructions field contains an array of labels and instructions. Labels are the targets of branch instructions. They are simple text. Slots are elements in an activation frame. They are designated by a small positive integer. Slots are the general registers of the pitmachine. Slots hold the arguments, variables, and temporaries of a function invocation.

{
    "name": "program_name",
    "data": {⸳⸳⸳},
    "source": "...",
The labels record associates labels with tokens for use by debuggers.

    "labels": {
        "entry": token,
        "beyond": token,
        ...
    },
The instructions array is a list of instructions and labels.

    instructions: [
A statement label:

        "entry",
go to beyond:

        ["jump", "beyond"],
assign slot 8: pi / 2

        ["access", 13, {"kind": "name", "name": "pi", "make": "intrinsic", ⸳⸳⸳}],
        ["int", 14, 2],
        ["divide", 8, 13, 14],
        ⸳⸳⸳
        "beyond"
        ⸳⸳⸳
    ]
}

## Pitcode instructions
This is a register based machine.

### Arithmetic
Arithmetic instructions perform operations on numbers. All other cases disrupt (except add, which is polymorphic).

"add", dest, left, right // dest, left, and right are numbers designating slots in the current activation frame. Also works on texts (concatenation).

"subtract", dest, left, right

"multiply", dest, left, right

"divide", dest, left, right

"integer_divide", dest, left, right

"modulo", dest, left, right

"remainder", dest, left, right

"max", dest, left, right

"min", dest, left, right

"abs", dest, right

"neg", dest, right

"sign", dest, right

"fraction", dest, right

"integer", dest, right

"ceiling", dest, right, place

"floor", dest, right, place

"round", dest, right, place

"trunc", dest, right, place

### Text
Text instructions perform operations on texts. All other cases disrupt.

"concat", dest, left, right // concat two texts

"concat_space", dest, left, right

"character", dest, right

"codepoint", dest, right

"length", dest, right

"lower", dest, right

"upper", dest, right

"append", pretext, right

Append the right text to the pretext, forwarding and growing its capacity if necessary.

### Comparison
Comparison instructions perform operations on texts or numbers. All other cases disrupt.

"eq", dest, left, right

"ne", dest, left, right

"lt", dest, left, right

"le", dest, left, right

"gt", dest, left, right

"ge", dest, left, right

### Logical

"not", dest, right

### Bitwise
Bitwise instructions convert operands to 32-bit integers. Non-numbers disrupt.

"bitand", dest, left, right

"bitor", dest, left, right

"bitxor", dest, left, right

"bitnot", dest, right

"shl", dest, left, right

"shr", dest, left, right

"ushr", dest, left, right

### Function

"frame", dest, func, nr_args

Prepare to invoke the func object. If the nr_args is too large, disrupt. Allocate the new activation frame. Put the current frame pointer into it.

"goframe", dest, func, nr_args

Same as frame, except that the current frame is reused if it is large enough.

"invoke", frame

Store the next instruction address in the current frame. Make the new frame the current frame. Jump to the entry point.

"goinvoke", frame

"apply", func, array

"return", value

"return_value", dest

"setarg", frame, slot, value // set the slot of frame to value

### Branching

"jump", label

"jump_true", slot, label

If the value in the slot is true, jump to the label. Otherwise, continue with the next instruction.

"jump_false": slot, label

If the value in the slot is false, jump to the label. Otherwise, continue with the next instruction.

"jump_null": slot, label

"jump_empty": slot, label

"wary_true", slot, label

If the value in the slot is true, jump to the label. If the value is false, continue with the next instruction. Otherwise disrupt because of a type error.

"wary_false": slot, label

If the value in the slot is false, jump to the label. If the value is true, continue with the next instruction. Otherwise disrupt because of a type error.

### Sensory

Does the right slot contain a value of the indicated type?

"array?", dest, right

"blob?", dest, right

"character?", dest, right

"data?", dest, right

"digit?", dest, right

"false?", dest, right

"fit?", dest, right

"function?", dest, right

"integer?", dest, right

"letter?", dest, right

"logical?", dest, right

"null?", dest, right

"pattern?", dest, right

"record?", dest, right

"stone?", dest, right

"text?", dest, right

"true?", dest, right

"upper?", dest, right

"whitespace?", dest, right

### Potpourri

"stone", dest, right // stone an object

"true", dest

"false", dest

"null", dest

"move", dest, right

"int", dest, small_int

"access", dest, literal

This is used to access values (numbers, texts) from the program's immutable memory. The literal is a number or text.

"load", dest, object, subscript

This is used to load values from records and arrays.

"store", dest, object, subscript

This is used to store values into records and arrays.

"delete", object, subscript

used to delete a field from a record.

"get", dest, slot, level

This is used to get values from slots in outer frames.

"put", value, slot, level

This is used to store values into slots in outer frames.

"push", array, slot

Append to a mutable array.

"pop", dest, array

Remove the last element of a mutable array, putting the element into dest.

"disrupt"

### Make

"array", dest, nr_elements

"blob", dest, nr_bits

"function", dest, code_name_text

"pretext", dest, nr_characters

A pretext must be converted to text by stone before it can leave the function scope.

"record", dest, nr_elements