S₀

S₀ is Swanson’s “machine language”. It defines the core operations that a program can perform in the Swanson execution model. The SBL format provides a binary representation of S₀ code.

Execution

A Swanson program operates on four stacks, numbered 0 through 3. Each instruction pops its inputs from the top of one or more stacks, and places its results back on top of one or more (possibly different) stacks. Most instructions operate only on stack 0. Move instructions transfer values between stacks.

Note

Many of the instructions are described as “popping” one or more values from a stack. Those instructions will halt and catch fire if that stack does not contain at least as many values as are expected, or if they are the wrong kind of values.

Modules and branches

An S₀ module has a name and a collection of branches. Each branch also has a name. A branch contains a sequence of instructions followed by exactly one invocation.

Invoking a module selects one of its branches. The branch’s instructions execute in order, and its final invocation transfers control to another invokable. Control does not return to the branch.

Instructions that operate on basic values

bytes

Creates a new literal containing the instruction’s binary content, and pushes it onto stack 0.

newtag

Creates a new tag that is distinct from every other tag in the current execution, and pushes it onto stack 0.

droptag

Pops a tag from stack 0, and drops it.

lock

Pops a value and a tag from stack 0. Constructs a new locked value from that value and tag. Pushes the tag and the locked value onto stack 0. (Note that the tag is not consumed; it is pushed back onto the stack so that you can lock multiple values with the same tag.)

unlock

Pops a locked value and a tag from stack 0. Halts and catches fire if the popped tag does not match the tag that was used to lock the value. Removes the value from the locked value and pushes the tag and the unlocked value onto stack 0. (Note that the tag is not consumed; it is pushed back onto the stack so that you can unlock multiple values with the same tag.)

nil

Pushes an empty list onto stack 0.

dropnil

Pops an empty list from stack 0, and drops it. Halts and catches fire if the list is not empty.

cons

Pops a value and a list from stack 0. Appends the value to the end of the list. Pushes the list onto stack 0.

uncons

Pops a list from stack 0. Halts and catches fire if the list is empty. Removes the last value from the list, and pushes the list and the removed value onto stack 0.

Moves

A move instruction identifies a source stack and a target stack. It pops a value from the source stack and pushes that value onto the target stack.

Quotations and closures

A quote instruction constructs an invokable whose branches are defined by S₀ code, and pushes it onto stack 0.

An enclosed quote instruction also consumes one value from stack 0. It pushes a closure that pairs that value with the new quotation. Invoking the closure first restores the enclosed value to stack 0, then executes the selected branch.

An upquote instruction finds a quotation that lexically encloses the instruction, and pushes that quotation onto stack 0. The instruction’s depth selects which enclosing quotation to use. A depth of 0 selects the immediately enclosing quotation.

An enclosed upquote consumes one value from stack 0 and pairs it with the selected enclosing quotation, producing a closure.

Invocation

Every branch ends with an invocation. An invocation contains the name of a branch. It consumes the invokable on top of stack 0 and transfers control to the selected branch of that invokable.