Merge branch 'mcode2' into mach

docs/pitcode.md

@@ -0,0 +1,287 @@
+# 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
+