Branching
Overview
Branching verbs control program flow by modifying the program counter (pc).
Branches may be unconditional, conditional, or part of a subroutine call. Branch targets may be specified using absolute line numbers, labels, or relative line references.
Integer branches compare integer values directly. String branches provide equality and inequality comparisons for string values.
Subroutines use a dedicated call stack to store return addresses, allowing execution to resume after a CALL.
Branch targets
Branching instructions accept a branch target as their first operand.
A target may be specified as an absolute line number:
JUMP 100
a label:
JUMP $loop
or a relative line reference:
JUMP @-3
Relative references use the current line as their origin. @0 refers to the current line, positive values refer to later lines, and negative values refer to earlier lines.
JUMP @5
-- > Jump 5 lines forward
JUMP @-5
-- > Jump 5 lines backward
Labels and relative references are resolved to absolute line numbers during the program pre-pass, before execution begins.
Unconditional branching
JUMP — Branch Always
JUMP <target>
Branches unconditionally to the specified target.
Alias: GOTO
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | target |
Branch target | — | Branch target. |
Modified registers
| Register | Description |
|---|---|
pc |
Updated to the target line. |
Examples
-- Jump to a line number.
JUMP 100
-- > Execution continues at line 100
-- Jump to a label.
JUMP $loop
-- > Execution continues at `$loop`
-- Jump backward three lines.
JUMP @-3
GOTO behaves identically to JUMP:
GOTO $loop
-- > Execution continues at `$loop`
Integer branching
Integer branches compare two integer values and branch when the specified condition is true.
| Verb | Branches when |
|---|---|
BEQ |
lhs == rhs |
BNEQ |
lhs != rhs |
BGT |
lhs > rhs |
BGE |
lhs >= rhs |
BLT |
lhs < rhs |
BLE |
lhs <= rhs |
BEQ — Branch Equal
BEQ <target> <lhs> <rhs>
Branches if two integer values are equal.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | target |
Branch target | — | Branch target. |
| 2 | lhs |
Integer value | — | Left-hand operand. |
| 3 | rhs |
Integer value | — | Right-hand operand. |
Modified registers
| Register | Description |
|---|---|
pc |
Updated if the branch is taken. |
Examples
-- Branch if two registers are equal.
BEQ $equal r0 r1
-- > Execution continues at `$equal` if r0 == r1
-- Branch if a register is zero.
BEQ $done r0 0
-- > Execution continues at `$done` if r0 == 0
BNEQ — Branch Not Equal
BNEQ <target> <lhs> <rhs>
Branches if two integer values are not equal.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | target |
Branch target | — | Branch target. |
| 2 | lhs |
Integer value | — | Left-hand operand. |
| 3 | rhs |
Integer value | — | Right-hand operand. |
Modified registers
| Register | Description |
|---|---|
pc |
Updated if the branch is taken. |
Examples
-- Branch if two registers differ.
BNEQ $different r0 r1
-- > Execution continues at `$different` if r0 != r1
-- Branch if a register is non-zero.
BNEQ $loop r0 0
-- > Execution continues at `$loop` if r0 != 0
-- Branch three lines backward while r0 is non-zero.
BNEQ @-3 r0 0
BGT — Branch Greater Than
BGT <target> <lhs> <rhs>
Branches if the left-hand integer value is greater than the right-hand value.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | target |
Branch target | — | Branch target. |
| 2 | lhs |
Integer value | — | Left-hand operand. |
| 3 | rhs |
Integer value | — | Right-hand operand. |
Modified registers
| Register | Description |
|---|---|
pc |
Updated if the branch is taken. |
Examples
-- Branch if a value is positive.
BGT $positive r0 0
-- > Execution continues at `$positive` if r0 > 0
-- Branch if one value exceeds another.
BGT $higher r0 r1
-- > Execution continues at `$higher` if r0 > r1
BGE — Branch Greater Than or Equal
BGE <target> <lhs> <rhs>
Branches if the left-hand integer value is greater than or equal to the right-hand value.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | target |
Branch target | — | Branch target. |
| 2 | lhs |
Integer value | — | Left-hand operand. |
| 3 | rhs |
Integer value | — | Right-hand operand. |
Modified registers
| Register | Description |
|---|---|
pc |
Updated if the branch is taken. |
Examples
-- Branch if a value is non-negative.
BGE $valid r0 0
-- > Execution continues at `$valid` if r0 >= 0
-- Branch if one value is at least another.
BGE $pass r0 r1
-- > Execution continues at `$pass` if r0 >= r1
BLT — Branch Less Than
BLT <target> <lhs> <rhs>
Branches if the left-hand integer value is less than the right-hand value.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | target |
Branch target | — | Branch target. |
| 2 | lhs |
Integer value | — | Left-hand operand. |
| 3 | rhs |
Integer value | — | Right-hand operand. |
Modified registers
| Register | Description |
|---|---|
pc |
Updated if the branch is taken. |
Examples
-- Branch if a value is negative.
BLT $negative r0 0
-- > Execution continues at `$negative` if r0 < 0
-- Branch if one value is less than another.
BLT $lower r0 r1
-- > Execution continues at `$lower` if r0 < r1
BLE — Branch Less Than or Equal
BLE <target> <lhs> <rhs>
Branches if the left-hand integer value is less than or equal to the right-hand value.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | target |
Branch target | — | Branch target. |
| 2 | lhs |
Integer value | — | Left-hand operand. |
| 3 | rhs |
Integer value | — | Right-hand operand. |
Modified registers
| Register | Description |
|---|---|
pc |
Updated if the branch is taken. |
Examples
-- Branch if a value is non-positive.
BLE $done r0 0
-- > Execution continues at `$done` if r0 <= 0
-- Branch if one value is at most another.
BLE $limit r0 r1
-- > Execution continues at `$limit` if r0 <= r1
String branching
String branches provide equality and inequality comparisons between string values.
The base CPU does not provide lexicographical string branches.
BSEQ — Branch String Equal
BSEQ <target> <lhs> <rhs>
Branches if two string values are equal.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | target |
Branch target | — | Branch target. |
| 2 | lhs |
String value | — | Left-hand operand. |
| 3 | rhs |
String value | — | Right-hand operand. |
Modified registers
| Register | Description |
|---|---|
pc |
Updated if the branch is taken. |
Examples
-- Branch if two strings are equal.
BSEQ $match s0 s1
-- > Execution continues at `$match` if s0 == s1
-- Branch if a string is empty.
BSEQ $empty s0 ""
-- > Execution continues at `$empty` if s0 is empty
BSNEQ — Branch String Not Equal
BSNEQ <target> <lhs> <rhs>
Branches if two string values are not equal.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | target |
Branch target | — | Branch target. |
| 2 | lhs |
String value | — | Left-hand operand. |
| 3 | rhs |
String value | — | Right-hand operand. |
Modified registers
| Register | Description |
|---|---|
pc |
Updated if the branch is taken. |
Examples
-- Branch if two strings differ.
BSNEQ $different s0 s1
-- > Execution continues at `$different` if s0 != s1
-- Branch if a string is not empty.
BSNEQ $continue s0 ""
-- > Execution continues at `$continue` if s0 is not empty
Subroutines
Subroutines allow execution to temporarily branch to another part of the program before returning to the point from which they were called.
Call stack
The CPU maintains a dedicated call stack for storing return addresses.
Unlike the value stack, the call stack is managed automatically by CALL and RET and cannot be accessed directly.
| Property | Value |
|---|---|
| Capacity | 16 entries |
| Stores | Return addresses |
Call stack overflow and underflow are fatal errors. Execution is aborted and control returns to the shell.
CALL — Call Subroutine
CALL <target>
Calls a subroutine at the specified target.
CALL stores the following program line as its return address. Any remaining coalesced instructions on the current line are skipped.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | target |
Branch target | — | Subroutine target. |
Modified registers
| Register | Description |
|---|---|
pc |
Updated to the target line. |
Examples
-- Call a line number.
CALL 100
-- > Execution continues at line 100
-- Call a label.
CALL $subroutine
-- > Execution continues at `$subroutine`
-- Call a subroutine five lines ahead.
CALL @5
Notes
CALLpushes a return address onto the dedicated call stack.- Call stack overflow is a fatal error.
- Execution is aborted and control returns to the shell.
RET — Return From Subroutine
RET
Returns from the current subroutine using the return address stored by CALL.
Operands
This instruction takes no operands.
Modified registers
| Register | Description |
|---|---|
pc |
Restored from the call stack. |
Examples
-- Return to the caller.
RET
-- > Returns using the most recent return address stored by CALL.
Notes
RETpops the return address from the dedicated call stack.- Call stack underflow is a fatal error.
- Execution is aborted and control returns to the shell.