From a0069d7818ac8b212b3e02e37b630c74e9976cd4 Mon Sep 17 00:00:00 2001 From: lash Date: Sat, 1 Apr 2023 15:33:35 +0100 Subject: [PATCH] Add readme --- README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..73f2373 --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +# 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 ` - Jump to symbol if signal is set (see `signal` below). +* `CROAK ` - Clear state and restart execution from tip if signal is set (see `signal` below). +* `LOAD ` - Execute the code symbol `symbol` and cache the data, constrained to the given `size`. +* `RELOAD ` - Execute a code symbol already loaded by `LOAD` and cache the data, constrained to the given `size`. +* `MAP ` - Expose a code symbol previously loaded by `LOAD`. Roughly corresponds to the `global` directive in Python. +* `MOVE ` - 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. +