render.html (14122B)
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>render (vise)</title> 8 9 <meta name="description" content="render (vise)"> 10 <meta name="keywords" content="render (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="language.html" rel="next" title="language"> 20 <link href="cache.html" rel="prev" title="cache"> 21 <style type="text/css"> 22 <!-- 23 a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em} 24 div.example {margin-left: 3.2em} 25 span:hover a.copiable-link {visibility: visible} 26 --> 27 </style> 28 29 30 </head> 31 32 <body lang="en"> 33 <div class="chapter-level-extent" id="render"> 34 <div class="nav-panel"> 35 <p> 36 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> 37 </div> 38 <hr> 39 <h2 class="chapter" id="Rendering"><span>8 Rendering<a class="copiable-link" href="#Rendering"> ¶</a></span></h2> 40 41 <p>Every node whose bytecode includes a <code class="code">HALT</code> statement <strong class="strong">MUST</strong> define a rendering template. 42 </p> 43 <p>Templates may be either static or dynamic. 44 </p> 45 46 <a class="anchor" id="dynamic_005ftemplates"></a><ul class="mini-toc"> 47 <li><a href="#Dynamic-templates" accesskey="1">Dynamic templates</a></li> 48 <li><a href="#Rendering-pipeline" accesskey="2">Rendering pipeline</a></li> 49 <li><a href="#Multiple_002dpage-rendering" accesskey="3">Multiple-page rendering</a></li> 50 </ul> 51 <div class="section-level-extent" id="Dynamic-templates"> 52 <h3 class="section"><span>8.1 Dynamic templates<a class="copiable-link" href="#Dynamic-templates"> ¶</a></span></h3> 53 54 <p>Using placeholders, the content behind <code class="code">MAP</code> calls in the current executing node may be embedded in the template. 55 </p> 56 <p>Placeholders have the following format: 57 </p><pre class="verbatim">{{.symbol}} 58 </pre><p>where <code class="code">symbol</code> is the corresponding argument to <code class="code">MAP</code>. 59 </p> 60 <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. 61 </p> 62 <ul class="mini-toc"> 63 <li><a href="#Examples" accesskey="1">Examples</a></li> 64 </ul> 65 <div class="subsection-level-extent" id="Examples"> 66 <h4 class="subsection"><span>8.1.1 Examples<a class="copiable-link" href="#Examples"> ¶</a></span></h4> 67 68 <p>Consider the following instruction sequence: 69 </p> 70 <div class="example"> 71 <pre class="example-preformatted">LOAD foo 32 72 MAP foo 73 HALT 74 </pre></div> 75 76 <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. 77 </p> 78 <p>However: 79 </p> 80 <div class="example"> 81 <pre class="example-preformatted">LOAD foo 32 82 HALT 83 </pre></div> 84 85 <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. 86 </p> 87 88 <div class="example"> 89 <pre class="example-preformatted">LOAD foo 32 90 MOVE bar 91 # (bar bytecode follows) 92 MAP foo 93 HALT 94 </pre></div> 95 96 <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. 97 </p> 98 <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. 99 </p> 100 <p>However: 101 </p> 102 <div class="example"> 103 <pre class="example-preformatted">LOAD foo 32 104 MOVE bar 105 # (bar bytecode follows) 106 MAP foo 107 MOVE baz 108 # (baz bytecode follows) 109 HALT 110 </pre></div> 111 112 <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>. 113 </p> 114 115 </div> 116 </div> 117 <div class="section-level-extent" id="Rendering-pipeline"> 118 <h3 class="section"><span>8.2 Rendering pipeline<a class="copiable-link" href="#Rendering-pipeline"> ¶</a></span></h3> 119 120 <p>The pipeline starts with the loading of the template corresponding to the current execution node. 121 </p> 122 <p>From there, three branches are possible: 123 </p> 124 <ol class="enumerate"> 125 <li> No <em class="emph">sink</em> has been defined. 126 </li><li> One of the encountered <code class="code">MAP</code> symbols resolves to a <em class="emph">sink</em>. 127 </li><li> <code class="code">MSINK</code> has been encountered. 128 </li></ol> 129 130 <p>If the resulting output from any of these branches is larger than the output size, failure ensues and execution is terminated. 131 </p> 132 133 <ul class="mini-toc"> 134 <li><a href="#No-sink" accesskey="1">No sink</a></li> 135 <li><a href="#MAP-sink" accesskey="2">MAP sink</a></li> 136 <li><a href="#Menu-sink" accesskey="3">Menu sink</a></li> 137 </ul> 138 <div class="subsection-level-extent" id="No-sink"> 139 <h4 class="subsection"><span>8.2.1 No sink<a class="copiable-link" href="#No-sink"> ¶</a></span></h4> 140 141 <ol class="enumerate"> 142 <li> Expand all placeholders in the template. 143 </li><li> Expand all menu items 144 </li></ol> 145 146 147 <a class="anchor" id="map_005fsink"></a></div> 148 <div class="subsection-level-extent" id="MAP-sink"> 149 <h4 class="subsection"><span>8.2.2 MAP sink<a class="copiable-link" href="#MAP-sink"> ¶</a></span></h4> 150 151 <ol class="enumerate"> 152 <li> Expand all non-sink placeholders in the template. 153 </li><li> Expand all menu items. 154 </li><li> Group sink items up to the remaining output size. 155 </li><li> If any item alone exceeds the remaining output size, fail and terminate execution. 156 </li><li> If any item together with the lateral navigation menu items exceed the remaining output size, fail and terminate execution. 157 </li><li> Check the page navigation index (see <a class="ref" href="navigation.html#lateral_005fnavigation">Lateral navigation</a>). 158 </li><li> Replace sink symbol result with group item corresponding to navigation index. 159 </li><li> Expand all sink placeholders in the template. 160 </li><li> Expand all menu items (including lateral navigation). 161 </li></ol> 162 163 164 </div> 165 <div class="subsection-level-extent" id="Menu-sink"> 166 <h4 class="subsection"><span>8.2.3 Menu sink<a class="copiable-link" href="#Menu-sink"> ¶</a></span></h4> 167 168 <ol class="enumerate"> 169 <li> Remove all menu items (any following menu expansion will only contain lateral navigation items, when and if they apply). 170 </li><li> Copy menu items to sink placeholder. 171 </li><li> Continue from <a class="ref" href="#map_005fsink">MAP sink</a>. 172 </li></ol> 173 174 175 <a class="anchor" id="render_005fmulti"></a></div> 176 </div> 177 <div class="section-level-extent" id="Multiple_002dpage-rendering"> 178 <h3 class="section"><span>8.3 Multiple-page rendering<a class="copiable-link" href="#Multiple_002dpage-rendering"> ¶</a></span></h3> 179 180 <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>). 181 </p> 182 <p>The result is split into rows using newline (<code class="code">0x0a</code>) as separator. 183 </p> 184 185 <ul class="mini-toc"> 186 <li><a href="#Missing-navigation" accesskey="1">Missing navigation</a></li> 187 <li><a href="#Multi_002dpage-example" accesskey="2">Multi-page example</a></li> 188 </ul> 189 <div class="subsection-level-extent" id="Missing-navigation"> 190 <h4 class="subsection"><span>8.3.1 Missing navigation<a class="copiable-link" href="#Missing-navigation"> ¶</a></span></h4> 191 192 <p>If no <em class="emph">lateral navigation</em> has been activated, any sinks will still be processed. 193 </p> 194 <p>The sink placeholder will then be replaced with the first item in the group. 195 </p> 196 197 </div> 198 <div class="subsection-level-extent" id="Multi_002dpage-example"> 199 <h4 class="subsection"><span>8.3.2 Multi-page example<a class="copiable-link" href="#Multi_002dpage-example"> ¶</a></span></h4> 200 201 <p>Consider the following instruction sequence: 202 </p> 203 <div class="example"> 204 <pre class="example-preformatted">LOAD foo 8 205 LOAD bar 16 206 LOAD baz 0 207 MAP foo 208 MAP bar 209 MAP baz 210 MOUT to_foo 0 211 MOUT to_bar 1 212 MNEXT to_next 11 213 MPREV to_prev 22 214 HALT 215 INCMP foo 0 216 INCMP bar 1 217 INCMP > 11 218 INCMP < 22 219 </pre></div> 220 221 <p>... and the following template (14 bytes, without the placeholders, including line break): 222 </p> 223 <pre class="verbatim">This is {{.foo}} and {{.bar}} 224 {{.baz}} 225 </pre> 226 227 <ul class="mini-toc"> 228 <li><a href="#Data-accounting" accesskey="1">Data accounting</a></li> 229 <li><a href="#Rendering-logic" accesskey="2">Rendering logic</a></li> 230 </ul> 231 <div class="subsubsection-level-extent" id="Data-accounting"> 232 <h4 class="subsubsection"><span>8.3.2.1 Data accounting<a class="copiable-link" href="#Data-accounting"> ¶</a></span></h4> 233 234 <p>Then consider that the symbols resolve as follows: 235 </p> 236 <table class="multitable"> 237 <thead><tr><th width="10%">symbol</th><th width="25%">returned value</th><th width="50%">rendered value</th><th width="15%">bytes</th></tr></thead> 238 <tbody><tr><td width="10%"><code class="code">foo</code></td><td width="25%"><code class="code">foobar</code></td><td width="50%"><code class="code">foobar</code></td><td width="15%">6</td></tr> 239 <tr><td width="10%"><code class="code">bar</code></td><td width="25%"><code class="code">barbarbar</code></td><td width="50%"><code class="code">barbarbar</code></td><td width="15%">9</td></tr> 240 <tr><td width="10%"><code class="code">baz</code></td><td width="25%"><pre class="verbatim">FOO 42 241 BAR 13 242 BAZ 666 243 XYZZY 1984 244 INKY 1 245 PINKY 22 246 BLINKY 333 247 CLYDE 4444 248 </pre></td><td width="50%">(deferred)</td><td width="15%">(71)</td></tr> 249 <tr><td width="10%"><code class="code">to_foo</code></td><td width="25%"><code class="code">go to foo</code></td><td width="50%"><code class="code">0:go to foo</code></td><td width="15%">11</td></tr> 250 <tr><td width="10%"><code class="code">to_bar</code></td><td width="25%"><code class="code">visit the bar</code></td><td width="50%"><code class="code">1:visit the bar</code></td><td width="15%">15</td></tr> 251 <tr><td width="10%"><code class="code">to_next</code></td><td width="25%"><code class="code">next page</code></td><td width="50%"><code class="code">11:next page</code></td><td width="15%">12</td></tr> 252 <tr><td width="10%"><code class="code">to_prev</code></td><td width="25%"><code class="code">go back</code></td><td width="50%"><code class="code">22:go back</code></td><td width="15%">10</td></tr> 253 </tbody> 254 </table> 255 256 <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: 257 </p> 258 <table class="multitable"> 259 <thead><tr><th width="33%">navigation case</th><th width="33%">bytes left for sink</th></tr></thead> 260 <tbody><tr><td width="33%">no navigation</td><td width="33%">39</td></tr> 261 <tr><td width="33%">next</td><td width="33%">27</td></tr> 262 <tr><td width="33%">previous</td><td width="33%">29</td></tr> 263 <tr><td width="33%">next + previous</td><td width="33%">17</td></tr> 264 </tbody> 265 </table> 266 267 268 </div> 269 <div class="subsubsection-level-extent" id="Rendering-logic"> 270 <h4 class="subsubsection"><span>8.3.2.2 Rendering logic<a class="copiable-link" href="#Rendering-logic"> ¶</a></span></h4> 271 272 <p>The total sink byte count is 72, whereas the maximum available sink capacity is 39. At least one extra page is needed. 273 </p> 274 <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: 275 </p> 276 <div class="example"> 277 <pre class="example-preformatted">This is foobar and barbarbar 278 FOO 42 279 BAR 13 280 BAZ 666 281 0:go to foo 282 1:visit the bar 283 11:next page 284 </pre></div> 285 286 <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: 287 </p> 288 <div class="example"> 289 <pre class="example-preformatted">This is foobar and barbarbar 290 XYZZY 1984 291 0:go to foo 292 1:visit the bar 293 11:next page 294 22:go back 295 </pre></div> 296 297 <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: 298 </p> 299 <div class="example"> 300 <pre class="example-preformatted">This is foobar and barbarbar 301 INKY 1 302 PINKY 22 303 0:go to foo 304 1:visit the bar 305 11:next page 306 22:go back 307 </pre></div> 308 309 <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: 310 </p> 311 312 <div class="example"> 313 <pre class="example-preformatted">This is foobar and barbarbar 314 BLINKY 333 315 CLYDE 4444 316 0:go to foo 317 1:visit the bar 318 22:go back 319 </pre></div> 320 </div> 321 </div> 322 </div> 323 </div> 324 <hr> 325 <div class="nav-panel"> 326 <p> 327 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> 328 </div> 329 330 331 332 </body> 333 </html>