navigation.html (7308B)
1 <!DOCTYPE html> 2 <html> 3 <!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ --> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 6 <!-- Released 2023 under AGPL3 --> 7 <title>navigation (vise)</title> 8 9 <meta name="description" content="navigation (vise)"> 10 <meta name="keywords" content="navigation (vise)"> 11 <meta name="resource-type" content="document"> 12 <meta name="distribution" content="global"> 13 <meta name="Generator" content="makeinfo"> 14 <meta name="viewport" content="width=device-width,initial-scale=1"> 15 16 <link href="index.html" rel="start" title="Top"> 17 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 18 <link href="index.html" rel="up" title="Top"> 19 <link href="cache.html" rel="next" title="cache"> 20 <link href="instructions.html" rel="prev" title="instructions"> 21 <style type="text/css"> 22 <!-- 23 a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em} 24 span:hover a.copiable-link {visibility: visible} 25 ul.mark-bullet {list-style-type: disc} 26 --> 27 </style> 28 29 30 </head> 31 32 <body lang="en"> 33 <div class="chapter-level-extent" id="navigation"> 34 <div class="nav-panel"> 35 <p> 36 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> 37 </div> 38 <hr> 39 <h2 class="chapter" id="Navigation"><span>6 Navigation<a class="copiable-link" href="#Navigation"> ¶</a></span></h2> 40 41 42 <p>Nodes are navigated by name, using a navigation stack. 43 </p> 44 <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. 45 </p> 46 <p>Additionally, <em class="emph">lateral</em> movement is available, for nodes whose contents span mulitple pages. 47 </p> 48 49 <ul class="mini-toc"> 50 <li><a href="#Entry-point" accesskey="1">Entry point</a></li> 51 <li><a href="#Lateral-navigation" accesskey="2">Lateral navigation</a></li> 52 <li><a href="#Node-names" accesskey="3">Node names</a></li> 53 <li><a href="#Navigation-stack" accesskey="4">Navigation stack</a></li> 54 </ul> 55 <div class="section-level-extent" id="Entry-point"> 56 <h3 class="section"><span>6.1 Entry point<a class="copiable-link" href="#Entry-point"> ¶</a></span></h3> 57 58 <p>All VM executions require an <em class="emph">entry point</em>. 59 </p> 60 <p>If not explicitly set in the code, the node name <code class="code">root</code> is used. 61 </p> 62 <p>Attempting to navigate <em class="emph">up</em> from the entry point node will fail and terminate execution. 63 </p> 64 65 <a class="anchor" id="lateral_005fnavigation"></a></div> 66 <div class="section-level-extent" id="Lateral-navigation"> 67 <h3 class="section"><span>6.2 Lateral navigation<a class="copiable-link" href="#Lateral-navigation"> ¶</a></span></h3> 68 69 <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. 70 </p> 71 <p>Lateral navigation will fail and terminate execution when: 72 </p> 73 <ul class="itemize mark-bullet"> 74 <li>executing a single-page node. 75 </li><li>attempting <em class="emph">next</em> beyond the last page. 76 </li><li>attempting <em class="emph">previous</em> on the first page. 77 </li></ul> 78 79 80 <a class="anchor" id="node_005fnames"></a></div> 81 <div class="section-level-extent" id="Node-names"> 82 <h3 class="section"><span>6.3 Node names<a class="copiable-link" href="#Node-names"> ¶</a></span></h3> 83 84 <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. 85 </p> 86 <ul class="mini-toc"> 87 <li><a href="#Special-node-names" accesskey="1">Special node names</a></li> 88 <li><a href="#Builtin-node-names" accesskey="2">Builtin node names</a></li> 89 </ul> 90 <div class="subsection-level-extent" id="Special-node-names"> 91 <h4 class="subsection"><span>6.3.1 Special node names<a class="copiable-link" href="#Special-node-names"> ¶</a></span></h4> 92 93 <p>A selection of special node names are available for relative navigation. They are single-character tokens, listed below with their respective ASCII codes. 94 </p> 95 <dl class="table"> 96 <dt><code class="code">. (0x2E)</code></dt> 97 <dd><p>Repeat the same node. 98 </p></dd> 99 <dt><code class="code">_ (0x5F)</code></dt> 100 <dd><p>Go to the previous node in the stack. 101 </p></dd> 102 <dt><code class="code">> (0x3E)</code></dt> 103 <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. 104 </p></dd> 105 <dt><code class="code">< (0x3C)</code></dt> 106 <dd><p>Go to the next page of a multi-page node. Will fail if used on the first (or single) page. 107 </p></dd> 108 <dt><code class="code">^ (0x5E)</code></dt> 109 <dd><p>Go to the topmost node. Will execute each intermediate node in the stack. 110 </p></dd> 111 </dl> 112 113 114 </div> 115 <div class="subsection-level-extent" id="Builtin-node-names"> 116 <h4 class="subsection"><span>6.3.2 Builtin node names<a class="copiable-link" href="#Builtin-node-names"> ¶</a></span></h4> 117 118 <p>Uncaught exceptions in the code flow that should not halt execution are routed to a builtin node named <code class="code">_catch</code>. 119 </p> 120 121 </div> 122 </div> 123 <div class="section-level-extent" id="Navigation-stack"> 124 <h3 class="section"><span>6.4 Navigation stack<a class="copiable-link" href="#Navigation-stack"> ¶</a></span></h3> 125 126 <p>Consider the following navigation example, illustrating the state of the stack for each step after execution. 127 </p> 128 <table class="multitable"> 129 <thead><tr><th width="25%">instruction</th><th width="65%">stack</th><th width="10%">page index</th></tr></thead> 130 <tbody><tr><td width="25%"><code class="code">MOVE foo</code></td><td width="65%">foo</td><td width="10%">0</td></tr> 131 <tr><td width="25%"><code class="code">MOVE bar</code></td><td width="65%">foo/bar</td><td width="10%">0</td></tr> 132 <tr><td width="25%"><code class="code">MOVE baz</code></td><td width="65%">foo/bar/baz</td><td width="10%">0</td></tr> 133 <tr><td width="25%"><code class="code">MOVE ></code></td><td width="65%">foo/bar/baz</td><td width="10%">1</td></tr> 134 <tr><td width="25%"><code class="code">MOVE ></code></td><td width="65%">foo/bar/baz</td><td width="10%">2</td></tr> 135 <tr><td width="25%"><code class="code">MOVE <</code></td><td width="65%">foo/bar/baz</td><td width="10%">1</td></tr> 136 <tr><td width="25%"><code class="code">MOVE .</code></td><td width="65%">foo/bar/baz</td><td width="10%">1</td></tr> 137 <tr><td width="25%"><code class="code">MOVE _</code></td><td width="65%">foo/bar</td><td width="10%">0</td></tr> 138 <tr><td width="25%"><code class="code">MOVE baz</code></td><td width="65%">foo/bar/baz</td><td width="10%">0</td></tr> 139 <tr><td width="25%"><code class="code">MOVE ^</code></td><td width="65%">foo</td><td width="10%">0</td></tr> 140 </tbody> 141 </table> 142 143 144 </div> 145 </div> 146 <hr> 147 <div class="nav-panel"> 148 <p> 149 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> 150 </div> 151 152 153 154 </body> 155 </html>