sim.html (11640B)
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>sim (vise)</title> 8 9 <meta name="description" content="sim (vise)"> 10 <meta name="keywords" content="sim (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="nomenclature.html" rel="next" title="nomenclature"> 20 <link href="overview.html" rel="prev" title="overview"> 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 ul.mark-bullet {list-style-type: disc} 27 --> 28 </style> 29 30 31 </head> 32 33 <body lang="en"> 34 <div class="chapter-level-extent" id="sim"> 35 <div class="nav-panel"> 36 <p> 37 Next: <a href="nomenclature.html" accesskey="n" rel="next">Nomenclature</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> 38 </div> 39 <hr> 40 <h2 class="chapter" id="An-example-vise-implementation"><span>2 An example vise implementation<a class="copiable-link" href="#An-example-vise-implementation"> ¶</a></span></h2> 41 42 43 <p>Consider the following interaction: 44 </p> 45 <div class="example"> 46 <pre class="example-preformatted">This is the root page 47 You have visited 1 time. 48 0:foo 49 1:bar 50 51 $ 1 52 Please visit foo first. 53 Any input to return. 54 55 $ x 56 This is the root page. 57 You have visited 2 times. 58 0:foo 59 1:bar 60 61 $ 0 62 Welcome to page foo. 63 Please write seomthing. 64 65 $ blah blah blah 66 This is the root page. 67 You have visited 3 times. 68 0:foo 69 1:bar 70 71 $ 1 72 Thanks for visiting foo and bar. 73 You have written: 74 blah blah blah 75 </pre></div> 76 77 <p>The simple interface above involves four different menu nodes. 78 </p> 79 <p>In order to engineer these using vise, three types of components are involved: 80 </p> 81 <ul class="itemize mark-bullet"> 82 <li>An assembly-like menu handling script. 83 </li><li>A display template. 84 </li><li>External code handlers for the counter and the "something" input. 85 </li></ul> 86 87 88 89 <p>The nodes are: 90 </p> 91 <dl class="table"> 92 <dt><code class="code">root</code></dt> 93 <dd><p>The first page. 94 </p></dd> 95 <dt><code class="code">foo</code></dt> 96 <dd><p>The "foo" page. 97 </p></dd> 98 <dt><code class="code">bar</code></dt> 99 <dd><p>The "bar" page after "foo" has been visited. 100 </p></dd> 101 <dt><code class="code">ouch</code></dt> 102 <dd><p>The "bar" page before "foo" has been visited. 103 </p></dd> 104 </dl> 105 106 107 <ul class="mini-toc"> 108 <li><a href="#Templates" accesskey="1">Templates</a></li> 109 <li><a href="#Scripts" accesskey="2">Scripts</a></li> 110 <li><a href="#External-code-handlers" accesskey="3">External code handlers</a></li> 111 <li><a href="#Handling-long-values" accesskey="4">Handling long values</a></li> 112 <li><a href="#Working-example" accesskey="5">Working example</a></li> 113 </ul> 114 <div class="section-level-extent" id="Templates"> 115 <h3 class="section"><span>2.1 Templates<a class="copiable-link" href="#Templates"> ¶</a></span></h3> 116 117 <p>Each page has a template that may or may not contain dynamic elements. 118 </p> 119 <p>In this example the <code class="code">root</code> and <code class="code">bar</code> nodes contains dynamic content. 120 </p> 121 <ul class="mini-toc"> 122 <li><a href="#root" accesskey="1">root</a></li> 123 <li><a href="#foo" accesskey="2">foo</a></li> 124 <li><a href="#bar" accesskey="3">bar</a></li> 125 <li><a href="#ouch" accesskey="4">ouch</a></li> 126 </ul> 127 <div class="subsection-level-extent" id="root"> 128 <h4 class="subsection"><span>2.1.1 root<a class="copiable-link" href="#root"> ¶</a></span></h4> 129 130 <pre class="verbatim">This is the root page 131 You have visited {{.count}}. 132 </pre> 133 </div> 134 <div class="subsection-level-extent" id="foo"> 135 <h4 class="subsection"><span>2.1.2 foo<a class="copiable-link" href="#foo"> ¶</a></span></h4> 136 137 <pre class="verbatim">Welcome to page foo. 138 Please write something. 139 </pre> 140 </div> 141 <div class="subsection-level-extent" id="bar"> 142 <h4 class="subsection"><span>2.1.3 bar<a class="copiable-link" href="#bar"> ¶</a></span></h4> 143 144 <pre class="verbatim">Thanks for visiting foo and bar. 145 You wrote "{{.something}}" in foo. 146 </pre> 147 </div> 148 <div class="subsection-level-extent" id="ouch"> 149 <h4 class="subsection"><span>2.1.4 ouch<a class="copiable-link" href="#ouch"> ¶</a></span></h4> 150 151 <pre class="verbatim">Please visit foo first. 152 Any input to return. 153 </pre> 154 155 </div> 156 </div> 157 <div class="section-level-extent" id="Scripts"> 158 <h3 class="section"><span>2.2 Scripts<a class="copiable-link" href="#Scripts"> ¶</a></span></h3> 159 160 <p>The scripts are responsible for defining menus, handling navigation flow control, and triggering external code handlers. 161 </p> 162 <ul class="mini-toc"> 163 <li><a href="#root-1" accesskey="1">root</a></li> 164 <li><a href="#foo-1" accesskey="2">foo</a></li> 165 <li><a href="#bar-1" accesskey="3">bar</a></li> 166 <li><a href="#ouch-1" accesskey="4">ouch</a></li> 167 </ul> 168 <div class="subsection-level-extent" id="root-1"> 169 <h4 class="subsection"><span>2.2.1 root<a class="copiable-link" href="#root-1"> ¶</a></span></h4> 170 171 <pre class="verbatim">LOAD count 8 # trigger external code handler "count" 172 LOAD something 0 # trigger external code handler "something" 173 RELOAD count # explicitly trigger "count" every time this code is executed. 174 MAP count # make the result from "count" available to the template renderer 175 MOUT foo 0 # menu item 176 MOUT bar 1 # menu item 177 HALT # render template and wait for input 178 INCMP foo 0 # match menu selection 0, move to node "foo" on match 179 INCMP bar 1 # match menu selection 1, move to node "bar" on match 180 </pre> 181 </div> 182 <div class="subsection-level-extent" id="foo-1"> 183 <h4 class="subsection"><span>2.2.2 foo<a class="copiable-link" href="#foo-1"> ¶</a></span></h4> 184 185 <pre class="verbatim">HALT # render template and wait for input 186 RELOAD something # pass input to the "something" external code handler. 187 # The input will be appended to the stored value. 188 # The "HAVESOMETHING" flag (8) will be set. 189 MOVE _ # move up one level 190 </pre> 191 192 </div> 193 <div class="subsection-level-extent" id="bar-1"> 194 <h4 class="subsection"><span>2.2.3 bar<a class="copiable-link" href="#bar-1"> ¶</a></span></h4> 195 196 <pre class="verbatim">CATCH ouch 8 0 # if the "HAVESOMETHING" (8) flag has NOT (0) been set, move to "ouch" 197 MNEXT next 11 # menu choice to display for advancing one page 198 MPREV back 22 # menu choice to display for going back to the previous page 199 MAP something # make the result from "something" available to the template renderer 200 HALT # render template and wait for input 201 INCMP > 11 # handle the "next" menu choice 202 INCMP < 22 # handle to "back" menu choice 203 INCMP _ * # move to the root node on any input 204 </pre> 205 206 </div> 207 <div class="subsection-level-extent" id="ouch-1"> 208 <h4 class="subsection"><span>2.2.4 ouch<a class="copiable-link" href="#ouch-1"> ¶</a></span></h4> 209 210 <pre class="verbatim">HALT # render template and wait for input 211 INCMP ^ * # move to the root node on any input 212 </pre> 213 214 </div> 215 </div> 216 <div class="section-level-extent" id="External-code-handlers"> 217 <h3 class="section"><span>2.3 External code handlers<a class="copiable-link" href="#External-code-handlers"> ¶</a></span></h3> 218 219 <p>The script code contains <code class="code">LOAD</code> instructions for two different methods. 220 </p> 221 <pre class="verbatim">import ( 222 "context" 223 "fmt" 224 "path" 225 "strings" 226 227 228 testdataloader "github.com/peteole/testdata-loader" 229 230 "git.defalsify.org/vise.git/state" 231 "git.defalsify.org/vise.git/resource" 232 ) 233 234 const ( 235 USERFLAG_HAVESOMETHING = iota + state.FLAG_USERSTART 236 ) 237 238 var ( 239 baseDir = testdataloader.GetBasePath() 240 scriptDir = path.Join(baseDir, "examples", "intro") 241 ) 242 243 type introResource struct { 244 *resource.FsResource 245 c int64 246 v []string 247 } 248 249 func newintroResource() introResource { 250 fs := resource.NewFsResource(scriptDir) 251 return introResource{fs, 0, []string{}} 252 } 253 254 // increment counter. 255 // return a string representing the current value of the counter. 256 func(c *introResource) count(ctx context.Context, sym string, input []byte) (resource.Result, error) { 257 s := "%v time" 258 if c.c != 1 { 259 s += "s" 260 } 261 r := resource.Result{ 262 Content: fmt.Sprintf(s, c.c), 263 } 264 c.c += 1 265 return r, nil 266 } 267 268 // if input is suppled, append it to the stored string vector and set the HAVESOMETHING flag. 269 // return the stored string vector value, one string per line. 270 func(c *introResource) something(ctx context.Context, sym string, input []byte) (resource.Result, error) { 271 c.v = append(c.v, string(input)) 272 r := resource.Result{ 273 Content: strings.Join(c.v, "\n"), 274 } 275 if len(input) > 0 { 276 r.FlagSet = []uint32{USERFLAG_HAVESOMETHING} 277 } 278 return r, nil 279 } 280 </pre> 281 282 <a class="anchor" id="long_005fvalues"></a></div> 283 <div class="section-level-extent" id="Handling-long-values"> 284 <h3 class="section"><span>2.4 Handling long values<a class="copiable-link" href="#Handling-long-values"> ¶</a></span></h3> 285 286 <p>In the above example, the more times the <code class="code">foo</code> page is supplied with a value, the longer the vector of values that need to be displayed by the <code class="code">bar</code> page will be. 287 </p> 288 <p>A core feature of <code class="code">vise</code> is to magically create browseable pages from these values, from a pre-defined maximum output capacity for each page. 289 </p> 290 <p>Consider the case where the contents of the <code class="code">something</code> symbol has become: 291 </p> 292 <pre class="verbatim">foo bar 293 baz bazbaz 294 inky pinky 295 blinky 296 clyde 297 </pre> 298 <p>Given a size constaint of 90 characters, the display will be split into two pages: 299 </p> 300 <pre class="verbatim">Thanks for visiting foo and bar. 301 You have written: 302 foo bar 303 baz bazbaz 304 11:next 305 </pre> 306 <pre class="verbatim">Thanks for visiting foo and bar. 307 You have written: 308 inky pinky 309 blinky 310 clyde 311 22:back 312 </pre> 313 314 </div> 315 <div class="section-level-extent" id="Working-example"> 316 <h3 class="section"><span>2.5 Working example<a class="copiable-link" href="#Working-example"> ¶</a></span></h3> 317 318 <p>In the source code repository, a full working example of this menu can be found in <samp class="file">examples/intro</samp>. 319 </p> 320 <p>To run it: 321 </p> 322 <div class="example"> 323 <pre class="example-preformatted">make -B intro 324 go run ./examples/intro 325 </pre></div> 326 327 <p>Use <code class="code">go run -tags logtrace ...</code> to peek at what is going on under the hood. 328 </p> 329 <p>To play the <a class="ref" href="#long_005fvalues">Long Values</a> case above, limit the output size by adding <code class="code">-s 90</code>. 330 </p></div> 331 </div> 332 <hr> 333 <div class="nav-panel"> 334 <p> 335 Next: <a href="nomenclature.html">Nomenclature</a>, Previous: <a href="overview.html">Overview</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> 336 </div> 337 338 339 340 </body> 341 </html>