Instructions
************

Data types
==========

node
----

A node name is a string.

Both regular and special node names exist.

Regular node
............

Must be one or more characters long.

Starts with a 7-bit alphabetical character.

The remainder of the string may contain 7-bit alphanumeric characters or underscore.

Special node
............

Special node names are a single character.

See Node names for details.

label
-----

Same rules as for symbol.

size
----

Numerical value of any size.

selector
--------

The selector * is used to catch any input.

Apart from that, a valid selector is a string of 7-bit alphanumeric characters.

symbol
------

Same rules as for regular node names.

signal
------

Numerical value of any size.

matchmode
---------

Binary numeric value, 0 or 1.

Instruction list
================

CATCH <node> <signal> <matchmode>
---------------------------------

Control flow using signal checking.

If matchmode is 1, then jump to node if signal is set.

If matchmode is 0, then jump to node if signal is not set.

Existing bytecode in buffer is cleared before the jump.

CROAK <signal> <matchmode>
--------------------------

Clear state and restart execution from top if signal is matched.

Signal match is the same as for CATCH.

HALT
----

Halt execution and yield control to client.

Any remaining bytecode is kept in buffer.

INCMP <node> <selector>
-----------------------

Compare registered input to selector.

If match, it has the same side-effects as MOVE.

In addition, any consecutive INCMP matches will be ignored until next HALT is encountered.

LOAD <symbol> <size>
--------------------

Execute the code symbol symbol and cache the result.

Result must be constrained to the given size.

This is a noop if symbol has already been loaded in the current scope.

MAP <symbol>
------------

Expose result from symbol previously loaded by LOAD to the renderer.

MNEXT <label> <selector>
------------------------

Activate the "next" part of lateral navigation.

Define how to display the menu choice for advancing to the next page.

MOUT <label> <selector>
-----------------------

Add menu entry.

Each entry should have a corresponding `INCMP` with matching selector.

Attempt to resolve label to a language-enabled string to use as menu title, or by default use the label directly.

MOVE <node>
-----------

Load bytecode and template corresponding to node.

The loaded bytecode is appended to existing bytecode in buffer.

Invalidates effects of all preceding MAP calls.

MPREV <label> <selector>
------------------------

Activate the "previous" part of lateral navigation.

Define how to display the menu choice for going back to the previous page.

MSINK
-----

If set, the menu is defined as the multi-page content sink.

Cannot be used with an active MAP of a symbol with LOAD size 0.

RELOAD <symbol>
---------------

Execute a code symbol already loaded by LOAD and overwrite the existing cache with the new results.

Constrained to the previously given size for the same symbol.

Batch instructions
==================

Some convenience instructions are made available for defining menus.

There instruction MUST be used at the end of the node's assembly code, as they expand to code on either side of a HALT instruction.

DOWN <symbol> <selector> <label>
     Descend to next frame and move to symbol.

UP <selector> <label>
     Return to the previous frame.

NEXT <selector> <label>
     Activate and set next menu option for browsing multiple-page renders.

PREVIOUS <selector> <label>
     Activate and set previuos menu option for browsing multiple-page renders.  (If MNEXT/NEXT has not been defined this will not be rendered).

Batch menu expansion
--------------------

Batch instruction
Expanded instruction

DOWN foo 0 to_foo

MOUT to_foo 0
HALT
INCMP foo 0

UP 1 back

MOUT back 1
HALT
INCMP _ 1

NEXT 2 fwd

MNEXT fwd 2
HALT
INCMP > 2

PREVIOUS 3 back

MPREV back 3
HALT
INCMP < 3

DOWN foo 0 to_foo
UP 1 back

MOUT to_foo 0
MOUT back 1
HALT
INCMP foo 0
INCMP _ 1