commit 8c5e43e1761bf958cf4d152523e6e4710bcf5431 parent c7e3ffa8d8070a2a4aa77bbb7368fc38bfe5d7a8 Author: lash <dev@holbrook.no> Date: Mon, 1 May 2023 20:31:50 +0100 Add html render of docs Diffstat:
| A | doc/build/builtin_005fflags.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/cache.html | | | 141 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/cookbook.html | | | 227 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/dev.html | | | 437 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/dynamic_005ftemplates.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/engine.html | | | 134 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/execution_005fcontext.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/handling_005fmenus.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/index.html | | | 222 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/instructions.html | | | 352 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/language.html | | | 57 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/lateral_005fnavigation.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/load_005fhandler.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/map_005fsink.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/multiple_005fmenus.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/multiple_005fpages.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/navigation.html | | | 153 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/node_005fnames.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/node_005ftype.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/nomenclature.html | | | 66 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/overview.html | | | 52 | ++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/render.html | | | 331 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/render_005fmulti.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/signals.html | | | 89 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/build/symbol_005ftype.html | | | 24 | ++++++++++++++++++++++++ |
| A | doc/build/tools.html | | | 150 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
26 files changed, 2723 insertions(+), 0 deletions(-)
diff --git a/doc/build/builtin_005fflags.html b/doc/build/builtin_005fflags.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>builtin_flags (vise)</title> + +<meta name="description" content="builtin_flags (vise)"> +<meta name="keywords" content="builtin_flags (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=signals.html#builtin_005fflags"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="signals.html#builtin_005fflags">builtin_flags</a>.</p> +</body> diff --git a/doc/build/cache.html b/doc/build/cache.html @@ -0,0 +1,141 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>cache (vise)</title> + +<meta name="description" content="cache (vise)"> +<meta name="keywords" content="cache (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="render.html" rel="next" title="render"> +<link href="navigation.html" rel="prev" title="navigation"> +<style type="text/css"> +<!-- +ul.mark-bullet {list-style-type: disc} +--> +</style> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="cache"> +<div class="nav-panel"> +<p> +Next: <a href="render.html" accesskey="n" rel="next">Rendering</a>, Previous: <a href="navigation.html" accesskey="p" rel="prev">Navigation</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="External-data">6 External data</h2> + +<p>The <code class="code">LOAD</code> instruction enables the client implementer to define external data retrieval and processing code. +</p> +<p>It can be used to: +</p> +<ul class="itemize mark-bullet"> +<li>Query and store data +</li><li>Alter the menu execution flow +</li><li>Change language +</li></ul> + + +<a class="anchor" id="load_005fhandler"></a><ul class="mini-toc"> +<li><a href="#The-LOAD-handler" accesskey="1">The <code class="code">LOAD</code> handler</a></li> +<li><a href="#Size-limits" accesskey="2">Size limits</a></li> +<li><a href="#Scope" accesskey="3">Scope</a></li> +<li><a href="#Refreshing-cache-contents" accesskey="4">Refreshing cache contents</a></li> +</ul> +<div class="section-level-extent" id="The-LOAD-handler"> +<h3 class="section">6.1 The <code class="code">LOAD</code> handler</h3> + +<p>In the <em class="emph">golang</em> code, the handler of the <code class="code">LOAD</code> instruction is an implementation of the <code class="code">resource.Resource</code> interface. +</p> +<p>It uses the method <code class="code">resource.Resource.FuncFor</code> to return a function pointer of type <code class="code">resource.EntryFunc</code> that can resolve the symbol. +</p> +<p>The <code class="code">resource.Result</code> value that it returns has the following capabilities: +</p> +<ul class="itemize mark-bullet"> +<li>Returned data payload (can be empty). +</li><li>A client-defined status code. +</li><li>A list of client-defined signal flags to <em class="emph">set</em>. +</li><li>A list of client-defined signal flags to <em class="emph">unset</em>. +</li></ul> + + +</div> +<div class="section-level-extent" id="Size-limits"> +<h3 class="section">6.2 Size limits</h3> + +<p><code class="code">LOAD</code> instructions include a size parameter. +</p> +<p>This indicates the maximum byte size of the result that will be allowed. +</p> +<p>If the returned data payload exceeds this size, execution will terminate. +</p> + +<ul class="mini-toc"> +<li><a href="#g_t_0022Sink_0022-symbols" accesskey="1">"Sink" symbols</a></li> +</ul> +<div class="subsection-level-extent" id="g_t_0022Sink_0022-symbols"> +<h4 class="subsection">6.2.1 "Sink" symbols</h4> + +<p>A sink is a symbol loaded with <code class="code">size</code> parameter <code class="code">0</code>. +</p> +<p>This allows the contents to expand to all remaining available space when rendering a template. See <a class="ref" href="render.html#dynamic_005ftemplates">Dynamic templates</a> for details. +</p> + +</div> +</div> +<div class="section-level-extent" id="Scope"> +<h3 class="section">6.3 Scope</h3> + +<p>The result data payload is stored under the symbol key for which it was loaded. It is kept in the cache until execution ascends from the execution stack level in which it was loaded. +</p> +<p>Consider the symbol <code class="code">foo</code> loaded at node <samp class="file">root/one/two</samp>. The symbol will still remain available in cache for e.g. node <samp class="file">root/one/two/three</samp>, but will be freed when entering <samp class="file">root/one</samp>. +</p> + +<ul class="mini-toc"> +<li><a href="#Duplicate-LOAD" accesskey="1">Duplicate <code class="code">LOAD</code></a></li> +</ul> +<div class="subsection-level-extent" id="Duplicate-LOAD"> +<h4 class="subsection">6.3.1 Duplicate <code class="code">LOAD</code></h4> + +<p>If a <code class="code">LOAD</code> statement with the same symbol is issued twice within the same <em class="emph">scope</em>, it will fail and execution will terminate. +</p> +<p>If a <code class="code">LOAD</code> statement with the same symbol is issued twice in the same <em class="emph">node</em>, the latter will be ignored. +</p> +<p>For example, if <code class="code">LOAD</code> is called on node <samp class="file">foo/bar</samp>, then execution descends to <samp class="file">foo/bar/baz</samp> before returning to <samp class="file">foo/bar</samp>, the second time the <code class="code">LOAD</code> statement is encountered in <samp class="file">foo/bar</samp> will have no effect. +</p> +<p>However, if <code class="code">LOAD</code> is called on node <samp class="file">foo/bar/baz</samp>, then execution ascends to <samp class="file">foo/bar</samp> before returning to <samp class="file">foo/bar/baz</samp>, the <code class="code">LOAD</code> will be executed again. +</p> + +</div> +</div> +<div class="section-level-extent" id="Refreshing-cache-contents"> +<h3 class="section">6.4 Refreshing cache contents</h3> + +<p>The <code class="code">RELOAD</code> instruction will trigger the <code class="code">LOAD</code> handler again. The <code class="code">RELOAD</code> instruction is bound to the same size constraint as the initial <code class="code">LOAD</code>. +</p> +<p>It is not possible for the handler code to distinguish between a <code class="code">LOAD</code> and a <code class="code">RELOAD</code> instruction. +</p> +<p>Note that using <code class="code">RELOAD</code> when rendering multi-page menus can have unpredictable consequences for the lateral navigation state. +</p></div> +</div> +<hr> +<div class="nav-panel"> +<p> +Next: <a href="render.html">Rendering</a>, Previous: <a href="navigation.html">Navigation</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> + + + +</body> +</html> diff --git a/doc/build/cookbook.html b/doc/build/cookbook.html @@ -0,0 +1,227 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>cookbook (vise)</title> + +<meta name="description" content="cookbook (vise)"> +<meta name="keywords" content="cookbook (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="dev.html" rel="next" title="dev"> +<link href="language.html" rel="prev" title="language"> +<style type="text/css"> +<!-- +div.example {margin-left: 3.2em} +ul.mark-bullet {list-style-type: disc} +--> +</style> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="cookbook"> +<div class="nav-panel"> +<p> +Next: <a href="dev.html" accesskey="n" rel="next">Developing with vise</a>, Previous: <a href="language.html" accesskey="p" rel="prev">Handling languages</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="Common-patterns">9 Common patterns</h2> + + +<ul class="mini-toc"> +<li><a href="#Hello-world" accesskey="1">Hello world</a></li> +<li><a href="#Handling-menus-and-inputs" accesskey="2">Handling menus and inputs</a></li> +<li><a href="#Signal-flow-control" accesskey="3">Signal flow control</a></li> +<li><a href="#Multiple-pages" accesskey="4">Multiple pages</a></li> +<li><a href="#Multi_002dpage-menus" accesskey="5">Multi-page menus</a></li> +<li><a href="#Default-input-handler" accesskey="6">Default input handler</a></li> +</ul> +<div class="section-level-extent" id="Hello-world"> +<h3 class="section">9.1 Hello world</h3> + +<div class="example"> +<pre class="example-preformatted">HALT +</pre></div> + +<p>Will render a template without any external symbols and terminate execution immediately. +</p> + +<a class="anchor" id="handling_005fmenus"></a></div> +<div class="section-level-extent" id="Handling-menus-and-inputs"> +<h3 class="section">9.2 Handling menus and inputs</h3> + +<div class="example"> +<pre class="example-preformatted">MOUT to_foo 0 +MOUT to_bar 1 +MOUT upup 2 +HALT +INCMP foo 0 +INCMP bar 1 +INCMP _ 2 +</pre></div> + +<p>Create three menu items, resolving the menu symbols <code class="code">to_foo</code>, <code class="code">to_bar</code> and <code class="code">upup</code> respectively to translated text and pairing with the selectors. +</p> +<p>Yield for client input. Then attempt to match input to selectors: +</p> +<ul class="itemize mark-bullet"> +<li>if selector is <code class="code">0</code>, execute node <code class="code">foo</code>. +</li><li>if selector is <code class="code">1</code>, execute node <code class="code">bar</code>. +</li><li>if selector is <code class="code">2</code>, execute previous node in stack. +</li></ul> + + +<ul class="mini-toc"> +<li><a href="#Menu-batch-version" accesskey="1">Menu batch version</a></li> +</ul> +<div class="subsection-level-extent" id="Menu-batch-version"> +<h4 class="subsection">9.2.1 Menu batch version</h4> + +<div class="example"> +<pre class="example-preformatted">DOWN foo 0 to_foo +DOWN bar 1 to_bar +UP 2 upup +</pre></div> + +<p>This example produces exactly the same bytecode result as the <a class="ref" href="#handling_005fmenus">previous example</a>. +</p> + +</div> +</div> +<div class="section-level-extent" id="Signal-flow-control"> +<h3 class="section">9.3 Signal flow control</h3> + +<div class="example"> +<pre class="example-preformatted">LOAD foo 1 +CATCH bar 8 1 +MOVE baz +</pre></div> + +<p>If loading the external symbol <code class="code">foo</code> sets the flag <code class="code">8</code>, then immediately move to <code class="code">bar</code>. +</p> +<p>Otherwise, move to <code class="code">baz</code>. +</p> + +<a class="anchor" id="multiple_005fpages"></a></div> +<div class="section-level-extent" id="Multiple-pages"> +<h3 class="section">9.4 Multiple pages</h3> + +<div class="example"> +<pre class="example-preformatted">LOAD foo 0 +MNEXT to_fwd 11 +MPREV to_back 22 +HALT +INCMP > 11 +INCMP < 22 +</pre></div> + +<p>Load external symbol <code class="code">foo</code> as a <em class="emph">sink</em>. +</p> +<p>If content spans multiple pages, resolve <code class="code">to_fwd</code> and <code class="code">to_back</code> as labels for lateral navigation options in the menu. +</p> +<p>Also handle the lateral navigation inputs. +</p> +<ul class="mini-toc"> +<li><a href="#Menu-batch-version-1" accesskey="1">Menu batch version</a></li> +</ul> +<div class="subsection-level-extent" id="Menu-batch-version-1"> +<h4 class="subsection">9.4.1 Menu batch version</h4> + +<div class="example"> +<pre class="example-preformatted">LOAD foo 0 +NEXT 11 to_fwd +PREVIOUS 22 to_back +</pre></div> + +<p>This example produces exactly the same bytecode result as the <a class="ref" href="#multiple_005fpages">previous example</a>. +</p> + +<a class="anchor" id="multiple_005fmenus"></a></div> +</div> +<div class="section-level-extent" id="Multi_002dpage-menus"> +<h3 class="section">9.5 Multi-page menus</h3> + +<div class="example"> +<pre class="example-preformatted">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 +</pre></div> + +<p>Enable splitting menu over several pages, and route all valid inputs to the <code class="code">foo</code> node, except for <code class="code">7</code> which is routed to the <code class="code">bar</code> node. +</p> + +<ul class="mini-toc"> +<li><a href="#Menu-batch-version-2" accesskey="1">Menu batch version</a></li> +</ul> +<div class="subsection-level-extent" id="Menu-batch-version-2"> +<h4 class="subsection">9.5.1 Menu batch version</h4> + +<div class="example"> +<pre class="example-preformatted">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 +</pre></div> + +<p>This example produces exactly the same bytecode result as the <a class="ref" href="#multiple_005fmenus">previous example</a>. +</p> + +</div> +</div> +<div class="section-level-extent" id="Default-input-handler"> +<h3 class="section">9.6 Default input handler</h3> + +<div class="example"> +<pre class="example-preformatted">MOUT to_foo 0 +HALT +INCMP foo 0 +INCMP bar * +</pre></div> + +<p>If input is <code class="code">0</code>, route to the <code class="code">foo</code>. Any other input will route to the <code class="code">bar</code> node. +</p></div> +</div> +<hr> +<div class="nav-panel"> +<p> +Next: <a href="dev.html">Developing with vise</a>, Previous: <a href="language.html">Handling languages</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> + + + +</body> +</html> diff --git a/doc/build/dev.html b/doc/build/dev.html @@ -0,0 +1,437 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>dev (vise)</title> + +<meta name="description" content="dev (vise)"> +<meta name="keywords" content="dev (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="cookbook.html" rel="prev" title="cookbook"> +<style type="text/css"> +<!-- +div.example {margin-left: 3.2em} +ul.mark-bullet {list-style-type: disc} +--> +</style> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="dev"> +<div class="nav-panel"> +<p> +Previous: <a href="cookbook.html" accesskey="p" rel="prev">Common patterns</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="Developing-with-vise">10 Developing with vise</h2> + + +<ul class="mini-toc"> +<li><a href="#Code-repository-structure" accesskey="1">Code repository structure</a></li> +<li><a href="#Interacting-with-vise" accesskey="2">Interacting with <code class="code">vise</code></a></li> +<li><a href="#Resolving-resources" accesskey="3">Resolving resources</a></li> +<li><a href="#Logging" accesskey="4">Logging</a></li> +<li><a href="#Tools" accesskey="5">Tools</a></li> +<li><a href="#Assembly-examples" accesskey="6">Assembly examples</a></li> +<li><a href="#Bytecode-example" accesskey="7">Bytecode example</a></li> +</ul> +<div class="section-level-extent" id="Code-repository-structure"> +<h3 class="section">10.1 Code repository structure</h3> + +<dl class="table"> +<dt><code class="code">asm</code></dt> +<dd><p>Assembly parser and compiler. +</p></dd> +<dt><code class="code">cache</code></dt> +<dd><p>Holds and manages all loaded content. +</p></dd> +<dt><code class="code">engine</code></dt> +<dd><p>Outermost interface. Orchestrates execution of bytecode against input. +</p></dd> +<dt><code class="code">lang</code></dt> +<dd><p>Validation and specification of language context. +</p></dd> +<dt><code class="code">logging</code></dt> +<dd><p>Logging interface and build tags for loglevels. +</p></dd> +<dt><code class="code">persist</code></dt> +<dd><p>Interface and reference implementation of ‘state‘ and ‘cache‘ persistence across asynchronous vm executions. +</p></dd> +<dt><code class="code">render</code></dt> +<dd><p>Renders menu and templates, and enforces output size constraints. +</p></dd> +<dt><code class="code">resource</code></dt> +<dd><p>Retrieves data and bytecode from external symbols, and retrieves templates. +</p></dd> +<dt><code class="code">state</code></dt> +<dd><p>Holds the bytecode buffer, error states and navigation states. +</p></dd> +<dt><code class="code">vm</code></dt> +<dd><p>Defines instructions, and applies transformations according to the instructions. +</p></dd> +</dl> + + +</div> +<div class="section-level-extent" id="Interacting-with-vise"> +<h3 class="section">10.2 Interacting with <code class="code">vise</code></h3> + +<p>Implementers of <code class="code">vise</code> should interface with the system using the <code class="code">engine</code> module. +</p> +<p>The engine comes in two implementations, one volatile base implemetnation and a subclass that includes persistent state. +</p> + +<ul class="mini-toc"> +<li><a href="#Modes-of-operation" accesskey="1">Modes of operation</a></li> +<li><a href="#Configuration" accesskey="2">Configuration</a></li> +<li><a href="#Sessions" accesskey="3">Sessions</a></li> +<li><a href="#Execution-context" accesskey="4">Execution context</a></li> +</ul> +<div class="subsection-level-extent" id="Modes-of-operation"> +<h4 class="subsection">10.2.1 Modes of operation</h4> + +<p>The <code class="code">engine</code> module provides three different modes of operation for the engine implementations. +</p> + +<ul class="mini-toc"> +<li><a href="#Manual-operation" accesskey="1">Manual operation</a></li> +<li><a href="#Synchronous-loop" accesskey="2">Synchronous loop</a></li> +<li><a href="#Asynchronous-one_002dshot" accesskey="3">Asynchronous one-shot</a></li> +</ul> +<div class="subsubsection-level-extent" id="Manual-operation"> +<h4 class="subsubsection">10.2.1.1 Manual operation</h4> + +<p>Directly interaction with an <code class="code">engine.Engine</code> instance. +</p> +<p>The engine is manually initialized, and execution must be explicitly triggered with input every time the VM yields control. +</p> +<p>Output flushing must also be operated manually. +</p> +<p>The interface is the same for both persistent and volatile operation. +</p> + +</div> +<div class="subsubsection-level-extent" id="Synchronous-loop"> +<h4 class="subsubsection">10.2.1.2 Synchronous loop</h4> + +<p>Receives input from a reader and writes into to a writer, and executes the underlying <code class="code">engine.Engine</code> with given inputs until execution is terminated. +</p> +<p>The loop may be either persistent or volatile. +</p> +<p>This mode drives the interactive driver execution tool. +</p> + +</div> +<div class="subsubsection-level-extent" id="Asynchronous-one_002dshot"> +<h4 class="subsubsection">10.2.1.3 Asynchronous one-shot</h4> + +<p>Compatible with e.g. a network socket or HTTP frontend. The <code class="code">engine.RunPersisted</code> method restores a persisted state and runs one single input until VM yield after which the new state is persisted. +</p> +<p>This mode of operation can only be used with persistent state. +</p> + +</div> +</div> +<div class="subsection-level-extent" id="Configuration"> +<h4 class="subsection">10.2.2 Configuration</h4> + +<p>The engine configuration defines the top-level parameters for the execution environment, including maximum output size, default language, execution entry point and more. +</p> +<p>Please refer to <code class="code">engine.Config</code> for details. +</p> + +</div> +<div class="subsection-level-extent" id="Sessions"> +<h4 class="subsection">10.2.3 Sessions</h4> + +<p>The <code class="code">engine.Config.SessionId</code> is used to disambiguate the end-user that is interacting with the engine. +</p> +<p>For example, in a <abbr class="abbr">USSD</abbr> context, the <code class="code">SessionId</code> may be the <em class="emph">phone number</em> of the end-user. +</p> + +<a class="anchor" id="execution_005fcontext"></a></div> +<div class="subsection-level-extent" id="Execution-context"> +<h4 class="subsection">10.2.4 Execution context</h4> + +<p>The engine stores the <code class="code">SessionId</code> aswell as the current chosen <code class="code">lang.Language</code> in the execution context. This is passed through to the VM operation, and is available for client code, specifically: +</p> +<ul class="itemize mark-bullet"> +<li>When resolving symbols with <code class="code">LOAD</code>. (<code class="code">resource.EntryFunc</code>). +</li><li>When resolving menu symbols (<code class="code">resource.Resource.GetMenu</code>). +</li><li>When retrieving node templates (<code class="code">resource.Resource.GetTemplate</code>). +</li></ul> + + +</div> +</div> +<div class="section-level-extent" id="Resolving-resources"> +<h3 class="section">10.3 Resolving resources</h3> + +<p>The core of implementation code is defined by implementing the <code class="code">resource.Resource</code> interface. This is also described in the <a class="ref" href="cache.html#load_005fhandler">LOAD handler</a> section. +</p> +<p>In addition to resolving external code symbols, <code class="code">resource.Resource</code> implementations also translate <em class="emph">menu labels</em> and <em class="emph">templates</em> based on the current language context, and retrieves bytecode for execution nodes. +</p> +<ul class="mini-toc"> +<li><a href="#Memory-resource-implementation" accesskey="1">Memory resource implementation</a></li> +<li><a href="#Filesystem-resource-implementation" accesskey="2">Filesystem resource implementation</a></li> +</ul> +<div class="subsection-level-extent" id="Memory-resource-implementation"> +<h4 class="subsection">10.3.1 Memory resource implementation</h4> + +<p>One of two reference implementations of <code class="code">resource.Resource</code> is the <code class="code">resource.MemResource</code> class. It enables the client to register all node and symbol resolutions at runtime, using its functions prefixed with <code class="code">Add...</code>. +</p> +<p>The <code class="code">resource.MemResource</code> implementation is primarily useful for use in tests. +</p> + +</div> +<div class="subsection-level-extent" id="Filesystem-resource-implementation"> +<h4 class="subsection">10.3.2 Filesystem resource implementation</h4> + +<p>The Filesystem based resource implemementation is used by the <code class="code">dev/interactive</code> tool, aswell as the executable examples in <samp class="file">examples/</samp> directory. +</p> +<p>It is instantiated with a base directory location relative to which all resources are read. +</p> + +<ul class="mini-toc"> +<li><a href="#Bytecode-_0028resource_002eResource_002eGetCode_0029" accesskey="1">Bytecode (<code class="code">resource.Resource.GetCode</code>)</a></li> +<li><a href="#Templates-_0028resource_002eResource_002eGetTemplate_0029" accesskey="2">Templates (<code class="code">resource.Resource.GetTemplate</code>)</a></li> +<li><a href="#Menus-_0028resource_002eResource_002eGetMenu_0029" accesskey="3">Menus (<code class="code">resource.Resource.GetMenu</code>)</a></li> +<li><a href="#External-symbols-_0028resource_002eResource_002eFuncFor_0029" accesskey="4">External symbols (<code class="code">resource.Resource.FuncFor</code>)</a></li> +</ul> +<div class="subsubsection-level-extent" id="Bytecode-_0028resource_002eResource_002eGetCode_0029"> +<h4 class="subsubsection">10.3.2.1 Bytecode (<code class="code">resource.Resource.GetCode</code>)</h4> + +<p>Read from <samp class="file">basedir/<node>.bin</samp>. +</p> + +</div> +<div class="subsubsection-level-extent" id="Templates-_0028resource_002eResource_002eGetTemplate_0029"> +<h4 class="subsubsection">10.3.2.2 Templates (<code class="code">resource.Resource.GetTemplate</code>)</h4> + +<p>If language has been set, the template will be read from <samp class="file">basedir/<node>_<lang></samp>. For example, the <em class="emph">norwegian</em> template for the node <code class="code">root</code> will be read from <samp class="file">basedir/root_nor</samp>. +</p> +<p>If reading the language specific template fails (or if no language has been set), template will be read from <samp class="file">basedir/<node></samp>. +</p> +<p>A missing template file will result in load failure and program termination. +</p> + +</div> +<div class="subsubsection-level-extent" id="Menus-_0028resource_002eResource_002eGetMenu_0029"> +<h4 class="subsubsection">10.3.2.3 Menus (<code class="code">resource.Resource.GetMenu</code>)</h4> + +<p>If language has been set, the template will be read from <samp class="file">basedir/<label>_<lang>_menu</samp>. For example, the <em class="emph">norwegian</em> template for the menu label <code class="code">foo</code> will be read from <samp class="file">basedir/foo_nor_menu</samp>. +</p> +<p>If reading the language specific menu label fails (or if no language has been set), label will be read from <samp class="file">basedir/<label>_menu</samp>. +</p> +<p>If this also fails, the implementation returns the original label used for lookup. +</p> + +</div> +<div class="subsubsection-level-extent" id="External-symbols-_0028resource_002eResource_002eFuncFor_0029"> +<h4 class="subsubsection">10.3.2.4 External symbols (<code class="code">resource.Resource.FuncFor</code>)</h4> + +<p>The implementation allows setting resolver functions for symbols at runtime, using the <code class="code">resource.FsResource.AddLocalFunc</code> method. This registers an <code class="code">resource.FsResource.EntryFunc</code> with the lookup symbol as key. Note that the <code class="code">EntryFunc</code> receives the language setting through the execution context. +</p> +<p>If no function has been registered for the requested symbol, it will be looked up in the filesystem on <samp class="file">basedir/<symbol>_<lang>.txt</samp>. For example, the <em class="emph">norwegian</em> entry for the symbol <code class="code">foo</code> will be read from <samp class="file">basedir/foo_nor.txt</samp>. +</p> +<p>If reading the language specific entry fails (or if no language has been set), entry will be read from <samp class="file">basedir/<symbol>.txt</samp>. +</p> +<p>A missing entry will result in load failure and program termination. +</p> +<p>The implementation contains no built-in handling of the <code class="code">SessionId</code> supplied by the context. +</p> + +</div> +</div> +</div> +<div class="section-level-extent" id="Logging"> +<h3 class="section">10.4 Logging</h3> + +<p>Loglevels are set at compile-time using the following build tags: +</p> +<ul class="itemize mark-bullet"> +<li><code class="code">lognone</code> +</li><li><code class="code">logerror</code> +</li><li><code class="code">logwarn</code> +</li><li><code class="code">loginfo</code> +</li><li><code class="code">logdebug</code> +</li><li><code class="code">logtrace</code> +</li></ul> + +<p>Only use <strong class="strong">ONE</strong> of these tags. +</p> +<p>The default tag is <code class="code">lognone</code> which disables logging completely. +</p> +<p><code class="code">logging.Logger</code> defines the logging interface. It is faintly inspired by the experimental <a class="url" href="https://pkg.go.dev/golang.org/x/exp/slog)%20package">slog</a>. +</p> + +</div> +<div class="section-level-extent" id="Tools"> +<h3 class="section">10.5 Tools</h3> + +<p>Located in the <samp class="file">dev/</samp> directory of the source code repository. +</p> + +<ul class="mini-toc"> +<li><a href="#Test-data-generation" accesskey="1">Test data generation</a></li> +<li><a href="#Interactive-runner" accesskey="2">Interactive runner</a></li> +<li><a href="#Assembler" accesskey="3">Assembler</a></li> +<li><a href="#Disassembler" accesskey="4">Disassembler</a></li> +<li><a href="#Interactive-case-examples" accesskey="5">Interactive case examples</a></li> +</ul> +<div class="subsection-level-extent" id="Test-data-generation"> +<h4 class="subsection">10.5.1 Test data generation</h4> + +<div class="example"> +<pre class="example-preformatted">go run ./dev/gendata/ <directory> +</pre></div> + +<p>Outputs bytecodes and templates for test data scenarios used in ‘engine‘ unit tests. +</p> + +</div> +<div class="subsection-level-extent" id="Interactive-runner"> +<h4 class="subsection">10.5.2 Interactive runner</h4> + +<div class="example"> +<pre class="example-preformatted">go run ./dev/interactive [-d <data_directory>] [--root <root_symbol>] [--session-id <session_id>] [--persist] +</pre></div> + +<p>Creates a new interactive session using <code class="code">engine.DefaultEngine</code>, starting execution at symbol <code class="code">root_symbol</code> +</p> +<p><code class="code">data_directory</code> points to a directory where templates and bytecode is to be found (in the same format as generated by <samp class="file">dev/gendata</samp>). +</p> +<p>If <code class="code">data_directory</code> is not set, current directory will be used. +</p> +<p>if <code class="code">root_symbol</code> is not set, the symbol <code class="code">root</code> will be used. +</p> +<p>if <code class="code">session_id</code> is set, mutable data will be stored and retrieved keyed by the given identifer (if implemented). +</p> +<p>If <code class="code">persist</code> is set, the execution state will be persisted across sessions. +</p> + +</div> +<div class="subsection-level-extent" id="Assembler"> +<h4 class="subsection">10.5.3 Assembler</h4> + +<div class="example"> +<pre class="example-preformatted">go run ./dev/asm <assembly_file> +</pre></div> + +<p>Will output bytecode on STDOUT generated from a valid assembly file. +</p> + +</div> +<div class="subsection-level-extent" id="Disassembler"> +<h4 class="subsection">10.5.4 Disassembler</h4> + +<div class="example"> +<pre class="example-preformatted">go run ./dev/disasm/ <binary_file> +</pre></div> + +<p>Will list all the instructions on STDOUT from a valid binary file. +</p> + +</div> +<div class="subsection-level-extent" id="Interactive-case-examples"> +<h4 class="subsection">10.5.5 Interactive case examples</h4> + +<p>Found in <samp class="file">examples/</samp>. +</p> +<p>Be sure to <code class="code">make examples</code> before running them. +</p> +<p>Can be run with: +</p> +<div class="example"> +<pre class="example-preformatted">go run ./examples/<case> [...] +</pre></div> + +<p>except helloworld which is run as +</p> +<div class="example"> +<pre class="example-preformatted">go run ./dev/interactive -d ./examples/helloworld [...] +</pre></div> + +<p>The available options are the same as for the <samp class="file">dev/interactive</samp> tool. +</p> +<p>Contents of the case directory: +</p> +<dl class="table"> +<dt><samp class="file">*.vis</samp></dt> +<dd><p>assembly code. +</p></dd> +<dt><samp class="file">*.bin</samp></dt> +<dd><p>bytecode for each node symbol (only available after make). +</p></dd> +<dt><samp class="file">*.txt.orig</samp></dt> +<dd><p>default contents of a single data entry. +</p></dd> +<dt><samp class="file">*.txt</samp></dt> +<dd><p>current contents of a single data entry (only available after make). +</p></dd> +</dl> + + +</div> +</div> +<div class="section-level-extent" id="Assembly-examples"> +<h3 class="section">10.6 Assembly examples</h3> + +<p>See <samp class="file">testdata/*.vis</samp> +</p> + +</div> +<div class="section-level-extent" id="Bytecode-example"> +<h3 class="section">10.7 Bytecode example</h3> + +<p>Currently the following rules apply for encoding in version <code class="code">0</code>: +</p> +<ul class="itemize mark-bullet"> +<li>A code instruction is a <em class="emph">big-endian</em> 2-byte value. See <samp class="file">vm/opcodes.go</samp> for valid opcode values. +</li><li><code class="code">symbol</code> value is encoded as <em class="emph">one byte</em> of string length, after which the byte-value of the string follows. +</li><li><code class="code">size</code> value is encoded as <em class="emph">one byte</em> of numeric length, after which the <em class="emph">big-endian</em> byte-value of the integer follows. +</li><li><code class="code">signal</code> value is encoded as <em class="emph">one byte</em> of byte length, after which a byte-array representing the defined signal follows. +</li></ul> + + +<ul class="mini-toc"> +<li><a href="#Example" accesskey="1">Example</a></li> +</ul> +<div class="subsection-level-extent" id="Example"> +<h4 class="subsection">10.7.1 Example</h4> + +<p>(Minimal, WIP) +</p> +<pre class="verbatim">000a 03666f6f 05746f666f6f # MOUT tofoo foo - display a menu entry for choice "foo", described by "to foo" +0008 03666f6f 03626172 # INCMP bar foo - move to node "bar" if input is "FOO" +0001 0461696565 01 01 # CATCH aiee 1 1 - move to node "aiee" (and immediately halt) if input match flag (1) is not set (1) +0003 04616263 020104 # LOAD abc 260 - execute code symbol "abc" with a result size limit of 260 (2 byte BE integer, 0x0104) +0003 04646566 00 # LOAD def 0 - execute code symbol "abc" with no size limit (sink) +0005 04616263 # MAP abc - make "abc" available for renderer +0007 # HALT - stop execution (require new input to continue) +0006 0461313233 # MOVE a123 - move to node "a123" (regardless of input) +0007 # HALT - stop execution +</pre></div> +</div> +</div> +<hr> +<div class="nav-panel"> +<p> +Previous: <a href="cookbook.html">Common patterns</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> + + + +</body> +</html> diff --git a/doc/build/dynamic_005ftemplates.html b/doc/build/dynamic_005ftemplates.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>dynamic_templates (vise)</title> + +<meta name="description" content="dynamic_templates (vise)"> +<meta name="keywords" content="dynamic_templates (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=render.html#dynamic_005ftemplates"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="render.html#dynamic_005ftemplates">dynamic_templates</a>.</p> +</body> diff --git a/doc/build/engine.html b/doc/build/engine.html @@ -0,0 +1,134 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>engine (vise)</title> + +<meta name="description" content="engine (vise)"> +<meta name="keywords" content="engine (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="language.html" rel="next" title="language"> +<link href="render.html" rel="prev" title="render"> +<style type="text/css"> +<!-- +ul.mark-bullet {list-style-type: disc} +--> +</style> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="engine"> +<div class="nav-panel"> +<p> +Next: <a href="language.html" accesskey="n" rel="next">Handling languages</a>, Previous: <a href="render.html" accesskey="p" rel="prev">Rendering</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="Using-vise">8 Using vise</h2> + +<p>Implementers of <code class="code">vise</code> should interface with the system using the <code class="code">engine</code> module. +</p> +<p>The engine comes in two implementations, one volatile base implemetnation and a subclass that includes persistent state. +</p> + +<ul class="mini-toc"> +<li><a href="#Modes-of-operation" accesskey="1">Modes of operation</a></li> +<li><a href="#Configuration" accesskey="2">Configuration</a></li> +<li><a href="#Sessions" accesskey="3">Sessions</a></li> +<li><a href="#Execution-context" accesskey="4">Execution context</a></li> +</ul> +<div class="section-level-extent" id="Modes-of-operation"> +<h3 class="section">8.1 Modes of operation</h3> + +<p>The <code class="code">engine</code> module provides three different modes of operation for the engine implementations. +</p> + +<ul class="mini-toc"> +<li><a href="#Manual-operation" accesskey="1">Manual operation</a></li> +<li><a href="#Synchronous-loop" accesskey="2">Synchronous loop</a></li> +<li><a href="#Asynchronous-one_002dshot" accesskey="3">Asynchronous one-shot</a></li> +</ul> +<div class="subsection-level-extent" id="Manual-operation"> +<h4 class="subsection">8.1.1 Manual operation</h4> + +<p>Directly interaction with an <code class="code">engine.Engine</code> instance. +</p> +<p>The engine is manually initialized, and execution must be explicitly triggered with input every time the VM yields control. +</p> +<p>Output flushing must also be operated manually. +</p> +<p>The interface is the same for both persistent and volatile operation. +</p> + +</div> +<div class="subsection-level-extent" id="Synchronous-loop"> +<h4 class="subsection">8.1.2 Synchronous loop</h4> + +<p>Receives input from a reader and writes into to a writer, and executes the underlying <code class="code">engine.Engine</code> with given inputs until execution is terminated. +</p> +<p>The loop may be either persistent or volatile. +</p> +<p>This mode drives the interactive driver execution tool. +</p> + +</div> +<div class="subsection-level-extent" id="Asynchronous-one_002dshot"> +<h4 class="subsection">8.1.3 Asynchronous one-shot</h4> + +<p>Compatible with e.g. a network socket or HTTP frontend. The <code class="code">engine.RunPersisted</code> method restores a persisted state and runs one single input until VM yield after which the new state is persisted. +</p> +<p>This mode of operation can only be used with persistent state. +</p> + +</div> +</div> +<div class="section-level-extent" id="Configuration"> +<h3 class="section">8.2 Configuration</h3> + +<p>The engine configuration defines the top-level parameters for the execution environment, including maximum output size, default language, execution entry point and more. +</p> +<p>Please refer to <code class="code">engine.Config</code> for details. +</p> + +</div> +<div class="section-level-extent" id="Sessions"> +<h3 class="section">8.3 Sessions</h3> + +<p>The <code class="code">engine.Config.SessionId</code> is used to disambiguate the end-user that is interacting with the engine. +</p> +<p>For example, in a <abbr class="abbr">USSD</abbr> context, the <code class="code">SessionId</code> may be the <em class="emph">phone number</em> of the end-user. +</p> + +<a class="anchor" id="execution_005fcontext"></a></div> +<div class="section-level-extent" id="Execution-context"> +<h3 class="section">8.4 Execution context</h3> + +<p>The engine stores the <code class="code">SessionId</code> aswell as the current chosen <code class="code">lang.Language</code> in the execution context. This is passed through to the VM operation, and is available for client code, specifically: +</p> +<ul class="itemize mark-bullet"> +<li>When resolving symbols with <code class="code">LOAD</code>. (<code class="code">resource.EntryFunc</code>). +</li><li>When resolving menu symbols (<code class="code">resource.Resource.GetMenu</code>). +</li><li>When retrieving node templates (<code class="code">resource.Resource.GetTemplate</code>). +</li></ul> +</div> +</div> +<hr> +<div class="nav-panel"> +<p> +Next: <a href="language.html">Handling languages</a>, Previous: <a href="render.html">Rendering</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> + + + +</body> +</html> diff --git a/doc/build/execution_005fcontext.html b/doc/build/execution_005fcontext.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>execution_context (vise)</title> + +<meta name="description" content="execution_context (vise)"> +<meta name="keywords" content="execution_context (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=dev.html#execution_005fcontext"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="dev.html#execution_005fcontext">execution_context</a>.</p> +</body> diff --git a/doc/build/handling_005fmenus.html b/doc/build/handling_005fmenus.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>handling_menus (vise)</title> + +<meta name="description" content="handling_menus (vise)"> +<meta name="keywords" content="handling_menus (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=cookbook.html#handling_005fmenus"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="cookbook.html#handling_005fmenus">handling_menus</a>.</p> +</body> diff --git a/doc/build/index.html b/doc/build/index.html @@ -0,0 +1,222 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>Top (vise)</title> + +<meta name="description" content="Top (vise)"> +<meta name="keywords" content="Top (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="#Top" rel="start" title="Top"> +<link href="#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="overview.html" rel="next" title="overview"> +<style type="text/css"> +<!-- +ul.toc-numbered-mark {list-style: none} +--> +</style> + + +</head> + +<body lang="en"> + + + + +<div class="top-level-extent" id="Top"> +<div class="nav-panel"> +<p> +Next: <a href="overview.html" accesskey="n" rel="next">Overview</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h1 class="top" id="Introduction">Introduction</h1> + +<div class="element-contents" id="SEC_Contents"> +<h2 class="contents-heading">Table of Contents</h2> + +<div class="contents"> + +<ul class="toc-numbered-mark"> + <li><a id="toc-Overview" href="overview.html">1 Overview</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Synopsis" href="overview.html#Synopsis">1.1 Synopsis</a></li> + </ul></li> + <li><a id="toc-Nomenclature" href="nomenclature.html">2 Nomenclature</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Common" href="nomenclature.html#Common">2.1 Common</a></li> + <li><a id="toc-Instructions-and-navigation" href="nomenclature.html#Instructions-and-navigation">2.2 Instructions and navigation</a></li> + </ul></li> + <li><a id="toc-Signal-flags" href="signals.html">3 Signal flags</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Client_002ddefined-signal-flags" href="signals.html#Client_002ddefined-signal-flags">3.1 Client-defined signal flags</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Flow-control" href="signals.html#Flow-control">3.1.1 Flow control</a></li> + </ul></li> + <li><a id="toc-Built_002din-signal-flags" href="signals.html#Built_002din-signal-flags">3.2 Built-in signal flags</a></li> + </ul></li> + <li><a id="toc-Instructions" href="instructions.html">4 Instructions</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Data-types" href="instructions.html#Data-types">4.1 Data types</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-node" href="instructions.html#node">4.1.1 node</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Regular-node" href="instructions.html#Regular-node">4.1.1.1 Regular node</a></li> + <li><a id="toc-Special-node" href="instructions.html#Special-node">4.1.1.2 Special node</a></li> + </ul></li> + <li><a id="toc-label" href="instructions.html#label">4.1.2 label</a></li> + <li><a id="toc-size" href="instructions.html#size">4.1.3 size</a></li> + <li><a id="toc-selector" href="instructions.html#selector">4.1.4 selector</a></li> + <li><a id="toc-symbol" href="instructions.html#symbol">4.1.5 symbol</a></li> + <li><a id="toc-signal" href="instructions.html#signal">4.1.6 signal</a></li> + <li><a id="toc-matchmode" href="instructions.html#matchmode">4.1.7 matchmode</a></li> + </ul></li> + <li><a id="toc-Instruction-list" href="instructions.html#Instruction-list">4.2 Instruction list</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-CATCH-_003cnode_003e-_003csignal_003e-_003cmatchmode_003e" href="instructions.html#CATCH-_003cnode_003e-_003csignal_003e-_003cmatchmode_003e">4.2.1 CATCH <node> <signal> <matchmode></a></li> + <li><a id="toc-CROAK-_003csignal_003e-_003cmatchmode_003e" href="instructions.html#CROAK-_003csignal_003e-_003cmatchmode_003e">4.2.2 CROAK <signal> <matchmode></a></li> + <li><a id="toc-HALT" href="instructions.html#HALT">4.2.3 HALT</a></li> + <li><a id="toc-INCMP-_003cnode_003e-_003cselector_003e" href="instructions.html#INCMP-_003cnode_003e-_003cselector_003e">4.2.4 INCMP <node> <selector></a></li> + <li><a id="toc-LOAD-_003csymbol_003e-_003csize_003e" href="instructions.html#LOAD-_003csymbol_003e-_003csize_003e">4.2.5 LOAD <symbol> <size></a></li> + <li><a id="toc-MAP-_003csymbol_003e" href="instructions.html#MAP-_003csymbol_003e">4.2.6 MAP <symbol></a></li> + <li><a id="toc-MNEXT-_003clabel_003e-_003cselector_003e" href="instructions.html#MNEXT-_003clabel_003e-_003cselector_003e">4.2.7 MNEXT <label> <selector></a></li> + <li><a id="toc-MOUT-_003clabel_003e-_003cselector_003e" href="instructions.html#MOUT-_003clabel_003e-_003cselector_003e">4.2.8 MOUT <label> <selector></a></li> + <li><a id="toc-MOVE-_003cnode_003e" href="instructions.html#MOVE-_003cnode_003e">4.2.9 MOVE <node></a></li> + <li><a id="toc-MPREV-_003clabel_003e-_003cselector_003e" href="instructions.html#MPREV-_003clabel_003e-_003cselector_003e">4.2.10 MPREV <label> <selector></a></li> + <li><a id="toc-MSINK" href="instructions.html#MSINK">4.2.11 MSINK</a></li> + <li><a id="toc-RELOAD-_003csymbol_003e" href="instructions.html#RELOAD-_003csymbol_003e">4.2.12 RELOAD <symbol></a></li> + </ul></li> + <li><a id="toc-Batch-instructions" href="instructions.html#Batch-instructions">4.3 Batch instructions</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Batch-menu-expansion" href="instructions.html#Batch-menu-expansion">4.3.1 Batch menu expansion</a></li> + </ul></li> + </ul></li> + <li><a id="toc-Navigation" href="navigation.html">5 Navigation</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Entry-point" href="navigation.html#Entry-point">5.1 Entry point</a></li> + <li><a id="toc-Lateral-navigation" href="navigation.html#Lateral-navigation">5.2 Lateral navigation</a></li> + <li><a id="toc-Node-names" href="navigation.html#Node-names">5.3 Node names</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Special-node-names" href="navigation.html#Special-node-names">5.3.1 Special node names</a></li> + <li><a id="toc-Builtin-node-names" href="navigation.html#Builtin-node-names">5.3.2 Builtin node names</a></li> + </ul></li> + <li><a id="toc-Navigation-stack" href="navigation.html#Navigation-stack">5.4 Navigation stack</a></li> + </ul></li> + <li><a id="toc-External-data" href="cache.html">6 External data</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-The-LOAD-handler" href="cache.html#The-LOAD-handler">6.1 The <code class="code">LOAD</code> handler</a></li> + <li><a id="toc-Size-limits" href="cache.html#Size-limits">6.2 Size limits</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-_0022Sink_0022-symbols" href="cache.html#g_t_0022Sink_0022-symbols">6.2.1 "Sink" symbols</a></li> + </ul></li> + <li><a id="toc-Scope" href="cache.html#Scope">6.3 Scope</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Duplicate-LOAD" href="cache.html#Duplicate-LOAD">6.3.1 Duplicate <code class="code">LOAD</code></a></li> + </ul></li> + <li><a id="toc-Refreshing-cache-contents" href="cache.html#Refreshing-cache-contents">6.4 Refreshing cache contents</a></li> + </ul></li> + <li><a id="toc-Rendering" href="render.html">7 Rendering</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Dynamic-templates" href="render.html#Dynamic-templates">7.1 Dynamic templates</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Examples" href="render.html#Examples">7.1.1 Examples</a></li> + </ul></li> + <li><a id="toc-Rendering-pipeline" href="render.html#Rendering-pipeline">7.2 Rendering pipeline</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-No-sink" href="render.html#No-sink">7.2.1 No sink</a></li> + <li><a id="toc-MAP-sink" href="render.html#MAP-sink">7.2.2 MAP sink</a></li> + <li><a id="toc-Menu-sink" href="render.html#Menu-sink">7.2.3 Menu sink</a></li> + </ul></li> + <li><a id="toc-Multiple_002dpage-rendering" href="render.html#Multiple_002dpage-rendering">7.3 Multiple-page rendering</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Missing-navigation" href="render.html#Missing-navigation">7.3.1 Missing navigation</a></li> + <li><a id="toc-Multi_002dpage-example" href="render.html#Multi_002dpage-example">7.3.2 Multi-page example</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Data-accounting" href="render.html#Data-accounting">7.3.2.1 Data accounting</a></li> + <li><a id="toc-Rendering-logic" href="render.html#Rendering-logic">7.3.2.2 Rendering logic</a></li> + </ul></li> + </ul></li> + </ul></li> + <li><a id="toc-Handling-languages" href="language.html">8 Handling languages</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Defining-language" href="language.html#Defining-language">8.1 Defining language</a></li> + </ul></li> + <li><a id="toc-Common-patterns" href="cookbook.html">9 Common patterns</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Hello-world" href="cookbook.html#Hello-world">9.1 Hello world</a></li> + <li><a id="toc-Handling-menus-and-inputs" href="cookbook.html#Handling-menus-and-inputs">9.2 Handling menus and inputs</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Menu-batch-version" href="cookbook.html#Menu-batch-version">9.2.1 Menu batch version</a></li> + </ul></li> + <li><a id="toc-Signal-flow-control" href="cookbook.html#Signal-flow-control">9.3 Signal flow control</a></li> + <li><a id="toc-Multiple-pages" href="cookbook.html#Multiple-pages">9.4 Multiple pages</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Menu-batch-version-1" href="cookbook.html#Menu-batch-version-1">9.4.1 Menu batch version</a></li> + </ul></li> + <li><a id="toc-Multi_002dpage-menus" href="cookbook.html#Multi_002dpage-menus">9.5 Multi-page menus</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Menu-batch-version-2" href="cookbook.html#Menu-batch-version-2">9.5.1 Menu batch version</a></li> + </ul></li> + <li><a id="toc-Default-input-handler" href="cookbook.html#Default-input-handler">9.6 Default input handler</a></li> + </ul></li> + <li><a id="toc-Developing-with-vise" href="dev.html">10 Developing with vise</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Code-repository-structure" href="dev.html#Code-repository-structure">10.1 Code repository structure</a></li> + <li><a id="toc-Interacting-with-vise" href="dev.html#Interacting-with-vise">10.2 Interacting with <code class="code">vise</code></a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Modes-of-operation" href="dev.html#Modes-of-operation">10.2.1 Modes of operation</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Manual-operation" href="dev.html#Manual-operation">10.2.1.1 Manual operation</a></li> + <li><a id="toc-Synchronous-loop" href="dev.html#Synchronous-loop">10.2.1.2 Synchronous loop</a></li> + <li><a id="toc-Asynchronous-one_002dshot" href="dev.html#Asynchronous-one_002dshot">10.2.1.3 Asynchronous one-shot</a></li> + </ul></li> + <li><a id="toc-Configuration" href="dev.html#Configuration">10.2.2 Configuration</a></li> + <li><a id="toc-Sessions" href="dev.html#Sessions">10.2.3 Sessions</a></li> + <li><a id="toc-Execution-context" href="dev.html#Execution-context">10.2.4 Execution context</a></li> + </ul></li> + <li><a id="toc-Resolving-resources" href="dev.html#Resolving-resources">10.3 Resolving resources</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Memory-resource-implementation" href="dev.html#Memory-resource-implementation">10.3.1 Memory resource implementation</a></li> + <li><a id="toc-Filesystem-resource-implementation" href="dev.html#Filesystem-resource-implementation">10.3.2 Filesystem resource implementation</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Bytecode-_0028resource_002eResource_002eGetCode_0029" href="dev.html#Bytecode-_0028resource_002eResource_002eGetCode_0029">10.3.2.1 Bytecode (<code class="code">resource.Resource.GetCode</code>)</a></li> + <li><a id="toc-Templates-_0028resource_002eResource_002eGetTemplate_0029" href="dev.html#Templates-_0028resource_002eResource_002eGetTemplate_0029">10.3.2.2 Templates (<code class="code">resource.Resource.GetTemplate</code>)</a></li> + <li><a id="toc-Menus-_0028resource_002eResource_002eGetMenu_0029" href="dev.html#Menus-_0028resource_002eResource_002eGetMenu_0029">10.3.2.3 Menus (<code class="code">resource.Resource.GetMenu</code>)</a></li> + <li><a id="toc-External-symbols-_0028resource_002eResource_002eFuncFor_0029" href="dev.html#External-symbols-_0028resource_002eResource_002eFuncFor_0029">10.3.2.4 External symbols (<code class="code">resource.Resource.FuncFor</code>)</a></li> + </ul></li> + </ul></li> + <li><a id="toc-Logging" href="dev.html#Logging">10.4 Logging</a></li> + <li><a id="toc-Tools" href="dev.html#Tools">10.5 Tools</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Test-data-generation" href="dev.html#Test-data-generation">10.5.1 Test data generation</a></li> + <li><a id="toc-Interactive-runner" href="dev.html#Interactive-runner">10.5.2 Interactive runner</a></li> + <li><a id="toc-Assembler" href="dev.html#Assembler">10.5.3 Assembler</a></li> + <li><a id="toc-Disassembler" href="dev.html#Disassembler">10.5.4 Disassembler</a></li> + <li><a id="toc-Interactive-case-examples" href="dev.html#Interactive-case-examples">10.5.5 Interactive case examples</a></li> + </ul></li> + <li><a id="toc-Assembly-examples" href="dev.html#Assembly-examples">10.6 Assembly examples</a></li> + <li><a id="toc-Bytecode-example" href="dev.html#Bytecode-example">10.7 Bytecode example</a> + <ul class="toc-numbered-mark"> + <li><a id="toc-Example" href="dev.html#Example">10.7.1 Example</a></li> + </ul></li> + </ul></li> +</ul> +</div> +</div> +</div> +<hr> +<div class="nav-panel"> +<p> +Next: <a href="overview.html" accesskey="n" rel="next">Overview</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> + + + +</body> +</html> diff --git a/doc/build/instructions.html b/doc/build/instructions.html @@ -0,0 +1,352 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>instructions (vise)</title> + +<meta name="description" content="instructions (vise)"> +<meta name="keywords" content="instructions (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="navigation.html" rel="next" title="navigation"> +<link href="signals.html" rel="prev" title="signals"> +<style type="text/css"> +<!-- +div.example {margin-left: 3.2em} +--> +</style> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="instructions"> +<div class="nav-panel"> +<p> +Next: <a href="navigation.html" accesskey="n" rel="next">Navigation</a>, Previous: <a href="signals.html" accesskey="p" rel="prev">Signal flags</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="Instructions">4 Instructions</h2> + + +<ul class="mini-toc"> +<li><a href="#Data-types" accesskey="1">Data types</a></li> +<li><a href="#Instruction-list" accesskey="2">Instruction list</a></li> +<li><a href="#Batch-instructions" accesskey="3">Batch instructions</a></li> +</ul> +<div class="section-level-extent" id="Data-types"> +<h3 class="section">4.1 Data types</h3> + + +<a class="anchor" id="node_005ftype"></a><ul class="mini-toc"> +<li><a href="#node" accesskey="1">node</a></li> +<li><a href="#label" accesskey="2">label</a></li> +<li><a href="#size" accesskey="3">size</a></li> +<li><a href="#selector" accesskey="4">selector</a></li> +<li><a href="#symbol" accesskey="5">symbol</a></li> +<li><a href="#signal" accesskey="6">signal</a></li> +<li><a href="#matchmode" accesskey="7">matchmode</a></li> +</ul> +<div class="subsection-level-extent" id="node"> +<h4 class="subsection">4.1.1 node</h4> + +<p>A node name is a string. +</p> +<p>Both regular and special node names exist. +</p> +<ul class="mini-toc"> +<li><a href="#Regular-node" accesskey="1">Regular node</a></li> +<li><a href="#Special-node" accesskey="2">Special node</a></li> +</ul> +<div class="subsubsection-level-extent" id="Regular-node"> +<h4 class="subsubsection">4.1.1.1 Regular node</h4> + +<p>Must be one or more characters long. +</p> +<p>Starts with a 7-bit alphabetical character. +</p> +<p>The remainder of the string may contain 7-bit alphanumeric characters or underscore. +</p> + +</div> +<div class="subsubsection-level-extent" id="Special-node"> +<h4 class="subsubsection">4.1.1.2 Special node</h4> + +<p>Special node names are a single character. +</p> +<p>See <a class="ref" href="navigation.html#node_005fnames">Node names</a> for details. +</p> + +</div> +</div> +<div class="subsection-level-extent" id="label"> +<h4 class="subsection">4.1.2 label</h4> + +<p>Same rules as for <a class="ref" href="#symbol_005ftype">symbol</a>. +</p> + +</div> +<div class="subsection-level-extent" id="size"> +<h4 class="subsection">4.1.3 size</h4> + +<p>Numerical value of any size. +</p> + +</div> +<div class="subsection-level-extent" id="selector"> +<h4 class="subsection">4.1.4 selector</h4> + +<p>The selector <code class="code">*</code> is used to catch any input. +</p> +<p>Apart from that, a valid selector is a string of 7-bit alphanumeric characters. +</p> + +<a class="anchor" id="symbol_005ftype"></a></div> +<div class="subsection-level-extent" id="symbol"> +<h4 class="subsection">4.1.5 symbol</h4> + +<p>Same rules as for <a class="ref" href="#node_005ftype">regular node names</a>. +</p> + +</div> +<div class="subsection-level-extent" id="signal"> +<h4 class="subsection">4.1.6 signal</h4> + +<p>Numerical value of any size. +</p> + +</div> +<div class="subsection-level-extent" id="matchmode"> +<h4 class="subsection">4.1.7 matchmode</h4> + +<p>Binary numeric value, 0 or 1. +</p> + +</div> +</div> +<div class="section-level-extent" id="Instruction-list"> +<h3 class="section">4.2 Instruction list</h3> + +<ul class="mini-toc"> +<li><a href="#CATCH-_003cnode_003e-_003csignal_003e-_003cmatchmode_003e" accesskey="1">CATCH <node> <signal> <matchmode></a></li> +<li><a href="#CROAK-_003csignal_003e-_003cmatchmode_003e" accesskey="2">CROAK <signal> <matchmode></a></li> +<li><a href="#HALT" accesskey="3">HALT</a></li> +<li><a href="#INCMP-_003cnode_003e-_003cselector_003e" accesskey="4">INCMP <node> <selector></a></li> +<li><a href="#LOAD-_003csymbol_003e-_003csize_003e" accesskey="5">LOAD <symbol> <size></a></li> +<li><a href="#MAP-_003csymbol_003e" accesskey="6">MAP <symbol></a></li> +<li><a href="#MNEXT-_003clabel_003e-_003cselector_003e" accesskey="7">MNEXT <label> <selector></a></li> +<li><a href="#MOUT-_003clabel_003e-_003cselector_003e" accesskey="8">MOUT <label> <selector></a></li> +<li><a href="#MOVE-_003cnode_003e" accesskey="9">MOVE <node></a></li> +<li><a href="#MPREV-_003clabel_003e-_003cselector_003e">MPREV <label> <selector></a></li> +<li><a href="#MSINK">MSINK</a></li> +<li><a href="#RELOAD-_003csymbol_003e">RELOAD <symbol></a></li> +</ul> +<div class="subsection-level-extent" id="CATCH-_003cnode_003e-_003csignal_003e-_003cmatchmode_003e"> +<h4 class="subsection">4.2.1 CATCH <node> <signal> <matchmode></h4> + +<p>Control flow using signal checking. +</p> +<p>If <code class="code">matchmode</code> is 1, then jump to <code class="code">node</code> if <code class="code">signal</code> is <em class="emph">set</em>. +</p> +<p>If <code class="code">matchmode</code> is 0, then jump to <code class="code">node</code> if <code class="code">signal</code> is <em class="emph">no set</em>. +</p> +<p>Existing bytecode in buffer is cleared before the jump. +</p> + +</div> +<div class="subsection-level-extent" id="CROAK-_003csignal_003e-_003cmatchmode_003e"> +<h4 class="subsection">4.2.2 CROAK <signal> <matchmode></h4> + +<p>Clear state and restart execution from top if signal is matched. +</p> +<p>Signal match is the same as for <code class="code">CATCH</code>. +</p> +</div> +<div class="subsection-level-extent" id="HALT"> +<h4 class="subsection">4.2.3 HALT</h4> + +<p>Halt execution and yield control to client. +</p> +<p>Any remaining bytecode is kept in buffer. +</p> + +</div> +<div class="subsection-level-extent" id="INCMP-_003cnode_003e-_003cselector_003e"> +<h4 class="subsection">4.2.4 INCMP <node> <selector></h4> + +<p>Compare registered input to <code class="code">selector</code>. +</p> +<p>If match, it has the same side-effects as <code class="code">MOVE</code>. +</p> +<p>In addition, any consecutive <code class="code">INCMP</code> matches will be ignored until next <code class="code">HALT</code> is encountered. +</p> + +</div> +<div class="subsection-level-extent" id="LOAD-_003csymbol_003e-_003csize_003e"> +<h4 class="subsection">4.2.5 LOAD <symbol> <size></h4> + +<p>Execute the code symbol <code class="code">symbol</code> and cache the result. +</p> +<p>Result must be constrained to the given <code class="code">size</code>. +</p> + +</div> +<div class="subsection-level-extent" id="MAP-_003csymbol_003e"> +<h4 class="subsection">4.2.6 MAP <symbol></h4> + +<p>Expose result from <code class="code">symbol</code> previously loaded by <code class="code">LOAD</code> to the renderer. +</p> + +</div> +<div class="subsection-level-extent" id="MNEXT-_003clabel_003e-_003cselector_003e"> +<h4 class="subsection">4.2.7 MNEXT <label> <selector></h4> + +<p>Activate the "next" part of lateral navigation. +</p> +<p>Define how to display the menu choice for advancing to the next page. +</p> + +</div> +<div class="subsection-level-extent" id="MOUT-_003clabel_003e-_003cselector_003e"> +<h4 class="subsection">4.2.8 MOUT <label> <selector></h4> + +<p>Add menu entry. +</p> +<p>Each entry should have a corresponding ‘INCMP‘ with matching <code class="code">selector</code>. +</p> +<p>Attempt to resolve <code class="code">label</code> to a language-enabled string to use as menu title, or by default use the <code class="code">label</code> directly. +</p> + +</div> +<div class="subsection-level-extent" id="MOVE-_003cnode_003e"> +<h4 class="subsection">4.2.9 MOVE <node></h4> + +<p>Load bytecode and template corresponding to <code class="code">node</code>. +</p> +<p>The loaded bytecode is appended to existing bytecode in buffer. +</p> +<p>Invalidates effects of all preceding <code class="code">MAP</code> calls. +</p> + +</div> +<div class="subsection-level-extent" id="MPREV-_003clabel_003e-_003cselector_003e"> +<h4 class="subsection">4.2.10 MPREV <label> <selector></h4> + +<p>Activate the "previous" part of lateral navigation. +</p> +<p>Define how to display the menu choice for going back to the previous page. +</p> + +</div> +<div class="subsection-level-extent" id="MSINK"> +<h4 class="subsection">4.2.11 MSINK</h4> + +<p>If set, the menu is defined as the multi-page content sink. +</p> +<p>Cannot be used with an active <code class="code">MAP</code> of a symbol with <code class="code">LOAD</code> size <code class="code">0</code>. +</p> + +</div> +<div class="subsection-level-extent" id="RELOAD-_003csymbol_003e"> +<h4 class="subsection">4.2.12 RELOAD <symbol></h4> + +<p>Execute a code symbol already loaded by <code class="code">LOAD</code> and overwrite the existing cache with the new results. +</p> +<p>Constrained to the previously given size for the same symbol. +</p> + + +</div> +</div> +<div class="section-level-extent" id="Batch-instructions"> +<h3 class="section">4.3 Batch instructions</h3> + +<p>Some convenience instructions are made available for defining menus. +</p> +<p>There instruction <strong class="strong">MUST</strong> be used at the <em class="emph">end</em> of the node’s assembly code, as they expand to code on either side of a <code class="code">HALT</code> instruction. +</p> +<dl class="table"> +<dt><code class="code">DOWN <symbol> <selector> <label></code></dt> +<dd><p>Descend to next frame and move to <code class="code">symbol</code>. +</p></dd> +<dt><code class="code">UP <selector> <label></code></dt> +<dd><p>Return to the previous frame. +</p></dd> +<dt><code class="code">NEXT <selector> <label></code></dt> +<dd><p>Activate and set <em class="emph">next</em> menu option for browsing multiple-page renders. +</p></dd> +<dt><code class="code">PREVIOUS <selector> <label></code></dt> +<dd><p>Activate and set <em class="emph">previuos</em> menu option for browsing multiple-page renders. (If <code class="code">MNEXT</code>/<code class="code">NEXT</code> has not been defined this will not be rendered). +</p></dd> +</dl> + + +<ul class="mini-toc"> +<li><a href="#Batch-menu-expansion" accesskey="1">Batch menu expansion</a></li> +</ul> +<div class="subsection-level-extent" id="Batch-menu-expansion"> +<h4 class="subsection">4.3.1 Batch menu expansion</h4> + +<table class="multitable"> +<thead><tr><th>Batch instruction</th><th>Expanded instruction</th></tr></thead> +<tbody><tr><td><div class="example"> +<pre class="example-preformatted">DOWN foo 0 to_foo +</pre></div></td><td><div class="example"> +<pre class="example-preformatted">MOUT to_foo 0 +HALT +INCMP foo 0 +</pre></div></td></tr> +<tr><td><div class="example"> +<pre class="example-preformatted">UP 1 back +</pre></div></td><td><div class="example"> +<pre class="example-preformatted">MOUT back 1 +HALT +INCMP _ 1 +</pre></div></td></tr> +<tr><td><div class="example"> +<pre class="example-preformatted">NEXT 2 fwd +</pre></div></td><td><div class="example"> +<pre class="example-preformatted">MNEXT fwd 2 +HALT +INCMP > 2 +</pre></div></td></tr> +<tr><td><div class="example"> +<pre class="example-preformatted">PREVIOUS 3 back +</pre></div></td><td><div class="example"> +<pre class="example-preformatted">MPREV back 3 +HALT +INCMP < 3 +</pre></div></td></tr> +<tr><td><div class="example"> +<pre class="example-preformatted">DOWN foo 0 to_foo +UP 1 back +</pre></div></td><td><div class="example"> +<pre class="example-preformatted">MOUT to_foo 0 +MOUT back 1 +HALT +INCMP foo 0 +INCMP _ 1 +</pre></div></td></tr> +</tbody> +</table> +</div> +</div> +</div> +<hr> +<div class="nav-panel"> +<p> +Next: <a href="navigation.html">Navigation</a>, Previous: <a href="signals.html">Signal flags</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> + + + +</body> +</html> diff --git a/doc/build/language.html b/doc/build/language.html @@ -0,0 +1,57 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>language (vise)</title> + +<meta name="description" content="language (vise)"> +<meta name="keywords" content="language (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="cookbook.html" rel="next" title="cookbook"> +<link href="render.html" rel="prev" title="render"> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="language"> +<div class="nav-panel"> +<p> +Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Previous: <a href="render.html" accesskey="p" rel="prev">Rendering</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="Handling-languages">8 Handling languages</h2> + + +<p>Templates, external code symbols and menu labels can be resolved differently depending on language. +</p> +<p>This is enabled by the <a class="ref" href="dev.html#execution_005fcontext">Execution context</a> of the engine. Through the context, the current language, if set, is always available to client code. +</p> +<p>Language specification is encapsulated by the <code class="code">lang</code> module, using the ISO639 language identifier standard. +</p> + +<ul class="mini-toc"> +<li><a href="#Defining-language" accesskey="1">Defining language</a></li> +</ul> +<div class="section-level-extent" id="Defining-language"> +<h3 class="section">8.1 Defining language</h3> + +<p>The default language can be set in <code class="code">engine.Config.Language</code>. +</p> +<p>It may also be set as a side-effect of bytecode execution. This is done by executing <code class="code">LOAD</code> with a symbol returning an <code class="code">ISO639</code> language code, while setting the <code class="code">LANG</code> signal flag (see <a class="ref" href="signals.html#builtin_005fflags">Built-in signal flags</a>. +</p></div> +</div> + + + +</body> +</html> diff --git a/doc/build/lateral_005fnavigation.html b/doc/build/lateral_005fnavigation.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>lateral_navigation (vise)</title> + +<meta name="description" content="lateral_navigation (vise)"> +<meta name="keywords" content="lateral_navigation (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=navigation.html#lateral_005fnavigation"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="navigation.html#lateral_005fnavigation">lateral_navigation</a>.</p> +</body> diff --git a/doc/build/load_005fhandler.html b/doc/build/load_005fhandler.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>load_handler (vise)</title> + +<meta name="description" content="load_handler (vise)"> +<meta name="keywords" content="load_handler (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=cache.html#load_005fhandler"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="cache.html#load_005fhandler">load_handler</a>.</p> +</body> diff --git a/doc/build/map_005fsink.html b/doc/build/map_005fsink.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>map_sink (vise)</title> + +<meta name="description" content="map_sink (vise)"> +<meta name="keywords" content="map_sink (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=render.html#map_005fsink"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="render.html#map_005fsink">map_sink</a>.</p> +</body> diff --git a/doc/build/multiple_005fmenus.html b/doc/build/multiple_005fmenus.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>multiple_menus (vise)</title> + +<meta name="description" content="multiple_menus (vise)"> +<meta name="keywords" content="multiple_menus (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=cookbook.html#multiple_005fmenus"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="cookbook.html#multiple_005fmenus">multiple_menus</a>.</p> +</body> diff --git a/doc/build/multiple_005fpages.html b/doc/build/multiple_005fpages.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>multiple_pages (vise)</title> + +<meta name="description" content="multiple_pages (vise)"> +<meta name="keywords" content="multiple_pages (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=cookbook.html#multiple_005fpages"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="cookbook.html#multiple_005fpages">multiple_pages</a>.</p> +</body> diff --git a/doc/build/navigation.html b/doc/build/navigation.html @@ -0,0 +1,153 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>navigation (vise)</title> + +<meta name="description" content="navigation (vise)"> +<meta name="keywords" content="navigation (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="cache.html" rel="next" title="cache"> +<link href="instructions.html" rel="prev" title="instructions"> +<style type="text/css"> +<!-- +ul.mark-bullet {list-style-type: disc} +--> +</style> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="navigation"> +<div class="nav-panel"> +<p> +Next: <a href="cache.html" accesskey="n" rel="next">External data</a>, Previous: <a href="instructions.html" accesskey="p" rel="prev">Instructions</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="Navigation">5 Navigation</h2> + + +<p>Nodes are navigated by name, using a navigation stack. +</p> +<p>Every movement <em class="emph">down</em> adds a node to the stack, and every movement <em class="emph">up</em> removes one node from the stack. +</p> +<p>Additionally, <em class="emph">lateral</em> movement is available, for nodes whose contents span mulitple pages. +</p> + +<ul class="mini-toc"> +<li><a href="#Entry-point" accesskey="1">Entry point</a></li> +<li><a href="#Lateral-navigation" accesskey="2">Lateral navigation</a></li> +<li><a href="#Node-names" accesskey="3">Node names</a></li> +<li><a href="#Navigation-stack" accesskey="4">Navigation stack</a></li> +</ul> +<div class="section-level-extent" id="Entry-point"> +<h3 class="section">5.1 Entry point</h3> + +<p>All VM executions require an <em class="emph">entry point</em>. +</p> +<p>If not explicitly set in the code, the node name <code class="code">root</code> is used. +</p> +<p>Attempting to navigate <em class="emph">up</em> from the entry point node will fail and terminate execution. +</p> + +<a class="anchor" id="lateral_005fnavigation"></a></div> +<div class="section-level-extent" id="Lateral-navigation"> +<h3 class="section">5.2 Lateral navigation</h3> + +<p>Lateral navigation is only available for node output spanning multiple pages. See <a class="ref" href="render.html#render_005fmulti">Multi-page rendering</a> for details. +</p> +<p>Lateral navigation will fail and terminate execution when: +</p> +<ul class="itemize mark-bullet"> +<li>executing a single-page node. +</li><li>attempting <em class="emph">next</em> beyond the last page. +</li><li>attempting <em class="emph">previous</em> on the first page. +</li></ul> + + +<a class="anchor" id="node_005fnames"></a></div> +<div class="section-level-extent" id="Node-names"> +<h3 class="section">5.3 Node names</h3> + +<p>Regular node names <em class="emph">must</em> start with an alphabetical character. The rest of the string may contain alphanumeric characters and underscore. +</p> +<ul class="mini-toc"> +<li><a href="#Special-node-names" accesskey="1">Special node names</a></li> +<li><a href="#Builtin-node-names" accesskey="2">Builtin node names</a></li> +</ul> +<div class="subsection-level-extent" id="Special-node-names"> +<h4 class="subsection">5.3.1 Special node names</h4> + +<p>A selection of special node names are available for relative navigation. They are single-character tokens, listed below with their respective ASCII codes. +</p> +<dl class="table"> +<dt><code class="code">. (0x2E)</code></dt> +<dd><p>Repeat the same node. +</p></dd> +<dt><code class="code">_ (0x5F)</code></dt> +<dd><p>Go to the previous node in the stack. +</p></dd> +<dt><code class="code">> (0x3E)</code></dt> +<dd><p>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. +</p></dd> +<dt><code class="code">< (0x3C)</code></dt> +<dd><p>Go to the next page of a multi-page node. Will fail if used on the first (or single) page. +</p></dd> +<dt><code class="code">^ (0x5E)</code></dt> +<dd><p>Go to the topmost node. Will execute each intermediate node in the stack. +</p></dd> +</dl> + + +</div> +<div class="subsection-level-extent" id="Builtin-node-names"> +<h4 class="subsection">5.3.2 Builtin node names</h4> + +<p>Uncaught exceptions in the code flow that should not halt execution are routed to a builtin node named <code class="code">_catch</code>. +</p> + +</div> +</div> +<div class="section-level-extent" id="Navigation-stack"> +<h3 class="section">5.4 Navigation stack</h3> + +<p>Consider the following navigation example, illustrating the state of the stack for each step after execution. +</p> +<table class="multitable"> +<thead><tr><th>instruction</th><th>stack</th><th>page index</th></tr></thead> +<tbody><tr><td><code class="code">MOVE foo</code></td><td>foo</td><td>0</td></tr> +<tr><td><code class="code">MOVE bar</code></td><td>foo/bar</td><td>0</td></tr> +<tr><td><code class="code">MOVE baz</code></td><td>foo/bar/baz</td><td>0</td></tr> +<tr><td><code class="code">MOVE ></code></td><td>foo/bar/baz</td><td>1</td></tr> +<tr><td><code class="code">MOVE ></code></td><td>foo/bar/baz</td><td>2</td></tr> +<tr><td><code class="code">MOVE <</code></td><td>foo/bar/baz</td><td>1</td></tr> +<tr><td><code class="code">MOVE .</code></td><td>foo/bar/baz</td><td>1</td></tr> +<tr><td><code class="code">MOVE _</code></td><td>foo/bar</td><td>0</td></tr> +<tr><td><code class="code">MOVE baz</code></td><td>foo/bar/baz</td><td>0</td></tr> +<tr><td><code class="code">MOVE ^</code></td><td>foo</td><td>0</td></tr> +</tbody> +</table> + + +</div> +</div> +<hr> +<div class="nav-panel"> +<p> +Next: <a href="cache.html">External data</a>, Previous: <a href="instructions.html">Instructions</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> + + + +</body> +</html> diff --git a/doc/build/node_005fnames.html b/doc/build/node_005fnames.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>node_names (vise)</title> + +<meta name="description" content="node_names (vise)"> +<meta name="keywords" content="node_names (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=navigation.html#node_005fnames"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="navigation.html#node_005fnames">node_names</a>.</p> +</body> diff --git a/doc/build/node_005ftype.html b/doc/build/node_005ftype.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>node_type (vise)</title> + +<meta name="description" content="node_type (vise)"> +<meta name="keywords" content="node_type (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=instructions.html#node_005ftype"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="instructions.html#node_005ftype">node_type</a>.</p> +</body> diff --git a/doc/build/nomenclature.html b/doc/build/nomenclature.html @@ -0,0 +1,66 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>nomenclature (vise)</title> + +<meta name="description" content="nomenclature (vise)"> +<meta name="keywords" content="nomenclature (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="signals.html" rel="next" title="signals"> +<link href="overview.html" rel="prev" title="overview"> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="nomenclature"> +<div class="nav-panel"> +<p> +Next: <a href="signals.html" accesskey="n" rel="next">Signal flags</a>, Previous: <a href="overview.html" accesskey="p" rel="prev">Overview</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="Nomenclature">2 Nomenclature</h2> + +<ul class="mini-toc"> +<li><a href="#Common" accesskey="1">Common</a></li> +<li><a href="#Instructions-and-navigation" accesskey="2">Instructions and navigation</a></li> +</ul> +<div class="section-level-extent" id="Common"> +<h3 class="section">2.1 Common</h3> + +<dl class="table"> +<dt>‘<samp class="samp">client</samp>’</dt> +<dd><p>Code that generates input to the VM and processes its output. Examples of clients are the <code class="code">engine</code> module, and the <samp class="file">/dev/interactive</samp> executable. +</p></dd> +</dl> + + +</div> +<div class="section-level-extent" id="Instructions-and-navigation"> +<h3 class="section">2.2 Instructions and navigation</h3> + +<dl class="table"> +<dt>‘<samp class="samp">node</samp>’</dt> +<dd><p>A node in the execution flow that has both bytecode and template associated with it. May also have language translations. +</p></dd> +<dt>‘<samp class="samp">symbol</samp>’</dt> +<dd><p>Token used as key to load external content and trigger side-effects. +</p></dd> +</dl> +</div> +</div> + + + +</body> +</html> diff --git a/doc/build/overview.html b/doc/build/overview.html @@ -0,0 +1,52 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>overview (vise)</title> + +<meta name="description" content="overview (vise)"> +<meta name="keywords" content="overview (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="nomenclature.html" rel="next" title="nomenclature"> +<link href="index.html" rel="prev" title="Top"> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="overview"> +<div class="nav-panel"> +<p> +Next: <a href="nomenclature.html" accesskey="n" rel="next">Nomenclature</a>, Previous: <a href="index.html" accesskey="p" rel="prev">Introduction</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="Overview">1 Overview</h2> + +<p>An attempt at defining a small VM to handle menu interaction for size-constrained clients and servers. +</p> +<p>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. +</p> + +<ul class="mini-toc"> +<li><a href="#Synopsis" accesskey="1">Synopsis</a></li> +</ul> +<div class="section-level-extent" id="Synopsis"> +<h3 class="section">1.1 Synopsis</h3> + +<p>TODO +</p></div> +</div> + + + +</body> +</html> diff --git a/doc/build/render.html b/doc/build/render.html @@ -0,0 +1,331 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>render (vise)</title> + +<meta name="description" content="render (vise)"> +<meta name="keywords" content="render (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="language.html" rel="next" title="language"> +<link href="cache.html" rel="prev" title="cache"> +<style type="text/css"> +<!-- +div.example {margin-left: 3.2em} +--> +</style> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="render"> +<div class="nav-panel"> +<p> +Next: <a href="language.html" accesskey="n" rel="next">Handling languages</a>, Previous: <a href="cache.html" accesskey="p" rel="prev">External data</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="Rendering">7 Rendering</h2> + +<p>Every node whose bytecode includes a <code class="code">HALT</code> statement <strong class="strong">MUST</strong> define a rendering template. +</p> +<p>Templates may be either static or dynamic. +</p> + +<a class="anchor" id="dynamic_005ftemplates"></a><ul class="mini-toc"> +<li><a href="#Dynamic-templates" accesskey="1">Dynamic templates</a></li> +<li><a href="#Rendering-pipeline" accesskey="2">Rendering pipeline</a></li> +<li><a href="#Multiple_002dpage-rendering" accesskey="3">Multiple-page rendering</a></li> +</ul> +<div class="section-level-extent" id="Dynamic-templates"> +<h3 class="section">7.1 Dynamic templates</h3> + +<p>Using placeholders, the content behind <code class="code">MAP</code> calls in the current executing node may be embedded in the template. +</p> +<p>Placeholders have the following format: +</p><pre class="verbatim">{{.symbol}} +</pre><p>where <code class="code">symbol</code> is the corresponding argument to <code class="code">MAP</code>. +</p> +<p>Note that <code class="code">MAP</code> can only be called on symbols who have a corresponding <code class="code">LOAD</code> on the same level or futher up the stack. +</p> +<ul class="mini-toc"> +<li><a href="#Examples" accesskey="1">Examples</a></li> +</ul> +<div class="subsection-level-extent" id="Examples"> +<h4 class="subsection">7.1.1 Examples</h4> + +<p>Consider the following instruction sequence: +</p> +<div class="example"> +<pre class="example-preformatted">LOAD foo 32 +MAP foo +HALT +</pre></div> + +<p>If the template contains the placeholder <code class="code">foo</code>, the contents of that placeholder will be replaced by the cached result of the <code class="code">LOAD foo</code> external symbol. +</p> +<p>However: +</p> +<div class="example"> +<pre class="example-preformatted">LOAD foo 32 +HALT +</pre></div> + +<p>This will not work for the same template, because the <code class="code">foo</code> symbol has not been exposed with a <code class="code">MAP</code> call. +</p> + +<div class="example"> +<pre class="example-preformatted">LOAD foo 32 +MOVE bar +# (bar bytecode follows) +MAP foo +HALT +</pre></div> + +<p>If the template for the node <code class="code">bar</code> contains the placeholder <code class="code">foo</code>, the contents of that placeholder will be replaced by the cached result of the <code class="code">LOAD foo</code> external symbol. +</p> +<p>This works because the <code class="code">MAP</code> is encountered further down the node execution stack than where the <code class="code">LOAD</code> was encountered. +</p> +<p>However: +</p> +<div class="example"> +<pre class="example-preformatted">LOAD foo 32 +MOVE bar +# (bar bytecode follows) +MAP foo +MOVE baz +# (baz bytecode follows) +HALT +</pre></div> + +<p>Here, if the template for <code class="code">baz</code> contains the placeholder <code class="code">foo</code>, the execution will fail because the <code class="code">MAP</code> in <code class="code">bar</code> was invalidated by the <code class="code">MOVE</code> to <code class="code">baz</code>. +</p> + +</div> +</div> +<div class="section-level-extent" id="Rendering-pipeline"> +<h3 class="section">7.2 Rendering pipeline</h3> + +<p>The pipeline starts with the loading of the template corresponding to the current execution node. +</p> +<p>From there, three branches are possible: +</p> +<ol class="enumerate"> +<li> No <em class="emph">sink</em> has been defined. +</li><li> One of the encountered <code class="code">MAP</code> symbols resolves to a <em class="emph">sink</em>. +</li><li> <code class="code">MSINK</code> has been encountered. +</li></ol> + +<p>If the resulting output from any of these branches is larger than the output size, failure ensues and execution is terminated. +</p> + +<ul class="mini-toc"> +<li><a href="#No-sink" accesskey="1">No sink</a></li> +<li><a href="#MAP-sink" accesskey="2">MAP sink</a></li> +<li><a href="#Menu-sink" accesskey="3">Menu sink</a></li> +</ul> +<div class="subsection-level-extent" id="No-sink"> +<h4 class="subsection">7.2.1 No sink</h4> + +<ol class="enumerate"> +<li> Expand all placeholders in the template. +</li><li> Expand all menu items +</li></ol> + + +<a class="anchor" id="map_005fsink"></a></div> +<div class="subsection-level-extent" id="MAP-sink"> +<h4 class="subsection">7.2.2 MAP sink</h4> + +<ol class="enumerate"> +<li> Expand all non-sink placeholders in the template. +</li><li> Expand all menu items. +</li><li> Group sink items up to the remaining output size. +</li><li> If any item alone exceeds the remaining output size, fail and terminate execution. +</li><li> If any item together with the lateral navigation menu items exceed the remaining output size, fail and terminate execution. +</li><li> Check the page navigation index (see <a class="ref" href="navigation.html#lateral_005fnavigation">Lateral navigation</a>). +</li><li> Replace sink symbol result with group item corresponding to navigation index. +</li><li> Expand all sink placeholders in the template. +</li><li> Expand all menu items (including lateral navigation). +</li></ol> + + +</div> +<div class="subsection-level-extent" id="Menu-sink"> +<h4 class="subsection">7.2.3 Menu sink</h4> + +<ol class="enumerate"> +<li> Remove all menu items (any following menu expansion will only contain lateral navigation items, when and if they apply). +</li><li> Copy menu items to sink placeholder. +</li><li> Continue from <a class="ref" href="#map_005fsink">MAP sink</a>. +</li></ol> + + +<a class="anchor" id="render_005fmulti"></a></div> +</div> +<div class="section-level-extent" id="Multiple_002dpage-rendering"> +<h3 class="section">7.3 Multiple-page rendering</h3> + +<p>As indicated above, multiple-page rendering is activated when a <code class="code">MAP</code> is issued to a symbol that is loaded with <code class="code">0</code> size. (<code class="code">LOAD <symbol> 0</code>). +</p> +<p>The result is split into rows using newline (<code class="code">0x0a</code>) as separator. +</p> + +<ul class="mini-toc"> +<li><a href="#Missing-navigation" accesskey="1">Missing navigation</a></li> +<li><a href="#Multi_002dpage-example" accesskey="2">Multi-page example</a></li> +</ul> +<div class="subsection-level-extent" id="Missing-navigation"> +<h4 class="subsection">7.3.1 Missing navigation</h4> + +<p>If no <em class="emph">lateral navigation</em> has been activated, any sinks will still be processed. +</p> +<p>The sink placeholder will then be replaced with the first item in the group. +</p> + +</div> +<div class="subsection-level-extent" id="Multi_002dpage-example"> +<h4 class="subsection">7.3.2 Multi-page example</h4> + +<p>Consider the following instruction sequence: +</p> +<div class="example"> +<pre class="example-preformatted">LOAD foo 8 +LOAD bar 16 +LOAD baz 0 +MAP foo +MAP bar +MAP baz +MOUT to_foo 0 +MOUT to_bar 1 +MNEXT to_next 11 +MPREV to_prev 22 +HALT +INCMP foo 0 +INCMP bar 1 +INCMP > 11 +INCMP < 22 +</pre></div> + +<p>... and the following template (14 bytes, without the placeholders, including line break): +</p> +<pre class="verbatim">This is {{.foo}} and {{.bar}} +{{.baz}} +</pre> + +<ul class="mini-toc"> +<li><a href="#Data-accounting" accesskey="1">Data accounting</a></li> +<li><a href="#Rendering-logic" accesskey="2">Rendering logic</a></li> +</ul> +<div class="subsubsection-level-extent" id="Data-accounting"> +<h4 class="subsubsection">7.3.2.1 Data accounting</h4> + +<p>Then consider that the symbols resolve as follows: +</p> +<table class="multitable"> +<thead><tr><th>symbol</th><th>returned value</th><th>rendered value</th><th>bytes</th></tr></thead> +<tbody><tr><td><code class="code">foo</code></td><td><code class="code">foobar</code></td><td><code class="code">foobar</code></td><td>6</td></tr> +<tr><td><code class="code">bar</code></td><td><code class="code">barbarbar</code></td><td><code class="code">barbarbar</code></td><td>9</td></tr> +<tr><td><code class="code">baz</code></td><td><pre class="verbatim">FOO 42 +BAR 13 +BAZ 666 +XYZZY 1984 +INKY 1 +PINKY 22 +BLINKY 333 +CLYDE 4444 +</pre></td><td>(deferred)</td><td>(71)</td></tr> +<tr><td><code class="code">to_foo</code></td><td><code class="code">go to foo</code></td><td><code class="code">0:go to foo</code></td><td>11</td></tr> +<tr><td><code class="code">to_bar</code></td><td><code class="code">visit the bar</code></td><td><code class="code">1:visit the bar</code></td><td>15</td></tr> +<tr><td><code class="code">to_next</code></td><td><code class="code">next page</code></td><td><code class="code">11:next page</code></td><td>12</td></tr> +<tr><td><code class="code">to_prev</code></td><td><code class="code">go back</code></td><td><code class="code">22:go back</code></td><td>10</td></tr> +</tbody> +</table> + +<p>Given an output size limit of 94, static part of the template (14 bytes). this results in the following render possibilities for the sink content: +</p> +<table class="multitable"> +<thead><tr><th>navigation case</th><th>bytes left for sink</th></tr></thead> +<tbody><tr><td>no navigation</td><td>39</td></tr> +<tr><td>next</td><td>27</td></tr> +<tr><td>previous</td><td>29</td></tr> +<tr><td>next + previous</td><td>17</td></tr> +</tbody> +</table> + + +</div> +<div class="subsubsection-level-extent" id="Rendering-logic"> +<h4 class="subsubsection">7.3.2.2 Rendering logic</h4> + +<p>The total sink byte count is 72, whereas the maximum available sink capacity is 39. At least one extra page is needed. +</p> +<p>The first page (with <code class="code">next</code>) has 27 bytes available, which covers the 3 first sink items (22 bytes, include line break). This results in the following output: +</p> +<div class="example"> +<pre class="example-preformatted">This is foobar and barbarbar +FOO 42 +BAR 13 +BAZ 666 +0:go to foo +1:visit the bar +11:next page +</pre></div> + +<p>Any page that is not first page has maximum 29 bytes available. There are 49 bytes left to render from the sink. This means that more pages are needed, and therefore both <code class="code">next</code> and <code class="code">previous</code> are needed, leaving a capacity of 17 bytes. This is only sufficient for the next item (11 bytes, with line break), resulting in the following output: +</p> +<div class="example"> +<pre class="example-preformatted">This is foobar and barbarbar +XYZZY 1984 +0:go to foo +1:visit the bar +11:next page +22:go back +</pre></div> + +<p>For the next page we again compare with the maximum of 29 bytes. There are 38 bytes left to render. Another intermediate page is required, with the two next entries (16 bytes) fitting inside the capacity (17 bytes). The page then looks like this: +</p> +<div class="example"> +<pre class="example-preformatted">This is foobar and barbarbar +INKY 1 +PINKY 22 +0:go to foo +1:visit the bar +11:next page +22:go back +</pre></div> + +<p>Lastly, with 22 bytes left to go, we can render within the maximum available space of 29 bytes (only using <code class="code">previous</code>). Thus: +</p> + +<div class="example"> +<pre class="example-preformatted">This is foobar and barbarbar +BLINKY 333 +CLYDE 4444 +0:go to foo +1:visit the bar +22:go back +</pre></div> +</div> +</div> +</div> +</div> +<hr> +<div class="nav-panel"> +<p> +Next: <a href="language.html">Handling languages</a>, Previous: <a href="cache.html">External data</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> + + + +</body> +</html> diff --git a/doc/build/render_005fmulti.html b/doc/build/render_005fmulti.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>render_multi (vise)</title> + +<meta name="description" content="render_multi (vise)"> +<meta name="keywords" content="render_multi (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=render.html#render_005fmulti"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="render.html#render_005fmulti">render_multi</a>.</p> +</body> diff --git a/doc/build/signals.html b/doc/build/signals.html @@ -0,0 +1,89 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>signals (vise)</title> + +<meta name="description" content="signals (vise)"> +<meta name="keywords" content="signals (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="instructions.html" rel="next" title="instructions"> +<link href="nomenclature.html" rel="prev" title="nomenclature"> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="signals"> +<div class="nav-panel"> +<p> +Next: <a href="instructions.html" accesskey="n" rel="next">Instructions</a>, Previous: <a href="nomenclature.html" accesskey="p" rel="prev">Nomenclature</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="Signal-flags">3 Signal flags</h2> + + +<ul class="mini-toc"> +<li><a href="#Client_002ddefined-signal-flags" accesskey="1">Client-defined signal flags</a></li> +<li><a href="#Built_002din-signal-flags" accesskey="2">Built-in signal flags</a></li> +</ul> +<div class="section-level-extent" id="Client_002ddefined-signal-flags"> +<h3 class="section">3.1 Client-defined signal flags</h3> + +<p>The client can define any number of signal flags to use. The number of signals <strong class="strong">MUST</strong> be declared explicitly in the client code, and <strong class="strong">MUST NOT</strong> change in stateful or asynchronous execution environments. +</p> +<p>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 class="code">8</code> or greater. +</p> + +<ul class="mini-toc"> +<li><a href="#Flow-control" accesskey="1">Flow control</a></li> +</ul> +<div class="subsection-level-extent" id="Flow-control"> +<h4 class="subsection">3.1.1 Flow control</h4> + +<p>Signal flags enables the client to control the execution flow as a side-effect of the execution of external code symbols. +</p> +<p>Branching is defined using either the <code class="code">CATCH</code> or <code class="code">CROAK</code> instructions. +</p> +<p>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. +</p> + +<a class="anchor" id="builtin_005fflags"></a></div> +</div> +<div class="section-level-extent" id="Built_002din-signal-flags"> +<h3 class="section">3.2 Built-in signal flags</h3> + +<p>For the numeric values of the signals, please refer to the signals appendix. +</p> +<table class="multitable"> +<thead><tr><th width="15%">Flag name</th><th width="20%">Description</th><th width="55%">Lifetime</th><th width="10%">Writeable?</th></tr></thead> +<tbody><tr><td width="15%"><code class="code">READIN</code></td><td width="20%">Input is being processed.</td><td width="55%">From first <code class="code">INCMP</code> until: an <code class="code">INCMP</code> match <em class="emph">or</em> an invalid input exception is triggered.</td><td width="10%">no</td></tr> +<tr><td width="15%"><code class="code">INMATCH</code></td><td width="20%">Input matched an <code class="code">INCMP</code> instruction.</td><td width="55%">Next instruction.</td><td width="10%">no</td></tr> +<tr><td width="15%"><code class="code">TERMINATE</code></td><td width="20%">Terminate execution before the following instruction.</td><td width="55%">Until explicit reseet.</td><td width="10%">no</td></tr> +<tr><td width="15%"><code class="code">DIRTY</code></td><td width="20%">Rendered output is available.</td><td width="55%">Until output is processed.</td><td width="10%">no</td></tr> +<tr><td width="15%"><code class="code">WAIT</code></td><td width="20%">Halt execution before the following instruction, and yield control to client.</td><td width="55%">Until control is yielded.</td><td width="10%">no</td></tr> +<tr><td width="15%"><code class="code">LOADFAIL</code></td><td width="20%">An unexpected error has occurred during execution of an external code symbol.</td><td width="55%">Next instruction.</td><td width="10%">no</td></tr> +<tr><td width="15%"><code class="code">LANG</code></td><td width="20%">Output from an external code symbol is a valid language code, and language should be changed accordingly.</td><td width="55%">Next instruction.</td><td width="10%">yes</td></tr> +</tbody> +</table> +</div> +</div> +<hr> +<div class="nav-panel"> +<p> +Next: <a href="instructions.html">Instructions</a>, Previous: <a href="nomenclature.html">Nomenclature</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> + + + +</body> +</html> diff --git a/doc/build/symbol_005ftype.html b/doc/build/symbol_005ftype.html @@ -0,0 +1,24 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>symbol_type (vise)</title> + +<meta name="description" content="symbol_type (vise)"> +<meta name="keywords" content="symbol_type (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> + +<meta http-equiv="Refresh" content="0; url=instructions.html#symbol_005ftype"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +</head> + +<body lang="en"> + +<p>The node you are looking for is at <a href="instructions.html#symbol_005ftype">symbol_type</a>.</p> +</body> diff --git a/doc/build/tools.html b/doc/build/tools.html @@ -0,0 +1,150 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Released 2023 under AGPL3 --> +<title>tools (vise)</title> + +<meta name="description" content="tools (vise)"> +<meta name="keywords" content="tools (vise)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html" rel="up" title="Top"> +<link href="dev.html" rel="prev" title="dev"> +<style type="text/css"> +<!-- +div.example {margin-left: 3.2em} +--> +</style> + + +</head> + +<body lang="en"> +<div class="chapter-level-extent" id="tools"> +<div class="nav-panel"> +<p> +Previous: <a href="dev.html" accesskey="p" rel="prev">Development</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<hr> +<h2 class="chapter" id="Development-tools">12 Development tools</h2> + +<p>Located in the <samp class="file">dev/</samp> directory of the source code repository. +</p> + +<ul class="mini-toc"> +<li><a href="#Test-data-generation" accesskey="1">Test data generation</a></li> +<li><a href="#Interactive-runner" accesskey="2">Interactive runner</a></li> +<li><a href="#Assembler" accesskey="3">Assembler</a></li> +<li><a href="#Disassembler" accesskey="4">Disassembler</a></li> +<li><a href="#Interactive-case-examples" accesskey="5">Interactive case examples</a></li> +</ul> +<div class="section-level-extent" id="Test-data-generation"> +<h3 class="section">12.1 Test data generation</h3> + +<div class="example"> +<pre class="example-preformatted">go run ./dev/gendata/ <directory> +</pre></div> + +<p>Outputs bytecodes and templates for test data scenarios used in ‘engine‘ unit tests. +</p> + +</div> +<div class="section-level-extent" id="Interactive-runner"> +<h3 class="section">12.2 Interactive runner</h3> + +<div class="example"> +<pre class="example-preformatted">go run ./dev/interactive [-d <data_directory>] [--root <root_symbol>] [--session-id <session_id>] [--persist] +</pre></div> + +<p>Creates a new interactive session using <code class="code">engine.DefaultEngine</code>, starting execution at symbol <code class="code">root_symbol</code> +</p> +<p><code class="code">data_directory</code> points to a directory where templates and bytecode is to be found (in the same format as generated by <samp class="file">dev/gendata</samp>). +</p> +<p>If <code class="code">data_directory</code> is not set, current directory will be used. +</p> +<p>if <code class="code">root_symbol</code> is not set, the symbol <code class="code">root</code> will be used. +</p> +<p>if <code class="code">session_id</code> is set, mutable data will be stored and retrieved keyed by the given identifer (if implemented). +</p> +<p>If <code class="code">persist</code> is set, the execution state will be persisted across sessions. +</p> + +</div> +<div class="section-level-extent" id="Assembler"> +<h3 class="section">12.3 Assembler</h3> + +<div class="example"> +<pre class="example-preformatted">go run ./dev/asm <assembly_file> +</pre></div> + +<p>Will output bytecode on STDOUT generated from a valid assembly file. +</p> + +</div> +<div class="section-level-extent" id="Disassembler"> +<h3 class="section">12.4 Disassembler</h3> + +<div class="example"> +<pre class="example-preformatted">go run ./dev/disasm/ <binary_file> +</pre></div> + +<p>Will list all the instructions on STDOUT from a valid binary file. +</p> + +</div> +<div class="section-level-extent" id="Interactive-case-examples"> +<h3 class="section">12.5 Interactive case examples</h3> + +<p>Found in <samp class="file">examples/</samp>. +</p> +<p>Be sure to <code class="code">make examples</code> before running them. +</p> +<p>Can be run with: +</p> +<div class="example"> +<pre class="example-preformatted">go run ./examples/<case> [...] +</pre></div> + +<p>except helloworld which is run as +</p> +<div class="example"> +<pre class="example-preformatted">go run ./dev/interactive -d ./examples/helloworld [...] +</pre></div> + +<p>The available options are the same as for the <samp class="file">dev/interactive</samp> tool. +</p> +<p>Contents of the case directory: +</p> +<dl class="table"> +<dt><samp class="file">*.vis</samp></dt> +<dd><p>assembly code. +</p></dd> +<dt><samp class="file">*.bin</samp></dt> +<dd><p>bytecode for each node symbol (only available after make). +</p></dd> +<dt><samp class="file">*.txt.orig</samp></dt> +<dd><p>default contents of a single data entry. +</p></dd> +<dt><samp class="file">*.txt</samp></dt> +<dd><p>current contents of a single data entry (only available after make). +</p></dd> +</dl> +</div> +</div> +<hr> +<div class="nav-panel"> +<p> +Previous: <a href="dev.html">Development</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> + + + +</body> +</html>