vise/README.md
2023-04-01 15:33:35 +01:00

1.6 KiB

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.