commit ba4bc480fcf09a16cfda99a34197bca3420228cf
parent 0170624432174bb93e9149352d19a642122f494d
Author: lash <dev@holbrook.no>
Date: Mon, 1 May 2023 10:34:00 +0100
WIP texinfo documentation
Diffstat:
8 files changed, 594 insertions(+), 0 deletions(-)
diff --git a/doc/texinfo/cookbook.texi b/doc/texinfo/cookbook.texi
@@ -0,0 +1,148 @@
+@node cookbook
+@chapter Common patterns
+
+
+@section Hello world
+
+@example
+HALT
+@end example
+
+Will render a template without any external symbols and terminate execution immediately.
+
+
+@anchor{handling_menus}
+@section Handling menus and inputs
+
+@example
+MOUT to_foo 0
+MOUT to_bar 1
+MOUT upup 2
+HALT
+INCMP foo 0
+INCMP bar 1
+INCMP _ 2
+@end example
+
+Create three menu items, resolving the menu symbols @code{to_foo}, @code{to_bar} and @code{upup} respectively to translated text and pairing with the selectors.
+
+Yield for client input. Then attempt to match input to selectors:
+
+@itemize
+@item if selector is @code{0}, execute node @code{foo}.
+@item if selector is @code{1}, execute node @code{bar}.
+@item if selector is @code{2}, execute previous node in stack.
+@end itemize
+
+
+@subsection Menu batch version
+
+@example
+DOWN foo 0 to_foo
+DOWN bar 1 to_bar
+UP 2 upup
+@end example
+
+This example produces exactly the same bytecode result as the @ref{handling_menus,previous example}.
+
+
+@section Signal flow control
+
+@example
+LOAD foo 1
+CATCH bar 8 1
+MOVE baz
+@end example
+
+If loading the external symbol @code{foo} sets the flag @code{8}, then immediately move to @code{bar}.
+
+Otherwise, move to @code{baz}.
+
+
+@anchor{multiple_pages}
+@section Multiple pages
+
+@example
+LOAD foo 0
+MNEXT to_fwd 11
+MPREV to_back 22
+HALT
+INCMP > 11
+INCMP < 22
+@end example
+
+Load external symbol @code{foo} as a @emph{sink}.
+
+If content spans multiple pages, resolve @code{to_fwd} and @code{to_back} as labels for lateral navigation options in the menu.
+
+Also handle the lateral navigation inputs.
+
+@subsection Menu batch version
+
+@example
+LOAD foo 0
+NEXT 11 to_fwd
+PREVIOUS 22 to_back
+@end example
+
+This example produces exactly the same bytecode result as the @ref{multiple_pages,previous example}.
+
+
+@anchor{multiple_menus}
+@section Multi-page menus
+
+@example
+MSINK
+MNEXT to_fwd 11
+MPREV to_back 22
+MOUT inky 0
+MOUT pinky 1
+MOUT blinky 2
+MOUT clyde 3
+MOUT tinkywinky 4
+MOUT dipsy 5
+MOUT lala 6
+MOUT pu 7
+HALT
+INCMP foo 0
+INCMP foo 1
+INCMP foo 2
+INCMP foo 3
+INCMP foo 4
+INCMP foo 5
+INCMP foo 6
+INCMP bar 7
+@end example
+
+Enable splitting menu over several pages, and route all valid inputs to the @code{foo} node, except for @code{7} which is routed to the @code{bar} node.
+
+
+@subsection Menu batch version
+
+@example
+MSINK
+MNEXT to_fwd 11
+MPREV to_back 22
+DOWN foo 0 inky
+DOWN foo 1 pinky
+DOWN foo 2 blinky
+DOWN foo 3 clyde
+DOWN foo 4 tinkywinky
+DOWN foo 5 dipsy
+DOWN foo 6 lala
+DOWN bar 7 pu
+@end example
+
+This example produces exactly the same bytecode result as the @ref{multiple_menus,previous example}.
+
+
+@section Default input handler
+
+@example
+MOUT to_foo 0
+HALT
+INCMP foo 0
+INCMP bar *
+@end example
+
+If input is @code{0}, route to the @code{foo}. Any other input will route to the @code{bar} node.
diff --git a/doc/texinfo/index.texi b/doc/texinfo/index.texi
@@ -0,0 +1,32 @@
+\input texinfo
+@settitle vise
+
+@copying
+Released 2023 under AGPL3
+@end copying
+
+@titlepage
+@title vise
+@author Louis Holbrook
+
+@end titlepage
+
+@c
+@contents
+
+@ifnottex
+@node Top
+@top Introduction
+@end ifnottex
+@menu
+* overview ::
+* instructions :
+@end menu
+
+@include overview.texi
+@include nomenclature.texi
+@include signals.texi
+@include instructions.texi
+@include navigation.texi
+@include render.texi
+@include cookbook.texi
diff --git a/doc/texinfo/instructions.texi b/doc/texinfo/instructions.texi
@@ -0,0 +1,224 @@
+@node instructions
+@chapter Instructions
+
+
+@section Data types
+
+
+@anchor{node_type}
+@subsection node
+
+A node name is a string.
+
+Both regular and special node names exist.
+
+@subsubsection 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.
+
+
+@subsubsection Special node
+
+Special node names are a single character.
+
+See @ref{node_names, Node names} for details.
+
+
+@subsection label
+
+Same rules as for @ref{symbol_type, symbol}.
+
+
+@subsection size
+
+Numerical value of any size.
+
+
+@subsection selector
+
+The selector @code{*} is used to catch any input.
+
+Apart from that, a valid selector is a string of 7-bit alphanumeric characters.
+
+
+@anchor{symbol_type}
+@subsection symbol
+
+Same rules as for @ref{node_type, regular node names}.
+
+
+@subsection signal
+
+Numerical value of any size.
+
+
+@subsection matchmode
+
+Binary numeric value, 0 or 1.
+
+
+@section Instruction list
+
+@subsection CATCH <node> <signal> <matchmode>
+
+Control flow using signal checking.
+
+If @code{matchmode} is 1, then jump to @code{node} if @code{signal} is @emph{set}.
+
+If @code{matchmode} is 0, then jump to @code{node} if @code{signal} is @emph{no set}.
+
+Existing bytecode in buffer is cleared before the jump.
+
+
+@subsection CROAK <signal> <matchmode>
+
+Clear state and restart execution from top if signal is matched.
+
+Signal match is the same as for @code{CATCH}.
+
+@subsection HALT
+
+Halt execution and yield control to client.
+
+Any remaining bytecode is kept in buffer.
+
+
+@subsection INCMP <node> <selector>
+
+Compare registered input to @code{selector}.
+
+If match, it has the same side-effects as @code{MOVE}.
+
+In addition, any consecutive @code{INCMP} matches will be ignored until next @code{HALT} is encountered.
+
+
+@subsection LOAD <symbol> <size>
+
+Execute the code symbol @code{symbol} and cache the result.
+
+Result must be constrained to the given @code{size}.
+
+
+@subsection MAP <symbol>
+
+Expose result from @code{symbol} previously loaded by @code{LOAD} to the renderer.
+
+
+@subsection MNEXT <label> <selector>
+
+Activate the "next" part of lateral navigation.
+
+Define how to display the menu choice for advancing to the next page.
+
+
+@subsection MOUT <label> <selector>
+
+Add menu entry.
+
+Each entry should have a corresponding `INCMP` with matching @code{selector}.
+
+Attempt to resolve @code{label} to a language-enabled string to use as menu title, or by default use the @code{label} directly.
+
+
+@subsection MOVE <node>
+
+Load bytecode and template corresponding to @code{node}.
+
+The loaded bytecode is appended to existing bytecode in buffer.
+
+Invalidates effects of all preceding @code{MAP} calls.
+
+
+@subsection MPREV <label> <selector>
+
+Activate the "previous" part of lateral navigation.
+
+Define how to display the menu choice for going back to the previous page.
+
+
+@subsection MSINK
+
+If set, the menu is defined as the multi-page content sink.
+
+Cannot be used with an active @code{MAP} of a symbol with @code{LOAD} size @code{0}.
+
+
+@subsection RELOAD <symbol>
+
+Execute a code symbol already loaded by @code{LOAD} and overwrite the existing cache with the new results.
+
+Constrained to the previously given size for the same symbol.
+
+
+
+@section Batch instructions
+
+Some convenience instructions are made available for defining menus.
+
+There instruction @strong{MUST} be used at the @emph{end} of the node's assembly code, as they expand to code on either side of a @code{HALT} instruction.
+
+@table @code
+@item DOWN <symbol> <selector> <label>
+Descend to next frame and move to @code{symbol}.
+@item UP <selector> <label>
+Return to the previous frame.
+@item NEXT <selector> <label>
+Activate and set @emph{next} menu option for browsing multiple-page renders.
+@item PREVIOUS <selector> <label>
+Activate and set @emph{previuos} menu option for browsing multiple-page renders. (If @code{MNEXT}/@code{NEXT} has not been defined this will not be rendered).
+@end table
+
+
+@subsection Batch menu expansion
+
+@multitable .50 .50
+@headitem Batch instruction
+@tab Expanded instruction
+@item @example
+DOWN foo 0 to_foo
+@end example
+@tab @example
+MOUT to_foo 0
+HALT
+INCMP foo 0
+@end example
+@item @example
+UP 1 back
+@end example
+@tab @example
+MOUT back 1
+HALT
+INCMP _ 1
+@end example
+@item @example
+NEXT 2 fwd
+@end example
+@tab @example
+MNEXT fwd 2
+HALT
+INCMP > 2
+@end example
+@item @example
+PREVIOUS 3 back
+@end example
+@tab @example
+MPREV back 3
+HALT
+INCMP < 3
+@end example
+@item @example
+DOWN foo 0 to_foo
+UP 1 back
+@end example
+@tab @example
+MOUT to_foo 0
+MOUT back 1
+HALT
+INCMP foo 0
+INCMP _ 1
+@end example
+@end multitable
diff --git a/doc/texinfo/navigation.texi b/doc/texinfo/navigation.texi
@@ -0,0 +1,102 @@
+@node navigation
+@chapter Navigation
+
+
+Nodes are navigated by name, using a navigation stack.
+
+Every movement @emph{down} adds a node to the stack, and every movement @emph{up} removes one node from the stack.
+
+Additionally, @emph{lateral} movement is available, for nodes whose contents span mulitple pages.
+
+
+@section Entry point
+
+All VM executions require an @emph{entry point}.
+
+If not explicitly set in the code, the node name @code{root} is used.
+
+Attempting to navigate @emph{up} from the entry point node will fail and terminate execution.
+
+
+@section Lateral navigation
+
+Lateral navigation is only available for node output spanning multiple pages. See @ref{render_multi, Multi-page rendering} for details.
+
+Lateral navigation will fail and terminate execution when:
+
+@itemize
+@item executing a single-page node.
+@item attempting @emph{next} beyond the last page.
+@item attempting @emph{previous} on the first page.
+@end itemize
+
+
+@anchor{node_names}
+@section Node names
+
+Regular node names @emph{must} start with an alphabetical character. The rest of the string may contain alphanumeric characters and underscore.
+
+@subsection Special node names
+
+A selection of special node names are available for relative navigation. They are single-character tokens, listed below with their respective ASCII codes.
+
+@table @code
+@item . (0x2E)
+Repeat the same node.
+@item _ (0x5F)
+Go to the previous node in the stack.
+@item > (0x3E)
+Go to the next page of a multi-page node. Will fail if used in a single-page context and/or resulting page index is out of bounds.
+@item < (0x3C)
+Go to the next page of a multi-page node. Will fail if used on the first (or single) page.
+@item ^ (0x5E)
+Go to the topmost node. Will execute each intermediate node in the stack.
+@end table
+
+
+@subsection Builtin node names
+
+Uncaught exceptions in the code flow that should not halt execution are routed to a builtin node named @code{_catch}.
+
+
+@section Navigation stack
+
+Consider the following navigation example, illustrating the state of the stack for each step after execution.
+
+@multitable .25 .65 .10
+@headitem instruction
+@tab stack
+@tab page index
+@item @code{MOVE foo}
+@tab foo
+@tab 0
+@item @code{MOVE bar}
+@tab foo/bar
+@tab 0
+@item @code{MOVE baz}
+@tab foo/bar/baz
+@tab 0
+@item @code{MOVE >}
+@tab foo/bar/baz
+@tab 1
+@item @code{MOVE >}
+@tab foo/bar/baz
+@tab 2
+@item @code{MOVE <}
+@tab foo/bar/baz
+@tab 1
+@item @code{MOVE .}
+@tab foo/bar/baz
+@tab 1
+@item @code{MOVE _}
+@tab foo/bar
+@tab 0
+@item @code{MOVE baz}
+@tab foo/bar/baz
+@tab 0
+@item @code{MOVE ^}
+@tab foo
+@tab 0
+@end multitable
+
+
diff --git a/doc/texinfo/nomenclature.texi b/doc/texinfo/nomenclature.texi
@@ -0,0 +1,19 @@
+@node nomenclature
+@chapter Nomenclature
+
+@section Common
+
+@table @samp
+@item client
+Code that generates input to the VM and processes its output. Examples of clients are the @code{engine} module, and the @file{/dev/interactive} executable.
+@end table
+
+
+@section Instructions and navigation
+
+@table @samp
+@item node
+A node in the execution flow that has both bytecode and template associated with it. May also have language translations.
+@item symbol
+Token used as key to load external content and trigger side-effects.
+@end table
diff --git a/doc/texinfo/overview.texi b/doc/texinfo/overview.texi
@@ -0,0 +1,6 @@
+@node overview
+@chapter Overview
+
+An attempt at defining a small VM to handle menu interaction 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.
diff --git a/doc/texinfo/render.texi b/doc/texinfo/render.texi
@@ -0,0 +1,5 @@
+@node render
+@chapter Rendering
+
+@anchor{render_multi}
+@section Multiple-page rendering
diff --git a/doc/texinfo/signals.texi b/doc/texinfo/signals.texi
@@ -0,0 +1,58 @@
+@node signals
+@chapter Signal flags
+
+
+@section Client-defined signal flags
+
+The client can define any number of signal flags to use. The number of signals @strong{MUST} be declared explicitly in the client code, and @strong{MUST NOT} change in stateful or asynchronous execution environments.
+
+In the assembly code, signals may only be referred to by their numerical value. The numeric value of client-defined signals must have numeric value @code{8} or greater.
+
+
+@subsection Flow control
+
+Signal flags enables the client to control the execution flow as a side-effect of the execution of external code symbols.
+
+Branching is defined using either the @code{CATCH} or @code{CROAK} instructions.
+
+The client specifies whether or not a set flag should be reset on next yield. If not, it is the responsiblity of the client to reset the flag when necessary.
+
+
+@section Builtin signal flags
+
+For the numeric values of the signals, please refer to the signals appendix.
+
+@multitable @columnfractions .15 .20 .55 .10
+@headitem Flag name
+@tab Description
+@tab Lifetime
+@tab Writeable?
+@item @code{READIN}
+@tab Input is being processed.
+@tab From first @code{INCMP} until: an @code{INCMP} match @emph{or} an invalid input exception is triggered.
+@tab no
+@item @code{INMATCH}
+@tab Input matched an @code{INCMP} instruction.
+@tab Next instruction.
+@tab no
+@item @code{TERMINATE}
+@tab Terminate execution before the following instruction.
+@tab Until explicit reseet.
+@tab no
+@item @code{DIRTY}
+@tab Rendered output is available.
+@tab Until output is processed.
+@tab no
+@item @code{WAIT}
+@tab Halt execution before the following instruction, and yield control to client.
+@tab Until control is yielded.
+@tab no
+@item @code{LOADFAIL}
+@tab An unexpected error has occurred during execution of an external code symbol.
+@tab Next instruction.
+@tab no
+@item @code{LANG}
+@tab Output from an external code symbol is a valid language code, and language should be changed accordingly.
+@tab Next instruction.
+@tab yes
+@end multitable
