doc/language.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   4     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" >
   5 <head>
   6 <title>The Voodoo Programming Language</title>
   7 <link rel="stylesheet" href="style.css" type="text/css" />
   8 </head>
   9 <body>
  10 <div class="body">
  11 <h1>The Voodoo Programming Language</h1>
  12
  13
  14 <p class="first">This document describes version 1.1 of the Voodoo
  15 programming language. Definitions in this document have been marked
  16 with the version of the language in which they have been
  17 introduced. Definitions first introduced by this document have been
  18 marked with <strong class="since current">1.1</strong>.</p>
  19
  20 <h2>Hello World in Voodoo</h2>
  21
  22 <p class="first">To quickly get a feeling for a programming language,
  23 it is often instructive to look at a simple yet complete program.
  24 The following is an implementation of the traditional
  25 Hello World program in Voodoo:</p>
  26
  27 <pre><code>
  28 # Hello world in Voodoo
  29
  30 section data
  31 greeting:
  32 string "Hello, world!\x00"
  33
  34 section functions
  35 import puts
  36 export main
  37
  38 main:
  39 function argc argv
  40     call puts greeting
  41     return 0
  42 end function
  43 </code></pre>
  44
  45 <p class="first">When compiled and linked with a library that provides
  46 an appropriate implementation of the <code>puts</code> function, this
  47 program will print <q>Hello, world!</q>.</p>
  48
  49 <p>What follows is a more formal description of the Voodoo
  50 programming language.</p>
  51
  52 <h2>Overview</h2>
  53
  54 <p class="first">The source code of a Voodoo program consists of
  55 <em>incantations</em> (e.g. <code>set x 42</code>) that define the code
  56 and data of the program.  Each incantation starts with a <em>magic
  57 word</em> (e.g. <code>set</code>) and may have zero or
  58 more <em>parameters</em>. Any incantation may be preceded by
  59 a <em>label</em> (e.g. <code>foo:</code>), which can then be used in
  60 other parts of the program to refer to the <em>address</em> at which the
  61 incantation starts.</p>
  62
  63 <p>The basic units of data in Voodoo are <em>bytes</em>
  64 and <em>words</em>. The range and size of bytes and words is
  65 <em>implementation-defined</em>, which means that the definition
  66 is allowed to differ from one Voodoo implementation to another,
  67 and even in ways defined by a specific implementation, e.g. the
  68 same Voodoo implementation may use different word sizes for
  69 different target platforms.</p>
  70
  71 <p>Most incantations in Voodoo perform very simple operations, such as
  72 adding two numbers. In addition to these simple operations, Voodoo
  73 supports <em>blocks</em> and <em>functions</em>. A block provides a
  74 scope for <em>local variables</em> and automatically managed memory.
  75 Variables and memory allocated inside a block will automatically be
  76 de-allocated after the end of that block. Functions, like blocks,
  77 provide a scope for local variables and automatically managed memory.
  78 In addition, functions may accept <em>parameters</em>, which are local
  79 variables whose values are supplied by the <em>caller</em> of the
  80 function.</p>
  81
  82 <p>At run-time, entering a function or block creates a
  83 <em>frame</em> and makes it the new <em>active frame</em>. These
  84 frames form a chain which logically runs from the <em>top-level
  85 frame</em> at the top to the active frame at the bottom. The active
  86 frame determines what local variables are <em>accessible</em>.
  87 The magic word <code>goto</code> can be used to continue execution
  88 of the program at a given incantation, provided that incantation
  89 is in the scope corresponding to the active frame.</p>
  90
  91 <p>This document does not define the correct behavior of every
  92 possible Voodoo program. In places where the correct behavior is not
  93 defined (either through omission, or explicitly documented as being
  94 undefined), a Voodoo implementation is not required to implement any
  95 specific behavior. In particular, the behavior of a program that
  96 invokes undefined behavior at any point does not have to be repeatable
  97 or desirable. Later versions of the Voodoo language may define correct
  98 behavior for programs whose behavior is undefined under the current
  99 language version.</p>
 100
 101 <h2>Features</h2>
 102 <p class="first"><strong class="since current">1.1</strong> To aid authors and programs in
 103 generating code that is compatible with a particular Voodoo
 104 implementation, implementations should provide means to query their
 105 features. This document specifies a number of features as key-value
 106 pairs, where the key is the feature name, and the value is a string
 107 that provides additional information about the feature (as described
 108 in the specification of the feature).</p>
 109
 110 <p>Implementations may also advertise features not specified in this
 111 document. To prevent conflicts with future versions of Voodoo, these
 112 features should have names starting in a prefix that identifies the
 113 implementation that introduced the feature. Implementations are
 114 encouraged to use this mechanism to advertise support for extensions
 115 to the language specified by this document.</p>
 116
 117 <p>For language extensions advertised using the feature mechanism, it
 118 is recommended that the value of the feature be a version number, with
 119 higher versions being backward compatible with lower versions.
 120 Incompatible changes can be indicated by a different feature name,
 121 e.g. through a numeric suffix at the end of the feature name.</p>
 122
 123 <table summary="Features">
 124 <thead>
 125 <tr><th>Name</th><th>Description</th></tr>
 126 </thead>
 127 <tbody>
 128 <tr>
 129 <td>bits-per-word</td>
 130 <td>The value indicates the number of bits per word for the given
 131 implementation. E.g. <q>32</q>.</td>
 132 </tr>
 133 <tr>
 134 <td>byte-order</td>
 135 <td>Order of bytes in a word. The following values are defined:
 136 <dl>
 137 <dt>big-endian</dt>
 138 <dd>Bytes are ordered from most significant to least significant</dd>
 139 <dt>little-endian</dt>
 140 <dd>Bytes are ordered from least significant to most significant</dd>
 141 </dl></td>
 142 </tr>
 143 <tr>
 144 <td>bytes-per-word</td>
 145 <td>The number of bytes required to store a word. E.g. <q>4</q>.</td>
 146 </tr>
 147 <tr>
 148 <td>voodoo</td>
 149 <td>Version of the Voodoo language supported by the implementation.
 150 The version described in this document is <q>1.1</q>.</td>
 151 </tr>
 152 </tbody>
 153 </table>
 154 <h2>Tokens</h2>
 155 <h3>Comments</h3>
 156
 157 <p class="first"><strong class="since">1.0</strong> Comments start with a hash mark (#)
 158 and run until the end of the line. The following is an example
 159 comment:</p>
 160
 161 <pre><code>
 162 # This is an example comment
 163 </code></pre>
 164
 165 <h3>Integers</h3>
 166
 167 <p class="first"><strong class="since">1.0</strong> Integers consist of an optional
 168 plus or minus sign, followed by one or more digits. Examples of valid
 169 integers:</p>
 170
 171 <pre><code>
 172 0
 173 +12
 174 -1
 175 </code></pre>
 176
 177 <h3>Strings</h3>
 178
 179 <p class="first"><strong class="since">1.0</strong> Strings consist of zero or more
 180 bytes enclosed in double quotes. An escape mechanism is provided to
 181 allow bytes of any value to be included in strings (see
 182 <a href="#escape_sequences">Escape Sequences</a> for details).
 183 Examples of valid strings:</p>
 184
 185 <pre><code>
 186 ""
 187 "Hello, world!"
 188 "some \"escape\x00 sequences"
 189 </code></pre>
 190
 191 <h3>Symbols</h3>
 192
 193 <p class="first"><strong class="since">1.0</strong> Symbols consist of letters, digits,
 194 underscores, hyphens, and escape sequences. Only a letter, underscore,
 195 or escape sequence may be used for the first byte of a
 196 symbol. Although this definition allows any byte to be part of a
 197 symbol, not all symbol names may be compatible with all target
 198 platforms. This document does not specify how implementations
 199 should represent symbols, and thus does not require that all
 200 syntactically valid symbols be usable on every implementation on
 201 every target platform. Examples of valid symbols:</p>
 202
 203 <pre><code>
 204 foo
 205 some_symbol
 206 </code></pre>
 207
 208 <h3>Substitute Tokens</h3>
 209
 210 <p class="first"><strong class="since current">1.1</strong> To aid in the writing of programs
 211 that are portable to multiple target platforms and Voodoo implementations,
 212 Voodoo defines a number of tokens that implementations must substitute
 213 appropriate values for.</p>
 214
 215 <p>A symbol prefixed by a percent character (%) must be treated as
 216 equivalent to an integer value. The following table shows the percent
 217 substitutes that must be recognized by Voodoo implementations:</p>
 218
 219 <table summary="Percent substitutes"><tr>
 220 <th>Symbol</th>
 221 <th>Meaning</th>
 222 </tr><tr>
 223 <td><code>%saved-frame-size</code></td>
 224 <td>The number of bytes required to save a frame</td>
 225 </tr><tr>
 226 <td>any feature that maps to an integer</td>
 227 <td>the integer value of the feature</td>
 228 </tr></table>
 229
 230 <p class="first">The effect of using a substitute token whose meaning
 231 is not defined above is undefined.</p>
 232
 233 <p>Examples of valid substitute tokens:</p>
 234
 235 <table summary="Substitute token examples"><tr>
 236 <td><code>%bytes-per-word</code></td>
 237 <td>number of bytes per word</td>
 238 </tr></table>
 239
 240 <h2>Escape Sequences</h2>
 241
 242 <p class="first"><strong class="since">1.0</strong> To facilitate entering bytes that
 243 may be treated differently by different systems and to inhibit the
 244 special meaning certain bytes normally have, an escape mechanism is
 245 provided. For example, the escape mechanism can be used to create
 246 strings that contain double quotes, or to spread a single incantation
 247 over multiple lines. Escape sequences start with a backslash, and have
 248 the following meanings:</p>
 249
 250 <table summary="Special bytes"><tr>
 251 <td><code>\\</code></td>
 252 <td>An actual backslash</td>
 253 </tr><tr>
 254 <td><code>\"</code></td>
 255 <td>A double quote</td>
 256 </tr><tr>
 257 <td><code>\n</code></td>
 258 <td>A newline</td>
 259 </tr><tr>
 260 <td><code>\r</code></td>
 261 <td>A carriage return</td>
 262 </tr><tr>
 263 <td><code>\t</code></td>
 264 <td>A tab</td>
 265 </tr><tr>
 266 <td><code>\x<var>XX</var></code></td>
 267 <td>The byte with hexadecimal value <var>XX</var></td>
 268 </tr><tr>
 269 <td><code>\&lt;space&gt;</code></td>
 270 <td>A space</td>
 271 </tr><tr>
 272 <td><code>\&lt;newline&gt;</code></td>
 273 <td>Line continuation. The newline
 274 and any leading whitespace on the next line
 275 is ignored.</td>
 276 </tr></table>
 277
 278 <p class="first">Examples of the usage of escape sequences:</p>
 279
 280 <table summary="Example Escape Sequences"><tr>
 281 <td><code>"Hello&nbsp;world\n"</code></td>
 282 <td>A string with a newline in it</td>
 283 </tr><tr>
 284 <td><code>"\\\""</code></td>
 285 <td>A string consisting of a backslash followed by a double quote</td>
 286 </tr><tr>
 287 <td><code>call foo \<br />
 288  bar</code></td>
 289 <td>Same as: <code>call&nbsp;foo&nbsp;bar</code></td>
 290 </tr></table>
 291
 292 <h2>Labels</h2>
 293
 294 <p class="first"><strong class="since">1.0</strong> Places in a program can be marked
 295 with labels, so that the place can be referred to from the code by
 296 mentioning the label. A label consists of a symbol followed by a
 297 colon. When referring to a label, only the symbol is used, without the
 298 colon.</p>
 299
 300 <p class="first">For example:</p>
 301
 302 <pre><code>
 303 foo:
 304 word 12
 305 </code></pre>
 306
 307 <p class="first">declares a word with the value 12, and a label 'foo'
 308 that refers to the place where this value is stored. For example, if
 309 the value happens to be loaded at the address 71234, writing 'foo' in
 310 the program will have the same effect as writing 71234 in the same
 311 place.</p>
 312
 313 <h2>Values</h2>
 314
 315 <p class="first"><strong class="since">1.0</strong> Values are the smallest unit of
 316 data in a Voodoo program. Examples of values are:</p>
 317
 318 <table summary="Example Values"><tr>
 319 <td><code>12</code></td>
 320 <td>The integer 12</td>
 321 </tr><tr>
 322 <td><code>x</code></td>
 323 <td>The value of x (may be a label or a local variable)</td>
 324 </tr></table>
 325
 326 <h2>At-Expressions</h2>
 327
 328 <p class="first"><strong class="since">1.0</strong> The character @ can be used to
 329 denote the value at some address. An address prefixed with @ denotes
 330 the word stored at that address, rather than the address itself. The
 331 address may be an integer, a local variable, or a label. For
 332 example:</p>
 333
 334 <table summary="Example at-expressions"><tr>
 335 <td><code>@12</code></td>
 336 <td>The word stored at address 12</td>
 337 </tr><tr>
 338 <td><code>@x</code></td>
 339 <td>The word stored at address x</td>
 340 </tr></table>
 341
 342 <p class="first">Syntactically, at-expressions are values. Therefore,
 343 in any place where a value can be used, an at-expression can also be
 344 used.</p>
 345
 346 <h2>Sections</h2>
 347
 348 <p class="first"><strong class="since">1.0</strong> A Voodoo program is divided in a number of sections.
 349 In source code, these are introduced by an incantation of the form
 350 <code>section &lt;identifier&gt;</code>, where &lt;identifier&gt; is an
 351 identifier for the section.</p>
 352
 353 <p>The following section identifiers are valid:</p>
 354
 355 <table summary="Section Identifiers"><tr>
 356 <th>Identifier</th>
 357 <th>Meaning</th>
 358 </tr><tr>
 359 <td><code>code</code></td>
 360 <td>This section contains executable code</td>
 361 </tr><tr>
 362 <td><code>data</code></td>
 363 <td>This section contains data</td>
 364 </tr><tr>
 365 <td><code>functions</code></td>
 366 <td>This section contains function definitions</td>
 367 </tr></table>
 368
 369 <p class="first">Example usage of the <code>section</code> incantation:</p>
 370
 371 <pre><code>
 372 section data
 373 # define data here ...
 374
 375 section functions
 376 # define functions here ...
 377 </code></pre>
 378
 379 <p class="first">Sections may appear in the source code in any order.
 380 The same section name may be used multiple times, in which case the
 381 contents of the section will be the concatenation of the contents of
 382 the multiple places in which it is defined.</p>
 383
 384 <h2>Data Definitions</h2>
 385
 386 <p class="first"><strong class="since">1.0</strong> Data can be inserted into a Voodoo
 387 program by means of the magic
 388 words <code>byte</code>, <code>word</code>, and
 389 <code>string</code>, followed by the value of the byte, word, or
 390 string to be inserted. For example:</p>
 391
 392 <pre><code>
 393 # A byte with value 42
 394 byte 42
 395
 396 # A word with value -1
 397 word -1
 398
 399 # The string "hello"
 400 string "hello"
 401 </code></pre>
 402
 403 <h2>Groups</h2>
 404
 405 <p class="first"><strong class="since current">1.1</strong> Groups are a mechanism to group
 406 multiple data definitions into a single unit. For example, to define
 407 a data structure consisting of a word and two bytes:</p>
 408
 409 <pre><code>
 410 example:
 411 group
 412     word 42
 413     byte 0
 414     byte 1
 415 end group
 416 </code></pre>
 417
 418 <h2>Import and Export</h2>
 419
 420 <p class="first"><strong class="since">1.0</strong> To allow Voodoo programs to refer to definitions in
 421 other files, and to allow other files to refer to definitions in
 422 Voodoo programs, the magic words <code>import</code>
 423 and <code>export</code> are used.</p>
 424
 425 <p>Using <code>import</code>, definitions from elsewhere are made
 426 available to a Voodoo program:</p>
 427
 428 <pre><code>
 429 section data
 430 import stderr
 431
 432 section functions
 433 import fputs
 434
 435 # We can now refer to stderr and fputs
 436 </code></pre>
 437
 438 <p>Data and functions defined in a Voodoo program can be made
 439 available to other programs using <code>export</code>:</p>
 440
 441 <pre><code>
 442 section data
 443 export answer
 444
 445 answer:
 446 word 42
 447
 448 section functions
 449 export foo
 450
 451 foo:
 452 function
 453   # some code here
 454 end function
 455 </code></pre>
 456
 457 <p><code>export</code> exports the first definition that follows it.
 458 Groups can be used to group together data that must be exported as a
 459 single unit.</p>
 460
 461 <h2>Alignment</h2>
 462
 463 <p class="first"><strong class="since">1.0</strong> Many architectures require that data and/or code
 464 observe certain alignment restrictions. For example, an architecture may
 465 require that a word of data be at an address that is a multiple of the
 466 word size. Voodoo provides the magic word <code>align</code>, which
 467 specifies the alignment for the next program element.</p>
 468
 469 <p>Without any parameters, <code>align</code> inserts filler bytes
 470 into the current section, so that the next element added to the section
 471 will respect the default alignment for the section. The default
 472 alignment for each section is implementation-defined, but must ensure
 473 that the alignment restrictions of the target platform are observed.</p>
 474
 475 <p>When written as <code>align &lt;n&gt;</code>, where &lt;n&gt; is an
 476 integer, the incantation will insert filler bytes as necessary to align
 477 the next element to be added to the section on a multiple of &lt;n&gt;
 478 bytes.</p>
 479
 480 <p>The filler bytes inserted by <code>align</code> are unspecified.
 481 In particular, they are not guaranteed to be valid code.</p>
 482
 483 <p>Example uses of the <code>align</code> incantation:</p>
 484
 485 <pre><code>
 486 section data
 487
 488 x:
 489 byte 1
 490
 491 # Ensure that y is aligned according to
 492 # the target platform's alignment restrictions
 493 align
 494 y:
 495 word 42
 496
 497
 498
 499 section functions
 500
 501 # Ensure that foo is aligned according to
 502 # the target platform's alignment restrictions
 503 align
 504 foo:
 505 function n
 506     # some code here
 507 end function
 508 </code></pre>
 509
 510 <h2>Actions</h2>
 511
 512 <p class="first">Voodoo code consists of actions. Actions consist of a
 513 magic word, usually followed by a number of values. This section lists
 514 all actions supported by Voodoo. In the list below, '&lt;x&gt;',
 515 '&lt;y&gt;', and '&lt;z&gt;' denote values, '&lt;symbol&gt;' denotes a
 516 symbol, and '&lt;expr&gt;' denotes an expression.  (expressions are
 517 discussed further on). Ellipsis (&hellip;) is used to denote that more
 518 items may follow, and square brackets ([ and ]) are used to denote
 519 that an item is optional.</p>
 520
 521 <dl>
 522
 523 <dt><strong class="since">1.0</strong> <code>call &lt;x&gt; &lt;y&gt; &lt;z&gt;
 524 &hellip;</code></dt>
 525 <dd><p class="first">Calls the function &lt;x&gt; with the parameters &lt;y&gt;
 526 &lt;z&gt; &hellip;. There may be zero or more parameters.</p></dd>
 527
 528 <dt><strong class="since">1.0</strong> <code>goto &lt;x&gt;</code></dt>
 529 <dd><p class="first">Continues the program at location &lt;x&gt;,
 530 rather than at the next action after the goto.</p>
 531
 532 <p>Any value can be used as the location to go to. However, the
 533 consequences of using <code>goto</code> to jump to a label outside
 534 the active frame are undefined. Since frames are introduced by
 535 blocks and functions, this means that <code>goto</code> should
 536 not jump to a label in a different block or function, unless the
 537 frame of that block or function has been restored using
 538 <code>restore-frame</code>.</p></dd>
 539
 540 <dt><strong class="since">1.0</strong> <code>let &lt;symbol&gt; &lt;expr&gt;</code></dt>
 541 <dd><p class="first">Introduces a local variable &lt;symbol&gt;, and
 542 initializes it to the result of evaluating &lt;expr&gt;.</p>
 543
 544 <p>This action is only allowed inside functions or blocks, that is,
 545 between <code>function</code> and the corresponding
 546 <code>end function</code>, or between <code>block</code> and the
 547 corresponding <code>end block</code>.</p>
 548
 549 <p>The scope of a variable introduced by <code>let</code> includes
 550 every statement after the <code>let</code> action and before the
 551 <code>end function</code> or <code>end block</code> that ends the
 552 function or block in which the variable is introduced.</p></dd>
 553
 554 <dt><strong class="since current">1.1</strong> <code>restore-frame &lt;x&gt;</code></dt>
 555
 556 <dd><p class="first">Restores a frame that was saved at address
 557 &lt;x&gt;. After this action, any frames below the restored frame
 558 are no longer valid. The behavior of <code>restore-frame</code> is
 559 undefined if &lt;x&gt; does not contain valid frame information.
 560 The values of local variables are undefined after
 561 <code>restore-frame</code> is performed.</p></dd>
 562
 563 <dt><strong class="since current">1.1</strong> <code>restore-locals &lt;x&gt;
 564     [&lt;locals&gt;]</code></dt>
 565
 566 <dd><p class="first">Sets local variables to values that have been
 567 stored at address &lt;x&gt;. If one or more local variables are
 568 specified, restores the specified local variables. Else, restores
 569 all local variables in scope. The behavior is undefined if the
 570 information saved at &lt;x&gt; does not contain a value for any of
 571 the variables to be restored.</p></dd>
 572
 573 <dt><strong class="since">1.0</strong> <code>return [&lt;expr&gt;]</code></dt>
 574 <dd><p class="first">Returns from the current function.
 575 If &lt;expr&gt; is specified, it is evaluated and the function returns
 576 the result of the evaluation. Otherwise, the return value is
 577 unspecified.</p></dd>
 578
 579 <dt><strong class="since current">1.1</strong> <code>save-frame &lt;x&gt;</code></dt>
 580
 581 <dd><p class="first">Saves information about the current frame to
 582 a block of memory at address &lt;x&gt;. The block of memory must be
 583 large enough to hold the required information. Allocating
 584 <code>%saved-frame-size</code> bytes ensures a block of memory large
 585 enough to hold a saved frame.</p></dd>
 586
 587 <dt><strong class="since current">1.1</strong> <code>save-frame-and-locals &lt;x&gt;
 588     [&lt;locals&gt;]</code></dt>
 589
 590 <dd><p class="first">Saves information about the current frame and
 591 local variables to a block of memory at address &lt;x&gt;. If one or
 592 more local variables are specified, at least the named local variables
 593 are saved. If no local variables are specified, all local variables
 594 are saved.</p>
 595
 596 <p>The block of memory starting at &lt;x&gt; must be large enough to
 597 hold the required
 598 information. Allocating <code>%saved-frame-size</code> bytes ensures a
 599 block of memory large enough to hold a saved frame plus local
 600 variables.</p></dd>
 601
 602 <dt><strong class="since current">1.1</strong> <code>save-locals &lt;x&gt; [&lt;locals&gt;]</code></dt>
 603
 604 <dd><p class="first">Saves local variables to a block of memory at
 605 address &lt;x&gt;. If one or more local variables are specified, at least the
 606 named local variables are saved. If no local variables are specified,
 607 all local variables are saved.</p>
 608
 609 <p>The block of memory starting at &lt;x&gt; must be large enough to
 610 hold the required
 611 information. Allocating <code>%saved-frame-size</code> bytes ensures a
 612 block of memory that is large enough.</p>
 613
 614 <p>This action does not invalidate frame information or local
 615 variables previously stored at &lt;x&gt;, except for updating the
 616 stored values for the local variables it saves to the values these
 617 local variables currently have.</p>
 618 </dd>
 619
 620 <dt><strong class="since">1.0</strong> <code>set &lt;symbol&gt; &lt;expr&gt;</code></dt>
 621 <dd><p class="first">Evaluates &lt;expr&gt; and assigns the result to
 622 &lt;symbol&gt;. &lt;symbol&gt; may not be a label, because labels cannot be
 623 assigned to.</p></dd>
 624
 625 <dt><strong class="since current">1.1</strong> <code>set &lt;at-expr&gt; &lt;expr&gt;</code></dt>
 626 <dd><p class="first">Evaluates &lt;expr&gt; and stores the result at
 627 the address specified by the at-expression &lt;at-expr&gt;.</p></dd>
 628
 629 <dt><strong class="since">1.0</strong> <code>set-byte &lt;base&gt; &lt;offset&gt; &lt;x&gt;</code></dt>
 630 <dd><p class="first">Sets the byte at &lt;base&gt; + &lt;offset&gt; to &lt;x&gt;.
 631 &lt;offset&gt; is given as a number of bytes.</p></dd>
 632
 633 <dt><strong class="since">1.0</strong> <code>set-word &lt;base&gt; &lt;offset&gt; &lt;x&gt;</code></dt>
 634 <dd><p class="first">Sets the word at &lt;base&gt; + WORDSIZE *
 635 &lt;offset&gt; to &lt;x&gt;.</p>
 636
 637 <p>The address computed by &lt;base&gt; + WORDSIZE * &lt;offset&gt;
 638 is expected to be a multiple of the word size.
 639 The behavior of <code>set-word</code> is undefined if this condition
 640 is not satisfied.
 641 </p></dd>
 642
 643 <dt><strong class="since">1.0</strong> <code>tail-call &lt;x&gt; &lt;y&gt; &lt;z&gt; ...</code></dt>
 644 <dd><p class="first">Performs a tail call to the function &lt;x&gt;
 645 with parameters &lt;y&gt; &lt;z&gt; &hellip;. This has an effect
 646 similar to 'return call &lt;x&gt; &lt;y&gt; &lt;z&gt; ...', but
 647 re-uses the call frame of the current function. This means that if
 648 &lt;x&gt; takes fewer or at most as many parameters as the current
 649 function, the tail call requires no extra space.</p></dd>
 650 </dl>
 651
 652 <h2>Expressions</h2>
 653
 654 <p class="first">Certain actions have the ability to evaluate
 655 expressions. Expressions can be simple values, but expressions can
 656 also perform computations on values. The following are valid
 657 expressions:</p>
 658
 659 <dl>
 660 <dt><strong class="since">1.0</strong> <code>add &lt;x&gt; &lt;y&gt;</code></dt>
 661 <dd><p class="first">The result of adding &lt;y&gt; to &lt;x&gt;.</p>
 662
 663 <p>If the result of the addition cannot be represented in a single word,
 664 the result of <code>add</code> is undefined.</p></dd>
 665
 666 <dt><strong class="since">1.0</strong> <code>and &lt;x&gt; &lt;y&gt;</code></dt>
 667 <dd><p class="first">The bitwise and of &lt;x&gt; and &lt;y&gt;.</p></dd>
 668
 669 <dt><strong class="since">1.0</strong> <code>asr &lt;x&gt; &lt;y&gt;</code></dt>
 670 <dd><p class="first">Performs an arithmetic right shift. The bits in
 671 &lt;x&gt; are shifted &lt;y&gt; positions to the right. The sign of
 672 &lt;x&gt; is preserved, so that the result has the same sign as
 673 &lt;x&gt;. The result is undefined if &lt;y&gt; is negative.</p></dd>
 674
 675 <dt><strong class="since current">1.1</strong> <code>auto-bytes &lt;x&gt;</code></dt>
 676 <dd><p class="first">Allocates &lt;x&gt; bytes of memory. The
 677 allocated bytes will automatically be released after the current frame
 678 ends. The result is the address of the allocated bytes.</p></dd>
 679
 680 <dt><strong class="since current">1.1</strong> <code>auto-words &lt;x&gt;</code></dt>
 681 <dd><p class="first">Allocates &lt;x&gt; words of memory. The
 682 allocated words will automatically be released after the current frame
 683 ends. The result is the address of the allocated words.</p></dd>
 684
 685 <dt><strong class="since">1.0</strong> <code>bsr &lt;x&gt; &lt;y&gt;</code></dt>
 686 <dd><p class="first">Performs a bitwise right shift. The bits in
 687 &lt;x&gt; are shifted &lt;y&gt; positions to the right. &lt;y&gt;
 688 zero-valued bits are shifted in from the left. The result does
 689 not necessarily have the same sign as &lt;x&gt;. The result is
 690 undefined if &lt;y&gt; is negative.</p></dd>
 691
 692 <dt><strong class="since">1.0</strong> <code>call &lt;x&gt; &lt;y&gt; &lt;z&gt; ...</code></dt>
 693 <dd><p class="first">Similar to the action call, this calls the
 694 function &lt;x&gt; with the parameters &lt;y&gt; &lt;z&gt; ... (there
 695 may be zero or more parameters). The result of this expression is the
 696 value returned from the function.</p></dd>
 697
 698 <dt><strong class="since">1.0</strong> <code>div &lt;x&gt; &lt;y&gt;</code></dt>
 699 <dd><p class="first">The (integer) result of dividing &lt;x&gt; by
 700 &lt;y&gt;.</p>
 701
 702 <p>If &lt;x&gt; &ge; 0 and &lt;y&gt; &gt; 0, the result is the largest
 703 integer equal to or less than the algebraic quotient of &lt;x&gt;
 704 and &lt;y&gt;.</p>
 705
 706 <p>If either &lt;x&gt; or &lt;y&gt; is negative, the result is
 707 implementation-defined.</p>
 708
 709 <p>If &lt;y&gt; is zero, or if the quotient cannot be represented in a
 710 single machine word, the result is undefined.</p></dd>
 711
 712 <dt><strong class="since">1.0</strong> <code>get-byte &lt;base&gt; &lt;offset&gt;</code></dt>
 713 <dd><p class="first">The value of the byte at address &lt;base&gt; + &lt;offset&gt;.</p></dd>
 714
 715 <dt><strong class="since">1.0</strong> <code>get-word &lt;base&gt; &lt;offset&gt;</code></dt>
 716 <dd><p class="first">The value of the word at address &lt;base&gt; +
 717 (WORDSIZE * &lt;offset&gt;).</p>
 718
 719 <p>The address computed as &lt;base&gt; + (WORDSIZE * &lt;offset&gt;) is
 720 expected to be a multiple of the word size. If this condition is not met,
 721 the behavior of <code>get-word</code> is undefined.</p></dd>
 722
 723 <dt><strong class="since">1.0</strong> <code>mod &lt;x&gt; &lt;y&gt;</code></dt>
 724 <dd><p class="first">For &lt;x&gt; &ge; 0 and &lt;y&gt; &gt; 0, returns
 725 &lt;x&gt; modulo &lt;y&gt;.</p>
 726
 727 <p>If either &lt;x&gt; or &lt;y&gt; is negative, the result is
 728 implementation-defined.</p>
 729
 730 <p>If &lt;y&gt; is zero, the result is undefined.</p></dd>
 731
 732 <dt><strong class="since">1.0</strong> <code>mul &lt;x&gt; &lt;y&gt;</code></dt>
 733 <dd><p class="first">The result of multiplying &lt;x&gt; by &lt;y&gt;.</p>
 734
 735 <p>If the algebraic result of &lt;x&gt; * &lt;y&gt; cannot be represented
 736 in a single word, the result of <code>mul &lt;x&gt; &lt;y&gt;</code>
 737 contains only the low-order bits of the full result.</p></dd>
 738
 739 <dt><strong class="since">1.0</strong> <code>not &lt;x&gt;</code></dt>
 740 <dd><p class="first">The ones' complement of &lt;x&gt;; i.e. all the
 741 bits in &lt;x&gt; inverted.</p></dd>
 742
 743 <dt><strong class="since">1.0</strong> <code>or &lt;x&gt; &lt;y&gt;</code></dt>
 744 <dd><p class="first">The bitwise or of &lt;x&gt; and &lt;y&gt;.</p></dd>
 745
 746 <dt><strong class="since">1.0</strong> <code>rol &lt;x&gt; &lt;y&gt;</code></dt>
 747 <dd><p class="first">Rotates the bits in &lt;x&gt; to the left by
 748 &lt;y&gt; positions. Bits that are rotated off the left are inserted
 749 on the right.
 750 The result is undefined if &lt;y&gt; is negative.</p></dd>
 751
 752 <dt><strong class="since">1.0</strong> <code>ror &lt;x&gt; &lt;y&gt;</code></dt>
 753 <dd><p class="first">Rotates the bits in &lt;x&gt; to the right by
 754 &lt;y&gt; positions. Bits that are rotated off the right are inserted
 755 on the left.
 756 The result is undefined if &lt;y&gt; is negative.</p></dd>
 757
 758 <dt><strong class="since">1.0</strong> <code>shl &lt;x&gt; &lt;y&gt;</code></dt>
 759 <dd><p class="first">Performs a left shift. The bits in
 760 &lt;x&gt; are shifted &lt;y&gt; positions to the left.
 761 The result is undefined if &lt;y&gt; is negative.</p></dd>
 762
 763 <dt><strong class="since">1.0</strong> <code>shr &lt;x&gt; &lt;y&gt;</code></dt>
 764 <dd><p class="first">Performs a right shift. The bits in
 765 &lt;x&gt; are shifted &lt;y&gt; positions to the right. It is
 766 implementation-defined whether this operation preserves the sign
 767 of &lt;x&gt; (for operations with specific sign-preservation
 768 properties, use asr or bsr).
 769 The result is undefined if &lt;y&gt; is negative.</p></dd>
 770
 771 <dt><strong class="since">1.0</strong> <code>sub &lt;x&gt; &lt;y&gt;</code></dt>
 772 <dd><p class="first">The result of subtracting &lt;y&gt; from &lt;x&gt;.</p>
 773
 774 <p>If the result of the subtraction cannot be represented in a single
 775 word, the result of <code>sub</code> is undefined.</p></dd>
 776
 777 <dt><strong class="since">1.0</strong> <code>xor &lt;x&gt; &lt;y&gt;</code></dt>
 778 <dd><p class="first">The bitwise exclusive or of &lt;x&gt; and
 779 &lt;y&gt;.</p></dd>
 780 </dl>
 781
 782 <h2>Conditionals</h2>
 783
 784 <p class="first"><strong class="since">1.0</strong> Conditionals in Voodoo take the following form:</p>
 785
 786 <pre><code>if&lt;test&gt;
 787     ... some code here ...
 788 else if&lt;test&gt;
 789     ... other code here ...
 790 ... more "else if" parts ...
 791 else
 792     ... some code ...
 793 end if
 794 </code></pre>
 795
 796 <p class="first">There can be any number of <q>else if</q> parts, and
 797 the final <q>else</q> clause is optional. The tests that are provided
 798 are the following:</p>
 799
 800 <dl>
 801 <dt><code>ifeq &lt;x&gt; &lt;y&gt;</code></dt>
 802 <dd><p class="first">Tests if &lt;x&gt; is equal to &lt;y&gt;.</p></dd>
 803
 804 <dt><code>ifge &lt;x&gt; &lt;y&gt;</code></dt>
 805 <dd><p class="first">Tests if &lt;x&gt; is greater than or equal to
 806 &lt;y&gt;.</p></dd>
 807
 808 <dt><code>ifgt &lt;x&gt; &lt;y&gt;</code></dt>
 809 <dd><p class="first">Tests if &lt;x&gt; is strictly greater than
 810 &lt;y&gt;.</p></dd>
 811
 812 <dt><code>ifle &lt;x&gt; &lt;y&gt;</code></dt>
 813 <dd><p class="first">Tests if &lt;x&gt; is less than or equal to
 814 &lt;y&gt;.</p></dd>
 815
 816 <dt><code>iflt &lt;x&gt; &lt;y&gt;</code></dt>
 817 <dd><p class="first">Tests if &lt;x&gt; is strictly less than
 818 &lt;y&gt;.</p></dd>
 819
 820 <dt><code>ifne &lt;x&gt; &lt;y&gt;</code></dt>
 821 <dd><p class="first">Tests if &lt;x&gt; is different from &lt;y&gt;.</p></dd>
 822 </dl>
 823
 824 <h2>Function Definitions</h2>
 825
 826 <p class="first"><strong class="since">1.0</strong> A function definition looks like:</p>
 827
 828 <pre><code>
 829 function x y z
 830     &lt;code&gt;
 831 end function
 832 </code></pre>
 833
 834 <p class="first">Here, the function being defined takes 3 parameters,
 835 which can be referred to as <code>x</code>, <code>y</code>, and
 836 <code>z</code> from the code inside the function body. A function may
 837 have zero or more parameters and is practically always preceded by a
 838 label, so that the function can be referenced from code.</p>
 839
 840 <p>A function should only be entered using <code>call</code>,
 841 <code>tail-call</code>, or entering a prior invocation of the function
 842 using <code>restore-frame</code> and <code>goto</code>. When calling
 843 a function, the number of supplied parameters should equal the number
 844 of parameters the function was declared with.
 845 A function should only be left through <code>return</code>,
 846 <code>tail-call</code>, or a valid combination
 847 of <code>restore-frame</code> and <code>goto</code>.
 848 Failing to meet these requirements results in undefined behavior.</p>
 849
 850 <h2>Blocks</h2>
 851
 852 <p class="first"><strong class="since">1.0</strong> Blocks can be used to define a scope in which local
 853 variables (introduced with <code>let</code>) can be referred to. A
 854 block looks like:</p>
 855
 856 <pre><code>
 857 block
 858     &lt;code&gt;
 859 end block
 860 </code></pre>
 861
 862 <p class="first">Inside a block, variables may be introduced using
 863 <code>let</code>. Such a variable is in scope (can be referred to)
 864 from the first statement after the <code>let</code> until the
 865 <code>end block</code> that terminates the block.</p>
 866
 867 <p>Blocks can be placed anywhere an action can be placed: at
 868 top-level, inside functions, inside blocks, and inside conditionals.</p>
 869 </div>
 870 </body>
 871 </html>