vise/README.md

festive: A Constrained Size Output Virtual Machine

An attempt at defining a small VM to create a stack machine for size-constrained clients and servers.

Original motivation was to create a simple templating renderer for USSD clients, combined with an agnostic data-retrieval reference that may conceal any level of complexity.

Opcodes

The VM defines the following opcode symbols:

• BACK - Return to the previous execution frame (will fail if at top frame).
• CATCH <symbol> <signal> - Jump to symbol if signal is set (see signal below).
• CROAK <signal> - Clear state and restart execution from tip if signal is set (see signal below).
• LOAD <symbol> <size> - Execute the code symbol symbol and cache the data, constrained to the given size.
• RELOAD <symbol> - Execute a code symbol already loaded by LOAD and cache the data, constrained to the given size.
• MAP <symbol> - Expose a code symbol previously loaded by LOAD. Roughly corresponds to the global directive in Python.
• MOVE <symbol> - Create a new execution frame, invalidating all previous MAP calls.

Rendering

The fixed-size output is generated using a templating language, and a combination of one or more max size properties, and an optional sink property that will attempt to consume all remaining capacity of the rendered template.

For example, in this example

• maxOutputSize is 256 bytes long.
• template is 120 bytes long.
• param one has max size 10 but uses 5.
• param two has max size 20 but uses 12.
• param three is a sink.

The renderer may use up to 256 - 120 - 5 - 12 = 119 bytes from the sink when rendering the output.