reference.html

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
   3     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
   5 <head>\r
   6 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
   7 <meta name="generator" content="AsciiDoc 8.6.10" />\r
   8 <title>RRQFORTH Reference Documentation</title>\r
   9 <style type="text/css">\r
  10 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */\r
  11 \r
  12 /* Default font. */\r
  13 body {\r
  14   font-family: Georgia,serif;\r
  15 }\r
  16 \r
  17 /* Title font. */\r
  18 h1, h2, h3, h4, h5, h6,\r
  19 div.title, caption.title,\r
  20 thead, p.table.header,\r
  21 #toctitle,\r
  22 #author, #revnumber, #revdate, #revremark,\r
  23 #footer {\r
  24   font-family: Arial,Helvetica,sans-serif;\r
  25 }\r
  26 \r
  27 body {\r
  28   margin: 1em 5% 1em 5%;\r
  29 }\r
  30 \r
  31 a {\r
  32   color: blue;\r
  33   text-decoration: underline;\r
  34 }\r
  35 a:visited {\r
  36   color: fuchsia;\r
  37 }\r
  38 \r
  39 em {\r
  40   font-style: italic;\r
  41   color: navy;\r
  42 }\r
  43 \r
  44 strong {\r
  45   font-weight: bold;\r
  46   color: #083194;\r
  47 }\r
  48 \r
  49 h1, h2, h3, h4, h5, h6 {\r
  50   color: #527bbd;\r
  51   margin-top: 1.2em;\r
  52   margin-bottom: 0.5em;\r
  53   line-height: 1.3;\r
  54 }\r
  55 \r
  56 h1, h2, h3 {\r
  57   border-bottom: 2px solid silver;\r
  58 }\r
  59 h2 {\r
  60   padding-top: 0.5em;\r
  61 }\r
  62 h3 {\r
  63   float: left;\r
  64 }\r
  65 h3 + * {\r
  66   clear: left;\r
  67 }\r
  68 h5 {\r
  69   font-size: 1.0em;\r
  70 }\r
  71 \r
  72 div.sectionbody {\r
  73   margin-left: 0;\r
  74 }\r
  75 \r
  76 hr {\r
  77   border: 1px solid silver;\r
  78 }\r
  79 \r
  80 p {\r
  81   margin-top: 0.5em;\r
  82   margin-bottom: 0.5em;\r
  83 }\r
  84 \r
  85 ul, ol, li > p {\r
  86   margin-top: 0;\r
  87 }\r
  88 ul > li     { color: #aaa; }\r
  89 ul > li > * { color: black; }\r
  90 \r
  91 .monospaced, code, pre {\r
  92   font-family: "Courier New", Courier, monospace;\r
  93   font-size: inherit;\r
  94   color: navy;\r
  95   padding: 0;\r
  96   margin: 0;\r
  97 }\r
  98 pre {\r
  99   white-space: pre-wrap;\r
 100 }\r
 101 \r
 102 #author {\r
 103   color: #527bbd;\r
 104   font-weight: bold;\r
 105   font-size: 1.1em;\r
 106 }\r
 107 #email {\r
 108 }\r
 109 #revnumber, #revdate, #revremark {\r
 110 }\r
 111 \r
 112 #footer {\r
 113   font-size: small;\r
 114   border-top: 2px solid silver;\r
 115   padding-top: 0.5em;\r
 116   margin-top: 4.0em;\r
 117 }\r
 118 #footer-text {\r
 119   float: left;\r
 120   padding-bottom: 0.5em;\r
 121 }\r
 122 #footer-badges {\r
 123   float: right;\r
 124   padding-bottom: 0.5em;\r
 125 }\r
 126 \r
 127 #preamble {\r
 128   margin-top: 1.5em;\r
 129   margin-bottom: 1.5em;\r
 130 }\r
 131 div.imageblock, div.exampleblock, div.verseblock,\r
 132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,\r
 133 div.admonitionblock {\r
 134   margin-top: 1.0em;\r
 135   margin-bottom: 1.5em;\r
 136 }\r
 137 div.admonitionblock {\r
 138   margin-top: 2.0em;\r
 139   margin-bottom: 2.0em;\r
 140   margin-right: 10%;\r
 141   color: #606060;\r
 142 }\r
 143 \r
 144 div.content { /* Block element content. */\r
 145   padding: 0;\r
 146 }\r
 147 \r
 148 /* Block element titles. */\r
 149 div.title, caption.title {\r
 150   color: #527bbd;\r
 151   font-weight: bold;\r
 152   text-align: left;\r
 153   margin-top: 1.0em;\r
 154   margin-bottom: 0.5em;\r
 155 }\r
 156 div.title + * {\r
 157   margin-top: 0;\r
 158 }\r
 159 \r
 160 td div.title:first-child {\r
 161   margin-top: 0.0em;\r
 162 }\r
 163 div.content div.title:first-child {\r
 164   margin-top: 0.0em;\r
 165 }\r
 166 div.content + div.title {\r
 167   margin-top: 0.0em;\r
 168 }\r
 169 \r
 170 div.sidebarblock > div.content {\r
 171   background: #ffffee;\r
 172   border: 1px solid #dddddd;\r
 173   border-left: 4px solid #f0f0f0;\r
 174   padding: 0.5em;\r
 175 }\r
 176 \r
 177 div.listingblock > div.content {\r
 178   border: 1px solid #dddddd;\r
 179   border-left: 5px solid #f0f0f0;\r
 180   background: #f8f8f8;\r
 181   padding: 0.5em;\r
 182 }\r
 183 \r
 184 div.quoteblock, div.verseblock {\r
 185   padding-left: 1.0em;\r
 186   margin-left: 1.0em;\r
 187   margin-right: 10%;\r
 188   border-left: 5px solid #f0f0f0;\r
 189   color: #888;\r
 190 }\r
 191 \r
 192 div.quoteblock > div.attribution {\r
 193   padding-top: 0.5em;\r
 194   text-align: right;\r
 195 }\r
 196 \r
 197 div.verseblock > pre.content {\r
 198   font-family: inherit;\r
 199   font-size: inherit;\r
 200 }\r
 201 div.verseblock > div.attribution {\r
 202   padding-top: 0.75em;\r
 203   text-align: left;\r
 204 }\r
 205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */\r
 206 div.verseblock + div.attribution {\r
 207   text-align: left;\r
 208 }\r
 209 \r
 210 div.admonitionblock .icon {\r
 211   vertical-align: top;\r
 212   font-size: 1.1em;\r
 213   font-weight: bold;\r
 214   text-decoration: underline;\r
 215   color: #527bbd;\r
 216   padding-right: 0.5em;\r
 217 }\r
 218 div.admonitionblock td.content {\r
 219   padding-left: 0.5em;\r
 220   border-left: 3px solid #dddddd;\r
 221 }\r
 222 \r
 223 div.exampleblock > div.content {\r
 224   border-left: 3px solid #dddddd;\r
 225   padding-left: 0.5em;\r
 226 }\r
 227 \r
 228 div.imageblock div.content { padding-left: 0; }\r
 229 span.image img { border-style: none; vertical-align: text-bottom; }\r
 230 a.image:visited { color: white; }\r
 231 \r
 232 dl {\r
 233   margin-top: 0.8em;\r
 234   margin-bottom: 0.8em;\r
 235 }\r
 236 dt {\r
 237   margin-top: 0.5em;\r
 238   margin-bottom: 0;\r
 239   font-style: normal;\r
 240   color: navy;\r
 241 }\r
 242 dd > *:first-child {\r
 243   margin-top: 0.1em;\r
 244 }\r
 245 \r
 246 ul, ol {\r
 247     list-style-position: outside;\r
 248 }\r
 249 ol.arabic {\r
 250   list-style-type: decimal;\r
 251 }\r
 252 ol.loweralpha {\r
 253   list-style-type: lower-alpha;\r
 254 }\r
 255 ol.upperalpha {\r
 256   list-style-type: upper-alpha;\r
 257 }\r
 258 ol.lowerroman {\r
 259   list-style-type: lower-roman;\r
 260 }\r
 261 ol.upperroman {\r
 262   list-style-type: upper-roman;\r
 263 }\r
 264 \r
 265 div.compact ul, div.compact ol,\r
 266 div.compact p, div.compact p,\r
 267 div.compact div, div.compact div {\r
 268   margin-top: 0.1em;\r
 269   margin-bottom: 0.1em;\r
 270 }\r
 271 \r
 272 tfoot {\r
 273   font-weight: bold;\r
 274 }\r
 275 td > div.verse {\r
 276   white-space: pre;\r
 277 }\r
 278 \r
 279 div.hdlist {\r
 280   margin-top: 0.8em;\r
 281   margin-bottom: 0.8em;\r
 282 }\r
 283 div.hdlist tr {\r
 284   padding-bottom: 15px;\r
 285 }\r
 286 dt.hdlist1.strong, td.hdlist1.strong {\r
 287   font-weight: bold;\r
 288 }\r
 289 td.hdlist1 {\r
 290   vertical-align: top;\r
 291   font-style: normal;\r
 292   padding-right: 0.8em;\r
 293   color: navy;\r
 294 }\r
 295 td.hdlist2 {\r
 296   vertical-align: top;\r
 297 }\r
 298 div.hdlist.compact tr {\r
 299   margin: 0;\r
 300   padding-bottom: 0;\r
 301 }\r
 302 \r
 303 .comment {\r
 304   background: yellow;\r
 305 }\r
 306 \r
 307 .footnote, .footnoteref {\r
 308   font-size: 0.8em;\r
 309 }\r
 310 \r
 311 span.footnote, span.footnoteref {\r
 312   vertical-align: super;\r
 313 }\r
 314 \r
 315 #footnotes {\r
 316   margin: 20px 0 20px 0;\r
 317   padding: 7px 0 0 0;\r
 318 }\r
 319 \r
 320 #footnotes div.footnote {\r
 321   margin: 0 0 5px 0;\r
 322 }\r
 323 \r
 324 #footnotes hr {\r
 325   border: none;\r
 326   border-top: 1px solid silver;\r
 327   height: 1px;\r
 328   text-align: left;\r
 329   margin-left: 0;\r
 330   width: 20%;\r
 331   min-width: 100px;\r
 332 }\r
 333 \r
 334 div.colist td {\r
 335   padding-right: 0.5em;\r
 336   padding-bottom: 0.3em;\r
 337   vertical-align: top;\r
 338 }\r
 339 div.colist td img {\r
 340   margin-top: 0.3em;\r
 341 }\r
 342 \r
 343 @media print {\r
 344   #footer-badges { display: none; }\r
 345 }\r
 346 \r
 347 #toc {\r
 348   margin-bottom: 2.5em;\r
 349 }\r
 350 \r
 351 #toctitle {\r
 352   color: #527bbd;\r
 353   font-size: 1.1em;\r
 354   font-weight: bold;\r
 355   margin-top: 1.0em;\r
 356   margin-bottom: 0.1em;\r
 357 }\r
 358 \r
 359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {\r
 360   margin-top: 0;\r
 361   margin-bottom: 0;\r
 362 }\r
 363 div.toclevel2 {\r
 364   margin-left: 2em;\r
 365   font-size: 0.9em;\r
 366 }\r
 367 div.toclevel3 {\r
 368   margin-left: 4em;\r
 369   font-size: 0.9em;\r
 370 }\r
 371 div.toclevel4 {\r
 372   margin-left: 6em;\r
 373   font-size: 0.9em;\r
 374 }\r
 375 \r
 376 span.aqua { color: aqua; }\r
 377 span.black { color: black; }\r
 378 span.blue { color: blue; }\r
 379 span.fuchsia { color: fuchsia; }\r
 380 span.gray { color: gray; }\r
 381 span.green { color: green; }\r
 382 span.lime { color: lime; }\r
 383 span.maroon { color: maroon; }\r
 384 span.navy { color: navy; }\r
 385 span.olive { color: olive; }\r
 386 span.purple { color: purple; }\r
 387 span.red { color: red; }\r
 388 span.silver { color: silver; }\r
 389 span.teal { color: teal; }\r
 390 span.white { color: white; }\r
 391 span.yellow { color: yellow; }\r
 392 \r
 393 span.aqua-background { background: aqua; }\r
 394 span.black-background { background: black; }\r
 395 span.blue-background { background: blue; }\r
 396 span.fuchsia-background { background: fuchsia; }\r
 397 span.gray-background { background: gray; }\r
 398 span.green-background { background: green; }\r
 399 span.lime-background { background: lime; }\r
 400 span.maroon-background { background: maroon; }\r
 401 span.navy-background { background: navy; }\r
 402 span.olive-background { background: olive; }\r
 403 span.purple-background { background: purple; }\r
 404 span.red-background { background: red; }\r
 405 span.silver-background { background: silver; }\r
 406 span.teal-background { background: teal; }\r
 407 span.white-background { background: white; }\r
 408 span.yellow-background { background: yellow; }\r
 409 \r
 410 span.big { font-size: 2em; }\r
 411 span.small { font-size: 0.6em; }\r
 412 \r
 413 span.underline { text-decoration: underline; }\r
 414 span.overline { text-decoration: overline; }\r
 415 span.line-through { text-decoration: line-through; }\r
 416 \r
 417 div.unbreakable { page-break-inside: avoid; }\r
 418 \r
 419 \r
 420 /*\r
 421  * xhtml11 specific\r
 422  *\r
 423  * */\r
 424 \r
 425 div.tableblock {\r
 426   margin-top: 1.0em;\r
 427   margin-bottom: 1.5em;\r
 428 }\r
 429 div.tableblock > table {\r
 430   border: 3px solid #527bbd;\r
 431 }\r
 432 thead, p.table.header {\r
 433   font-weight: bold;\r
 434   color: #527bbd;\r
 435 }\r
 436 p.table {\r
 437   margin-top: 0;\r
 438 }\r
 439 /* Because the table frame attribute is overriden by CSS in most browsers. */\r
 440 div.tableblock > table[frame="void"] {\r
 441   border-style: none;\r
 442 }\r
 443 div.tableblock > table[frame="hsides"] {\r
 444   border-left-style: none;\r
 445   border-right-style: none;\r
 446 }\r
 447 div.tableblock > table[frame="vsides"] {\r
 448   border-top-style: none;\r
 449   border-bottom-style: none;\r
 450 }\r
 451 \r
 452 \r
 453 /*\r
 454  * html5 specific\r
 455  *\r
 456  * */\r
 457 \r
 458 table.tableblock {\r
 459   margin-top: 1.0em;\r
 460   margin-bottom: 1.5em;\r
 461 }\r
 462 thead, p.tableblock.header {\r
 463   font-weight: bold;\r
 464   color: #527bbd;\r
 465 }\r
 466 p.tableblock {\r
 467   margin-top: 0;\r
 468 }\r
 469 table.tableblock {\r
 470   border-width: 3px;\r
 471   border-spacing: 0px;\r
 472   border-style: solid;\r
 473   border-color: #527bbd;\r
 474   border-collapse: collapse;\r
 475 }\r
 476 th.tableblock, td.tableblock {\r
 477   border-width: 1px;\r
 478   padding: 4px;\r
 479   border-style: solid;\r
 480   border-color: #527bbd;\r
 481 }\r
 482 \r
 483 table.tableblock.frame-topbot {\r
 484   border-left-style: hidden;\r
 485   border-right-style: hidden;\r
 486 }\r
 487 table.tableblock.frame-sides {\r
 488   border-top-style: hidden;\r
 489   border-bottom-style: hidden;\r
 490 }\r
 491 table.tableblock.frame-none {\r
 492   border-style: hidden;\r
 493 }\r
 494 \r
 495 th.tableblock.halign-left, td.tableblock.halign-left {\r
 496   text-align: left;\r
 497 }\r
 498 th.tableblock.halign-center, td.tableblock.halign-center {\r
 499   text-align: center;\r
 500 }\r
 501 th.tableblock.halign-right, td.tableblock.halign-right {\r
 502   text-align: right;\r
 503 }\r
 504 \r
 505 th.tableblock.valign-top, td.tableblock.valign-top {\r
 506   vertical-align: top;\r
 507 }\r
 508 th.tableblock.valign-middle, td.tableblock.valign-middle {\r
 509   vertical-align: middle;\r
 510 }\r
 511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {\r
 512   vertical-align: bottom;\r
 513 }\r
 514 \r
 515 \r
 516 /*\r
 517  * manpage specific\r
 518  *\r
 519  * */\r
 520 \r
 521 body.manpage h1 {\r
 522   padding-top: 0.5em;\r
 523   padding-bottom: 0.5em;\r
 524   border-top: 2px solid silver;\r
 525   border-bottom: 2px solid silver;\r
 526 }\r
 527 body.manpage h2 {\r
 528   border-style: none;\r
 529 }\r
 530 body.manpage div.sectionbody {\r
 531   margin-left: 3em;\r
 532 }\r
 533 \r
 534 @media print {\r
 535   body.manpage div#toc { display: none; }\r
 536 }\r
 537 \r
 538 \r
 539 </style>\r
 540 <script type="text/javascript">\r
 541 /*<![CDATA[*/\r
 542 var asciidoc = {  // Namespace.\r
 543 \r
 544 /////////////////////////////////////////////////////////////////////\r
 545 // Table Of Contents generator\r
 546 /////////////////////////////////////////////////////////////////////\r
 547 \r
 548 /* Author: Mihai Bazon, September 2002\r
 549  * http://students.infoiasi.ro/~mishoo\r
 550  *\r
 551  * Table Of Content generator\r
 552  * Version: 0.4\r
 553  *\r
 554  * Feel free to use this script under the terms of the GNU General Public\r
 555  * License, as long as you do not remove or alter this notice.\r
 556  */\r
 557 \r
 558  /* modified by Troy D. Hanson, September 2006. License: GPL */\r
 559  /* modified by Stuart Rackham, 2006, 2009. License: GPL */\r
 560 \r
 561 // toclevels = 1..4.\r
 562 toc: function (toclevels) {\r
 563 \r
 564   function getText(el) {\r
 565     var text = "";\r
 566     for (var i = el.firstChild; i != null; i = i.nextSibling) {\r
 567       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.\r
 568         text += i.data;\r
 569       else if (i.firstChild != null)\r
 570         text += getText(i);\r
 571     }\r
 572     return text;\r
 573   }\r
 574 \r
 575   function TocEntry(el, text, toclevel) {\r
 576     this.element = el;\r
 577     this.text = text;\r
 578     this.toclevel = toclevel;\r
 579   }\r
 580 \r
 581   function tocEntries(el, toclevels) {\r
 582     var result = new Array;\r
 583     var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');\r
 584     // Function that scans the DOM tree for header elements (the DOM2\r
 585     // nodeIterator API would be a better technique but not supported by all\r
 586     // browsers).\r
 587     var iterate = function (el) {\r
 588       for (var i = el.firstChild; i != null; i = i.nextSibling) {\r
 589         if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {\r
 590           var mo = re.exec(i.tagName);\r
 591           if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {\r
 592             result[result.length] = new TocEntry(i, getText(i), mo[1]-1);\r
 593           }\r
 594           iterate(i);\r
 595         }\r
 596       }\r
 597     }\r
 598     iterate(el);\r
 599     return result;\r
 600   }\r
 601 \r
 602   var toc = document.getElementById("toc");\r
 603   if (!toc) {\r
 604     return;\r
 605   }\r
 606 \r
 607   // Delete existing TOC entries in case we're reloading the TOC.\r
 608   var tocEntriesToRemove = [];\r
 609   var i;\r
 610   for (i = 0; i < toc.childNodes.length; i++) {\r
 611     var entry = toc.childNodes[i];\r
 612     if (entry.nodeName.toLowerCase() == 'div'\r
 613      && entry.getAttribute("class")\r
 614      && entry.getAttribute("class").match(/^toclevel/))\r
 615       tocEntriesToRemove.push(entry);\r
 616   }\r
 617   for (i = 0; i < tocEntriesToRemove.length; i++) {\r
 618     toc.removeChild(tocEntriesToRemove[i]);\r
 619   }\r
 620 \r
 621   // Rebuild TOC entries.\r
 622   var entries = tocEntries(document.getElementById("content"), toclevels);\r
 623   for (var i = 0; i < entries.length; ++i) {\r
 624     var entry = entries[i];\r
 625     if (entry.element.id == "")\r
 626       entry.element.id = "_toc_" + i;\r
 627     var a = document.createElement("a");\r
 628     a.href = "#" + entry.element.id;\r
 629     a.appendChild(document.createTextNode(entry.text));\r
 630     var div = document.createElement("div");\r
 631     div.appendChild(a);\r
 632     div.className = "toclevel" + entry.toclevel;\r
 633     toc.appendChild(div);\r
 634   }\r
 635   if (entries.length == 0)\r
 636     toc.parentNode.removeChild(toc);\r
 637 },\r
 638 \r
 639 \r
 640 /////////////////////////////////////////////////////////////////////\r
 641 // Footnotes generator\r
 642 /////////////////////////////////////////////////////////////////////\r
 643 \r
 644 /* Based on footnote generation code from:\r
 645  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html\r
 646  */\r
 647 \r
 648 footnotes: function () {\r
 649   // Delete existing footnote entries in case we're reloading the footnodes.\r
 650   var i;\r
 651   var noteholder = document.getElementById("footnotes");\r
 652   if (!noteholder) {\r
 653     return;\r
 654   }\r
 655   var entriesToRemove = [];\r
 656   for (i = 0; i < noteholder.childNodes.length; i++) {\r
 657     var entry = noteholder.childNodes[i];\r
 658     if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")\r
 659       entriesToRemove.push(entry);\r
 660   }\r
 661   for (i = 0; i < entriesToRemove.length; i++) {\r
 662     noteholder.removeChild(entriesToRemove[i]);\r
 663   }\r
 664 \r
 665   // Rebuild footnote entries.\r
 666   var cont = document.getElementById("content");\r
 667   var spans = cont.getElementsByTagName("span");\r
 668   var refs = {};\r
 669   var n = 0;\r
 670   for (i=0; i<spans.length; i++) {\r
 671     if (spans[i].className == "footnote") {\r
 672       n++;\r
 673       var note = spans[i].getAttribute("data-note");\r
 674       if (!note) {\r
 675         // Use [\s\S] in place of . so multi-line matches work.\r
 676         // Because JavaScript has no s (dotall) regex flag.\r
 677         note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];\r
 678         spans[i].innerHTML =\r
 679           "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +\r
 680           "' title='View footnote' class='footnote'>" + n + "</a>]";\r
 681         spans[i].setAttribute("data-note", note);\r
 682       }\r
 683       noteholder.innerHTML +=\r
 684         "<div class='footnote' id='_footnote_" + n + "'>" +\r
 685         "<a href='#_footnoteref_" + n + "' title='Return to text'>" +\r
 686         n + "</a>. " + note + "</div>";\r
 687       var id =spans[i].getAttribute("id");\r
 688       if (id != null) refs["#"+id] = n;\r
 689     }\r
 690   }\r
 691   if (n == 0)\r
 692     noteholder.parentNode.removeChild(noteholder);\r
 693   else {\r
 694     // Process footnoterefs.\r
 695     for (i=0; i<spans.length; i++) {\r
 696       if (spans[i].className == "footnoteref") {\r
 697         var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");\r
 698         href = href.match(/#.*/)[0];  // Because IE return full URL.\r
 699         n = refs[href];\r
 700         spans[i].innerHTML =\r
 701           "[<a href='#_footnote_" + n +\r
 702           "' title='View footnote' class='footnote'>" + n + "</a>]";\r
 703       }\r
 704     }\r
 705   }\r
 706 },\r
 707 \r
 708 install: function(toclevels) {\r
 709   var timerId;\r
 710 \r
 711   function reinstall() {\r
 712     asciidoc.footnotes();\r
 713     if (toclevels) {\r
 714       asciidoc.toc(toclevels);\r
 715     }\r
 716   }\r
 717 \r
 718   function reinstallAndRemoveTimer() {\r
 719     clearInterval(timerId);\r
 720     reinstall();\r
 721   }\r
 722 \r
 723   timerId = setInterval(reinstall, 500);\r
 724   if (document.addEventListener)\r
 725     document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);\r
 726   else\r
 727     window.onload = reinstallAndRemoveTimer;\r
 728 }\r
 729 \r
 730 }\r
 731 asciidoc.install();\r
 732 /*]]>*/\r
 733 </script>\r
 734 </head>\r
 735 <body class="article">\r
 736 <div id="header">\r
 737 <h1>RRQFORTH Reference Documentation</h1>\r
 738 <span id="author">Ralph Ronnquist &lt;ralph.ronnquist@gmail.com&gt;</span><br />\r
 739 </div>\r
 740 <div id="content">\r
 741 <div class="sect1">\r
 742 <h2 id="_word_index">Word Index</h2>\r
 743 <div class="sectionbody">\r
 744 <div class="paragraph"><p><a href="#p_lparen">( (left parenthesis)</a> &#160;\r
 745 <a href="#p_colon">: (colon)</a> &#160;\r
 746 <a href="#p_semicolon">: (semi-colon)</a> &#160;\r
 747 <a href="#p_comma">, (comma)</a> &#160;\r
 748 <a href="#p_dot">. (dot)</a> &#160;\r
 749 <a href="#p_double_quote">" (double-quote)</a> &#160;\r
 750 <a href="#p_quote">' (single-quote)</a> &#160;\r
 751 <a href="#p_left_bracket">[ (left bracket)</a> &#160;\r
 752 <a href="#p_right_bracket">] (right bracket)</a> &#160;</p></div>\r
 753 <div class="paragraph"><p><a href="#p_lessthan">&lt;</a> &#160;\r
 754 <a href="#p_lessequal">&lt;=</a> &#160;\r
 755 <a href="#p_equal">=</a> &#160;\r
 756 <a href="#p_unequal">!=</a> &#160;\r
 757 <a href="#p_greaterthan">&gt;</a> &#160;\r
 758 <a href="#p_greaterequal">&gt;= </a> &#160;\r
 759 <a href="#p_0equal">0=</a> &#160;\r
 760 <a href="#p_0less">0&lt;</a> &#160;\r
 761 <a href="#p_minus">-</a> &#160;\r
 762 <a href="#p_mult">*</a> &#160;\r
 763 <a href="#p_plus">&#43;</a> &#160;\r
 764 <a href="#p_div">/</a> &#160;\r
 765 <a href="#p_shift_left">&lt;&lt;</a> &#160;\r
 766 <a href="#p_shift_right">&gt;&gt;</a> &#160;\r
 767 <a href="#p_shift_signed_right">s&gt;&gt;</a> &#160;\r
 768 <a href="#p_bracketed_quote">[']</a> &#160;</p></div>\r
 769 <div class="paragraph"><p><a href="#p_get">@</a> &#160;\r
 770 <a href="#p_put">!</a> &#160;\r
 771 <a href="#p_Cget">C@</a> &#160;\r
 772 <a href="#p_Cput">C!</a> &#160;\r
 773 <a href="#p_2get">2@</a> &#160;\r
 774 <a href="#p_2put">2!</a> &#160;\r
 775 <a href="#p_put_plus">!&#43;</a> &#160;\r
 776 <a href="#p_get_n_increment">@n&#43;&#43;</a> &#160;\r
 777 <a href="#p_get_n_decrement">@n--</a> &#160;\r
 778 <a href="#p_Ccomma">C,</a> &#160;\r
 779 <a href="#p_literal_string">S"</a> &#160;\r
 780 <a href="#p_gtR">&gt;R</a> &#160;\r
 781 <a href="#p_Rget">R@</a> &#160;\r
 782 <a href="#p_Rgt">R&gt;</a> &#160;\r
 783 <a href="#p_rbpn">R[n]</a> &#160;</p></div>\r
 784 <div class="paragraph"><p><a href="#data_stack">DATA-STACK</a> &#160;\r
 785 <a href="#return_stack">RETURN-STACK</a> &#160;\r
 786 &#160;\r
 787 <a href="#p_branch">BRANCH</a> &#160;\r
 788 <a href="#p_0branch">0BRANCH</a> &#160;\r
 789 <a href="#p_1branch">1BRANCH</a> &#160;\r
 790 &#160;\r
 791 <a href="#p_2drop">2DROP</a> &#160;\r
 792 <a href="#p_2dup">2DUP</a> &#160;\r
 793 <a href="#p_2over">2OVER</a> &#160;\r
 794 <a href="#p_2swap">2SWAP</a> &#160;</p></div>\r
 795 <div class="paragraph"><p><a href="#p_abs">ABS</a> &#160;\r
 796 <a href="#p_again">AGAIN</a> &#160;\r
 797 <a href="#p_allot">ALLOT</a> &#160;\r
 798 <a href="#p_and">AND</a> &#160;\r
 799 <a href="#inline_code">[ASM]</a> &#160;</p></div>\r
 800 <div class="paragraph"><p><a href="#p_base">BASE</a> &#160;\r
 801 <a href="#p_begin">BEGIN</a> &#160;\r
 802 <a href="#p_break">BREAK</a> &#160;</p></div>\r
 803 <div class="paragraph"><p><a href="#p_cfa2flags_get">CFA&gt;FLAGS@</a> &#160;\r
 804 <a href="#p_cfa2tfa">CFA&gt;TFA</a> &#160;\r
 805 <a href="#p_clear_stream">CLEAR-STREAM</a> &#160;\r
 806 <a href="#p_create">CREATE</a> &#160;\r
 807 <a href="#p_current_wordlist">CURRENT-WORDLIST</a> &#160;</p></div>\r
 808 <div class="paragraph"><p><a href="#p_decimal">DECIMAL</a> &#160;\r
 809 <a href="#p_definitions">DEFINITIONS</a> &#160;\r
 810 <a href="#p_depth">DEPTH</a> &#160;\r
 811 <a href="#p_digits">DIGITS</a> &#160;\r
 812 <a href="#p_divmod">/MOD</a> &#160;\r
 813 <a href="#p_dfa2tfa">DFA&gt;TFA</a> &#160;\r
 814 <a href="#p_dodoes">doDOES</a> &#160;\r
 815 <a href="#p_does">DOES&gt;</a> &#160;\r
 816 <a href="#p_dofasm">doFASM</a> &#160;\r
 817 <a href="#p_doforth">doFORTH</a> &#160;\r
 818 <a href="#p_dostring">doSTRING</a> &#160;\r
 819 <a href="#p_dovalue">doVALUE</a> &#160;\r
 820 <a href="#p_dovariable">doVARIABLE</a> &#160;\r
 821 <a href="#p_drop">DROP</a> &#160;\r
 822 <a href="#p_dup">DUP</a> &#160;</p></div>\r
 823 <div class="paragraph"><p><a href="#p_else">ELSE</a> &#160;\r
 824 <a href="#p_emit">EMIT</a> &#160;\r
 825 <a href="#p_end">END</a> &#160;\r
 826 <a href="#p_erase">ERASE</a> &#160;\r
 827 <a href="#p_evaluate_stream">EVALUATE-STREAM</a> &#160;\r
 828 <a href="#p_execute">EXECUTE</a> &#160;\r
 829 <a href="#p_exit">EXIT</a> &#160;</p></div>\r
 830 <div class="paragraph"><p><a href="#p_false">FALSE</a> &#160;\r
 831 <a href="#p_fdemit">FDEMIT</a> &#160;\r
 832 <a href="#p_fdtell">FDTELL</a> &#160;\r
 833 <a href="#p_find">FIND</a> &#160;\r
 834 <a href="#p_forth">FORTH</a> &#160;</p></div>\r
 835 <div class="paragraph"><p><a href="#p_here">HERE</a> &#160;\r
 836 <a href="#p_hex">HEX</a> &#160;</p></div>\r
 837 <div class="paragraph"><p><a href="#p_if">IF</a> &#160;\r
 838 <a href="#p_ifagain">IFAGAIN</a> &#160;\r
 839 <a href="#p_ifbreak">IFBREAK</a> &#160;\r
 840 <a href="#p_immediate">IMMEDIATE</a> &#160;\r
 841 <a href="#p_input">INPUT</a> &#160;</p></div>\r
 842 <div class="paragraph"><p><a href="#p_literal">LIT</a> &#160;\r
 843 <a href="#p_load_buffer_size">LOAD-BUFFER-SIZE</a> &#160;\r
 844 <a href="#p_load_file">LOAD-FILE</a> &#160;</p></div>\r
 845 <div class="paragraph"><p><a href="#p_args">MAIN-ARGS</a> &#160;\r
 846 <a href="#p_malloc">MALLOC</a> &#160;</p></div>\r
 847 <div class="paragraph"><p><a href="#p_negate">NEGATE</a> &#160;\r
 848 <a href="#p_nip">NIP</a> &#160;\r
 849 <a href="#p_nl">NL</a> &#160;\r
 850 <a href="#p_not">NOT</a> &#160;\r
 851 <a href="#p_number">NUMBER</a> &#160;</p></div>\r
 852 <div class="paragraph"><p><a href="#p_open_file">OPEN-FILE</a> &#160;\r
 853 <a href="#p_or">OR</a> &#160;\r
 854 <a href="#p_over">OVER</a> &#160;</p></div>\r
 855 <div class="paragraph"><p><a href="#p_pad">PAD</a> &#160;\r
 856 <a href="#p_pick">PICK</a> &#160;\r
 857 <a href="#p_program_version">PROGRAM_VERSION</a> &#160;</p></div>\r
 858 <div class="paragraph"><p><a href="#p_quit">QUIT</a> &#160;</p></div>\r
 859 <div class="paragraph"><p><a href="#p_read_stream_char">READ-STREAM-CHAR</a> &#160;\r
 860 <a href="#p_read_word">READ-WORD</a> &#160;\r
 861 <a href="#p_realloc">REALLOC</a> &#160;\r
 862 <a href="#p_return">RETURN</a> &#160;\r
 863 <a href="#p_roll">ROLL</a> &#160;\r
 864 <a href="#p_rot">ROT</a> &#160;\r
 865 <a href="#p_rbp">RSP</a> &#160;</p></div>\r
 866 <div class="paragraph"><p><a href="#p_sp">SP</a> &#160;\r
 867 <a href="#p_state">STATE</a> &#160;\r
 868 <a href="#p_stdin">STDIN</a> &#160;\r
 869 <a href="#p_stream">STREAM</a> &#160;\r
 870 <a href="#p_stream_nchars">STREAM-NCHARS</a> &#160;\r
 871 <a href="#p_strlen">STRLEN</a> &#160;\r
 872 <a href="#p_strncmp">STRNCMP</a> &#160;\r
 873 <a href="#p_strncpy">STRNCPY</a> &#160;\r
 874 <a href="#p_swap">SWAP</a> &#160;\r
 875 <a href="#p_system">SYSTEM</a> &#160;</p></div>\r
 876 <div class="paragraph"><p><a href="#p_tell">TELL</a> &#160;\r
 877 <a href="#p_dot_temp">.TEMP</a> &#160;\r
 878 <a href="#p_terminate0">TERMINATE0</a> &#160;\r
 879 <a href="#p_tfa2cfa">TFA&gt;CFA</a> &#160;\r
 880 <a href="#p_tfa2dfa">TFA&gt;DFA</a> &#160;\r
 881 <a href="#p_tfa2flags_get">TFA&gt;FLAGS@</a> &#160;\r
 882 <a href="#p_tfa2namez">TFA&gt;NAMEZ</a> &#160;\r
 883 <a href="#p_then">THEN</a> &#160;\r
 884 <a href="#p_this_word">THIS-WORD</a> &#160;\r
 885 <a href="#p_true">TRUE</a> &#160;\r
 886 <a href="#p_tuck">TUCK</a> &#160;</p></div>\r
 887 <div class="paragraph"><p><a href="#p_unstream">UNSTREAM</a> &#160;\r
 888 <a href="#p_use">USE</a> &#160;</p></div>\r
 889 <div class="paragraph"><p><a href="#p_verboseQ">VERBOSE?</a> &#160;</p></div>\r
 890 <div class="paragraph"><p><a href="#p_within">WITHIN</a> &#160;\r
 891 <a href="#p_words">WORDS</a> &#160;</p></div>\r
 892 <div class="paragraph"><p><a href="#p_xor">XOR</a> &#160;</p></div>\r
 893 <div class="paragraph"><p><a href="#p_calltrace">[calltrace]</a> &#160;\r
 894 <a href="#p_setup_signals">[setup_signals]</a> &#160;</p></div>\r
 895 </div>\r
 896 </div>\r
 897 <div class="sect1">\r
 898 <h2 id="_word_descriptions">Word Descriptions</h2>\r
 899 <div class="sectionbody">\r
 900 <div class="paragraph"><p><a id="inline_code"></a></p></div>\r
 901 <div class="sect2">\r
 902 <h3 id="_word_asm">Word: [ASM]</h3>\r
 903 <div class="literalblock">\r
 904 <div class="content">\r
 905 <pre><code>data stack: ( -- )</code></pre>\r
 906 </div></div>\r
 907 <div class="paragraph"><p>"[ASM]" is a function word that introduces inline assembly in an\r
 908 RRQFORTH definition. Such assembly code may return to subsequence\r
 909 RRQFORTH executon by means of the following instruction sequence:</p></div>\r
 910 <div class="exampleblock">\r
 911 <div class="content">\r
 912 <div class="listingblock">\r
 913 <div class="content">\r
 914 <pre><code>        mov rsi,forthcode\r
 915         lodsq\r
 916         jmp qword [rax]\r
 917 forthcode:</code></pre>\r
 918 </div></div>\r
 919 </div></div>\r
 920 <div class="paragraph"><p>Note that the FORTH compiler does not invoke an assembler so any\r
 921 inline assembly code must be provided in its binary form.</p></div>\r
 922 <div style="text-align:center">\r
 923 _______________________________________________________\r
 924 </div>\r
 925 <div class="paragraph"><p><a id="p_0branch"></a></p></div>\r
 926 </div>\r
 927 <div class="sect2">\r
 928 <h3 id="_word_0branch">Word: 0BRANCH</h3>\r
 929 <div class="literalblock">\r
 930 <div class="content">\r
 931 <pre><code>Data stack: ( v -- )</code></pre>\r
 932 </div></div>\r
 933 <div class="paragraph"><p>"0BRANCH" is a function word that implements execution conditional by\r
 934 means of optionally adding the subsequent branch offset, or not, to\r
 935 the point of execution. If the value, v, is 0 then the branch offset\r
 936 is added, and otherwise execution continues with the cell following\r
 937 the branch offset in the definition.</p></div>\r
 938 <div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a\r
 939 definition take up a cell of 8 bytes. The offset is relative to the\r
 940 cell address immediately subsequent to the offset cell. In other\r
 941 words, offset 0 is not branching anywhere and an offset of -16 would\r
 942 make a tight loop back to the branch instruction itself. The latter\r
 943 would pull data stack values until and including the first non-zero\r
 944 value.</p></div>\r
 945 <div class="paragraph"><p>See also <a href="#p_1branch">1BRANCH</a>, <a href="#p_branch">BRANCH</a>, <a href="#p_if">IF</a>,\r
 946 <a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
 947 <div style="text-align:center">\r
 948 _______________________________________________________\r
 949 </div>\r
 950 <div class="paragraph"><p><a id="p_0equal"></a></p></div>\r
 951 </div>\r
 952 <div class="sect2">\r
 953 <h3 id="_word_0">Word: 0=</h3>\r
 954 <div class="literalblock">\r
 955 <div class="content">\r
 956 <pre><code>Data stack: ( v -- 0/-1 )</code></pre>\r
 957 </div></div>\r
 958 <div class="paragraph"><p>"0=" is a function word that replaces a value with its logical\r
 959 complement; the result is zero if the value non-zero, and the result\r
 960 is non-zero if the value is zero.</p></div>\r
 961 <div class="paragraph"><p>This is the same function as <a href="#p_not">NOT</a>.</p></div>\r
 962 <div style="text-align:center">\r
 963 _______________________________________________________\r
 964 </div>\r
 965 <div class="paragraph"><p><a id="p_0less"></a></p></div>\r
 966 </div>\r
 967 <div class="sect2">\r
 968 <h3 id="_word_0_lt">Word: 0&lt;</h3>\r
 969 <div class="literalblock">\r
 970 <div class="content">\r
 971 <pre><code>Data stack: ( v -- 0/-1 )</code></pre>\r
 972 </div></div>\r
 973 <div class="paragraph"><p>"0&lt;" is a function word that replaces a value with -1 if the value is\r
 974 less than 0, and 0 otherwise.</p></div>\r
 975 <div class="exampleblock">\r
 976 <div class="content">\r
 977 <div class="sidebarblock">\r
 978 <div class="content">\r
 979 <div class="title">Definition concept for 0&lt;</div>\r
 980 <div class="paragraph"><p>( v&#8201;&#8212;&#8201;0/1 ) : 0= 0 SWAP &lt; ;</p></div>\r
 981 </div></div>\r
 982 </div></div>\r
 983 <div class="paragraph"><p>See also <a href="#p_swap">SWAP</a> and <a href="#p_lessthan">&lt;</a>.</p></div>\r
 984 <div style="text-align:center">\r
 985 _______________________________________________________\r
 986 </div>\r
 987 <div class="paragraph"><p><a id="p_1branch"></a></p></div>\r
 988 </div>\r
 989 <div class="sect2">\r
 990 <h3 id="_word_1branch">Word: 1BRANCH</h3>\r
 991 <div class="literalblock">\r
 992 <div class="content">\r
 993 <pre><code>Data stack: ( v -- )</code></pre>\r
 994 </div></div>\r
 995 <div class="paragraph"><p>"1BRANCH" is a function word that implements execution conditional by\r
 996 means of optionally adding the subsequent branch offset, or not, to\r
 997 the point of execution. If the value, v, is non-zero then the branch\r
 998 offset is added, and otherwise execution continues with the cell\r
 999 following the branch offset in the definition.</p></div>\r
1000 <div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a\r
1001 definition take up a cell of 8 bytes. The offset is relative to the\r
1002 cell address immediately subsequent to the offset cell. In other\r
1003 words, offset 0 is not branching anywhere and an offset of -16 would\r
1004 make a tight loop back to the branch instruction itself. The latter\r
1005 would pull data stack values until and including the first zero value.</p></div>\r
1006 <div class="paragraph"><p>See also <a href="#p_0branch">0BRANCH</a>, <a href="#p_branch">BRANCH</a>, <a href="#p_if">IF</a>,\r
1007 <a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
1008 <div style="text-align:center">\r
1009 _______________________________________________________\r
1010 </div>\r
1011 <div class="paragraph"><p><a id="p_2drop"></a></p></div>\r
1012 </div>\r
1013 <div class="sect2">\r
1014 <h3 id="_word_2drop">Word: 2DROP</h3>\r
1015 <div class="literalblock">\r
1016 <div class="content">\r
1017 <pre><code>Data stack: ( v1 v2 -- )</code></pre>\r
1018 </div></div>\r
1019 <div class="paragraph"><p>"2DROP" is a function word that plainly discards the top 2 cells from\r
1020 the data stack.</p></div>\r
1021 <div style="text-align:center">\r
1022 _______________________________________________________\r
1023 </div>\r
1024 <div class="paragraph"><p><a id="p_2dup"></a></p></div>\r
1025 </div>\r
1026 <div class="sect2">\r
1027 <h3 id="_word_2dup">Word: 2DUP</h3>\r
1028 <div class="literalblock">\r
1029 <div class="content">\r
1030 <pre><code>Data stack: ( v1 v2 -- v1 v2 v1 v2 )</code></pre>\r
1031 </div></div>\r
1032 <div class="paragraph"><p>"2DUP" is a function word that duplicates the top 2 cells on the data\r
1033 stack.</p></div>\r
1034 <div class="exampleblock">\r
1035 <div class="content">\r
1036 <div class="sidebarblock">\r
1037 <div class="content">\r
1038 <div class="title">Definition concept for 2DUP</div>\r
1039 <div class="paragraph"><p>( v1 v2&#8201;&#8212;&#8201;v1 v2 v1 v2 ) : 2DUP OVER OVER ;</p></div>\r
1040 </div></div>\r
1041 </div></div>\r
1042 <div style="text-align:center">\r
1043 _______________________________________________________\r
1044 </div>\r
1045 <div class="paragraph"><p><a id="p_2get"></a></p></div>\r
1046 </div>\r
1047 <div class="sect2">\r
1048 <h3 id="_word_2">Word: 2@</h3>\r
1049 <div class="literalblock">\r
1050 <div class="content">\r
1051 <pre><code>Data stack: ( a -- v2 v1 )</code></pre>\r
1052 </div></div>\r
1053 <div class="paragraph"><p>"2@" is a function word that pushes the two concecutive values v1 and\r
1054 v2 from the address a onto the data stack. Value v1 is from address a\r
1055 and value v2 is from address a + 8.</p></div>\r
1056 <div style="text-align:center">\r
1057 _______________________________________________________\r
1058 </div>\r
1059 <div class="paragraph"><p><a id="p_2over"></a></p></div>\r
1060 </div>\r
1061 <div class="sect2">\r
1062 <h3 id="_word_2over">Word: 2OVER</h3>\r
1063 <div class="literalblock">\r
1064 <div class="content">\r
1065 <pre><code>Data stack: ( v1 v2 v3 v4 -- v1 v2 v3 v4 v1 v2 )</code></pre>\r
1066 </div></div>\r
1067 <div class="paragraph"><p>"2OVER" is a function word that replicates the second duble-cell pair\r
1068 onto the top of the data stack. This is similar to <a href="#p_over">OVER</a> but\r
1069 working with cell pairs rather than single cells.</p></div>\r
1070 <div class="exampleblock">\r
1071 <div class="content">\r
1072 <div class="sidebarblock">\r
1073 <div class="content">\r
1074 <div class="title">Definition concept for 2OVER</div>\r
1075 <div class="paragraph"><p>( v1 v2 v3 v4&#8201;&#8212;&#8201;v1 v2 v3 v4 v1 v2 ) : 2OVER 3 PICK 3 PICK ;</p></div>\r
1076 </div></div>\r
1077 </div></div>\r
1078 <div style="text-align:center">\r
1079 _______________________________________________________\r
1080 </div>\r
1081 <div class="paragraph"><p><a id="p_2put"></a></p></div>\r
1082 </div>\r
1083 <div class="sect2">\r
1084 <h3 id="_word_2_2">Word: 2!</h3>\r
1085 <div class="literalblock">\r
1086 <div class="content">\r
1087 <pre><code>Data stack: ( v2 v1 a -- )</code></pre>\r
1088 </div></div>\r
1089 <div class="paragraph"><p>"2!" is a function word that stors two concecutive values v1 and v2 to\r
1090 the address a from the data stack. Value v1 is stored at address a and\r
1091 value v2 is stored at address a + 8.</p></div>\r
1092 <div style="text-align:center">\r
1093 _______________________________________________________\r
1094 </div>\r
1095 <div class="paragraph"><p><a id="p_2swap"></a></p></div>\r
1096 </div>\r
1097 <div class="sect2">\r
1098 <h3 id="_word_2swap">Word: 2SWAP</h3>\r
1099 <div class="literalblock">\r
1100 <div class="content">\r
1101 <pre><code>Data stack: ( v1 v2 v3 v4 -- v3 v4 v1 v2 )</code></pre>\r
1102 </div></div>\r
1103 <div class="paragraph"><p>"2SWAP" is a function word the reorgnizes the top 4 cells swappping\r
1104 the upper and lower pair. This is similar to <a href="#p_swap">SWAP</a> but\r
1105 working with cell pairs rather than single cells.</p></div>\r
1106 <div class="exampleblock">\r
1107 <div class="content">\r
1108 <div class="sidebarblock">\r
1109 <div class="content">\r
1110 <div class="title">Definition concept for 2SWAP</div>\r
1111 <div class="paragraph"><p>( v1 v2 v3 v4&#8201;&#8212;&#8201;v3 v4 v1 v2 ) : 2SWAP 3 ROLL 3 ROLL ;</p></div>\r
1112 </div></div>\r
1113 </div></div>\r
1114 <div style="text-align:center">\r
1115 _______________________________________________________\r
1116 </div>\r
1117 <div class="paragraph"><p><a id="p_Ccomma"></a></p></div>\r
1118 </div>\r
1119 <div class="sect2">\r
1120 <h3 id="_word_c">Word: C,</h3>\r
1121 <div class="literalblock">\r
1122 <div class="content">\r
1123 <pre><code>Data stack: ( v -- )</code></pre>\r
1124 </div></div>\r
1125 <div class="paragraph"><p>"C," (C-comma) is a function word that puts a byte on the\r
1126 <a href="#p_here">HERE</a> heap. The least significant byte of the value is put\r
1127 at the current free head address, which also is incremented.</p></div>\r
1128 <div class="exampleblock">\r
1129 <div class="content">\r
1130 <div class="sidebarblock">\r
1131 <div class="content">\r
1132 <div class="title">Definition concept for C,</div>\r
1133 <div class="paragraph"><p>: C, HERE @ 1 ALLOT C! ;  ( v&#8201;&#8212;&#8201;; Claim 1 byte and put lsb value there )</p></div>\r
1134 </div></div>\r
1135 </div></div>\r
1136 <div class="paragraph"><p>See also <a href="#p_colon">:</a>, <a href="#p_comma">[p_comma]</a>. <a href="#p_here">HERE</a>, <a href="#p_get">@</a>,\r
1137 <a href="#p_allot">ALLOT</a>, <a href="#p_Cput">C!</a> and <a href="#p_semicolon">;</a>.</p></div>\r
1138 <div style="text-align:center">\r
1139 _______________________________________________________\r
1140 </div>\r
1141 <div class="paragraph"><p><a id="p_cfa2tfa"></a></p></div>\r
1142 </div>\r
1143 <div class="sect2">\r
1144 <h3 id="_word_cfa_gt_tfa">Word: CFA&gt;TFA</h3>\r
1145 <div class="literalblock">\r
1146 <div class="content">\r
1147 <pre><code>Data stack: ( cfa -- tfa )</code></pre>\r
1148 </div></div>\r
1149 <div class="paragraph"><p>"CFA&gt;TFA" is a function word that pushes word tfa of the given cfa.</p></div>\r
1150 <div class="exampleblock">\r
1151 <div class="content">\r
1152 <div class="sidebarblock">\r
1153 <div class="content">\r
1154 <div class="title">Definition concept for CFA&gt;TFA</div>\r
1155 <div class="paragraph"><p>: CFA&gt;TFA 14 - @ ;</p></div>\r
1156 </div></div>\r
1157 </div></div>\r
1158 <div style="text-align:center">\r
1159 _______________________________________________________\r
1160 </div>\r
1161 <div class="paragraph"><p><a id="p_Cget"></a></p></div>\r
1162 </div>\r
1163 <div class="sect2">\r
1164 <h3 id="_word_c_2">Word: C@</h3>\r
1165 <div class="literalblock">\r
1166 <div class="content">\r
1167 <pre><code>Data stack: ( a -- v )</code></pre>\r
1168 </div></div>\r
1169 <div class="paragraph"><p>"C@" is a function word that pushes the byte value v from the address a.</p></div>\r
1170 <div style="text-align:center">\r
1171 _______________________________________________________\r
1172 </div>\r
1173 <div class="paragraph"><p><a id="p_Cput"></a></p></div>\r
1174 </div>\r
1175 <div class="sect2">\r
1176 <h3 id="_word_c_3">Word: C!</h3>\r
1177 <div class="literalblock">\r
1178 <div class="content">\r
1179 <pre><code>Data stack: ( v a -- )</code></pre>\r
1180 </div></div>\r
1181 <div class="paragraph"><p>"C!" is a function word that stores the byte value v (the least\r
1182 significant byte of the cell) at the address a.</p></div>\r
1183 <div style="text-align:center">\r
1184 _______________________________________________________\r
1185 </div>\r
1186 <div class="paragraph"><p><a id="p_Rget"></a></p></div>\r
1187 </div>\r
1188 <div class="sect2">\r
1189 <h3 id="_word_r">Word: R@</h3>\r
1190 <div class="literalblock">\r
1191 <div class="content">\r
1192 <pre><code>Data stack: ( -- v )   Return stack: ( v -- v )</code></pre>\r
1193 </div></div>\r
1194 <div class="paragraph"><p>"R@" is a function word that "copies" the top return stack value onto\r
1195 the data stack.</p></div>\r
1196 <div style="text-align:center">\r
1197 _______________________________________________________\r
1198 </div>\r
1199 <div class="paragraph"><p><a id="p_Rgt"></a></p></div>\r
1200 </div>\r
1201 <div class="sect2">\r
1202 <h3 id="_word_r_gt">Word: R&gt;</h3>\r
1203 <div class="literalblock">\r
1204 <div class="content">\r
1205 <pre><code>Data stack: ( -- v )   Return stack: ( v -- )</code></pre>\r
1206 </div></div>\r
1207 <div class="paragraph"><p>"R&gt;" is a function word that "moves" the top return stack value onto\r
1208 the data stack.</p></div>\r
1209 <div style="text-align:center">\r
1210 _______________________________________________________\r
1211 </div>\r
1212 <div class="paragraph"><p><a id="p_abs"></a></p></div>\r
1213 </div>\r
1214 <div class="sect2">\r
1215 <h3 id="_word_abs">Word: ABS</h3>\r
1216 <div class="literalblock">\r
1217 <div class="content">\r
1218 <pre><code>Data stack: ( v1 -- v2 )</code></pre>\r
1219 </div></div>\r
1220 <div class="paragraph"><p>"ABS" is a function word that replaces a value with its absolute\r
1221 value. To that end, the values are 64-bit signed integers.</p></div>\r
1222 <div style="text-align:center">\r
1223 _______________________________________________________\r
1224 </div>\r
1225 <div class="paragraph"><p><a id="p_again"></a></p></div>\r
1226 </div>\r
1227 <div class="sect2">\r
1228 <h3 id="_word_again">Word: AGAIN</h3>\r
1229 <div class="literalblock">\r
1230 <div class="content">\r
1231 <pre><code>Data stack: Compiling: ( -- a )</code></pre>\r
1232 </div></div>\r
1233 <div class="paragraph"><p>"AGAIN" is an immediate function word that is used together with\r
1234 <a href="#p_begin">BEGIN</a> and instead of <a href="#p_end">END</a> to implement structured\r
1235 execution control. AGAIN scans the datastack for the nearest preceding\r
1236 BEGIN marker and lays out an unconditional branch from this point the\r
1237 beginning of the block during execution. It thereafter performs the\r
1238 <a href="#p_end">END</a> compile action to end the block.</p></div>\r
1239 <div style="text-align:center">\r
1240 _______________________________________________________\r
1241 </div>\r
1242 <div class="paragraph"><p><a id="p_allot"></a></p></div>\r
1243 </div>\r
1244 <div class="sect2">\r
1245 <h3 id="_word_allot">Word: ALLOT</h3>\r
1246 <div class="literalblock">\r
1247 <div class="content">\r
1248 <pre><code>Data stack: ( n -- )</code></pre>\r
1249 </div></div>\r
1250 <div class="paragraph"><p>"ALLOT" is a function word that merely increments the <a href="#p_here">HERE</a>\r
1251 variable with <code>n</code> so as to claim that amount of the heap.</p></div>\r
1252 <div class="exampleblock">\r
1253 <div class="content">\r
1254 <div class="sidebarblock">\r
1255 <div class="content">\r
1256 <div class="title">Defintion concept for ALLOT</div>\r
1257 <div class="paragraph"><p>( n&#8201;&#8212;&#8201;) : ALLOT HERE @ + HERE ! ;</p></div>\r
1258 </div></div>\r
1259 </div></div>\r
1260 <div class="exampleblock">\r
1261 <div class="content">\r
1262 <div class="paragraph"><div class="title">Usage example 1: claim 16 bytes for variable FOO</div><p>CREATE FOO DROP HERE @ 16 ALLOT</p></div>\r
1263 </div></div>\r
1264 <div style="text-align:center">\r
1265 _______________________________________________________\r
1266 </div>\r
1267 <div class="paragraph"><p><a id="p_and"></a></p></div>\r
1268 </div>\r
1269 <div class="sect2">\r
1270 <h3 id="_word_and">Word: AND</h3>\r
1271 <div class="literalblock">\r
1272 <div class="content">\r
1273 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>\r
1274 </div></div>\r
1275 <div class="paragraph"><p>"AND" is a function word that replaces a value pair with their bitwise\r
1276 conjunction; each bit is 1 if the corresponding bits of both operands\r
1277 are 1 and 0 if not.</p></div>\r
1278 <div style="text-align:center">\r
1279 _______________________________________________________\r
1280 </div>\r
1281 <div class="paragraph"><p><a id="p_args"></a></p></div>\r
1282 </div>\r
1283 <div class="sect2">\r
1284 <h3 id="_word_main_args">Word: MAIN-ARGS</h3>\r
1285 <div class="literalblock">\r
1286 <div class="content">\r
1287 <pre><code>Data stack: ( -- p[argv** argc] )</code></pre>\r
1288 </div></div>\r
1289 <div class="paragraph"><p>"ARGS" is a value word that holds a pointer to the command line data\r
1290 block which consists of a count cell followed by that many asciiz\r
1291 pointers and then a 0 cell.</p></div>\r
1292 <div class="exampleblock">\r
1293 <div class="content">\r
1294 <div class="listingblock">\r
1295 <div class="title">Usage example 2: the command line argument block</div>\r
1296 <div class="content">\r
1297 <pre><code>ARGS -&gt; 8 bytes: count of non-zero asciiz pointers following\r
1298         8 bytes: command name string\r
1299         8 bytes: first argument string\r
1300         8* ...\r
1301         8 zero</code></pre>\r
1302 </div></div>\r
1303 </div></div>\r
1304 <div style="text-align:center">\r
1305 _______________________________________________________\r
1306 </div>\r
1307 <div class="paragraph"><p><a id="p_base"></a></p></div>\r
1308 </div>\r
1309 <div class="sect2">\r
1310 <h3 id="_word_base">Word: BASE</h3>\r
1311 <div class="literalblock">\r
1312 <div class="content">\r
1313 <pre><code>Data stack: ( -- a )</code></pre>\r
1314 </div></div>\r
1315 <div class="paragraph"><p>"BASE" is a variable word for the numerical base used by input and\r
1316 output functions, <a href="#p_number">NUMBER</a> and <a href="#p_dot">[p_dot]</a>, when\r
1317 translating numbers between cell value form and text form. The\r
1318 numerical base is set to 10 or 16 by <a href="#p_decimal">DECIMAL</a> and\r
1319 <a href="#p_hex">HEX</a> respectively, and those are the only two bases currently\r
1320 supported.</p></div>\r
1321 <div class="paragraph"><p>See also <a href="#p_digits">DIGITS</a>, which holds the mapping table from\r
1322 digits to text.</p></div>\r
1323 <div style="text-align:center">\r
1324 _______________________________________________________\r
1325 </div>\r
1326 <div class="paragraph"><p><a id="p_begin"></a></p></div>\r
1327 </div>\r
1328 <div class="sect2">\r
1329 <h3 id="_word_begin">Word: BEGIN</h3>\r
1330 <div class="literalblock">\r
1331 <div class="content">\r
1332 <pre><code>Data stack: Compiling: ( -- a 0 )</code></pre>\r
1333 </div></div>\r
1334 <div class="paragraph"><p>"BEGIN" is an immediate function word that is used together with\r
1335 <a href="#p_ifbreak">IFBREAK</a>, <a href="#p_ifagain">IFAGAIN</a> and <a href="#p_end">END</a> to\r
1336 implement structured execution control. BEGIN simply places the\r
1337 address for resolving branches back to this point during execution,\r
1338 and then a 0 as a marker so as to allow for an unknown number of block\r
1339 exit points.</p></div>\r
1340 <div class="exampleblock">\r
1341 <div class="content">\r
1342 <div class="listingblock">\r
1343 <div class="title">Usage example 3:</div>\r
1344 <div class="content">\r
1345 <pre><code>: WTELL ( tfa -- ; Print word pname )\r
1346   24 + DUP 8 + SWAP @ TELL SP EMIT\r
1347 ;\r
1348 \r
1349 : WORDS ( wordlist -- ; Print all words of word list )\r
1350   BEGIN\r
1351     @ DUP 0= IFBREAK\r
1352     DUP WTELL\r
1353   END\r
1354   DROP\r
1355   NL EMIT\r
1356 ;</code></pre>\r
1357 </div></div>\r
1358 </div></div>\r
1359 <div style="text-align:center">\r
1360 _______________________________________________________\r
1361 </div>\r
1362 <div class="paragraph"><p><a id="p_bracketed_quote"></a></p></div>\r
1363 </div>\r
1364 <div class="sect2">\r
1365 <h3 id="_word">Word: [']</h3>\r
1366 <div class="literalblock">\r
1367 <div class="content">\r
1368 <pre><code>Data stack: ( -- cfa )   Input stream: word</code></pre>\r
1369 </div></div>\r
1370 <div class="paragraph"><p>"[']" is an immediate function word that reads the next word on the\r
1371 input stream and pushes its cfa.</p></div>\r
1372 <div class="exampleblock">\r
1373 <div class="content">\r
1374 <div class="sidebarblock">\r
1375 <div class="content">\r
1376 <div class="title">Definition concept for [']</div>\r
1377 <div class="paragraph"><p>: ['] IMMEDIATE ' ;</p></div>\r
1378 </div></div>\r
1379 </div></div>\r
1380 <div style="text-align:center">\r
1381 _______________________________________________________\r
1382 </div>\r
1383 <div class="paragraph"><p><a id="p_branch"></a></p></div>\r
1384 </div>\r
1385 <div class="sect2">\r
1386 <h3 id="_word_branch">Word: BRANCH</h3>\r
1387 <div class="literalblock">\r
1388 <div class="content">\r
1389 <pre><code>Data stack: ( -- )</code></pre>\r
1390 </div></div>\r
1391 <div class="paragraph"><p>"BRANCH" is a function word that implements execution transfer by\r
1392 means of adding the subsequent branch offset to the point of\r
1393 execution.</p></div>\r
1394 <div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a\r
1395 definition take up a cell of 8 bytes. The offset is relative to the\r
1396 cell address immediately subsequent to the offset cell. In other\r
1397 words, offset 0 is not branching anywhere and an offset of -16 would\r
1398 make a tight loop back to the branch instruction itself. The latter\r
1399 would pull data stack values until and including the first zero value.</p></div>\r
1400 <div class="paragraph"><p>See also <a href="#p_0branch">0BRANCH</a>, <a href="#p_1branch">1BRANCH</a>, <a href="#p_if">IF</a>,\r
1401 <a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
1402 <div style="text-align:center">\r
1403 _______________________________________________________\r
1404 </div>\r
1405 <div class="paragraph"><p><a id="p_break"></a></p></div>\r
1406 </div>\r
1407 <div class="sect2">\r
1408 <h3 id="_word_break">Word: BREAK</h3>\r
1409 <div class="paragraph"><p>"BREAK" is an immediate function word that lays out an unconditional\r
1410 branch out of an enclosing xef:p_begin[BEGIN]-<a href="#p_end">END</a> block.\r
1411 Similar to <a href="#p_ifbreak">IFBREAK</a> it lays out the branch cell\r
1412 followed by a reserved cell for the branch offset, and inserts the\r
1413 resolution address just above the required 0 on the data stack.</p></div>\r
1414 <div class="exampleblock">\r
1415 <div class="content">\r
1416 <div class="listingblock">\r
1417 <div class="title">Usage example 4: unconditional break with a condition.</div>\r
1418 <div class="content">\r
1419 <pre><code>: WTELL ( tfa -- ; Print word pname )\r
1420   24 + DUP 8 + SWAP @ TELL SP EMIT\r
1421 ;\r
1422 \r
1423 : WORDS ( wordlist -- ; Print all words of word list )\r
1424   BEGIN\r
1425     @ DUP IF DUP WTELL ELSE BREAK THEN\r
1426     1 IFAGAIN\r
1427   END\r
1428   DROP\r
1429   NL EMIT\r
1430 ;</code></pre>\r
1431 </div></div>\r
1432 </div></div>\r
1433 <div class="paragraph"><p>See also <a href="#p_branch">BRANCH</a>, <a href="#p_0branch">0BRANCH</a>,\r
1434 <a href="#p_1branch">1BRANCH</a>, <a href="#p_if">IF</a>, <a href="#p_else">ELSE</a>,\r
1435 <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
1436 <div style="text-align:center">\r
1437 _______________________________________________________\r
1438 </div>\r
1439 <div class="paragraph"><p><a id="p_calltrace"></a></p></div>\r
1440 </div>\r
1441 <div class="sect2">\r
1442 <h3 id="_word_calltrace">Word: [calltrace]</h3>\r
1443 <div class="paragraph"><p>"[calltrace]" is a variable word that ccontains a small assembly\r
1444 snippet that may be used for debugging when running under <code>gdb</code>.</p></div>\r
1445 <div style="text-align:center">\r
1446 _______________________________________________________\r
1447 </div>\r
1448 <div class="paragraph"><p><a id="p_cfa2flags_get"></a></p></div>\r
1449 </div>\r
1450 <div class="sect2">\r
1451 <h3 id="_word_cfa_gt_flags">Word: CFA&gt;FLAGS@</h3>\r
1452 <div class="literalblock">\r
1453 <div class="content">\r
1454 <pre><code>Data stack: ( cfa -- flags )</code></pre>\r
1455 </div></div>\r
1456 <div class="paragraph"><p>"CFA&gt;FLAGS@" is a function word that pushes word flags of the given cfa.</p></div>\r
1457 <div class="exampleblock">\r
1458 <div class="content">\r
1459 <div class="sidebarblock">\r
1460 <div class="content">\r
1461 <div class="title">Defintion concept for CFA&gt;FLAGS@</div>\r
1462 <div class="paragraph"><p>: CFA&gt;FLAGS@ 16 - @ 16 + ;</p></div>\r
1463 </div></div>\r
1464 </div></div>\r
1465 <div style="text-align:center">\r
1466 _______________________________________________________\r
1467 </div>\r
1468 <div class="paragraph"><p><a id="p_clear_stream"></a></p></div>\r
1469 </div>\r
1470 <div class="sect2">\r
1471 <h3 id="_word_clear_stream">Word: CLEAR-STREAM</h3>\r
1472 <div class="literalblock">\r
1473 <div class="content">\r
1474 <pre><code>Data stack: ( stream -- )</code></pre>\r
1475 </div></div>\r
1476 <div class="paragraph"><p>"CLEAR-STREAM" is a function word that discards whatever is currently\r
1477 remaining in the buffer for the stream, so that a subsequent read will\r
1478 pull in more data from its source.</p></div>\r
1479 <div class="paragraph"><p>See also <a href="#p_read_stream_char">READ-STREAM-CHAR</a>.</p></div>\r
1480 <div style="text-align:center">\r
1481 _______________________________________________________\r
1482 </div>\r
1483 <div class="paragraph"><p><a id="p_colon"></a></p></div>\r
1484 </div>\r
1485 <div class="sect2">\r
1486 <h3 id="_word_3">Word: :</h3>\r
1487 <div class="literalblock">\r
1488 <div class="content">\r
1489 <pre><code>Data stack: ( -- )    Input stream: word</code></pre>\r
1490 </div></div>\r
1491 <div class="paragraph"><p>":" (colon) is a function word that starts a new forth definition.\r
1492 This includes reading the next word for making a new dictionary entry\r
1493 and setting evaluation state to compiling mode.</p></div>\r
1494 <div class="exampleblock">\r
1495 <div class="content">\r
1496 <div class="sidebarblock">\r
1497 <div class="content">\r
1498 <div class="title">Definition concept for :</div>\r
1499 <div class="paragraph"><p>: : doFORTH READ-WORD CREATE TFA&gt;CFA ! ] ;</p></div>\r
1500 </div></div>\r
1501 </div></div>\r
1502 <div class="paragraph"><p>See also <a href="#p_doforth">doFORTH</a>, <a href="#p_read_word">READ-WORD</a>,\r
1503 <a href="#p_create">CREATE</a>, <a href="#p_tfa2cfa">TFA&gt;CFA</a>, <a href="#p_put">!</a>,\r
1504 <a href="#p_left_bracket">]</a> and <a href="#p_semicolon">;</a>.</p></div>\r
1505 <div style="text-align:center">\r
1506 _______________________________________________________\r
1507 </div>\r
1508 <div class="paragraph"><p><a id="p_comma"></a></p></div>\r
1509 </div>\r
1510 <div class="sect2">\r
1511 <h3 id="_word_4">Word: ,</h3>\r
1512 <div class="literalblock">\r
1513 <div class="content">\r
1514 <pre><code>Data stack: ( v -- )</code></pre>\r
1515 </div></div>\r
1516 <div class="paragraph"><p>"," (comma) is a function word that puts a cell value on the\r
1517 <a href="#p_here">HERE</a> heap.</p></div>\r
1518 <div class="exampleblock">\r
1519 <div class="content">\r
1520 <div class="sidebarblock">\r
1521 <div class="content">\r
1522 <div class="title">Definition concept for ,</div>\r
1523 <div class="paragraph"><p>: , HERE @ 8 ALLOT ! ; ( v&#8201;&#8212;&#8201;; Claim 8 bytes and put value there )</p></div>\r
1524 </div></div>\r
1525 </div></div>\r
1526 <div class="paragraph"><p>See also <a href="#p_colon">:</a>, <a href="#p_Ccomma">[p_Ccomma]</a>. <a href="#p_here">HERE</a>, <a href="#p_get">@</a>,\r
1527 <a href="#p_allot">ALLOT</a>, <a href="#p_put">!</a> and <a href="#p_semicolon">;</a>.</p></div>\r
1528 <div style="text-align:center">\r
1529 _______________________________________________________\r
1530 </div>\r
1531 <div class="paragraph"><p><a id="p_create"></a></p></div>\r
1532 </div>\r
1533 <div class="sect2">\r
1534 <h3 id="_word_create">Word: CREATE</h3>\r
1535 <div class="literalblock">\r
1536 <div class="content">\r
1537 <pre><code>Data stack: ( char* n -- tfa )</code></pre>\r
1538 </div></div>\r
1539 <div class="paragraph"><p>"CREATE" is a function word that allocates a "word header" with the\r
1540 indicated [n:char*] print name, and returns the "TFA" (Token Field\r
1541 Address) of the word. The header memory layout is as follows:</p></div>\r
1542 <div class="exampleblock">\r
1543 <div class="content">\r
1544 <div class="listingblock">\r
1545 <div class="title">Layout 1: rrqforth word structure</div>\r
1546 <div class="content">\r
1547 <pre><code>struct WORD\r
1548 TFA  8 link ; tfa of previous word\r
1549 pCFA 8 cfap ; CFA = Code Field Address of this word\r
1550      8 flags ;\r
1551 PFA  8 length ; length of pname representation\r
1552      ? pname ; the pname bytes\r
1553      1 nul ; a forced nul byte following the pname\r
1554 pTFA 8 tfap ; TFA = Token Field Address of this word\r
1555 OFF  8 doff ; entry offset for FORTH level execution\r
1556 CFA  8 doer ; word execution semantics\r
1557 DFA  0 content ; DFA = Data Field Address\r
1558 end_struct</code></pre>\r
1559 </div></div>\r
1560 </div></div>\r
1561 <div class="paragraph"><p>A "word" is generally understod as a marker in memory for some content\r
1562 as held in the memory space following the DFA (Data Field Address).</p></div>\r
1563 <div class="paragraph"><p>The words CFA (Code Field Address) is the most important field for\r
1564 RRQFORTH execution, as holding a jump address to the assembly code\r
1565 that implements the particular execution semantics for the word.\r
1566 "CREATE" will assign this as "dovariable", which makes the word push\r
1567 its DFA when executed. This is changed to "doforth" for RRQFORTH\r
1568 function words initiated by ":" (aka "COLON") or changed to "dovalue"\r
1569 for RRQFORTH constants created by "CONSTANT".</p></div>\r
1570 <div class="exampleblock">\r
1571 <div class="content">\r
1572 <div class="sidebarblock">\r
1573 <div class="content">\r
1574 <div class="title">Definition concept for CREATE</div>\r
1575 <div class="paragraph"><p>HERE @ R&gt; ( save tfa on RS )\r
1576   R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )\r
1577   DUP 49 + R@ + ,             ( pCFA )\r
1578   0 ,                         ( flags )\r
1579   DUP , ( length )\r
1580   HERE @ ROT ROT MEMCPY 0 C,  ( pname + NUL )\r
1581   R@ ,                        ( pTFA )\r
1582   0 ,                         ( OFF )\r
1583   doVARIABLE                  ( CFA, default semantics )</p></div>\r
1584 </div></div>\r
1585 </div></div>\r
1586 <div class="exampleblock">\r
1587 <div class="content">\r
1588 <div class="listingblock">\r
1589 <div class="title">Usage example 5: a possible definition of CONSTANT</div>\r
1590 <div class="content">\r
1591 <pre><code>: CONSTANT READ-WORD CREATE TFA&gt;DFA doVALUE OVER 8 - ! ! ;</code></pre>\r
1592 </div></div>\r
1593 </div></div>\r
1594 <div class="paragraph"><p>See also <a href="#p_put">!</a>, <a href="#p_plus">+</a>, <a href="#p_comma">[p_comma]</a>, <a href="#p_get">@</a>,\r
1595 <a href="#p_Ccomma">[p_Ccomma]</a>, <a href="#p_current_word">CURRENT-WORD</a>, <a href="#p_dup">DUP</a>,\r
1596 <a href="#p_here">HERE</a>, <a href="#p_herememcpy">HERE</a>, <a href="#p_Rget">R@</a>, <a href="#p_rot">ROT</a>,\r
1597 and <a href="#p_dovariable">doVARIABLE</a>,\r
1598 as well as <a href="#p_execute">EXECUTE</a>\r
1599 about the range of "doer" assignments and their meanings.</p></div>\r
1600 <div style="text-align:center">\r
1601 _______________________________________________________\r
1602 </div>\r
1603 <div class="paragraph"><p><a id="p_current_wordlist"></a></p></div>\r
1604 </div>\r
1605 <div class="sect2">\r
1606 <h3 id="_word_current_wordlist">Word: CURRENT-WORDLIST</h3>\r
1607 <div class="literalblock">\r
1608 <div class="content">\r
1609 <pre><code>Data stack: ( -- a )</code></pre>\r
1610 </div></div>\r
1611 <div class="paragraph"><p>"CURRENT-WORDLIST" is a variable word that points out the DFA of the\r
1612 current word list word for <a href="#p_find">FIND</a> to use finding words. The\r
1613 word list word content is as follows:</p></div>\r
1614 <div class="exampleblock">\r
1615 <div class="content">\r
1616 <div class="listingblock">\r
1617 <div class="title">Layout 2: word list word content</div>\r
1618 <div class="content">\r
1619 <pre><code>  8 TFA of latest word in the word list\r
1620   8 DFA of the/a subsequent word list to search through</code></pre>\r
1621 </div></div>\r
1622 </div></div>\r
1623 <div class="paragraph"><p>Note that word lists are chained by "extension" and in general it ends\r
1624 with the <a href="#p_forth">FORTH</a> word list. Initially the\r
1625 <a href="#p_system">SYSTEM</a> word list is the only other word list.</p></div>\r
1626 <div style="text-align:center">\r
1627 _______________________________________________________\r
1628 </div>\r
1629 <div class="paragraph"><p><a id="data_stack"></a></p></div>\r
1630 </div>\r
1631 <div class="sect2">\r
1632 <h3 id="_word_data_stack">Word: DATA-STACK</h3>\r
1633 <div class="literalblock">\r
1634 <div class="content">\r
1635 <pre><code>Data stack: ( -- a )</code></pre>\r
1636 </div></div>\r
1637 <div class="paragraph"><p>"DATA-STACK" is a variable word that harbours the data stack.</p></div>\r
1638 <div style="text-align:center">\r
1639 _______________________________________________________\r
1640 </div>\r
1641 <div class="paragraph"><p><a id="p_decimal"></a></p></div>\r
1642 </div>\r
1643 <div class="sect2">\r
1644 <h3 id="_word_decimal">Word: DECIMAL</h3>\r
1645 <div class="literalblock">\r
1646 <div class="content">\r
1647 <pre><code>Data stack: ( -- )</code></pre>\r
1648 </div></div>\r
1649 <div class="paragraph"><p>"DECIMAL" is a function word that sets <a href="#p_base">BASE</a> to 10.</p></div>\r
1650 <div class="exampleblock">\r
1651 <div class="content">\r
1652 <div class="sidebarblock">\r
1653 <div class="content">\r
1654 <div class="title">Definition concept for DECIMAL</div>\r
1655 <div class="paragraph"><p>: DECIMAL 10 BASE ! ;</p></div>\r
1656 </div></div>\r
1657 </div></div>\r
1658 <div style="text-align:center">\r
1659 _______________________________________________________\r
1660 </div>\r
1661 <div class="paragraph"><p><a id="p_definitions"></a></p></div>\r
1662 </div>\r
1663 <div class="sect2">\r
1664 <h3 id="_word_definitions">Word: DEFINITIONS</h3>\r
1665 <div class="literalblock">\r
1666 <div class="content">\r
1667 <pre><code>Data stack: ( wordlist -- )</code></pre>\r
1668 </div></div>\r
1669 <div class="paragraph"><p>"DEFINITIONS" is a function word that installs the given wordlist as\r
1670 the <a href="#p_current_wordlist">CURRENT-WORDLIST</a> one.</p></div>\r
1671 <div class="exampleblock">\r
1672 <div class="content">\r
1673 <div class="sidebarblock">\r
1674 <div class="content">\r
1675 <div class="title">Definition concept for DEFINITIONS</div>\r
1676 <div class="paragraph"><p>: DEFINITIONS CURRENT-WORDLIST ! ;</p></div>\r
1677 </div></div>\r
1678 </div></div>\r
1679 <div style="text-align:center">\r
1680 _______________________________________________________\r
1681 </div>\r
1682 <div class="paragraph"><p><a id="p_depth"></a></p></div>\r
1683 </div>\r
1684 <div class="sect2">\r
1685 <h3 id="_word_depth">Word: DEPTH</h3>\r
1686 <div class="literalblock">\r
1687 <div class="content">\r
1688 <pre><code>Data stack: ( -- v )</code></pre>\r
1689 </div></div>\r
1690 <div class="paragraph"><p>"DEPTH" is a function word that pushes the count of data stack cells\r
1691 onto the data stack.</p></div>\r
1692 <div style="text-align:center">\r
1693 _______________________________________________________\r
1694 </div>\r
1695 <div class="paragraph"><p><a id="p_dfa2tfa"></a></p></div>\r
1696 </div>\r
1697 <div class="sect2">\r
1698 <h3 id="_word_dfa_gt_tfa">Word: DFA&gt;TFA</h3>\r
1699 <div class="literalblock">\r
1700 <div class="content">\r
1701 <pre><code>Data stack: ( dfa -- tfa )</code></pre>\r
1702 </div></div>\r
1703 <div class="paragraph"><p>"DFA&gt;TFA" is a function word that pushes word tfa of the given dfa.</p></div>\r
1704 <div class="exampleblock">\r
1705 <div class="content">\r
1706 <div class="sidebarblock">\r
1707 <div class="content">\r
1708 <div class="title">Definition concept for DFA&gt;TFA</div>\r
1709 <div class="paragraph"><p>: DFA&gt;TFA 24 - @ ;</p></div>\r
1710 </div></div>\r
1711 </div></div>\r
1712 <div style="text-align:center">\r
1713 _______________________________________________________\r
1714 </div>\r
1715 <div class="paragraph"><p><a id="p_digits"></a></p></div>\r
1716 </div>\r
1717 <div class="sect2">\r
1718 <h3 id="_word_digits">Word: DIGITS</h3>\r
1719 <div class="literalblock">\r
1720 <div class="content">\r
1721 <pre><code>Data stack: ( -- a )</code></pre>\r
1722 </div></div>\r
1723 <div class="paragraph"><p>"DIGITS" is a variable word that holds the character array for mapping\r
1724 digit values to characters. It contains the 16 characters 0-9 and a-f.</p></div>\r
1725 <div style="text-align:center">\r
1726 _______________________________________________________\r
1727 </div>\r
1728 <div class="paragraph"><p><a id="p_div"></a></p></div>\r
1729 </div>\r
1730 <div class="sect2">\r
1731 <h3 id="_word_5">Word: /</h3>\r
1732 <div class="literalblock">\r
1733 <div class="content">\r
1734 <pre><code>Data stack: ( v1 v2 -- q )</code></pre>\r
1735 </div></div>\r
1736 <div class="paragraph"><p>"/" (div) is a function word that replaces a pair of values with the\r
1737 results of signed integer division of the first, v1, divided by the\r
1738 second, v2. To that end, the values are 64-bit signed integers. The\r
1739 result is the integer quotient, q, and the discarded remainder, r,\r
1740 where q and r are the respectively largest and smallest integers to\r
1741 satisfy the formula:</p></div>\r
1742 <div class="literalblock">\r
1743 <div class="content">\r
1744 <pre><code>       v1 = q * v2 + r</code></pre>\r
1745 </div></div>\r
1746 <div style="text-align:center">\r
1747 _______________________________________________________\r
1748 </div>\r
1749 <div class="paragraph"><p><a id="p_divmod"></a></p></div>\r
1750 </div>\r
1751 <div class="sect2">\r
1752 <h3 id="_word_mod">Word: /MOD</h3>\r
1753 <div class="literalblock">\r
1754 <div class="content">\r
1755 <pre><code>Data stack: ( v1 v2 -- q r )</code></pre>\r
1756 </div></div>\r
1757 <div class="paragraph"><p>"/MOD" (div-mod) is a function word that replaces a pair of values\r
1758 with the results of signed integer division of the first, v1, divided\r
1759 by the second, v2. To that end, the values are 64-bit signed integers.\r
1760 The result is the integer quotient, q, and the remainder, r, where q\r
1761 and r are the respectively largest and smallest integers to satisfy\r
1762 the formula:</p></div>\r
1763 <div class="literalblock">\r
1764 <div class="content">\r
1765 <pre><code>       v1 = q * v2 + r</code></pre>\r
1766 </div></div>\r
1767 <div style="text-align:center">\r
1768 _______________________________________________________\r
1769 </div>\r
1770 <div class="paragraph"><p><a id="p_dodoes"></a></p></div>\r
1771 </div>\r
1772 <div class="sect2">\r
1773 <h3 id="_word_dodoes">Word: doDOES</h3>\r
1774 <div class="literalblock">\r
1775 <div class="content">\r
1776 <pre><code>Data stack: ( -- a )</code></pre>\r
1777 </div></div>\r
1778 <div class="paragraph"><p>"doDOES" is a variable word whose value is the implementation of the\r
1779 <a href="#p_does">[p_does]</a> execution semantics. This is the same as\r
1780 <a href="#p_doforth">doFORTH</a> but it starts at an offset into the word\r
1781 concerned.</p></div>\r
1782 <div style="text-align:center">\r
1783 _______________________________________________________\r
1784 </div>\r
1785 <div class="paragraph"><p><a id="p_does"></a></p></div>\r
1786 </div>\r
1787 <div class="sect2">\r
1788 <h3 id="_word_does_gt">WORD: DOES&gt;</h3>\r
1789 <div class="literalblock">\r
1790 <div class="content">\r
1791 <pre><code>Data stack: ( -- )</code></pre>\r
1792 </div></div>\r
1793 <div class="paragraph"><p>"DOES&gt;" is a function that in execution mode does nothing but in\r
1794 compilation mode it changes the execution semantics assignments for\r
1795 the most recent word to use the <code>dodoes</code> sematics with adjustment\r
1796 offset to the current heap address. I.e., the word being defined will\r
1797 have its execution start at whatever comes after "DOES&gt;".</p></div>\r
1798 <div class="exampleblock">\r
1799 <div class="content">\r
1800 <div class="sidebarblock">\r
1801 <div class="content">\r
1802 <div class="title">Defintion concept for DOES&gt;</div>\r
1803 <div class="paragraph"><p>: DOES&gt; IMMEDIATE\r
1804 STATE @ != IF ( only for compilation mode )\r
1805   CURRENT-WORDLIST @ @ TFA&gt;CFA    ( cfa of current word )\r
1806     doDOES OVER !                 ( set up doer )\r
1807     HERE @ OVER 8 + - SWAP 8 - !  ( set up offset\r
1808   THEN\r
1809 ;</p></div>\r
1810 </div></div>\r
1811 </div></div>\r
1812 <div class="paragraph"><p>See also\r
1813 <a href="#p_put">!</a>,\r
1814 <a href="#p_unequal">!&#8658;&gt;</a>,\r
1815 <a href="#p_minus">&#8594;&gt;</a>,\r
1816 <a href="#p_get">@</a>,\r
1817 <a href="#p_current_wordlist">CURRENT-WORDLIST</a>,\r
1818 <a href="#p_here">HERE</a>,\r
1819 <a href="#p_if">IF</a>,\r
1820 <a href="#p_immediate">IMMEDIATE</a>,\r
1821 <a href="#p_over">OVER</a>,\r
1822 <a href="#p_state">STATE</a>,\r
1823 <a href="#p_swap">SWAP</a>,\r
1824 <a href="#p_tfa2cfa">TFA&gt;CFA</a>,\r
1825 <a href="#p_then">THEN</a>,\r
1826 <a href="#p_dodoes">doDOES</a>,\r
1827 as well as  <a href="#p_execute">EXECUTE</a>\r
1828 about the range of "doer" assignments and their meanings.</p></div>\r
1829 <div style="text-align:center">\r
1830 _______________________________________________________\r
1831 </div>\r
1832 <div class="paragraph"><p><a id="p_dofasm"></a></p></div>\r
1833 </div>\r
1834 <div class="sect2">\r
1835 <h3 id="_word_dofasm">Word: doFASM</h3>\r
1836 <div class="literalblock">\r
1837 <div class="content">\r
1838 <pre><code>Data stack: ( -- a )</code></pre>\r
1839 </div></div>\r
1840 <div class="paragraph"><p>"doFASM" is a variable word whose value is the implementation of the\r
1841 execution semantics for assembly code content.</p></div>\r
1842 <div style="text-align:center">\r
1843 _______________________________________________________\r
1844 </div>\r
1845 <div class="paragraph"><p><a id="p_doforth"></a></p></div>\r
1846 </div>\r
1847 <div class="sect2">\r
1848 <h3 id="_word_doforth">Word: doFORTH</h3>\r
1849 <div class="literalblock">\r
1850 <div class="content">\r
1851 <pre><code>Data stack: ( -- a )</code></pre>\r
1852 </div></div>\r
1853 <div class="paragraph"><p>"doFORTH" is a variable word whose value is the implementation of the\r
1854 RRQFORTH execution semantics.</p></div>\r
1855 <div style="text-align:center">\r
1856 _______________________________________________________\r
1857 </div>\r
1858 <div class="paragraph"><p><a id="p_dostring"></a></p></div>\r
1859 </div>\r
1860 <div class="sect2">\r
1861 <h3 id="_word_dostring">Word: doSTRING</h3>\r
1862 <div class="literalblock">\r
1863 <div class="content">\r
1864 <pre><code>Data stack: ( -- a )</code></pre>\r
1865 </div></div>\r
1866 <div class="paragraph"><p>"doFASM" is a variable word whose value is the implementation of the\r
1867 execution semantics for assembly code implemented words. In those\r
1868 cases the execution leads to the word content.</p></div>\r
1869 <div class="paragraph"><p>The register context at entry to an assembly code implemented word is\r
1870 as follows:</p></div>\r
1871 <div class="listingblock">\r
1872 <div class="content">\r
1873 <pre><code>    rax = cfa* of word to execute\r
1874     rsi = cell* in the calling definition, after calling cell\r
1875     rsp = data stack pointer\r
1876     rbp = return stack pointer</code></pre>\r
1877 </div></div>\r
1878 <div class="paragraph"><p>The assembly code must ensure that <code>rsi</code> is preserved and that <code>rsp</code>\r
1879 and <code>rbp</code> are used according to their roles.</p></div>\r
1880 <div style="text-align:center">\r
1881 _______________________________________________________\r
1882 </div>\r
1883 <div class="paragraph"><p><a id="p_dot"></a></p></div>\r
1884 </div>\r
1885 <div class="sect2">\r
1886 <h3 id="_word_6">Word: .</h3>\r
1887 <div class="literalblock">\r
1888 <div class="content">\r
1889 <pre><code>Data stack: ( v -- )</code></pre>\r
1890 </div></div>\r
1891 <div class="paragraph"><p>"." is a function word that prints the top stack value to stdout using\r
1892 the current <a href="#p_base">BASE</a> (either <a href="#p_decimal">DECIMAL</a> or\r
1893 <a href="#p_hex">HEX</a>).</p></div>\r
1894 <div style="text-align:center">\r
1895 _______________________________________________________\r
1896 </div>\r
1897 <div class="paragraph"><p><a id="p_dot_temp"></a></p></div>\r
1898 </div>\r
1899 <div class="sect2">\r
1900 <h3 id="_word_temp">Word: .TEMP</h3>\r
1901 <div class="literalblock">\r
1902 <div class="content">\r
1903 <pre><code>Data stack: ( v -- char* n )</code></pre>\r
1904 </div></div>\r
1905 <div class="paragraph"><p>".TEMP" is a function word that renders a cell value as an integer\r
1906 using the current <a href="#p_base">BASE</a>, which is either\r
1907 <a href="#p_decimal">DECIMAL</a> or <a href="#p_hex">HEX</a>. In <a href="#p_decimal">DECIMAL</a>\r
1908 <a href="#p_base">BASE</a>, a negative value is rendered as such with a leading\r
1909 minus sign, whereas <a href="#p_hex">HEX</a> <a href="#p_base">BASE</a> rendering is\r
1910 unsigned.</p></div>\r
1911 <div style="text-align:center">\r
1912 _______________________________________________________\r
1913 </div>\r
1914 <div class="paragraph"><p><a id="p_double_quote"></a></p></div>\r
1915 </div>\r
1916 <div class="sect2">\r
1917 <h3 id="_word_7">Word: "</h3>\r
1918 <div class="literalblock">\r
1919 <div class="content">\r
1920 <pre><code>data stack: ( -- char n )    Input stream: ...."</code></pre>\r
1921 </div></div>\r
1922 <div class="paragraph"><p>""" (double quote) is a function word that copies the input stream\r
1923 text up to next double quote to <a href="#p_pad">PAD</a>, and returns the\r
1924 [n:char*] cell pair for that string.</p></div>\r
1925 <div style="text-align:center">\r
1926 _______________________________________________________\r
1927 </div>\r
1928 <div class="paragraph"><p><a id="p_dovalue"></a></p></div>\r
1929 </div>\r
1930 <div class="sect2">\r
1931 <h3 id="_word_dovalue">Word: doVALUE</h3>\r
1932 <div class="literalblock">\r
1933 <div class="content">\r
1934 <pre><code>Data stack: ( -- a )</code></pre>\r
1935 </div></div>\r
1936 <div class="paragraph"><p>"doVALUE" is a variable word whose value is the implementation of the\r
1937 execution semantics for cell values, which are variables with a single\r
1938 64-bit cell holding the value.</p></div>\r
1939 <div class="paragraph"><p>The execution of this result in pushing the value:</p></div>\r
1940 <div class="literalblock">\r
1941 <div class="content">\r
1942 <pre><code>Resulting data stack: ( -- v )</code></pre>\r
1943 </div></div>\r
1944 <div style="text-align:center">\r
1945 _______________________________________________________\r
1946 </div>\r
1947 <div class="paragraph"><p><a id="p_dovariable"></a></p></div>\r
1948 </div>\r
1949 <div class="sect2">\r
1950 <h3 id="_word_dovariable">Word: doVARIABLE</h3>\r
1951 <div class="literalblock">\r
1952 <div class="content">\r
1953 <pre><code>Data stack: ( -- a )</code></pre>\r
1954 </div></div>\r
1955 <div class="paragraph"><p>"doVARIABLE" is a variable word whose value is the implementation of\r
1956 the execution semantics for "variables", which basically are markers\r
1957 into the heap for some number block of memory.</p></div>\r
1958 <div class="paragraph"><p>The execution of a variable results in pushing its content address:</p></div>\r
1959 <div class="literalblock">\r
1960 <div class="content">\r
1961 <pre><code>Resulting data stack: ( -- a )</code></pre>\r
1962 </div></div>\r
1963 <div style="text-align:center">\r
1964 _______________________________________________________\r
1965 </div>\r
1966 <div class="paragraph"><p><a id="p_drop"></a></p></div>\r
1967 </div>\r
1968 <div class="sect2">\r
1969 <h3 id="_word_drop">Word: DROP</h3>\r
1970 <div class="literalblock">\r
1971 <div class="content">\r
1972 <pre><code>Data stack: ( v -- )</code></pre>\r
1973 </div></div>\r
1974 <div class="paragraph"><p>"DROP" is a function word that discards the top stack cell.</p></div>\r
1975 <div style="text-align:center">\r
1976 _______________________________________________________\r
1977 </div>\r
1978 <div class="paragraph"><p><a id="p_dup"></a></p></div>\r
1979 </div>\r
1980 <div class="sect2">\r
1981 <h3 id="_word_dup">Word: DUP</h3>\r
1982 <div class="literalblock">\r
1983 <div class="content">\r
1984 <pre><code>Data stack: ( v -- v v )</code></pre>\r
1985 </div></div>\r
1986 <div class="paragraph"><p>"DUP" is a function word that duplicates the top stack cell.</p></div>\r
1987 <div style="text-align:center">\r
1988 _______________________________________________________\r
1989 </div>\r
1990 <div class="paragraph"><p><a id="p_else"></a></p></div>\r
1991 </div>\r
1992 <div class="sect2">\r
1993 <h3 id="_word_else">Word: ELSE</h3>\r
1994 <div class="literalblock">\r
1995 <div class="content">\r
1996 <pre><code>Data stack: Compiling: ( a -- a )</code></pre>\r
1997 </div></div>\r
1998 <div class="paragraph"><p>"ELSE" is an immediate function word that is used together with\r
1999 <a href="#p_if">IF</a> and <a href="#p_then">THEN</a> to implement structured execution\r
2000 control. ELSE lays out an unresolved unconditional branch as an ending\r
2001 for the "then-part" of the structured statement, and it then performs\r
2002 the branch resolution for the "else-part". To that end it replaces the\r
2003 stacked address which pin-points the foot address the branch offset to\r
2004 resolve, so that at execution time there is an appropriate conditional\r
2005 branch past the "then-part" and the "else-part" of the "structured\r
2006 statement".</p></div>\r
2007 <div style="text-align:center">\r
2008 _______________________________________________________\r
2009 </div>\r
2010 <div class="paragraph"><p><a id="p_emit"></a></p></div>\r
2011 </div>\r
2012 <div class="sect2">\r
2013 <h3 id="_word_emit">Word: EMIT</h3>\r
2014 <div class="literalblock">\r
2015 <div class="content">\r
2016 <pre><code>Data stack: ( c -- )</code></pre>\r
2017 </div></div>\r
2018 <div class="paragraph"><p>"EMIT" is a function word that puts the given character code to\r
2019 standard output (file descriptor 1). The character is the least\r
2020 significant byte of the top cell.</p></div>\r
2021 <div style="text-align:center">\r
2022 _______________________________________________________\r
2023 </div>\r
2024 <div class="paragraph"><p><a id="p_end"></a></p></div>\r
2025 </div>\r
2026 <div class="sect2">\r
2027 <h3 id="_word_end">Word: END</h3>\r
2028 <div class="literalblock">\r
2029 <div class="content">\r
2030 <pre><code>Data stack: Compiling: ( a 0 * -- )</code></pre>\r
2031 </div></div>\r
2032 <div class="paragraph"><p>"END" is an immediate function word that is used together with\r
2033 <a href="#p_begin">BEGIN</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a> to\r
2034 implement structured execution control. END processes the data stack\r
2035 to resolve any dangling <a href="#p_ifbreak">IFBREAK</a> branch offset for the\r
2036 block of the matching <a href="#p_begin">BEGIN</a>.</p></div>\r
2037 <div style="text-align:center">\r
2038 _______________________________________________________\r
2039 </div>\r
2040 <div class="paragraph"><p><a id="p_equal"></a></p></div>\r
2041 </div>\r
2042 <div class="sect2">\r
2043 <h3 id="_word_8">Word: =</h3>\r
2044 <div class="literalblock">\r
2045 <div class="content">\r
2046 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>\r
2047 </div></div>\r
2048 <div class="paragraph"><p>"=" is a function word that replaces a pair of values with -1 of the\r
2049 values are equal, and 0 otherwise.</p></div>\r
2050 <div style="text-align:center">\r
2051 _______________________________________________________\r
2052 </div>\r
2053 <div class="paragraph"><p><a id="p_erase"></a></p></div>\r
2054 </div>\r
2055 <div class="sect2">\r
2056 <h3 id="_word_erase">Word: ERASE</h3>\r
2057 <div class="literalblock">\r
2058 <div class="content">\r
2059 <pre><code>Data stack: ( a n -- )</code></pre>\r
2060 </div></div>\r
2061 <div class="paragraph"><p>"ERASE" is a function word that stores n NUL bytes at address a an up.</p></div>\r
2062 <div style="text-align:center">\r
2063 _______________________________________________________\r
2064 </div>\r
2065 <div class="paragraph"><p><a id="p_evaluate_stream"></a></p></div>\r
2066 </div>\r
2067 <div class="sect2">\r
2068 <h3 id="_word_evaluate_stream">Word: EVALUATE-STREAM</h3>\r
2069 <div class="literalblock">\r
2070 <div class="content">\r
2071 <pre><code>Data stack: ( stream -- ??? 0/1 )     Input stream: ......</code></pre>\r
2072 </div></div>\r
2073 <div class="paragraph"><p>"EVALUATE-STREAM" is a function word that reads words separated by\r
2074 whitespace from the stream until it discovers an unknown word, or the\r
2075 stream is exhausted. Depending on <a href="#p_state">STATE</a>, the words are\r
2076 either executed or compiled, and all ther stack and heap effects are\r
2077 preserved. "EVALUATE-STREAM" returns with an additional 0 or 1 on the\r
2078 stack to respectively indicate that the last word was unkown, i.e. not\r
2079 found (<a href="#p_find">FIND</a>) in the current word list\r
2080 (<a href="#p_current_wordlist">CURRENT-WORDLIST</a>) and not a\r
2081 <a href="#p_number">NUMBER</a> of the current <a href="#p_base">BASE</a>.</p></div>\r
2082 <div class="paragraph"><p>Note that numbers in the current <a href="#p_base">BASE</a> are treated as known\r
2083 words that are parsed into cell values. If interpreting, then the\r
2084 value is left on the stack. If compiling, then the value is added to\r
2085 the heap subsequent to first adding <a href="#p_literal">LIT</a>, which is done\r
2086 so as to make that value be push to the data stack upon a later\r
2087 execution.</p></div>\r
2088 <div class="paragraph"><p>In the <a href="#p_decimal">DECIMAL</a> base, the number word may begin with a\r
2089 minus sign.</p></div>\r
2090 <div class="paragraph"><p>The words are read and executed one by one, accounting for whether its\r
2091 a number word or not, whether it is an <a href="#p_immediate">IMMEDIATE</a> word\r
2092 or not, and whether the state at the time of execution indicates\r
2093 "compiling" of "interpreting". Immediate words are executed in both\r
2094 interpreting and compiling state, while other words have their CFA get\r
2095 added to the heap so as to gain their execution effect upon a later\r
2096 execution.</p></div>\r
2097 <div class="paragraph"><p>Note that "EVALUATE-STREAM" keeps the stream (pointer) on the return\r
2098 stack while reading, parsing and executing.</p></div>\r
2099 <div class="paragraph"><p>If "EVALUATE-STREAM" ends with 0, then <a href="#p_this_word">THIS-WORD</a> holds\r
2100 the [n:chars] reference of the offending word in the stream buffer.</p></div>\r
2101 <div style="text-align:center">\r
2102 _______________________________________________________\r
2103 </div>\r
2104 <div class="paragraph"><p><a id="p_execute"></a></p></div>\r
2105 </div>\r
2106 <div class="sect2">\r
2107 <h3 id="_word_execute">Word: EXECUTE</h3>\r
2108 <div class="literalblock">\r
2109 <div class="content">\r
2110 <pre><code>Data stack: ( cfa -- )</code></pre>\r
2111 </div></div>\r
2112 <div class="paragraph"><p>"EXECUTE" is a function word that transfers the execution to the\r
2113 indicated "Code Field Address", which typically is the CFA of an\r
2114 RRQFORTH word with the CFA cell containing a jump address for the code\r
2115 that implements the execution semnatics of the word.</p></div>\r
2116 <div class="paragraph"><p>The following execution semantics are predefined:</p></div>\r
2117 <div class="ulist"><ul>\r
2118 <li>\r
2119 <p>\r
2120 assembler implemented words constitute their own execution\r
2121    semantics;\r
2122 </p>\r
2123 </li>\r
2124 <li>\r
2125 <p>\r
2126 <a href="#p_doforth">[p_doforth]</a> implements the FORTH machine. This treats the word\r
2127    content as a succession of cells that hold the cfa pointers for the\r
2128    words that make of the definition. As is customary in FORTH\r
2129    machines, the advance through that succession is provided by each\r
2130    word code ending making an explicit jump to its successor. The\r
2131    <a href="#p_return_stack">RETURN-STACK</a> serves as a call stack for tracking\r
2132    the nesting of FORTH executions by saving the "addresses" of the\r
2133    successor cells.\r
2134 </p>\r
2135 </li>\r
2136 <li>\r
2137 <p>\r
2138 <a href="#p_dodoes">[p_dodoes]</a> implements the variation of starting the FORTH\r
2139    execution somewhere within a definition rather than at the\r
2140    beginning.\r
2141 </p>\r
2142 </li>\r
2143 <li>\r
2144 <p>\r
2145 <a href="#p_dostring">[p_dostring]</a>, <a href="#p_dovalue">[p_dovalue]</a> and <a href="#p_dovariable">[p_dovariable]</a> implement\r
2146    different common ways of using word content other the as FORTH\r
2147    definitions.\r
2148 </p>\r
2149 </li>\r
2150 </ul></div>\r
2151 <div style="text-align:center">\r
2152 _______________________________________________________\r
2153 </div>\r
2154 <div class="paragraph"><p><a id="p_exit"></a></p></div>\r
2155 </div>\r
2156 <div class="sect2">\r
2157 <h3 id="_word_exit">Word: EXIT</h3>\r
2158 <div class="literalblock">\r
2159 <div class="content">\r
2160 <pre><code>Data stack: ( v -- )</code></pre>\r
2161 </div></div>\r
2162 <div class="paragraph"><p>"EXIT" is a function word that terminates the <code>rrqforth</code> process\r
2163 immediately with the given exit code.</p></div>\r
2164 <div style="text-align:center">\r
2165 _______________________________________________________\r
2166 </div>\r
2167 <div class="paragraph"><p><a id="p_false"></a></p></div>\r
2168 </div>\r
2169 <div class="sect2">\r
2170 <h3 id="_word_false">Word: FALSE</h3>\r
2171 <div class="literalblock">\r
2172 <div class="content">\r
2173 <pre><code>Data stack: ( -- 0 )</code></pre>\r
2174 </div></div>\r
2175 <div class="paragraph"><p>"FALSE" is a value word representing logical false.</p></div>\r
2176 <div style="text-align:center">\r
2177 _______________________________________________________\r
2178 </div>\r
2179 <div class="paragraph"><p><a id="p_fdemit"></a></p></div>\r
2180 </div>\r
2181 <div class="sect2">\r
2182 <h3 id="_word_fdemit">Word: FDEMIT</h3>\r
2183 <div class="literalblock">\r
2184 <div class="content">\r
2185 <pre><code>Data stack: ( c fd -- )</code></pre>\r
2186 </div></div>\r
2187 <div class="paragraph"><p>"FDEMIT" is a function word that puts the given character code to the\r
2188 given file descriptor. The character is the least significant byte of\r
2189 the data stack cell.</p></div>\r
2190 <div style="text-align:center">\r
2191 _______________________________________________________\r
2192 </div>\r
2193 <div class="paragraph"><p><a id="p_fdtell"></a></p></div>\r
2194 </div>\r
2195 <div class="sect2">\r
2196 <h3 id="_word_fdtell">Word: FDTELL</h3>\r
2197 <div class="literalblock">\r
2198 <div class="content">\r
2199 <pre><code>Data stack: ( char* n fd -- )</code></pre>\r
2200 </div></div>\r
2201 <div class="paragraph"><p>"FDTELL" is a function word that prints a string to the given file\r
2202 descriptor.</p></div>\r
2203 <div style="text-align:center">\r
2204 _______________________________________________________\r
2205 </div>\r
2206 <div class="paragraph"><p><a id="p_find"></a></p></div>\r
2207 </div>\r
2208 <div class="sect2">\r
2209 <h3 id="_word_find">Word: FIND</h3>\r
2210 <div class="literalblock">\r
2211 <div class="content">\r
2212 <pre><code>Data stack: ( char* n -- [ char* n 0 ]/[ tfa ] )</code></pre>\r
2213 </div></div>\r
2214 <div class="paragraph"><p>"FIND" is a function word that searches the current word list search\r
2215 path for the given [n:char*] word, and returns the TFA of the matching\r
2216 word if any. Otherwise FIND preserves the initial data stack but adds\r
2217 0 to it.</p></div>\r
2218 <div class="paragraph"><p>The word is sought starting with the\r
2219 <a href="#p_current_wordlist">CURRENT-WORDLIST</a> word list, for the first\r
2220 occurence of a match. If not found, the search continues with the\r
2221 subsequent word list, and so on.</p></div>\r
2222 <div class="paragraph"><p>When a word is found, then the data stack is changed by discarding the\r
2223 [n:char*] double cell string pointer and pushing (only) the TFA of the\r
2224 matching word instead.</p></div>\r
2225 <div style="text-align:center">\r
2226 _______________________________________________________\r
2227 </div>\r
2228 <div class="paragraph"><p><a id="p_forth"></a></p></div>\r
2229 </div>\r
2230 <div class="sect2">\r
2231 <h3 id="_word_forth">Word: FORTH</h3>\r
2232 <div class="literalblock">\r
2233 <div class="content">\r
2234 <pre><code>data stack: ( -- a )</code></pre>\r
2235 </div></div>\r
2236 <div class="paragraph"><p>"FORTH" is a variable word for the FORTH word list, which does not\r
2237 have any subsequent word list.</p></div>\r
2238 <div style="text-align:center">\r
2239 _______________________________________________________\r
2240 </div>\r
2241 <div class="paragraph"><p><a id="p_get"></a></p></div>\r
2242 </div>\r
2243 <div class="sect2">\r
2244 <h3 id="_word_9">Word: @</h3>\r
2245 <div class="literalblock">\r
2246 <div class="content">\r
2247 <pre><code>Data stack: ( a -- v )</code></pre>\r
2248 </div></div>\r
2249 <div class="paragraph"><p>"@" is a function word that pushes the value v from the address a.</p></div>\r
2250 <div style="text-align:center">\r
2251 _______________________________________________________\r
2252 </div>\r
2253 <div class="paragraph"><p><a id="p_get_n_decrement"></a></p></div>\r
2254 </div>\r
2255 <div class="sect2">\r
2256 <h3 id="_word_n">Word: @n--</h3>\r
2257 <div class="literalblock">\r
2258 <div class="content">\r
2259 <pre><code>Data stack: ( a n -- v )</code></pre>\r
2260 </div></div>\r
2261 <div class="paragraph"><p>"@n--" is a function word that pushes the value from the address, a,\r
2262 then decrements the cell at that address by n.</p></div>\r
2263 <div class="exampleblock">\r
2264 <div class="content">\r
2265 <div class="sidebarblock">\r
2266 <div class="content">\r
2267 <div class="title">Defintion concept for @n++</div>\r
2268 <div class="paragraph"><p>: @n++ OVER @ DUP ROT - ROT ! ;</p></div>\r
2269 </div></div>\r
2270 </div></div>\r
2271 <div style="text-align:center">\r
2272 _______________________________________________________\r
2273 </div>\r
2274 <div class="paragraph"><p><a id="p_get_n_increment"></a></p></div>\r
2275 </div>\r
2276 <div class="sect2">\r
2277 <h3 id="_word_n_2">Word: @n++</h3>\r
2278 <div class="literalblock">\r
2279 <div class="content">\r
2280 <pre><code>Data stack: ( a n -- v )</code></pre>\r
2281 </div></div>\r
2282 <div class="paragraph"><p>"@n++" is a function word that pushes the value from the address, a,\r
2283 then increments the cell at that address by n.</p></div>\r
2284 <div class="exampleblock">\r
2285 <div class="content">\r
2286 <div class="sidebarblock">\r
2287 <div class="content">\r
2288 <div class="title">Defintion concept for @n++</div>\r
2289 <div class="paragraph"><p>( a n&#8201;&#8212;&#8201;v ) : @n++ OVER @ DUP ROT + ROT ! ;</p></div>\r
2290 </div></div>\r
2291 </div></div>\r
2292 <div style="text-align:center">\r
2293 _______________________________________________________\r
2294 </div>\r
2295 <div class="paragraph"><p><a id="p_greaterequal"></a></p></div>\r
2296 </div>\r
2297 <div class="sect2">\r
2298 <h3 id="_word_gt">Word: &gt;=</h3>\r
2299 <div class="literalblock">\r
2300 <div class="content">\r
2301 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>\r
2302 </div></div>\r
2303 <div class="paragraph"><p>"&gt;=" is a function word that replaces a pair of values with -1 if the\r
2304 first, v1, is greater than or equal to the second, v1, otherwise 0. To\r
2305 that end, the values are 64-bit signed integers.</p></div>\r
2306 <div style="text-align:center">\r
2307 _______________________________________________________\r
2308 </div>\r
2309 <div class="paragraph"><p><a id="p_greaterthan"></a></p></div>\r
2310 </div>\r
2311 <div class="sect2">\r
2312 <h3 id="_word_gt_2">Word: &gt;</h3>\r
2313 <div class="literalblock">\r
2314 <div class="content">\r
2315 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>\r
2316 </div></div>\r
2317 <div class="paragraph"><p>"&gt;" is a function word that replaces a pair of values with -1 if the\r
2318 first, v1, is greater than the second, v1, otherwise 0. To that end,\r
2319 the values are 64-bit signed integers.</p></div>\r
2320 <div style="text-align:center">\r
2321 _______________________________________________________\r
2322 </div>\r
2323 <div class="paragraph"><p><a id="p_gtR"></a></p></div>\r
2324 </div>\r
2325 <div class="sect2">\r
2326 <h3 id="_word_gt_r">Word: &gt;R</h3>\r
2327 <div class="literalblock">\r
2328 <div class="content">\r
2329 <pre><code>Data stack: ( v -- )   Return stack: ( -- v )</code></pre>\r
2330 </div></div>\r
2331 <div class="paragraph"><p>"&gt;R" is a function word that "moves" the top data stack value onto the\r
2332 return stack.</p></div>\r
2333 <div style="text-align:center">\r
2334 _______________________________________________________\r
2335 </div>\r
2336 <div class="paragraph"><p><a id="p_here"></a></p></div>\r
2337 </div>\r
2338 <div class="sect2">\r
2339 <h3 id="_word_here">Word: HERE</h3>\r
2340 <div class="literalblock">\r
2341 <div class="content">\r
2342 <pre><code>Data stack: ( -- a )</code></pre>\r
2343 </div></div>\r
2344 <div class="paragraph"><p>"HERE" is a variable word that keeps the lowest address of the free\r
2345 allocation space. It get updated by all words that allocate memory.</p></div>\r
2346 <div class="exampleblock">\r
2347 <div class="content">\r
2348 <div class="sidebarblock">\r
2349 <div class="content">\r
2350 <div class="title">allocate 1024 bytes on the heap</div>\r
2351 <div class="paragraph"><p>1024 HEAP @ + HEAP !</p></div>\r
2352 </div></div>\r
2353 </div></div>\r
2354 <div class="paragraph"><p>See also <a href="#p_allot">ALLOT</a>.</p></div>\r
2355 <div style="text-align:center">\r
2356 _______________________________________________________\r
2357 </div>\r
2358 <div class="paragraph"><p><a id="p_hex"></a></p></div>\r
2359 </div>\r
2360 <div class="sect2">\r
2361 <h3 id="_word_hex">Word: HEX</h3>\r
2362 <div class="literalblock">\r
2363 <div class="content">\r
2364 <pre><code>Data stack: ( -- )</code></pre>\r
2365 </div></div>\r
2366 <div class="paragraph"><p>"HEX" is a function word that sets <a href="#p_base">BASE</a> to 16, which uses\r
2367 letters a-f as additional digits. (Uppercase letter are also accepted\r
2368 on input).</p></div>\r
2369 <div class="exampleblock">\r
2370 <div class="content">\r
2371 <div class="sidebarblock">\r
2372 <div class="content">\r
2373 <div class="title">Definition concept for HEX</div>\r
2374 <div class="paragraph"><p>: HEX 16 BASE ! ;</p></div>\r
2375 </div></div>\r
2376 </div></div>\r
2377 <div style="text-align:center">\r
2378 _______________________________________________________\r
2379 </div>\r
2380 <div class="paragraph"><p><a id="p_if"></a></p></div>\r
2381 </div>\r
2382 <div class="sect2">\r
2383 <h3 id="_word_if">Word: IF</h3>\r
2384 <div class="literalblock">\r
2385 <div class="content">\r
2386 <pre><code>Data stack: Compiling: ( -- a )</code></pre>\r
2387 </div></div>\r
2388 <div class="paragraph"><p>"IF" is an immediate function word that is used together with\r
2389 <a href="#p_else">ELSE</a> and <a href="#p_then">THEN</a> to implement structured execution\r
2390 control. IF results in layout of a <a href="#p_0branch">0BRANCH</a> instruction\r
2391 with an unresolved branch offset, and places the address for resolving\r
2392 this instruction on the datastack. This address will then be resolved\r
2393 and asssigned by a subsequent <a href="#p_else">ELSE</a> or <a href="#p_then">THEN</a> so\r
2394 that at execution time there is an appropriate conditional branch past\r
2395 the "then-part" of the "structured statement".</p></div>\r
2396 <div style="text-align:center">\r
2397 _______________________________________________________\r
2398 </div>\r
2399 <div class="paragraph"><p><a id="p_ifagain"></a></p></div>\r
2400 </div>\r
2401 <div class="sect2">\r
2402 <h3 id="_word_ifagain">Word: IFAGAIN</h3>\r
2403 <div class="literalblock">\r
2404 <div class="content">\r
2405 <pre><code>Data stack: Compiling: ( -- a )</code></pre>\r
2406 </div></div>\r
2407 <div class="paragraph"><p>"IFAGAIN" is an immediate function word that is used together with\r
2408 <a href="#p_begin">BEGIN</a>, <a href="#p_ifbreak">BREAK</a> and <a href="#p_end">END</a> to implement\r
2409 structured execution control. IFAGAIN scans the datastack for the\r
2410 nearest preceding BEGIN marker and lays out a branch from this point\r
2411 the beginning of the block during execution.</p></div>\r
2412 <div style="text-align:center">\r
2413 _______________________________________________________\r
2414 </div>\r
2415 <div class="paragraph"><p><a id="p_ifbreak"></a></p></div>\r
2416 </div>\r
2417 <div class="sect2">\r
2418 <h3 id="_word_ifbreak">Word: IFBREAK</h3>\r
2419 <div class="literalblock">\r
2420 <div class="content">\r
2421 <pre><code>Data stack: Compiling: ( -- a )</code></pre>\r
2422 </div></div>\r
2423 <div class="paragraph"><p>"IFBREAK" is an immediate function word that is used together with\r
2424 <a href="#p_begin">BEGIN</a>, <a href="#p_ifagain">IFAGAIN</a> and <a href="#p_end">END</a> to\r
2425 implement structured execution control. IFBREAK simply places the\r
2426 address for resolving branches from this point the end of the block\r
2427 during execution.</p></div>\r
2428 <div style="text-align:center">\r
2429 _______________________________________________________\r
2430 </div>\r
2431 <div class="paragraph"><p><a id="p_immediate"></a></p></div>\r
2432 </div>\r
2433 <div class="sect2">\r
2434 <h3 id="_word_immediate">Word: IMMEDIATE</h3>\r
2435 <div class="literalblock">\r
2436 <div class="content">\r
2437 <pre><code>Data stack: ( -- )</code></pre>\r
2438 </div></div>\r
2439 <div class="paragraph"><p>"IMMEDIATE" is an immediate function word that sets the flags field of\r
2440 the most recent word to 1, thereby making that word an immediate word.</p></div>\r
2441 <div class="exampleblock">\r
2442 <div class="content">\r
2443 <div class="sidebarblock">\r
2444 <div class="content">\r
2445 <div class="title">Definition concept for IMMEDIATE</div>\r
2446 <div class="paragraph"><p>: IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;</p></div>\r
2447 </div></div>\r
2448 </div></div>\r
2449 <div class="paragraph"><p>See also <a href="#p_colon">:</a>, <a href="#p_current_wordlist">CURRENT-WORDLIST</a>,\r
2450 <a href="#p_get">@</a>, <a href="#p_plus">+</a>, <a href="#p_put">!</a>, and <a href="#p_semicolon;">[p_semicolon;]</a>.</p></div>\r
2451 <div style="text-align:center">\r
2452 _______________________________________________________\r
2453 </div>\r
2454 <div class="paragraph"><p><a id="p_input"></a></p></div>\r
2455 </div>\r
2456 <div class="sect2">\r
2457 <h3 id="_word_input">Word: INPUT</h3>\r
2458 <div class="literalblock">\r
2459 <div class="content">\r
2460 <pre><code>Data stack: ( -- a )</code></pre>\r
2461 </div></div>\r
2462 <div class="paragraph"><p>"INPUT" is a variable word for the input stream buffer used by\r
2463 <a href="#p_evaluate_stream">EVALUATE-STREAM</a>.</p></div>\r
2464 <div style="text-align:center">\r
2465 _______________________________________________________\r
2466 </div>\r
2467 <div class="paragraph"><p><a id="p_left_bracket"></a></p></div>\r
2468 </div>\r
2469 <div class="sect2">\r
2470 <h3 id="_word_10">Word: [</h3>\r
2471 <div class="literalblock">\r
2472 <div class="content">\r
2473 <pre><code>Data stack: ( -- )</code></pre>\r
2474 </div></div>\r
2475 <div class="paragraph"><p>"[" (left bracket) is a function word that sets the stream evaluation\r
2476 mode to be intepreting. In this mode, words are executed immediately\r
2477 after parsing, by invoking their "doer".</p></div>\r
2478 <div class="exampleblock">\r
2479 <div class="content">\r
2480 <div class="sidebarblock">\r
2481 <div class="content">\r
2482 <div class="title">Definition concept for [</div>\r
2483 <div class="paragraph"><p>: [ IMMEDIATE 0 STATE ! ;</p></div>\r
2484 </div></div>\r
2485 </div></div>\r
2486 <div style="text-align:center">\r
2487 _______________________________________________________\r
2488 </div>\r
2489 <div class="paragraph"><p><a id="p_lessequal"></a></p></div>\r
2490 </div>\r
2491 <div class="sect2">\r
2492 <h3 id="_word_lt">Word: &lt;=</h3>\r
2493 <div class="literalblock">\r
2494 <div class="content">\r
2495 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>\r
2496 </div></div>\r
2497 <div class="paragraph"><p>"&lt;=" is a function word that replaces a pair of values with -1 if the\r
2498 first, v1, is less than or equal to the second, v1, otherwise 0. To\r
2499 that end, the values are 64-bit signed integers.</p></div>\r
2500 <div style="text-align:center">\r
2501 _______________________________________________________\r
2502 </div>\r
2503 <div class="paragraph"><p><a id="p_lessthan"></a></p></div>\r
2504 </div>\r
2505 <div class="sect2">\r
2506 <h3 id="_word_lt_2">Word: &lt;</h3>\r
2507 <div class="literalblock">\r
2508 <div class="content">\r
2509 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>\r
2510 </div></div>\r
2511 <div class="paragraph"><p>"&lt;" is a function word that replaces a pair of values with -1 if the\r
2512 first, v1, is less than the second, v1, otherwise 0. To that end, the\r
2513 values are 64-bit signed integers.</p></div>\r
2514 <div style="text-align:center">\r
2515 _______________________________________________________\r
2516 </div>\r
2517 <div class="paragraph"><p><a id="p_literal"></a></p></div>\r
2518 </div>\r
2519 <div class="sect2">\r
2520 <h3 id="_word_lit">Word: LIT</h3>\r
2521 <div class="literalblock">\r
2522 <div class="content">\r
2523 <pre><code>Data stack: ( -- v )</code></pre>\r
2524 </div></div>\r
2525 <div class="paragraph"><p>"LIT" is a function word that pushes the cell subsequent and moves\r
2526 excution past that. The literal value is thus layed out as if a\r
2527 subsequent CFA pointer in the containing definition, and the LIT\r
2528 execution will make the execution skip past that and instead contine\r
2529 with the CFA pointer following the value.</p></div>\r
2530 <div class="paragraph"><p>It&#8217;s not a good idea to use "LIT" interactively.</p></div>\r
2531 <div class="exampleblock">\r
2532 <div class="content">\r
2533 <div class="sidebarblock">\r
2534 <div class="content">\r
2535 <div class="title">Definition concept for LIT</div>\r
2536 <div class="paragraph"><p>: LIT R&gt; DUP 8 + &gt;R @ ;</p></div>\r
2537 </div></div>\r
2538 </div></div>\r
2539 <div style="text-align:center">\r
2540 _______________________________________________________\r
2541 </div>\r
2542 <div class="paragraph"><p><a id="p_literal_string"></a></p></div>\r
2543 </div>\r
2544 <div class="sect2">\r
2545 <h3 id="_word_s">Word: S"</h3>\r
2546 <div class="literalblock">\r
2547 <div class="content">\r
2548 <pre><code>Data stack: ( -- chars* n )</code></pre>\r
2549 </div></div>\r
2550 <div class="paragraph"><p>"S"" is a function word that pushes the [n:char] pointer for a string\r
2551 inlined subsequently to it in the containing definition. This is\r
2552 similar to <a href="#p_lit">LIT</a> but for a string literal.</p></div>\r
2553 <div class="exampleblock">\r
2554 <div class="content">\r
2555 <div class="sidebarblock">\r
2556 <div class="content">\r
2557 <div class="title">Definition concept for LIT</div>\r
2558 <div class="paragraph"><p>: LIT R&gt; DUP @ 2DUP + 8 + &gt;R SWAP 8 + SWAP ;</p></div>\r
2559 </div></div>\r
2560 </div></div>\r
2561 <div style="text-align:center">\r
2562 _______________________________________________________\r
2563 </div>\r
2564 <div class="paragraph"><p><a id="p_load_buffer_size"></a></p></div>\r
2565 </div>\r
2566 <div class="sect2">\r
2567 <h3 id="_word_load_buffer_size">Word: LOAD-BUFFER-SIZE</h3>\r
2568 <div class="literalblock">\r
2569 <div class="content">\r
2570 <pre><code>data stack: ( -- a )</code></pre>\r
2571 </div></div>\r
2572 <div class="paragraph"><p>"LOAD-BUFFER-SIZE" is a variable word telling the buffer size in bytes\r
2573 that <a href="#p_load_file">LOAD-FILE</a> should use.</p></div>\r
2574 <div style="text-align:center">\r
2575 _______________________________________________________\r
2576 </div>\r
2577 <div class="paragraph"><p><a id="p_load_file"></a></p></div>\r
2578 </div>\r
2579 <div class="sect2">\r
2580 <h3 id="_word_load_file">Word: LOAD-FILE</h3>\r
2581 <div class="literalblock">\r
2582 <div class="content">\r
2583 <pre><code>data stack: ( chaz* -- * 0/1 )</code></pre>\r
2584 </div></div>\r
2585 <div class="paragraph"><p>"LOAD-FILE" is a function word that evaluates a text file. It opens a\r
2586 file via <a href="#p_open_file">OPEN-FILE</a> and sets up a stream with a\r
2587 buffer of <a href="#p_load_buffer_size">LOAD-BUFFER-SIZE</a> bytes for\r
2588 reading it. The stream is passed to\r
2589 <a href="#p_evaluate_stream">EVALUATE-STREAM</a> for processing its words. Upon\r
2590 its return the file is closed and the stream memory is reclaimed, and\r
2591 then the function returns whatever\r
2592 <a href="#p_evaluate_stream">EVALUATE-STREAM</a> returns.</p></div>\r
2593 <div style="text-align:center">\r
2594 _______________________________________________________\r
2595 </div>\r
2596 <div class="paragraph"><p><a id="p_lparen"></a></p></div>\r
2597 </div>\r
2598 <div class="sect2">\r
2599 <h3 id="_word_11">Word: (</h3>\r
2600 <div class="literalblock">\r
2601 <div class="content">\r
2602 <pre><code>Data stack: ( -- )</code></pre>\r
2603 </div></div>\r
2604 <div class="paragraph"><p>"(" (left parenthesis) is a function word that scans and ignores words\r
2605 until the next right parenthesis, or the end of the stream. This is\r
2606 used for comments in RRQFORTH code.</p></div>\r
2607 <div class="paragraph"><p>Note that the terminating right parenthesis is a word, i.e. must have\r
2608 whitespace before and after it.</p></div>\r
2609 <div style="text-align:center">\r
2610 _______________________________________________________\r
2611 </div>\r
2612 <div class="paragraph"><p><a id="p_malloc"></a></p></div>\r
2613 </div>\r
2614 <div class="sect2">\r
2615 <h3 id="_word_malloc">Word: MALLOC</h3>\r
2616 <div class="literalblock">\r
2617 <div class="content">\r
2618 <pre><code>Data stack: ( n -- a )</code></pre>\r
2619 </div></div>\r
2620 <div class="paragraph"><p>"MALLOC" is a word that allocates memory using mmap of at least n\r
2621 bytes and returns the lowest address of the allocated block.</p></div>\r
2622 <div class="paragraph"><p>Note that this makes new page allocations for the process from the\r
2623 kernel, and the granularity is in pages, i.e. a multiple of 4 kb.</p></div>\r
2624 <div class="paragraph"><p>The memory is allocated with READ and WRITE access but not EXEC\r
2625 access, and flagged as PRIVATE, ANONYMOUS and LOCKED. See the "man\r
2626 page" of mmap for details.</p></div>\r
2627 <div class="paragraph"><p>See also <a href="#p_stream">STREAM</a></p></div>\r
2628 <div style="text-align:center">\r
2629 _______________________________________________________\r
2630 </div>\r
2631 <div class="paragraph"><p><a id="p_minus"></a></p></div>\r
2632 </div>\r
2633 <div class="sect2">\r
2634 <h3 id="_word_12">Word: -</h3>\r
2635 <div class="literalblock">\r
2636 <div class="content">\r
2637 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>\r
2638 </div></div>\r
2639 <div class="paragraph"><p>"-" (minus) is a function word that replaces a pair of values with the\r
2640 result of reducing the first, v1, with the second, v2. To that end,\r
2641 the values are 64-bit signed integers.</p></div>\r
2642 <div style="text-align:center">\r
2643 _______________________________________________________\r
2644 </div>\r
2645 <div class="paragraph"><p><a id="p_mult"></a></p></div>\r
2646 </div>\r
2647 <div class="sect2">\r
2648 <h3 id="_word_13">Word: *</h3>\r
2649 <div class="literalblock">\r
2650 <div class="content">\r
2651 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>\r
2652 </div></div>\r
2653 <div class="paragraph"><p>"*" is a function word that replaces a pair of values with the result\r
2654 of multiplying them. To that end, the values are 64-bit signed\r
2655 integers, and clipping the result to the least signifcant 64 bits.</p></div>\r
2656 <div style="text-align:center">\r
2657 _______________________________________________________\r
2658 </div>\r
2659 <div class="paragraph"><p><a id="p_negate"></a></p></div>\r
2660 </div>\r
2661 <div class="sect2">\r
2662 <h3 id="_word_negate">Word: NEGATE</h3>\r
2663 <div class="literalblock">\r
2664 <div class="content">\r
2665 <pre><code>Data stack: ( v1 -- v2 )</code></pre>\r
2666 </div></div>\r
2667 <div class="paragraph"><p>"NEGATE" is a function word that replaces a value with its\r
2668 2&#8217;s-complement negation. To that end, the values are 64-bit signed\r
2669 integers.</p></div>\r
2670 <div style="text-align:center">\r
2671 _______________________________________________________\r
2672 </div>\r
2673 <div class="paragraph"><p><a id="p_nip"></a></p></div>\r
2674 </div>\r
2675 <div class="sect2">\r
2676 <h3 id="_word_nip">Word: NIP</h3>\r
2677 <div class="literalblock">\r
2678 <div class="content">\r
2679 <pre><code>Data stack: ( v1 v2 -- v2 )</code></pre>\r
2680 </div></div>\r
2681 <div class="paragraph"><p>"NIP" is a function word that discards the second of the top two cells\r
2682 on the data stack.</p></div>\r
2683 <div class="exampleblock">\r
2684 <div class="content">\r
2685 <div class="sidebarblock">\r
2686 <div class="content">\r
2687 <div class="title">Definition concept for NIP</div>\r
2688 <div class="paragraph"><p>: NIP SWAP DROP ;</p></div>\r
2689 </div></div>\r
2690 </div></div>\r
2691 <div style="text-align:center">\r
2692 _______________________________________________________\r
2693 </div>\r
2694 <div class="paragraph"><p><a id="p_nl"></a></p></div>\r
2695 </div>\r
2696 <div class="sect2">\r
2697 <h3 id="_word_nl">Word: NL</h3>\r
2698 <div class="literalblock">\r
2699 <div class="content">\r
2700 <pre><code>Data stack: ( -- v )</code></pre>\r
2701 </div></div>\r
2702 <div class="paragraph"><p>"NL" is a value word pushing a newline character onto the data stack.</p></div>\r
2703 <div style="text-align:center">\r
2704 _______________________________________________________\r
2705 </div>\r
2706 <div class="paragraph"><p><a id="p_not"></a></p></div>\r
2707 </div>\r
2708 <div class="sect2">\r
2709 <h3 id="_word_not">Word: NOT</h3>\r
2710 <div class="literalblock">\r
2711 <div class="content">\r
2712 <pre><code>Data stack: ( v1 -- v2 )</code></pre>\r
2713 </div></div>\r
2714 <div class="paragraph"><p>"NOT" is a function word that replaces a value with its bitwise\r
2715 complement; each bit is zero if non-zero, and non-zero if zero.</p></div>\r
2716 <div class="paragraph"><p>Compare with &lt;&lt;p_0equal,0&#8658;&gt;.</p></div>\r
2717 <div style="text-align:center">\r
2718 _______________________________________________________\r
2719 </div>\r
2720 <div class="paragraph"><p><a id="p_number"></a></p></div>\r
2721 </div>\r
2722 <div class="sect2">\r
2723 <h3 id="_word_number">Word: NUMBER</h3>\r
2724 <div class="literalblock">\r
2725 <div class="content">\r
2726 <pre><code>Data stack: ( char n -- [ 0 ]/[ v 1 ] )</code></pre>\r
2727 </div></div>\r
2728 <div class="paragraph"><p>"NUMBER" is a function word that parses a text number using\r
2729 <a href="#p_base">BASE</a> as numerical base, then returns the result number and\r
2730 a 1 on top, or just a 0 if the word didn&#8217;t parse.</p></div>\r
2731 <div class="paragraph"><p>A number consists of, first an optional minus sign, if in\r
2732 <a href="#p_decimal">DECIMAL</a> base, then digits 0-9 and, if in <a href="#p_hex">HEX</a>\r
2733 base, letters a-f or A-F for values 10-15. I.e. the normal positive or\r
2734 negative decimal integers or normal (positive only) hexadecimal\r
2735 integers.</p></div>\r
2736 <div style="text-align:center">\r
2737 _______________________________________________________\r
2738 </div>\r
2739 <div class="paragraph"><p><a id="p_open_file"></a></p></div>\r
2740 </div>\r
2741 <div class="sect2">\r
2742 <h3 id="_word_open_file">Word: OPEN-FILE</h3>\r
2743 <div class="literalblock">\r
2744 <div class="content">\r
2745 <pre><code>Data stack: ( chaz* -- fd )</code></pre>\r
2746 </div></div>\r
2747 <div class="paragraph"><p>"OPEN-FILE" is a function word that opens the file named by the zero\r
2748 terminated character string and returns the file descriptor, or if\r
2749 less than 0, the system call error code.</p></div>\r
2750 <div style="text-align:center">\r
2751 _______________________________________________________\r
2752 </div>\r
2753 <div class="paragraph"><p><a id="p_or"></a></p></div>\r
2754 </div>\r
2755 <div class="sect2">\r
2756 <h3 id="_word_or">Word: OR</h3>\r
2757 <div class="literalblock">\r
2758 <div class="content">\r
2759 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>\r
2760 </div></div>\r
2761 <div class="paragraph"><p>"OR" is a function word that replaces a value pair with their bitwise\r
2762 disjunction; each bit is 1 if the corresponding bits of any operand\r
2763 is 1 and 0 if not.</p></div>\r
2764 <div style="text-align:center">\r
2765 _______________________________________________________\r
2766 </div>\r
2767 <div class="paragraph"><p><a id="p_over"></a></p></div>\r
2768 </div>\r
2769 <div class="sect2">\r
2770 <h3 id="_word_over">Word: OVER</h3>\r
2771 <div class="literalblock">\r
2772 <div class="content">\r
2773 <pre><code>Data stack: ( v1 v2 -- v1 v2 v1 )</code></pre>\r
2774 </div></div>\r
2775 <div class="paragraph"><p>"OVER" is a function word that duplicates the second top stack cell on\r
2776 the data stack.</p></div>\r
2777 <div style="text-align:center">\r
2778 _______________________________________________________\r
2779 </div>\r
2780 <div class="paragraph"><p><a id="p_pad"></a></p></div>\r
2781 </div>\r
2782 <div class="sect2">\r
2783 <h3 id="_word_pad">Word: PAD</h3>\r
2784 <div class="literalblock">\r
2785 <div class="content">\r
2786 <pre><code>Data stack: ( -- a )</code></pre>\r
2787 </div></div>\r
2788 <div class="paragraph"><p>"PAD" is a variable word for a 1 kb data space that is used by\r
2789 <a href="#p_double_quote">[p_double_quote]</a> (only), and otherwise free for temporary use.</p></div>\r
2790 <div style="text-align:center">\r
2791 _______________________________________________________\r
2792 </div>\r
2793 <div class="paragraph"><p><a id="p_pick"></a></p></div>\r
2794 </div>\r
2795 <div class="sect2">\r
2796 <h3 id="_word_pick">Word: PICK</h3>\r
2797 <div class="literalblock">\r
2798 <div class="content">\r
2799 <pre><code>Data stack: ( vu...v1 v0 u -- vu...v1 v0 vu )</code></pre>\r
2800 </div></div>\r
2801 <div class="paragraph"><p>"PICK" is a function word that pushes the u:th data stack cell down\r
2802 from top onto the data stack. 0 indicates the top cell making it the\r
2803 same as <a href="#p_dup">DUP</a>, and 1 indicates the second top cell making it\r
2804 the same as <a href="#p_over">OVER</a>.</p></div>\r
2805 <div style="text-align:center">\r
2806 _______________________________________________________\r
2807 </div>\r
2808 <div class="paragraph"><p><a id="p_plus"></a></p></div>\r
2809 </div>\r
2810 <div class="sect2">\r
2811 <h3 id="_word_43">Word: &#43;</h3>\r
2812 <div class="literalblock">\r
2813 <div class="content">\r
2814 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>\r
2815 </div></div>\r
2816 <div class="paragraph"><p>"+" (plus) is a function word that replaces a pair of values with the\r
2817 result of adding them. To that end, the values are 64-bit signed\r
2818 integers.</p></div>\r
2819 <div style="text-align:center">\r
2820 _______________________________________________________\r
2821 </div>\r
2822 <div class="paragraph"><p><a id="p_program_version"></a></p></div>\r
2823 </div>\r
2824 <div class="sect2">\r
2825 <h3 id="_word_program_version">Word: PROGRAM_VERSION</h3>\r
2826 <div class="literalblock">\r
2827 <div class="content">\r
2828 <pre><code>Data stack: ( -- char* length )</code></pre>\r
2829 </div></div>\r
2830 <div class="paragraph"><p>"PROGRAM_VERSION" is a string variable hilding the version string.</p></div>\r
2831 <div style="text-align:center">\r
2832 _______________________________________________________\r
2833 </div>\r
2834 <div class="paragraph"><p><a id="p_put"></a></p></div>\r
2835 </div>\r
2836 <div class="sect2">\r
2837 <h3 id="_word_14">Word: !</h3>\r
2838 <div class="literalblock">\r
2839 <div class="content">\r
2840 <pre><code>Data stack: ( v a -- )</code></pre>\r
2841 </div></div>\r
2842 <div class="paragraph"><p>"!" is a function word that stores the cell value v at the address a.</p></div>\r
2843 <div style="text-align:center">\r
2844 _______________________________________________________\r
2845 </div>\r
2846 <div class="paragraph"><p><a id="p_put_plus"></a></p></div>\r
2847 </div>\r
2848 <div class="sect2">\r
2849 <h3 id="_word_15">Word: !+</h3>\r
2850 <div class="literalblock">\r
2851 <div class="content">\r
2852 <pre><code>Data stack: ( a n -- )</code></pre>\r
2853 </div></div>\r
2854 <div class="paragraph"><p>"!+" is a function word that adds n to the cell value at a.</p></div>\r
2855 <div class="exampleblock">\r
2856 <div class="content">\r
2857 <div class="sidebarblock">\r
2858 <div class="content">\r
2859 <div class="title">definition concept for !+</div>\r
2860 <div class="paragraph"><p>( a n&#8201;&#8212;&#8201;) : !+ OVER @ + SWAP ! ;</p></div>\r
2861 </div></div>\r
2862 </div></div>\r
2863 <div style="text-align:center">\r
2864 _______________________________________________________\r
2865 </div>\r
2866 <div class="paragraph"><p><a id="p_quit"></a></p></div>\r
2867 </div>\r
2868 <div class="sect2">\r
2869 <h3 id="_word_quit">Word: QUIT</h3>\r
2870 <div class="literalblock">\r
2871 <div class="content">\r
2872 <pre><code>Data stack: ??</code></pre>\r
2873 </div></div>\r
2874 <div class="paragraph"><p>"QUIT" is a function word that implements the root execution loop of\r
2875 RRQFORTH. First it resets the stacks to their original settings, and\r
2876 thereafter it enters loop of reading words from <a href="#p_stdin">STDIN</a> and\r
2877 executing them.</p></div>\r
2878 <div style="text-align:center">\r
2879 _______________________________________________________\r
2880 </div>\r
2881 <div class="paragraph"><p><a id="p_quote"></a></p></div>\r
2882 </div>\r
2883 <div class="sect2">\r
2884 <h3 id="_word_16">Word: '</h3>\r
2885 <div class="literalblock">\r
2886 <div class="content">\r
2887 <pre><code>data stack: ( -- cfa )    Input stream: word</code></pre>\r
2888 </div></div>\r
2889 <div class="paragraph"><p>"'" (single quote) is a function word that reads and find the next\r
2890 word on the input stream and pushes its cfa.</p></div>\r
2891 <div style="text-align:center">\r
2892 _______________________________________________________\r
2893 </div>\r
2894 <div class="paragraph"><p><a id="p_rbp"></a></p></div>\r
2895 </div>\r
2896 <div class="sect2">\r
2897 <h3 id="_word_rsp">Word: RSP</h3>\r
2898 <div class="literalblock">\r
2899 <div class="content">\r
2900 <pre><code>Data stack: ( -- a )</code></pre>\r
2901 </div></div>\r
2902 <div class="paragraph"><p>"RSP" is a function word that pushes the return stack pointer value\r
2903 onto the data stack.</p></div>\r
2904 <div style="text-align:center">\r
2905 _______________________________________________________\r
2906 </div>\r
2907 <div class="paragraph"><p><a id="p_rbpn"></a></p></div>\r
2908 </div>\r
2909 <div class="sect2">\r
2910 <h3 id="_word_r_n">Word: R[n]</h3>\r
2911 <div class="literalblock">\r
2912 <div class="content">\r
2913 <pre><code>Data stack: ( n -- a )</code></pre>\r
2914 </div></div>\r
2915 <div class="paragraph"><p>"R[n]" is a function word that pushes the address for the n:th cell on\r
2916 the top return stack value onto the data stack.</p></div>\r
2917 <div class="exampleblock">\r
2918 <div class="content">\r
2919 <div class="sidebarblock">\r
2920 <div class="content">\r
2921 <div class="title">Defintion concept for R[n]</div>\r
2922 <div class="paragraph"><p>( n&#8201;&#8212;&#8201;a ) : R[n] 8 * RSP + ;</p></div>\r
2923 </div></div>\r
2924 </div></div>\r
2925 <div style="text-align:center">\r
2926 _______________________________________________________\r
2927 </div>\r
2928 <div class="paragraph"><p><a id="p_read_stream_char"></a></p></div>\r
2929 </div>\r
2930 <div class="sect2">\r
2931 <h3 id="_word_read_stream_char">Word: READ-STREAM-CHAR</h3>\r
2932 <div class="literalblock">\r
2933 <div class="content">\r
2934 <pre><code>Data stack: ( stream -- c )</code></pre>\r
2935 </div></div>\r
2936 <div class="paragraph"><p>"READ-STREAM-CHAR" is a function word that gets the next character\r
2937 from the given stream buffer, possibly refilling the buffer if it is\r
2938 backed by a file descriptor. The refill is done by a SYS_READ call\r
2939 when more characters are needed. The next character is pushed on the\r
2940 stack, unless the stream is exhausted in which case the -1 is pushed\r
2941 instead.</p></div>\r
2942 <div class="paragraph"><p>See also <a href="#p_stream">STREAM</a>.</p></div>\r
2943 <div style="text-align:center">\r
2944 _______________________________________________________\r
2945 </div>\r
2946 <div class="paragraph"><p><a id="p_read_word"></a></p></div>\r
2947 </div>\r
2948 <div class="sect2">\r
2949 <h3 id="_word_read_word">Word: READ-WORD</h3>\r
2950 <div class="literalblock">\r
2951 <div class="content">\r
2952 <pre><code>Data stack: ( stream -- char* n )</code></pre>\r
2953 </div></div>\r
2954 <div class="paragraph"><p>"READ-WORD" is a function word that "reads" the next whitespace\r
2955 separated word from the given stream and returns the [n:char*] duoble\r
2956 cell pointer for it. The characters of the word are copied to\r
2957 <a href="#p_pad">PAD</a>, and there is a limit of 1024 characters.</p></div>\r
2958 <div class="paragraph"><p>At the end of the stream READ-WORD returns 0 length.</p></div>\r
2959 <div class="exampleblock">\r
2960 <div class="title">Special syntax 1: Whitespace</div>\r
2961 <div class="content">\r
2962 <div class="paragraph"><p>All character codes less or equal to 32 are regarded as "whitespace".</p></div>\r
2963 </div></div>\r
2964 <div class="exampleblock">\r
2965 <div class="title">Special syntax 2: Rest-of-line comment</div>\r
2966 <div class="content">\r
2967 <div class="paragraph"><p>The "#" character following whitespace starts a line comment and the\r
2968 rest of the line is ignored. Note that this is also recognised with\r
2969 <a href="#p_lparen">parethesis commenting</a>.</p></div>\r
2970 </div></div>\r
2971 <div style="text-align:center">\r
2972 _______________________________________________________\r
2973 </div>\r
2974 <div class="paragraph"><p><a id="p_realloc"></a></p></div>\r
2975 </div>\r
2976 <div class="sect2">\r
2977 <h3 id="_word_realloc">Word: REALLOC</h3>\r
2978 <div class="literalblock">\r
2979 <div class="content">\r
2980 <pre><code>Data stack: ( a m n -- a )</code></pre>\r
2981 </div></div>\r
2982 <div class="paragraph"><p>"REALLOC" is a word that reallocates memory using mremap of address a\r
2983 of size m to be size n bytes and returns the lowest address of the\r
2984 allocated block.</p></div>\r
2985 <div class="paragraph"><p>Note that this makes new page allocations for the process from the\r
2986 kernel, and the granularity is in pages, i.e. a multiple of 4 kb.</p></div>\r
2987 <div class="paragraph"><p>The memory is reampped using the MREMAP_MAYMOVE flag,</p></div>\r
2988 <div class="paragraph"><p>See also <a href="#p_malloc">MALLOC</a></p></div>\r
2989 <div style="text-align:center">\r
2990 _______________________________________________________\r
2991 </div>\r
2992 <div class="paragraph"><p><a id="p_return"></a></p></div>\r
2993 </div>\r
2994 <div class="sect2">\r
2995 <h3 id="_word_return">Word: RETURN</h3>\r
2996 <div class="literalblock">\r
2997 <div class="content">\r
2998 <pre><code>Data stack: ( -- )</code></pre>\r
2999 </div></div>\r
3000 <div class="paragraph"><p>"RETURN" is a function word that implements the ending of a FORTH\r
3001 definition and make execution return to the next step in the calling\r
3002 definition.</p></div>\r
3003 <div style="text-align:center">\r
3004 _______________________________________________________\r
3005 </div>\r
3006 <div class="paragraph"><p>compile.asm:    WORD p_right_bracket,<em>]</em>,fasm</p></div>\r
3007 <div class="paragraph"><p><a id="p_right_bracket"></a></p></div>\r
3008 </div>\r
3009 <div class="sect2">\r
3010 <h3 id="_word_17">Word: ]</h3>\r
3011 <div class="literalblock">\r
3012 <div class="content">\r
3013 <pre><code>Data stack: ( -- )</code></pre>\r
3014 </div></div>\r
3015 <div class="paragraph"><p>"]" (right bracket) is a function word that sets the stream evaluation\r
3016 mode to be compiling. In this mode words parsed into CFA pointers\r
3017 which are placed on the heap in the given order, unless the word is\r
3018 flagged as <a href="#p_immediate">IMMEDIATE</a> or a <a href="#p_number">NUMBER</a>. An\r
3019 immediate word is executed immediately, and a number is parsed and\r
3020 left on the stack.</p></div>\r
3021 <div class="paragraph"><p>Note that a word is parsed as a number only if it is not found in the\r
3022 wordlist; i.e., the word list may contain definitions for numbers.</p></div>\r
3023 <div class="exampleblock">\r
3024 <div class="content">\r
3025 <div class="sidebarblock">\r
3026 <div class="content">\r
3027 <div class="title">Definition concept for ]</div>\r
3028 <div class="paragraph"><p>: ] 1 STATE ! ;</p></div>\r
3029 </div></div>\r
3030 </div></div>\r
3031 <div style="text-align:center">\r
3032 _______________________________________________________\r
3033 </div>\r
3034 <div class="paragraph"><p><a id="p_roll"></a></p></div>\r
3035 </div>\r
3036 <div class="sect2">\r
3037 <h3 id="_word_roll">Word: ROLL</h3>\r
3038 <div class="literalblock">\r
3039 <div class="content">\r
3040 <pre><code>Data stack: ( vu...v1 v0 u -- ...v1 v0 vu )</code></pre>\r
3041 </div></div>\r
3042 <div class="paragraph"><p>"ROLL" is a function word that "moves" the u:th data stack cell down\r
3043 from top onto the data stack while discarding it. 0 indicates the top\r
3044 cell; 1 indicates the second top cell making it the same as\r
3045 <a href="#p_swap">SWAP</a>; 2 indicates the third top cell making it the same as\r
3046 <a href="#p_rot">ROT</a>.</p></div>\r
3047 <div style="text-align:center">\r
3048 _______________________________________________________\r
3049 </div>\r
3050 <div class="paragraph"><p><a id="p_rot"></a></p></div>\r
3051 </div>\r
3052 <div class="sect2">\r
3053 <h3 id="_word_rot">Word: ROT</h3>\r
3054 <div class="literalblock">\r
3055 <div class="content">\r
3056 <pre><code>Data stack: ( v1 v2 v3 -- v2 v3 v1 )</code></pre>\r
3057 </div></div>\r
3058 <div class="paragraph"><p>"ROT" is a function word that "rotates" the top three data stack cells\r
3059 such that the third becomes the first while the second becomes third\r
3060 and the first becomes the second.</p></div>\r
3061 <div class="paragraph"><p>See also <a href="#p_roll">ROLL</a>.</p></div>\r
3062 <div style="text-align:center">\r
3063 _______________________________________________________\r
3064 </div>\r
3065 <div class="paragraph"><p><a id="p_semicolon"></a></p></div>\r
3066 </div>\r
3067 <div class="sect2">\r
3068 <h3 id="_word_18">Word: ;</h3>\r
3069 <div class="literalblock">\r
3070 <div class="content">\r
3071 <pre><code>Data stack: ( -- )</code></pre>\r
3072 </div></div>\r
3073 <div class="paragraph"><p>";" (semi-colon) is a function word that ends a new forth definition\r
3074 by means of adding an <a href="#p_exit">EXIT</a></p></div>\r
3075 <div class="exampleblock">\r
3076 <div class="content">\r
3077 <div class="sidebarblock">\r
3078 <div class="content">\r
3079 <div class="title">Definition concept for ;</div>\r
3080 <div class="paragraph"><p>: ; IMMEDIATE ' EXIT , ;</p></div>\r
3081 </div></div>\r
3082 </div></div>\r
3083 <div style="text-align:center">\r
3084 _______________________________________________________\r
3085 </div>\r
3086 <div class="paragraph"><p><a id="p_setup_signals"></a></p></div>\r
3087 </div>\r
3088 <div class="sect2">\r
3089 <h3 id="_word_p_setup_signals">Word: [p_setup_signals]</h3>\r
3090 <div class="literalblock">\r
3091 <div class="content">\r
3092 <pre><code>Data stack: ( -- a )</code></pre>\r
3093 </div></div>\r
3094 <div class="paragraph"><p>"[p_setup_signals]" is a variable word that contains the assembly code\r
3095 sniippet for setting up the signal handling. rrqforth handles SEGV by\r
3096 restarting the interpreter loop on <a href="#p_stdin">STDIN</a>.</p></div>\r
3097 <div style="text-align:center">\r
3098 _______________________________________________________\r
3099 </div>\r
3100 <div class="paragraph"><p><a id="p_shift_left"></a></p></div>\r
3101 </div>\r
3102 <div class="sect2">\r
3103 <h3 id="_word_lt_lt">Word: &lt;&lt;</h3>\r
3104 <div class="literalblock">\r
3105 <div class="content">\r
3106 <pre><code>Data stack: ( v1 n -- v2 )</code></pre>\r
3107 </div></div>\r
3108 <div class="paragraph"><p>"&lt;&lt;" is a function word that shifts value v1 n steps left (i.e.\r
3109 "moving" bits towards more significant bits) to form value v2.</p></div>\r
3110 <div style="text-align:center">\r
3111 _______________________________________________________\r
3112 </div>\r
3113 <div class="paragraph"><p><a id="p_shift_right"></a></p></div>\r
3114 </div>\r
3115 <div class="sect2">\r
3116 <h3 id="_word_gt_gt">Word: &gt;&gt;</h3>\r
3117 <div class="literalblock">\r
3118 <div class="content">\r
3119 <pre><code>Data stack: ( v1 n -- v2 )</code></pre>\r
3120 </div></div>\r
3121 <div class="paragraph"><p>"&gt;&gt;" is a function word that shifts value v1 n steps right (i.e.\r
3122 "moving" bits towards less significant bits) to form value v2.</p></div>\r
3123 <div style="text-align:center">\r
3124 _______________________________________________________\r
3125 </div>\r
3126 <div class="paragraph"><p><a id="p_shift_signed_right"></a></p></div>\r
3127 </div>\r
3128 <div class="sect2">\r
3129 <h3 id="_word_s_gt_gt">Word: s&gt;&gt;</h3>\r
3130 <div class="literalblock">\r
3131 <div class="content">\r
3132 <pre><code>Data stack: ( v1 n -- v2 )</code></pre>\r
3133 </div></div>\r
3134 <div class="paragraph"><p>"s&gt;&gt;" is a function word that shifts value v1 n steps right (i.e.\r
3135 "moving" bits towards less significant bits) to form value v2, but\r
3136 preserving (and copying) the sign bit.</p></div>\r
3137 <div style="text-align:center">\r
3138 _______________________________________________________\r
3139 </div>\r
3140 <div class="paragraph"><p><a id="p_sp"></a></p></div>\r
3141 </div>\r
3142 <div class="sect2">\r
3143 <h3 id="_word_sp">Word: SP</h3>\r
3144 <div class="literalblock">\r
3145 <div class="content">\r
3146 <pre><code>Data stack: ( -- v )</code></pre>\r
3147 </div></div>\r
3148 <div class="paragraph"><p>"SP" is a value word pushing a space character onto the data stack.</p></div>\r
3149 <div style="text-align:center">\r
3150 _______________________________________________________\r
3151 </div>\r
3152 <div class="paragraph"><p><a id="p_state"></a></p></div>\r
3153 </div>\r
3154 <div class="sect2">\r
3155 <h3 id="_word_state">Word: STATE</h3>\r
3156 <div class="literalblock">\r
3157 <div class="content">\r
3158 <pre><code>Data stack: ( -- a )</code></pre>\r
3159 </div></div>\r
3160 <div class="paragraph"><p>"STATE" is a variable word marking whether the stream evaluator is in\r
3161 compiling mode (1) or interpreting (0) mode.</p></div>\r
3162 <div style="text-align:center">\r
3163 _______________________________________________________\r
3164 </div>\r
3165 <div class="paragraph"><p><a id="p_stdin"></a></p></div>\r
3166 </div>\r
3167 <div class="sect2">\r
3168 <h3 id="_word_stdin">Word: STDIN</h3>\r
3169 <div class="literalblock">\r
3170 <div class="content">\r
3171 <pre><code>Data stack: ( -- stream )</code></pre>\r
3172 </div></div>\r
3173 <div class="paragraph"><p>"STDIN" is a value word referring to the stream buffer for the\r
3174 standard input file descriptor.</p></div>\r
3175 <div style="text-align:center">\r
3176 _______________________________________________________\r
3177 </div>\r
3178 <div class="paragraph"><p><a id="p_stream"></a></p></div>\r
3179 </div>\r
3180 <div class="sect2">\r
3181 <h3 id="_word_stream">Word: STREAM</h3>\r
3182 <div class="literalblock">\r
3183 <div class="content">\r
3184 <pre><code>Data stack: ( fd size -- addr ) or ( block -1 -- addr )</code></pre>\r
3185 </div></div>\r
3186 <div class="paragraph"><p>"STREAM" is a function word that sets up a buffer for an input file\r
3187 descriptor or for a memory block (of size+data).</p></div>\r
3188 <div class="sect3">\r
3189 <h4 id="_file_descriptor_backed_stream">File descriptor backed STREAM</h4>\r
3190 <div class="paragraph"><p>A file descriptor backed STREAM gains a buffer of the given size\r
3191 prefixed by a 32 byte STREAM header of the following layout:</p></div>\r
3192 <div class="exampleblock">\r
3193 <div class="content">\r
3194 <div class="listingblock">\r
3195 <div class="title">Layout 3: file descriptor stream</div>\r
3196 <div class="content">\r
3197 <pre><code>  8 bytes = size of buffer (excluding the 32 byte header)\r
3198   8 bytes source file descriptor\r
3199   8 bytes current fill\r
3200   8 current read position</code></pre>\r
3201 </div></div>\r
3202 </div></div>\r
3203 </div>\r
3204 <div class="sect3">\r
3205 <h4 id="_memory_block_backed_stream">Memory block backed STREAM</h4>\r
3206 <div class="paragraph"><p>A memory block stream is only the header (though allocated via\r
3207 <a href="#p_malloc">MALLOC</a> which reserves a full kernel page) with the\r
3208 following layout:</p></div>\r
3209 <div class="exampleblock">\r
3210 <div class="content">\r
3211 <div class="listingblock">\r
3212 <div class="title">Layout 4: memory block stream</div>\r
3213 <div class="content">\r
3214 <pre><code>  8 bytes = block address\r
3215   8 -1 (indicates memory block)\r
3216   8 size of block (taken from the block's first 8 bytes)\r
3217   8 current read position</code></pre>\r
3218 </div></div>\r
3219 </div></div>\r
3220 <div style="text-align:center">\r
3221 _______________________________________________________\r
3222 </div>\r
3223 <div class="paragraph"><p><a id="p_stream_nchars"></a></p></div>\r
3224 </div>\r
3225 </div>\r
3226 <div class="sect2">\r
3227 <h3 id="_word_stream_nchars">Word: STREAM-NCHARS</h3>\r
3228 <div class="literalblock">\r
3229 <div class="content">\r
3230 <pre><code>Data stack: ( stream -- n )</code></pre>\r
3231 </div></div>\r
3232 <div class="paragraph"><p>"STREAM-NCHARS" is a function word that scans ahead in the stream\r
3233 buffer for the next non-whitespace character, and returns its position\r
3234 relative to the end of the buffer. This is done without changing the\r
3235 stream (or filling it by reading the backing file).</p></div>\r
3236 <div style="text-align:center">\r
3237 _______________________________________________________\r
3238 </div>\r
3239 <div class="paragraph"><p><a id="p_strlen"></a></p></div>\r
3240 </div>\r
3241 <div class="sect2">\r
3242 <h3 id="_word_strlen">Word: STRLEN</h3>\r
3243 <div class="literalblock">\r
3244 <div class="content">\r
3245 <pre><code>Data stack: ( s -- n )</code></pre>\r
3246 </div></div>\r
3247 <div class="paragraph"><p>"STRLEN" is a function words that counts how many bytes there are from\r
3248 s to the first NUL byte and returns that count, n, not including the\r
3249 NUL byte.</p></div>\r
3250 <div style="text-align:center">\r
3251 _______________________________________________________\r
3252 </div>\r
3253 <div class="paragraph"><p><a id="p_strncmp"></a></p></div>\r
3254 </div>\r
3255 <div class="sect2">\r
3256 <h3 id="_word_strncmp">Word: STRNCMP</h3>\r
3257 <div class="literalblock">\r
3258 <div class="content">\r
3259 <pre><code>Data stack: ( s1 s2 n -- v )</code></pre>\r
3260 </div></div>\r
3261 <div class="paragraph"><p>"STRNCMP" is a function words that compares up to n characters of\r
3262 character sequences s1 and s2, and returns the difference of the first\r
3263 differing characters, as in <code>s2[i] - s1[i]</code>, or 0 if all n characters\r
3264 are the same.</p></div>\r
3265 <div class="paragraph"><p>I.e., the value v is less than 0 if string [n:s1] is alpha-numerically\r
3266 less than [n:s2],\r
3267 v is greater than 0 if [n:s1] is greater than [n:s2],\r
3268 and v is 0 if [n:s1] and [n:s2] are equal.</p></div>\r
3269 <div style="text-align:center">\r
3270 _______________________________________________________\r
3271 </div>\r
3272 <div class="paragraph"><p><a id="p_strncpy"></a></p></div>\r
3273 </div>\r
3274 <div class="sect2">\r
3275 <h3 id="_word_strncpy">Word: STRNCPY</h3>\r
3276 <div class="literalblock">\r
3277 <div class="content">\r
3278 <pre><code>Data stack: ( s1 s2 n -- )</code></pre>\r
3279 </div></div>\r
3280 <div class="paragraph"><p>"STRNCPY" is a function words that copies n bytes of byte sequence s1\r
3281 to s2.</p></div>\r
3282 <div style="text-align:center">\r
3283 _______________________________________________________\r
3284 </div>\r
3285 <div class="paragraph"><p><a id="p_swap"></a></p></div>\r
3286 </div>\r
3287 <div class="sect2">\r
3288 <h3 id="_word_swap">Word: SWAP</h3>\r
3289 <div class="literalblock">\r
3290 <div class="content">\r
3291 <pre><code>Data stack: ( v1 v2 -- v2 v1 )</code></pre>\r
3292 </div></div>\r
3293 <div class="paragraph"><p>"SWAP" is a function word the swaps the top two data stack cells.</p></div>\r
3294 <div style="text-align:center">\r
3295 _______________________________________________________\r
3296 </div>\r
3297 <div class="paragraph"><p><a id="p_system"></a></p></div>\r
3298 </div>\r
3299 <div class="sect2">\r
3300 <h3 id="_word_system">Word: SYSTEM</h3>\r
3301 <div class="literalblock">\r
3302 <div class="content">\r
3303 <pre><code>Data value: ( -- a )</code></pre>\r
3304 </div></div>\r
3305 <div class="paragraph"><p>"SYSTEM" is a variable that holds the word list data for the system\r
3306 calls. This is set up as separate word list from <a href="#p_forth">FORTH</a>\r
3307 merely as a matter of segregation.</p></div>\r
3308 <div style="text-align:center">\r
3309 _______________________________________________________\r
3310 </div>\r
3311 <div class="paragraph"><p><a id="p_tell"></a></p></div>\r
3312 </div>\r
3313 <div class="sect2">\r
3314 <h3 id="_word_tell">Word: TELL</h3>\r
3315 <div class="literalblock">\r
3316 <div class="content">\r
3317 <pre><code>Data stack: ( char* n -- )</code></pre>\r
3318 </div></div>\r
3319 <div class="paragraph"><p>"TELL" is a function word that prints a string to stdout (file\r
3320 descriptor 1).</p></div>\r
3321 <div style="text-align:center">\r
3322 _______________________________________________________\r
3323 </div>\r
3324 <div class="paragraph"><p><a id="p_terminate0"></a></p></div>\r
3325 </div>\r
3326 <div class="sect2">\r
3327 <h3 id="_word_terminate0">Word: TERMINATE0</h3>\r
3328 <div class="literalblock">\r
3329 <div class="content">\r
3330 <pre><code>Data stack: ( -- )</code></pre>\r
3331 </div></div>\r
3332 <div class="paragraph"><p>"TERMINATE0" is a function word that terminates the program with exit\r
3333 code 0.</p></div>\r
3334 <div style="text-align:center">\r
3335 _______________________________________________________\r
3336 </div>\r
3337 <div class="paragraph"><p><a id="p_tfa2cfa"></a></p></div>\r
3338 </div>\r
3339 <div class="sect2">\r
3340 <h3 id="_word_tfa_gt_cfa">Word: TFA&gt;CFA</h3>\r
3341 <div class="literalblock">\r
3342 <div class="content">\r
3343 <pre><code>Data stack: ( tfa -- cfa )</code></pre>\r
3344 </div></div>\r
3345 <div class="paragraph"><p>"TFA&gt;CFA" is a function word that pushes word cfa of the given tfa.</p></div>\r
3346 <div class="exampleblock">\r
3347 <div class="content">\r
3348 <div class="sidebarblock">\r
3349 <div class="content">\r
3350 <div class="title">Definition concept for TFA&gt;CFA</div>\r
3351 <div class="paragraph"><p>: TFA&gt;CFA 8 + @ ;</p></div>\r
3352 </div></div>\r
3353 </div></div>\r
3354 <div style="text-align:center">\r
3355 _______________________________________________________\r
3356 </div>\r
3357 <div class="paragraph"><p><a id="p_tfa2dfa"></a></p></div>\r
3358 </div>\r
3359 <div class="sect2">\r
3360 <h3 id="_word_tfa_gt_dfa">Word: TFA&gt;DFA</h3>\r
3361 <div class="literalblock">\r
3362 <div class="content">\r
3363 <pre><code>Data stack: ( tfa -- dfa )</code></pre>\r
3364 </div></div>\r
3365 <div class="paragraph"><p>"TFA&gt;DFA" is a function word that pushes word dfa of the given tfa.</p></div>\r
3366 <div class="exampleblock">\r
3367 <div class="content">\r
3368 <div class="sidebarblock">\r
3369 <div class="content">\r
3370 <div class="title">Definition concept for TFA&gt;DFA</div>\r
3371 <div class="paragraph"><p>: TFA&gt;DFA TFA&gt;CFA 8 + ;</p></div>\r
3372 </div></div>\r
3373 </div></div>\r
3374 <div style="text-align:center">\r
3375 _______________________________________________________\r
3376 </div>\r
3377 <div class="paragraph"><p><a id="p_tfa2flags_get"></a></p></div>\r
3378 </div>\r
3379 <div class="sect2">\r
3380 <h3 id="_word_tfa_gt_flags">Word: TFA&gt;FLAGS@</h3>\r
3381 <div class="literalblock">\r
3382 <div class="content">\r
3383 <pre><code>Data stack: ( tfa -- flags )</code></pre>\r
3384 </div></div>\r
3385 <div class="paragraph"><p>"TFA&gt;FLAGS@" is a function word that pushes word flags of the given tfa.</p></div>\r
3386 <div class="exampleblock">\r
3387 <div class="content">\r
3388 <div class="sidebarblock">\r
3389 <div class="content">\r
3390 <div class="title">Defintion concept for TFA&gt;FLAGS@</div>\r
3391 <div class="paragraph"><p>: TFA&gt;FLAGS@ 16 + @ ;</p></div>\r
3392 </div></div>\r
3393 </div></div>\r
3394 <div style="text-align:center">\r
3395 _______________________________________________________\r
3396 </div>\r
3397 <div class="paragraph"><p><a id="p_tfa2namez"></a></p></div>\r
3398 </div>\r
3399 <div class="sect2">\r
3400 <h3 id="_word_tfa_gt_namez">Word: TFA&gt;NAMEZ</h3>\r
3401 <div class="literalblock">\r
3402 <div class="content">\r
3403 <pre><code>Data stack: ( tfa -- char* )</code></pre>\r
3404 </div></div>\r
3405 <div class="paragraph"><p>"TFA&gt;NAMEZ" is a function word that pushes changes a tfa pointer to a\r
3406 pointer to the word pname&#8217;s character sequence, which is zero\r
3407 terminated as well as preceded by a length cell.</p></div>\r
3408 <div class="exampleblock">\r
3409 <div class="content">\r
3410 <div class="sidebarblock">\r
3411 <div class="content">\r
3412 <div class="title">Defintion concept for TFA&gt;NAMEZ</div>\r
3413 <div class="paragraph"><p>: TFA&gt;NAMEZ 32 + ;</p></div>\r
3414 </div></div>\r
3415 </div></div>\r
3416 <div style="text-align:center">\r
3417 _______________________________________________________\r
3418 </div>\r
3419 <div class="paragraph"><p><a id="p_then"></a></p></div>\r
3420 </div>\r
3421 <div class="sect2">\r
3422 <h3 id="_word_then">Word: THEN</h3>\r
3423 <div class="literalblock">\r
3424 <div class="content">\r
3425 <pre><code>Data stack: Compiling: ( a -- )</code></pre>\r
3426 </div></div>\r
3427 <div class="paragraph"><p>"THEN" is an immediate function word that is used together with\r
3428 <a href="#p_if">IF</a> and <a href="#p_else">ELSE</a> to implement structured execution\r
3429 control. THEN performs the branch resolution for the stacked address\r
3430 which pinpoints the foot address the branch offset to resolve, so that\r
3431 at execution time there is an appropriate conditional branch past the\r
3432 "then-part" or the "else-part" of the "structured statement".</p></div>\r
3433 <div style="text-align:center">\r
3434 _______________________________________________________\r
3435 </div>\r
3436 <div class="paragraph"><p><a id="p_this_word"></a></p></div>\r
3437 </div>\r
3438 <div class="sect2">\r
3439 <h3 id="_word_this_word">Word: THIS-WORD</h3>\r
3440 <div class="literalblock">\r
3441 <div class="content">\r
3442 <pre><code>Data stack: ( -- a )</code></pre>\r
3443 </div></div>\r
3444 <div class="paragraph"><p>"THIS-WORD" is a variable word used in\r
3445 <a href="#p_evaluate_stream:EVALUATE-STREAM">[p_evaluate_stream:EVALUATE-STREAM]</a> as cache for the [n:char*]\r
3446 values of the successive words being evaluated. This typically points\r
3447 into the input stream buffer and remain valid until further stream\r
3448 buffering functions are used.</p></div>\r
3449 <div style="text-align:center">\r
3450 _______________________________________________________\r
3451 </div>\r
3452 <div class="paragraph"><p><a id="p_true"></a></p></div>\r
3453 </div>\r
3454 <div class="sect2">\r
3455 <h3 id="_word_true">Word: TRUE</h3>\r
3456 <div class="literalblock">\r
3457 <div class="content">\r
3458 <pre><code>Data stack: ( -- -1 )</code></pre>\r
3459 </div></div>\r
3460 <div class="paragraph"><p>"TRUE" is a value word representing logical true.</p></div>\r
3461 <div style="text-align:center">\r
3462 _______________________________________________________\r
3463 </div>\r
3464 <div class="paragraph"><p><a id="p_tuck"></a></p></div>\r
3465 </div>\r
3466 <div class="sect2">\r
3467 <h3 id="_word_tuck">Word: TUCK</h3>\r
3468 <div class="literalblock">\r
3469 <div class="content">\r
3470 <pre><code>Data stack ( v1 v2 -- v2 v1 v2 )</code></pre>\r
3471 </div></div>\r
3472 <div class="paragraph"><p>"TUCK" is a function word that "inserts" the top cell below the second\r
3473 cell on the data stack.</p></div>\r
3474 <div class="exampleblock">\r
3475 <div class="content">\r
3476 <div class="sidebarblock">\r
3477 <div class="content">\r
3478 <div class="title">Definition concept for TUCK</div>\r
3479 <div class="paragraph"><p>: TUCK SWAP OVER ;</p></div>\r
3480 </div></div>\r
3481 </div></div>\r
3482 <div style="text-align:center">\r
3483 _______________________________________________________\r
3484 </div>\r
3485 <div class="paragraph"><p><a id="p_unequal"></a></p></div>\r
3486 </div>\r
3487 <div class="sect2">\r
3488 <h3 id="_word_19">Word: !=</h3>\r
3489 <div class="literalblock">\r
3490 <div class="content">\r
3491 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>\r
3492 </div></div>\r
3493 <div class="paragraph"><p>"!=" is a function word that replaces a pair of values with -1 of the\r
3494 values are unequal, and 0 otherwise.</p></div>\r
3495 <div style="text-align:center">\r
3496 _______________________________________________________\r
3497 </div>\r
3498 <div class="paragraph"><p><a id="p_unstream"></a></p></div>\r
3499 </div>\r
3500 <div class="sect2">\r
3501 <h3 id="_word_unstream">Word: UNSTREAM</h3>\r
3502 <div class="literalblock">\r
3503 <div class="content">\r
3504 <pre><code>Data stack: ( stream* -- )</code></pre>\r
3505 </div></div>\r
3506 <div class="paragraph"><p>"UNSTREAM" is a function word that releases the memory allocated for a\r
3507 stream, and closes the associated file if it&#8217;s a file stream.</p></div>\r
3508 <div class="sect3">\r
3509 <h4 id="_file_descriptor_backed_stream_2">File descriptor backed stream</h4>\r
3510 <div class="paragraph"><p>This kind of stream has the stream header as a prefix within the\r
3511 allocated memory. Thus, stream* is the base address for the memory to\r
3512 reclaim, and the size of this is determined from the cell at (stream*\r
3513 + 16) plus the 32 bytes head itself.</p></div>\r
3514 </div>\r
3515 <div class="sect3">\r
3516 <h4 id="_memory_block_backed_stream_2">Memory block backed STREAM</h4>\r
3517 <div class="paragraph"><p>This kind of stream has a separate header which points at the memory\r
3518 area to reclaim. The cell at stream* is the base address, and the cell\r
3519 at (stream* + 16) is its size.</p></div>\r
3520 <div style="text-align:center">\r
3521 _______________________________________________________\r
3522 </div>\r
3523 <div class="paragraph"><p><a id="p_use"></a></p></div>\r
3524 </div>\r
3525 </div>\r
3526 <div class="sect2">\r
3527 <h3 id="_word_use">Word: USE</h3>\r
3528 <div class="literalblock">\r
3529 <div class="content">\r
3530 <pre><code>Data value: ( wordlist -- )  Input stream: word</code></pre>\r
3531 </div></div>\r
3532 <div class="paragraph"><p>"USE" is a function word that looks up next word given the wordlist.\r
3533 It reads next word on <a href="#p_input">INPUT</a> via <a href="#p_read_word">READ-WORD</a>,\r
3534 then temporarily changes <a href="#p_current_wordlist">CURRENT-WORDLIST</a> to\r
3535 <a href="#p_find">FIND</a> the word via the given wordlist, and returns the TFA\r
3536 of that word, or just 0 if the word coudn&#8217;t be found.</p></div>\r
3537 <div style="text-align:center">\r
3538 _______________________________________________________\r
3539 </div>\r
3540 <div class="paragraph"><p><a id="p_verboseQ"></a></p></div>\r
3541 </div>\r
3542 <div class="sect2">\r
3543 <h3 id="_word_verbose">Word: VERBOSE?</h3>\r
3544 <div class="literalblock">\r
3545 <div class="content">\r
3546 <pre><code>Data stack: ( -- a )</code></pre>\r
3547 </div></div>\r
3548 <div class="paragraph"><p>"VERBOSE?" is a variable word that is assigned at start up to -1 or 0\r
3549 signify whether or not the command line arguments includes "-v". When\r
3550 non-zero (i.e. running rrqforth with "-v") the evaluation loop is more\r
3551 verbose.</p></div>\r
3552 <div style="text-align:center">\r
3553 _______________________________________________________\r
3554 </div>\r
3555 <div class="paragraph"><p><a id="p_within"></a></p></div>\r
3556 </div>\r
3557 <div class="sect2">\r
3558 <h3 id="_word_within">Word: WITHIN</h3>\r
3559 <div class="literalblock">\r
3560 <div class="content">\r
3561 <pre><code>Data stack: ( v lo hi -- 0/-1</code></pre>\r
3562 </div></div>\r
3563 <div class="paragraph"><p>"WITHIN" is a function word that replaces a triple of values with -1\r
3564 of the the first, v, is within the value range spanned by the second,\r
3565 lo, inclusive and third, hi, exclusive.</p></div>\r
3566 <div class="exampleblock">\r
3567 <div class="content">\r
3568 <div class="sidebarblock">\r
3569 <div class="content">\r
3570 <div class="title">Definition concept for WITHIN</div>\r
3571 <div class="paragraph"><p>: WITHIN 2 PICK &gt; ROT ROT &#8656; AND ;</p></div>\r
3572 </div></div>\r
3573 </div></div>\r
3574 <div style="text-align:center">\r
3575 _______________________________________________________\r
3576 </div>\r
3577 <div class="paragraph"><p><a id="p_words"></a></p></div>\r
3578 </div>\r
3579 <div class="sect2">\r
3580 <h3 id="_word_words">Word: WORDS</h3>\r
3581 <div class="literalblock">\r
3582 <div class="content">\r
3583 <pre><code>Data stack: ( wl -- )</code></pre>\r
3584 </div></div>\r
3585 <div class="paragraph"><p>"WORDS" is a function word that prints all words of teh given word\r
3586 list to stdout (file descriptor 1).</p></div>\r
3587 <div style="text-align:center">\r
3588 _______________________________________________________\r
3589 </div>\r
3590 <div class="paragraph"><p><a id="p_xor"></a></p></div>\r
3591 </div>\r
3592 <div class="sect2">\r
3593 <h3 id="_word_xor">Word: XOR</h3>\r
3594 <div class="literalblock">\r
3595 <div class="content">\r
3596 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>\r
3597 </div></div>\r
3598 <div class="paragraph"><p>"XOR" is a function word that replaces a value pair with their bitwise\r
3599 exclusion; each bit is 1 if the corresponding bits of the two operands\r
3600 differ and 0 if not.</p></div>\r
3601 <div style="text-align:center">\r
3602 _______________________________________________________\r
3603 </div>\r
3604 <div class="paragraph"><p><a id="return_stack"></a></p></div>\r
3605 </div>\r
3606 <div class="sect2">\r
3607 <h3 id="_word_return_stack">Word: RETURN-STACK</h3>\r
3608 <div class="literalblock">\r
3609 <div class="content">\r
3610 <pre><code>Data stack: ( -- a )</code></pre>\r
3611 </div></div>\r
3612 <div class="paragraph"><p>"RETURN-STACK" is a variable word harbouring the return stack.</p></div>\r
3613 </div>\r
3614 </div>\r
3615 </div>\r
3616 <div class="sect1">\r
3617 <h2 id="_system_calls">System calls</h2>\r
3618 <div class="sectionbody">\r
3619 <div class="paragraph"><p>RRQFORTH includes function wrapping for all "Linux syscalls", which\r
3620 generally are described in their "man pages. This wrapping takes the\r
3621 arguments fro the data stack in reverse order, i.e. the first argument\r
3622 is deepest.</p></div>\r
3623 <div class="paragraph"><p>Use <code>SYSTEM WORDS</code> to get a list of all (321) available syscalls.</p></div>\r
3624 </div>\r
3625 </div>\r
3626 </div>\r
3627 <div id="footnotes"><hr /></div>\r
3628 <div id="footer">\r
3629 <div id="footer-text">\r
3630 Last updated\r
3631  2021-06-06 23:19:36 AEST\r
3632 </div>\r
3633 </div>\r
3634 </body>\r
3635 </html>\r