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
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
14 font-family: Georgia,serif;
\r
18 h1, h2, h3, h4, h5, h6,
\r
19 div.title, caption.title,
\r
20 thead, p.table.header,
\r
22 #author, #revnumber, #revdate, #revremark,
\r
24 font-family: Arial,Helvetica,sans-serif;
\r
28 margin: 1em 5% 1em 5%;
\r
33 text-decoration: underline;
\r
49 h1, h2, h3, h4, h5, h6 {
\r
52 margin-bottom: 0.5em;
\r
57 border-bottom: 2px solid silver;
\r
77 border: 1px solid silver;
\r
82 margin-bottom: 0.5em;
\r
88 ul > li { color: #aaa; }
\r
89 ul > li > * { color: black; }
\r
91 .monospaced, code, pre {
\r
92 font-family: "Courier New", Courier, monospace;
\r
99 white-space: pre-wrap;
\r
109 #revnumber, #revdate, #revremark {
\r
114 border-top: 2px solid silver;
\r
115 padding-top: 0.5em;
\r
120 padding-bottom: 0.5em;
\r
124 padding-bottom: 0.5em;
\r
129 margin-bottom: 1.5em;
\r
131 div.imageblock, div.exampleblock, div.verseblock,
\r
132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
\r
133 div.admonitionblock {
\r
135 margin-bottom: 1.5em;
\r
137 div.admonitionblock {
\r
139 margin-bottom: 2.0em;
\r
144 div.content { /* Block element content. */
\r
148 /* Block element titles. */
\r
149 div.title, caption.title {
\r
154 margin-bottom: 0.5em;
\r
160 td div.title:first-child {
\r
163 div.content div.title:first-child {
\r
166 div.content + div.title {
\r
170 div.sidebarblock > div.content {
\r
171 background: #ffffee;
\r
172 border: 1px solid #dddddd;
\r
173 border-left: 4px solid #f0f0f0;
\r
177 div.listingblock > div.content {
\r
178 border: 1px solid #dddddd;
\r
179 border-left: 5px solid #f0f0f0;
\r
180 background: #f8f8f8;
\r
184 div.quoteblock, div.verseblock {
\r
185 padding-left: 1.0em;
\r
186 margin-left: 1.0em;
\r
188 border-left: 5px solid #f0f0f0;
\r
192 div.quoteblock > div.attribution {
\r
193 padding-top: 0.5em;
\r
197 div.verseblock > pre.content {
\r
198 font-family: inherit;
\r
199 font-size: inherit;
\r
201 div.verseblock > div.attribution {
\r
202 padding-top: 0.75em;
\r
205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
\r
206 div.verseblock + div.attribution {
\r
210 div.admonitionblock .icon {
\r
211 vertical-align: top;
\r
214 text-decoration: underline;
\r
216 padding-right: 0.5em;
\r
218 div.admonitionblock td.content {
\r
219 padding-left: 0.5em;
\r
220 border-left: 3px solid #dddddd;
\r
223 div.exampleblock > div.content {
\r
224 border-left: 3px solid #dddddd;
\r
225 padding-left: 0.5em;
\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
234 margin-bottom: 0.8em;
\r
239 font-style: normal;
\r
242 dd > *:first-child {
\r
247 list-style-position: outside;
\r
250 list-style-type: decimal;
\r
253 list-style-type: lower-alpha;
\r
256 list-style-type: upper-alpha;
\r
259 list-style-type: lower-roman;
\r
262 list-style-type: upper-roman;
\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
269 margin-bottom: 0.1em;
\r
281 margin-bottom: 0.8em;
\r
284 padding-bottom: 15px;
\r
286 dt.hdlist1.strong, td.hdlist1.strong {
\r
290 vertical-align: top;
\r
291 font-style: normal;
\r
292 padding-right: 0.8em;
\r
296 vertical-align: top;
\r
298 div.hdlist.compact tr {
\r
304 background: yellow;
\r
307 .footnote, .footnoteref {
\r
311 span.footnote, span.footnoteref {
\r
312 vertical-align: super;
\r
316 margin: 20px 0 20px 0;
\r
317 padding: 7px 0 0 0;
\r
320 #footnotes div.footnote {
\r
326 border-top: 1px solid silver;
\r
335 padding-right: 0.5em;
\r
336 padding-bottom: 0.3em;
\r
337 vertical-align: top;
\r
339 div.colist td img {
\r
344 #footer-badges { display: none; }
\r
348 margin-bottom: 2.5em;
\r
356 margin-bottom: 0.1em;
\r
359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
\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
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
410 span.big { font-size: 2em; }
\r
411 span.small { font-size: 0.6em; }
\r
413 span.underline { text-decoration: underline; }
\r
414 span.overline { text-decoration: overline; }
\r
415 span.line-through { text-decoration: line-through; }
\r
417 div.unbreakable { page-break-inside: avoid; }
\r
427 margin-bottom: 1.5em;
\r
429 div.tableblock > table {
\r
430 border: 3px solid #527bbd;
\r
432 thead, p.table.header {
\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
443 div.tableblock > table[frame="hsides"] {
\r
444 border-left-style: none;
\r
445 border-right-style: none;
\r
447 div.tableblock > table[frame="vsides"] {
\r
448 border-top-style: none;
\r
449 border-bottom-style: none;
\r
460 margin-bottom: 1.5em;
\r
462 thead, p.tableblock.header {
\r
471 border-spacing: 0px;
\r
472 border-style: solid;
\r
473 border-color: #527bbd;
\r
474 border-collapse: collapse;
\r
476 th.tableblock, td.tableblock {
\r
479 border-style: solid;
\r
480 border-color: #527bbd;
\r
483 table.tableblock.frame-topbot {
\r
484 border-left-style: hidden;
\r
485 border-right-style: hidden;
\r
487 table.tableblock.frame-sides {
\r
488 border-top-style: hidden;
\r
489 border-bottom-style: hidden;
\r
491 table.tableblock.frame-none {
\r
492 border-style: hidden;
\r
495 th.tableblock.halign-left, td.tableblock.halign-left {
\r
498 th.tableblock.halign-center, td.tableblock.halign-center {
\r
499 text-align: center;
\r
501 th.tableblock.halign-right, td.tableblock.halign-right {
\r
505 th.tableblock.valign-top, td.tableblock.valign-top {
\r
506 vertical-align: top;
\r
508 th.tableblock.valign-middle, td.tableblock.valign-middle {
\r
509 vertical-align: middle;
\r
511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
\r
512 vertical-align: bottom;
\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
528 border-style: none;
\r
530 body.manpage div.sectionbody {
\r
535 body.manpage div#toc { display: none; }
\r
540 <script type="text/javascript">
\r
542 var asciidoc = { // Namespace.
\r
544 /////////////////////////////////////////////////////////////////////
\r
545 // Table Of Contents generator
\r
546 /////////////////////////////////////////////////////////////////////
\r
548 /* Author: Mihai Bazon, September 2002
\r
549 * http://students.infoiasi.ro/~mishoo
\r
551 * Table Of Content generator
\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
558 /* modified by Troy D. Hanson, September 2006. License: GPL */
\r
559 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
\r
561 // toclevels = 1..4.
\r
562 toc: function (toclevels) {
\r
564 function getText(el) {
\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
569 else if (i.firstChild != null)
\r
570 text += getText(i);
\r
575 function TocEntry(el, text, toclevel) {
\r
578 this.toclevel = toclevel;
\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
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
602 var toc = document.getElementById("toc");
\r
607 // Delete existing TOC entries in case we're reloading the TOC.
\r
608 var tocEntriesToRemove = [];
\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
617 for (i = 0; i < tocEntriesToRemove.length; i++) {
\r
618 toc.removeChild(tocEntriesToRemove[i]);
\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
635 if (entries.length == 0)
\r
636 toc.parentNode.removeChild(toc);
\r
640 /////////////////////////////////////////////////////////////////////
\r
641 // Footnotes generator
\r
642 /////////////////////////////////////////////////////////////////////
\r
644 /* Based on footnote generation code from:
\r
645 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
\r
648 footnotes: function () {
\r
649 // Delete existing footnote entries in case we're reloading the footnodes.
\r
651 var noteholder = document.getElementById("footnotes");
\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
661 for (i = 0; i < entriesToRemove.length; i++) {
\r
662 noteholder.removeChild(entriesToRemove[i]);
\r
665 // Rebuild footnote entries.
\r
666 var cont = document.getElementById("content");
\r
667 var spans = cont.getElementsByTagName("span");
\r
670 for (i=0; i<spans.length; i++) {
\r
671 if (spans[i].className == "footnote") {
\r
673 var note = spans[i].getAttribute("data-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
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
692 noteholder.parentNode.removeChild(noteholder);
\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
700 spans[i].innerHTML =
\r
701 "[<a href='#_footnote_" + n +
\r
702 "' title='View footnote' class='footnote'>" + n + "</a>]";
\r
708 install: function(toclevels) {
\r
711 function reinstall() {
\r
712 asciidoc.footnotes();
\r
714 asciidoc.toc(toclevels);
\r
718 function reinstallAndRemoveTimer() {
\r
719 clearInterval(timerId);
\r
723 timerId = setInterval(reinstall, 500);
\r
724 if (document.addEventListener)
\r
725 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
\r
727 window.onload = reinstallAndRemoveTimer;
\r
731 asciidoc.install();
\r
735 <body class="article">
\r
737 <h1>RRQFORTH Reference Documentation</h1>
\r
738 <span id="author">Ralph Ronnquist <ralph.ronnquist@gmail.com></span><br />
\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>  
\r
745 <a href="#p_colon">: (colon)</a>  
\r
746 <a href="#p_semicolon">: (semi-colon)</a>  
\r
747 <a href="#p_comma">, (comma)</a>  
\r
748 <a href="#p_dot">. (dot)</a>  
\r
749 <a href="#p_double_quote">" (double-quote)</a>  
\r
750 <a href="#p_quote">' (single-quote)</a>  
\r
751 <a href="#p_left_bracket">[ (left bracket)</a>  
\r
752 <a href="#p_right_bracket">] (right bracket)</a>  </p></div>
\r
753 <div class="paragraph"><p><a href="#p_lessthan"><</a>  
\r
754 <a href="#p_lessequal"><=</a>  
\r
755 <a href="#p_equal">=</a>  
\r
756 <a href="#p_unequal">!=</a>  
\r
757 <a href="#p_greaterthan">></a>  
\r
758 <a href="#p_greaterequal">>= </a>  
\r
759 <a href="#p_0equal">0=</a>  
\r
760 <a href="#p_0less">0<</a>  
\r
761 <a href="#p_minus">-</a>  
\r
762 <a href="#p_mult">*</a>  
\r
763 <a href="#p_plus">+</a>  
\r
764 <a href="#p_div">/</a>  
\r
765 <a href="#p_shift_left"><<</a>  
\r
766 <a href="#p_shift_right">>></a>  
\r
767 <a href="#p_shift_signed_right">s>></a>  
\r
768 <a href="#p_bracketed_quote">[']</a>  </p></div>
\r
769 <div class="paragraph"><p><a href="#p_get">@</a>  
\r
770 <a href="#p_put">!</a>  
\r
771 <a href="#p_Cget">C@</a>  
\r
772 <a href="#p_Cput">C!</a>  
\r
773 <a href="#p_Wget">W@</a>  
\r
774 <a href="#p_Wput">W!</a>  
\r
775 <a href="#p_Dget">D@</a>  
\r
776 <a href="#p_Dput">D!</a>  
\r
777 <a href="#p_2get">2@</a>  
\r
778 <a href="#p_2put">2!</a>  
\r
779 <a href="#p_put_plus">!+</a>  
\r
780 <a href="#p_get_n_increment">@n++</a>  
\r
781 <a href="#p_get_n_decrement">@n--</a>  
\r
782 <a href="#p_Ccomma">C,</a>  
\r
783 <a href="#p_Wcomma">W,</a>  
\r
784 <a href="#p_Dcomma">D,</a>  
\r
785 <a href="#p_literal_string_compile">S"</a>  
\r
786 <a href="#p_gtR">>R</a>  
\r
787 <a href="#p_Rget">R@</a>  
\r
788 <a href="#p_Rgt">R></a>  
\r
789 <a href="#p_rbpn">R[n]</a>  
\r
790 <a href="#p_dsp">D[n]</a>  </p></div>
\r
791 <div class="paragraph"><p><a href="#data_stack">DATA-STACK</a>  
\r
792 <a href="#return_stack">RETURN-STACK</a>  
\r
794 <a href="#p_branch">BRANCH</a>  
\r
795 <a href="#p_0branch">0BRANCH</a>  
\r
796 <a href="#p_1branch">1BRANCH</a>  
\r
798 <a href="#p_2drop">2DROP</a>  
\r
799 <a href="#p_2dup">2DUP</a>  
\r
800 <a href="#p_2over">2OVER</a>  
\r
801 <a href="#p_2swap">2SWAP</a>  </p></div>
\r
802 <div class="paragraph"><p><a href="#p_abs">ABS</a>  
\r
803 <a href="#p_again">AGAIN</a>  
\r
804 <a href="#p_allot">ALLOT</a>  
\r
805 <a href="#p_and">AND</a>  
\r
806 <a href="#inline_code">[ASM]</a>  </p></div>
\r
807 <div class="paragraph"><p><a href="#p_base">BASE</a>  
\r
808 <a href="#p_begin">BEGIN</a>  
\r
809 <a href="#p_break">BREAK</a>  </p></div>
\r
810 <div class="paragraph"><p><a href="#p_cfa2flags_get">CFA>FLAGS@</a>  
\r
811 <a href="#p_cfa2tfa">CFA>TFA</a>  
\r
812 <a href="#p_clear_stream">CLEAR-STREAM</a>  
\r
813 <a href="#p_create">CREATE</a>  
\r
814 <a href="#p_current_wordlist">CURRENT-WORDLIST</a>  </p></div>
\r
815 <div class="paragraph"><p><a href="#p_decimal">DECIMAL</a>  
\r
816 <a href="#p_definitions">DEFINITIONS</a>  
\r
817 <a href="#p_depth">DEPTH</a>  
\r
818 <a href="#p_digits">DIGITS</a>  
\r
819 <a href="#p_divmod">/MOD</a>  
\r
820 <a href="#p_dfa2tfa">DFA>TFA</a>  
\r
821 <a href="#p_dodoes">doDOES</a>  
\r
822 <a href="#p_does">DOES></a>  
\r
823 <a href="#p_dofasm">doFASM</a>  
\r
824 <a href="#p_doforth">doFORTH</a>  
\r
825 <a href="#p_dostring">doSTRING</a>  
\r
826 <a href="#p_dovalue">doVALUE</a>  
\r
827 <a href="#p_dovariable">doVARIABLE</a>  
\r
828 <a href="#p_drop">DROP</a>  
\r
829 <a href="#p_dup">DUP</a>  </p></div>
\r
830 <div class="paragraph"><p><a href="#p_else">ELSE</a>  
\r
831 <a href="#p_emit">EMIT</a>  
\r
832 <a href="#p_end">END</a>  
\r
833 <a href="#p_erase">ERASE</a>  
\r
834 <a href="#p_evaluate_stream">EVALUATE-STREAM</a>  
\r
835 <a href="#p_execute">EXECUTE</a>  
\r
836 <a href="#p_exit">EXIT</a>  </p></div>
\r
837 <div class="paragraph"><p><a href="#p_false">FALSE</a>  
\r
838 <a href="#p_fdemit">FDEMIT</a>  
\r
839 <a href="#p_fdtell">FDTELL</a>  
\r
840 <a href="#p_find">FIND</a>  
\r
841 <a href="#p_forth">FORTH</a>  </p></div>
\r
842 <div class="paragraph"><p><a href="#p_here">HERE</a>  
\r
843 <a href="#p_hex">HEX</a>  </p></div>
\r
844 <div class="paragraph"><p><a href="#p_if">IF</a>  
\r
845 <a href="#p_ifagain">IFAGAIN</a>  
\r
846 <a href="#p_ifbreak">IFBREAK</a>  
\r
847 <a href="#p_immediate">IMMEDIATE</a>  
\r
848 <a href="#p_input">INPUT</a>  </p></div>
\r
849 <div class="paragraph"><p><a href="#p_literal">LIT</a>  
\r
850 <a href="#p_literal_string">LIT-STRING</a>  
\r
851 <a href="#p_load_buffer_size">LOAD-BUFFER-SIZE</a>  
\r
852 <a href="#p_load_file">LOAD-FILE</a>  </p></div>
\r
853 <div class="paragraph"><p><a href="#p_args">MAIN-ARGS</a>  
\r
854 <a href="#p_malloc">MALLOC</a>  </p></div>
\r
855 <div class="paragraph"><p><a href="#p_negate">NEGATE</a>  
\r
856 <a href="#p_nip">NIP</a>  
\r
857 <a href="#p_nl">NL</a>  
\r
858 <a href="#p_not">NOT</a>  
\r
859 <a href="#p_number">NUMBER</a>  </p></div>
\r
860 <div class="paragraph"><p><a href="#p_open_file">OPEN-FILE</a>  
\r
861 <a href="#p_or">OR</a>  
\r
862 <a href="#p_over">OVER</a>  </p></div>
\r
863 <div class="paragraph"><p><a href="#p_pad">PAD</a>  
\r
864 <a href="#p_pick">PICK</a>  
\r
865 <a href="#p_program_version">PROGRAM_VERSION</a>  </p></div>
\r
866 <div class="paragraph"><p><a href="#p_quit">QUIT</a>  </p></div>
\r
867 <div class="paragraph"><p><a href="#p_read_stream_char">READ-STREAM-CHAR</a>  
\r
868 <a href="#p_read_stream_char">READ-STREAM-LINE</a>  
\r
869 <a href="#p_read_word">READ-WORD</a>  
\r
870 <a href="#p_realloc">REALLOC</a>  
\r
871 <a href="#p_return">RETURN</a>  
\r
872 <a href="#p_roll">ROLL</a>  
\r
873 <a href="#p_rot">ROT</a>  
\r
874 <a href="#p_rbp">RSP</a>  </p></div>
\r
875 <div class="paragraph"><p><a href="#p_sp">SP</a>  
\r
876 <a href="#p_state">STATE</a>  
\r
877 <a href="#p_stdin">STDIN</a>  
\r
878 <a href="#p_stream">STREAM</a>  
\r
879 <a href="#p_stream_nchars">STREAM-NCHARS</a>  
\r
880 <a href="#p_str2temp">STR>TEMP</a>  
\r
881 <a href="#p_strlen">STRLEN</a>  
\r
882 <a href="#p_strncmp">STRNCMP</a>  
\r
883 <a href="#p_strncpy">STRNCPY</a>  
\r
884 <a href="#p_swap">SWAP</a>  
\r
885 <a href="#p_system">SYSTEM</a>  </p></div>
\r
886 <div class="paragraph"><p><a href="#p_tell">TELL</a>  
\r
887 <a href="#p_dot_temp">.TEMP</a>  
\r
888 <a href="#p_temp.adoc">TEMP</a>  
\r
889 <a href="#p_tempheld.adoc">TEMPHELD</a>  
\r
890 <a href="#p_tempspace">TEMPSPACE</a>  
\r
891 <a href="#p_terminate0">TERMINATE0</a>  
\r
892 <a href="#p_tfa2cfa">TFA>CFA</a>  
\r
893 <a href="#p_tfa2dfa">TFA>DFA</a>  
\r
894 <a href="#p_tfa2flags_get">TFA>FLAGS@</a>  
\r
895 <a href="#p_tfa2namez">TFA>NAMEZ</a>  
\r
896 <a href="#p_then">THEN</a>  
\r
897 <a href="#p_this_word">THIS-WORD</a>  
\r
898 <a href="#p_true">TRUE</a>  
\r
899 <a href="#p_tuck">TUCK</a>  </p></div>
\r
900 <div class="paragraph"><p><a href="#p_unstream">UNSTREAM</a>  
\r
901 <a href="#p_use">USE</a>  </p></div>
\r
902 <div class="paragraph"><p><a href="#p_verboseQ">VERBOSE?</a>  </p></div>
\r
903 <div class="paragraph"><p><a href="#p_within">WITHIN</a>  
\r
904 <a href="#p_words">WORDS</a>  </p></div>
\r
905 <div class="paragraph"><p><a href="#p_xor">XOR</a>  </p></div>
\r
906 <div class="paragraph"><p><a href="#p_calltrace">[calltrace]</a>  
\r
907 <a href="#p_setup_signals">[setup_signals]</a>  </p></div>
\r
910 <div class="sect1">
\r
911 <h2 id="_word_descriptions">Word Descriptions</h2>
\r
912 <div class="sectionbody">
\r
913 <div class="paragraph"><p><a id="inline_code"></a></p></div>
\r
914 <div class="sect2">
\r
915 <h3 id="_word_asm">Word: [ASM]</h3>
\r
916 <div class="literalblock">
\r
917 <div class="content">
\r
918 <pre><code>data stack: ( -- )</code></pre>
\r
920 <div class="paragraph"><p>"[ASM]" is a function word that introduces inline assembly in an
\r
921 RRQFORTH definition. Such assembly code may return to subsequence
\r
922 RRQFORTH executon by means of the following instruction sequence:</p></div>
\r
923 <div class="exampleblock">
\r
924 <div class="content">
\r
925 <div class="listingblock">
\r
926 <div class="content">
\r
927 <pre><code> mov rsi,forthcode
\r
930 forthcode:</code></pre>
\r
933 <div class="paragraph"><p>Note that the FORTH compiler does not invoke an assembler so any
\r
934 inline assembly code must be provided in its binary form.</p></div>
\r
935 <div style="text-align:center">
\r
936 _______________________________________________________
\r
938 <div class="paragraph"><p><a id="p_0branch"></a></p></div>
\r
940 <div class="sect2">
\r
941 <h3 id="_word_0branch">Word: 0BRANCH</h3>
\r
942 <div class="literalblock">
\r
943 <div class="content">
\r
944 <pre><code>Data stack: ( v -- )</code></pre>
\r
946 <div class="paragraph"><p>"0BRANCH" is a function word that implements execution conditional by
\r
947 means of optionally adding the subsequent branch offset, or not, to
\r
948 the point of execution. If the value, v, is 0 then the branch offset
\r
949 is added, and otherwise execution continues with the cell following
\r
950 the branch offset in the definition.</p></div>
\r
951 <div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a
\r
952 definition take up a cell of 8 bytes. The offset is relative to the
\r
953 cell address immediately subsequent to the offset cell. In other
\r
954 words, offset 0 is not branching anywhere and an offset of -16 would
\r
955 make a tight loop back to the branch instruction itself. The latter
\r
956 would pull data stack values until and including the first non-zero
\r
958 <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
959 <a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>
\r
960 <div style="text-align:center">
\r
961 _______________________________________________________
\r
963 <div class="paragraph"><p><a id="p_0equal"></a></p></div>
\r
965 <div class="sect2">
\r
966 <h3 id="_word_0">Word: 0=</h3>
\r
967 <div class="literalblock">
\r
968 <div class="content">
\r
969 <pre><code>Data stack: ( v -- 0/-1 )</code></pre>
\r
971 <div class="paragraph"><p>"0=" is a function word that replaces a value with its logical
\r
972 complement; the result is zero if the value non-zero, and the result
\r
973 is non-zero if the value is zero.</p></div>
\r
974 <div class="paragraph"><p>This is the same function as <a href="#p_not">NOT</a>.</p></div>
\r
975 <div style="text-align:center">
\r
976 _______________________________________________________
\r
978 <div class="paragraph"><p><a id="p_0less"></a></p></div>
\r
980 <div class="sect2">
\r
981 <h3 id="_word_0_lt">Word: 0<</h3>
\r
982 <div class="literalblock">
\r
983 <div class="content">
\r
984 <pre><code>Data stack: ( v -- 0/-1 )</code></pre>
\r
986 <div class="paragraph"><p>"0<" is a function word that replaces a value with -1 if the value is
\r
987 less than 0, and 0 otherwise.</p></div>
\r
988 <div class="exampleblock">
\r
989 <div class="content">
\r
990 <div class="sidebarblock">
\r
991 <div class="content">
\r
992 <div class="title">Definition concept for 0<</div>
\r
993 <div class="paragraph"><p>( v — 0/1 ) : 0= 0 SWAP < ;</p></div>
\r
996 <div class="paragraph"><p>See also <a href="#p_swap">SWAP</a> and <a href="#p_lessthan"><</a>.</p></div>
\r
997 <div style="text-align:center">
\r
998 _______________________________________________________
\r
1000 <div class="paragraph"><p><a id="p_1branch"></a></p></div>
\r
1002 <div class="sect2">
\r
1003 <h3 id="_word_1branch">Word: 1BRANCH</h3>
\r
1004 <div class="literalblock">
\r
1005 <div class="content">
\r
1006 <pre><code>Data stack: ( v -- )</code></pre>
\r
1008 <div class="paragraph"><p>"1BRANCH" is a function word that implements execution conditional by
\r
1009 means of optionally adding the subsequent branch offset, or not, to
\r
1010 the point of execution. If the value, v, is non-zero then the branch
\r
1011 offset is added, and otherwise execution continues with the cell
\r
1012 following the branch offset in the definition.</p></div>
\r
1013 <div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a
\r
1014 definition take up a cell of 8 bytes. The offset is relative to the
\r
1015 cell address immediately subsequent to the offset cell. In other
\r
1016 words, offset 0 is not branching anywhere and an offset of -16 would
\r
1017 make a tight loop back to the branch instruction itself. The latter
\r
1018 would pull data stack values until and including the first zero value.</p></div>
\r
1019 <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
1020 <a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>
\r
1021 <div style="text-align:center">
\r
1022 _______________________________________________________
\r
1024 <div class="paragraph"><p><a id="p_2drop"></a></p></div>
\r
1026 <div class="sect2">
\r
1027 <h3 id="_word_2drop">Word: 2DROP</h3>
\r
1028 <div class="literalblock">
\r
1029 <div class="content">
\r
1030 <pre><code>Data stack: ( v1 v2 -- )</code></pre>
\r
1032 <div class="paragraph"><p>"2DROP" is a function word that plainly discards the top 2 cells from
\r
1033 the data stack.</p></div>
\r
1034 <div style="text-align:center">
\r
1035 _______________________________________________________
\r
1037 <div class="paragraph"><p><a id="p_2dup"></a></p></div>
\r
1039 <div class="sect2">
\r
1040 <h3 id="_word_2dup">Word: 2DUP</h3>
\r
1041 <div class="literalblock">
\r
1042 <div class="content">
\r
1043 <pre><code>Data stack: ( v1 v2 -- v1 v2 v1 v2 )</code></pre>
\r
1045 <div class="paragraph"><p>"2DUP" is a function word that duplicates the top 2 cells on the data
\r
1047 <div class="exampleblock">
\r
1048 <div class="content">
\r
1049 <div class="sidebarblock">
\r
1050 <div class="content">
\r
1051 <div class="title">Definition concept for 2DUP</div>
\r
1052 <div class="paragraph"><p>( v1 v2 — v1 v2 v1 v2 ) : 2DUP OVER OVER ;</p></div>
\r
1055 <div style="text-align:center">
\r
1056 _______________________________________________________
\r
1058 <div class="paragraph"><p><a id="p_2get"></a></p></div>
\r
1060 <div class="sect2">
\r
1061 <h3 id="_word_2">Word: 2@</h3>
\r
1062 <div class="literalblock">
\r
1063 <div class="content">
\r
1064 <pre><code>Data stack: ( a -- v2 v1 )</code></pre>
\r
1066 <div class="paragraph"><p>"2@" is a function word that pushes the two concecutive values v1 and
\r
1067 v2 from the address a onto the data stack. Value v1 is from address a
\r
1068 and value v2 is from address a + 8.</p></div>
\r
1069 <div style="text-align:center">
\r
1070 _______________________________________________________
\r
1072 <div class="paragraph"><p><a id="p_2over"></a></p></div>
\r
1074 <div class="sect2">
\r
1075 <h3 id="_word_2over">Word: 2OVER</h3>
\r
1076 <div class="literalblock">
\r
1077 <div class="content">
\r
1078 <pre><code>Data stack: ( v1 v2 v3 v4 -- v1 v2 v3 v4 v1 v2 )</code></pre>
\r
1080 <div class="paragraph"><p>"2OVER" is a function word that replicates the second duble-cell pair
\r
1081 onto the top of the data stack. This is similar to <a href="#p_over">OVER</a> but
\r
1082 working with cell pairs rather than single cells.</p></div>
\r
1083 <div class="exampleblock">
\r
1084 <div class="content">
\r
1085 <div class="sidebarblock">
\r
1086 <div class="content">
\r
1087 <div class="title">Definition concept for 2OVER</div>
\r
1088 <div class="paragraph"><p>( v1 v2 v3 v4 — v1 v2 v3 v4 v1 v2 ) : 2OVER 3 PICK 3 PICK ;</p></div>
\r
1091 <div style="text-align:center">
\r
1092 _______________________________________________________
\r
1094 <div class="paragraph"><p><a id="p_2put"></a></p></div>
\r
1096 <div class="sect2">
\r
1097 <h3 id="_word_2_2">Word: 2!</h3>
\r
1098 <div class="literalblock">
\r
1099 <div class="content">
\r
1100 <pre><code>Data stack: ( v2 v1 a -- )</code></pre>
\r
1102 <div class="paragraph"><p>"2!" is a function word that stors two concecutive values v1 and v2 to
\r
1103 the address a from the data stack. Value v1 is stored at address a and
\r
1104 value v2 is stored at address a + 8.</p></div>
\r
1105 <div style="text-align:center">
\r
1106 _______________________________________________________
\r
1108 <div class="paragraph"><p><a id="p_2swap"></a></p></div>
\r
1110 <div class="sect2">
\r
1111 <h3 id="_word_2swap">Word: 2SWAP</h3>
\r
1112 <div class="literalblock">
\r
1113 <div class="content">
\r
1114 <pre><code>Data stack: ( v1 v2 v3 v4 -- v3 v4 v1 v2 )</code></pre>
\r
1116 <div class="paragraph"><p>"2SWAP" is a function word the reorgnizes the top 4 cells swappping
\r
1117 the upper and lower pair. This is similar to <a href="#p_swap">SWAP</a> but
\r
1118 working with cell pairs rather than single cells.</p></div>
\r
1119 <div class="exampleblock">
\r
1120 <div class="content">
\r
1121 <div class="sidebarblock">
\r
1122 <div class="content">
\r
1123 <div class="title">Definition concept for 2SWAP</div>
\r
1124 <div class="paragraph"><p>( v1 v2 v3 v4 — v3 v4 v1 v2 ) : 2SWAP 3 ROLL 3 ROLL ;</p></div>
\r
1127 <div style="text-align:center">
\r
1128 _______________________________________________________
\r
1130 <div class="paragraph"><p><a id="p_Ccomma"></a></p></div>
\r
1132 <div class="sect2">
\r
1133 <h3 id="_word_c">Word: C,</h3>
\r
1134 <div class="literalblock">
\r
1135 <div class="content">
\r
1136 <pre><code>Data stack: ( v -- )</code></pre>
\r
1138 <div class="paragraph"><p>"C," (C-comma) is a function word that puts a byte on the
\r
1139 <a href="#p_here">HERE</a> heap. The least significant byte of the value is put
\r
1140 at the current free head address, which also is incremented.</p></div>
\r
1141 <div class="exampleblock">
\r
1142 <div class="content">
\r
1143 <div class="sidebarblock">
\r
1144 <div class="content">
\r
1145 <div class="title">Definition concept for C,</div>
\r
1146 <div class="paragraph"><p>: C, HERE @ 1 ALLOT C! ; ( v — ; Claim 1 byte and put lsb value there )</p></div>
\r
1149 <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
1150 <a href="#p_allot">ALLOT</a>, <a href="#p_Cput">C!</a> and <a href="#p_semicolon">;</a>.</p></div>
\r
1151 <div style="text-align:center">
\r
1152 _______________________________________________________
\r
1154 <div class="paragraph"><p><a id="p_Wcomma"></a></p></div>
\r
1156 <div class="sect2">
\r
1157 <h3 id="_word_w">Word: W,</h3>
\r
1158 <div class="literalblock">
\r
1159 <div class="content">
\r
1160 <pre><code>Data stack: ( v -- )</code></pre>
\r
1162 <div class="paragraph"><p>"W," (W-comma) is a function word that puts a "word" (double-byte) on
\r
1163 the <a href="#p_here">HERE</a> heap. The two least significant bytes of the value
\r
1164 are put at the current free head address, which also is incremented
\r
1165 accordingly.</p></div>
\r
1166 <div class="exampleblock">
\r
1167 <div class="content">
\r
1168 <div class="sidebarblock">
\r
1169 <div class="content">
\r
1170 <div class="title">Definition concept for W,</div>
\r
1171 <div class="paragraph"><p>: W, HERE @ 2 ALLOT W! ;</p></div>
\r
1174 <div style="text-align:center">
\r
1175 _______________________________________________________
\r
1177 <div class="paragraph"><p><a id="p_Dcomma"></a></p></div>
\r
1179 <div class="sect2">
\r
1180 <h3 id="_word_d">Word: D,</h3>
\r
1181 <div class="literalblock">
\r
1182 <div class="content">
\r
1183 <pre><code>Data stack: ( v -- )</code></pre>
\r
1185 <div class="paragraph"><p>"D," (D-comma) is a function word that puts a "double word"
\r
1186 (double-byte) on the <a href="#p_here">HERE</a> heap. The four least significant
\r
1187 bytes of the value are put at the current free head address, which
\r
1188 also is incremented accordingly.</p></div>
\r
1189 <div class="exampleblock">
\r
1190 <div class="content">
\r
1191 <div class="sidebarblock">
\r
1192 <div class="content">
\r
1193 <div class="title">Definition concept for D,</div>
\r
1194 <div class="paragraph"><p>: D, HERE @ 4 ALLOT D! ;</p></div>
\r
1197 <div style="text-align:center">
\r
1198 _______________________________________________________
\r
1200 <div class="paragraph"><p><a id="p_dsp"></a></p></div>
\r
1202 <div class="sect2">
\r
1203 <h3 id="_word_d_n">Word: D[n]</h3>
\r
1204 <div class="literalblock">
\r
1205 <div class="content">
\r
1206 <pre><code>Data stack: ( n -- a )</code></pre>
\r
1208 <div class="paragraph"><p>"D[n]" is a function word that pushes the address for the n:th cell of
\r
1209 the data stack onto the data stack.</p></div>
\r
1210 <div style="text-align:center">
\r
1211 _______________________________________________________
\r
1213 <div class="paragraph"><p><a id="p_cfa2tfa"></a></p></div>
\r
1215 <div class="sect2">
\r
1216 <h3 id="_word_cfa_gt_tfa">Word: CFA>TFA</h3>
\r
1217 <div class="literalblock">
\r
1218 <div class="content">
\r
1219 <pre><code>Data stack: ( cfa -- tfa )</code></pre>
\r
1221 <div class="paragraph"><p>"CFA>TFA" is a function word that pushes word tfa of the given cfa.</p></div>
\r
1222 <div class="exampleblock">
\r
1223 <div class="content">
\r
1224 <div class="sidebarblock">
\r
1225 <div class="content">
\r
1226 <div class="title">Definition concept for CFA>TFA</div>
\r
1227 <div class="paragraph"><p>: CFA>TFA 14 - @ ;</p></div>
\r
1230 <div style="text-align:center">
\r
1231 _______________________________________________________
\r
1233 <div class="paragraph"><p><a id="p_Cget"></a></p></div>
\r
1235 <div class="sect2">
\r
1236 <h3 id="_word_c_2">Word: C@</h3>
\r
1237 <div class="literalblock">
\r
1238 <div class="content">
\r
1239 <pre><code>Data stack: ( a -- v )</code></pre>
\r
1241 <div class="paragraph"><p>"C@" is a function word that pushes the byte value v from the address a.</p></div>
\r
1242 <div style="text-align:center">
\r
1243 _______________________________________________________
\r
1245 <div class="paragraph"><p><a id="p_Wget"></a></p></div>
\r
1247 <div class="sect2">
\r
1248 <h3 id="_word_w_2">Word: W@</h3>
\r
1249 <div class="literalblock">
\r
1250 <div class="content">
\r
1251 <pre><code>Data stack: ( a -- v )</code></pre>
\r
1253 <div class="paragraph"><p>"W@" is a function word that pushes the "word" (double-byte) value v
\r
1254 from the address a.</p></div>
\r
1255 <div style="text-align:center">
\r
1256 _______________________________________________________
\r
1258 <div class="paragraph"><p><a id="p_Rget"></a></p></div>
\r
1260 <div class="sect2">
\r
1261 <h3 id="_word_r">Word: R@</h3>
\r
1262 <div class="literalblock">
\r
1263 <div class="content">
\r
1264 <pre><code>Data stack: ( -- v ) Return stack: ( v -- v )</code></pre>
\r
1266 <div class="paragraph"><p>"R@" is a function word that "copies" the top return stack value onto
\r
1267 the data stack.</p></div>
\r
1268 <div style="text-align:center">
\r
1269 _______________________________________________________
\r
1271 <div class="paragraph"><p><a id="p_Cput"></a></p></div>
\r
1273 <div class="sect2">
\r
1274 <h3 id="_word_c_3">Word: C!</h3>
\r
1275 <div class="literalblock">
\r
1276 <div class="content">
\r
1277 <pre><code>Data stack: ( v a -- )</code></pre>
\r
1279 <div class="paragraph"><p>"C!" is a function word that stores the byte value v (the least
\r
1280 significant byte of the cell) at the address a.</p></div>
\r
1281 <div style="text-align:center">
\r
1282 _______________________________________________________
\r
1284 <div class="paragraph"><p><a id="p_Wput"></a></p></div>
\r
1286 <div class="sect2">
\r
1287 <h3 id="_word_w_3">Word: W!</h3>
\r
1288 <div class="literalblock">
\r
1289 <div class="content">
\r
1290 <pre><code>Data stack: ( v a -- )</code></pre>
\r
1292 <div class="paragraph"><p>"W!" is a function word that stores the "word" (2-byte) value v (the
\r
1293 two least significant bytes of the cell) at the address a.</p></div>
\r
1294 <div style="text-align:center">
\r
1295 _______________________________________________________
\r
1297 <div class="paragraph"><p><a id="p_Dput"></a></p></div>
\r
1299 <div class="sect2">
\r
1300 <h3 id="_word_d_2">Word: D!</h3>
\r
1301 <div class="literalblock">
\r
1302 <div class="content">
\r
1303 <pre><code>Data stack: ( v a -- )</code></pre>
\r
1305 <div class="paragraph"><p>"D!" is a function word that stores the "doublw word" (4-byte) value v
\r
1306 (the four least significant bytes of the cell) at the address a.</p></div>
\r
1307 <div style="text-align:center">
\r
1308 _______________________________________________________
\r
1310 <div class="paragraph"><p><a id="p_Rget"></a></p></div>
\r
1312 <div class="sect2">
\r
1313 <h3 id="_word_r_2">Word: R@</h3>
\r
1314 <div class="literalblock">
\r
1315 <div class="content">
\r
1316 <pre><code>Data stack: ( -- v ) Return stack: ( v -- v )</code></pre>
\r
1318 <div class="paragraph"><p>"R@" is a function word that "copies" the top return stack value onto
\r
1319 the data stack.</p></div>
\r
1320 <div style="text-align:center">
\r
1321 _______________________________________________________
\r
1323 <div class="paragraph"><p><a id="p_Rgt"></a></p></div>
\r
1325 <div class="sect2">
\r
1326 <h3 id="_word_r_gt">Word: R></h3>
\r
1327 <div class="literalblock">
\r
1328 <div class="content">
\r
1329 <pre><code>Data stack: ( -- v ) Return stack: ( v -- )</code></pre>
\r
1331 <div class="paragraph"><p>"R>" is a function word that "moves" the top return stack value onto
\r
1332 the data stack.</p></div>
\r
1333 <div style="text-align:center">
\r
1334 _______________________________________________________
\r
1336 <div class="paragraph"><p><a id="p_abs"></a></p></div>
\r
1338 <div class="sect2">
\r
1339 <h3 id="_word_abs">Word: ABS</h3>
\r
1340 <div class="literalblock">
\r
1341 <div class="content">
\r
1342 <pre><code>Data stack: ( v1 -- v2 )</code></pre>
\r
1344 <div class="paragraph"><p>"ABS" is a function word that replaces a value with its absolute
\r
1345 value. To that end, the values are 64-bit signed integers.</p></div>
\r
1346 <div style="text-align:center">
\r
1347 _______________________________________________________
\r
1349 <div class="paragraph"><p><a id="p_again"></a></p></div>
\r
1351 <div class="sect2">
\r
1352 <h3 id="_word_again">Word: AGAIN</h3>
\r
1353 <div class="literalblock">
\r
1354 <div class="content">
\r
1355 <pre><code>Data stack: Compiling: ( -- a )</code></pre>
\r
1357 <div class="paragraph"><p>"AGAIN" is an immediate function word that is used together with
\r
1358 <a href="#p_begin">BEGIN</a> and instead of <a href="#p_end">END</a> to implement structured
\r
1359 execution control. AGAIN scans the datastack for the nearest preceding
\r
1360 BEGIN marker and lays out an unconditional branch from this point the
\r
1361 beginning of the block during execution. It thereafter performs the
\r
1362 <a href="#p_end">END</a> compile action to end the block.</p></div>
\r
1363 <div style="text-align:center">
\r
1364 _______________________________________________________
\r
1366 <div class="paragraph"><p><a id="p_allot"></a></p></div>
\r
1368 <div class="sect2">
\r
1369 <h3 id="_word_allot">Word: ALLOT</h3>
\r
1370 <div class="literalblock">
\r
1371 <div class="content">
\r
1372 <pre><code>Data stack: ( n -- )</code></pre>
\r
1374 <div class="paragraph"><p>"ALLOT" is a function word that merely increments the <a href="#p_here">HERE</a>
\r
1375 variable with <code>n</code> so as to claim that amount of the heap.</p></div>
\r
1376 <div class="exampleblock">
\r
1377 <div class="content">
\r
1378 <div class="sidebarblock">
\r
1379 <div class="content">
\r
1380 <div class="title">Defintion concept for ALLOT</div>
\r
1381 <div class="paragraph"><p>( n — ) : ALLOT HERE @ + HERE ! ;</p></div>
\r
1384 <div class="exampleblock">
\r
1385 <div class="content">
\r
1386 <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
1388 <div style="text-align:center">
\r
1389 _______________________________________________________
\r
1391 <div class="paragraph"><p><a id="p_and"></a></p></div>
\r
1393 <div class="sect2">
\r
1394 <h3 id="_word_and">Word: AND</h3>
\r
1395 <div class="literalblock">
\r
1396 <div class="content">
\r
1397 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>
\r
1399 <div class="paragraph"><p>"AND" is a function word that replaces a value pair with their bitwise
\r
1400 conjunction; each bit is 1 if the corresponding bits of both operands
\r
1401 are 1 and 0 if not.</p></div>
\r
1402 <div style="text-align:center">
\r
1403 _______________________________________________________
\r
1405 <div class="paragraph"><p><a id="p_args"></a></p></div>
\r
1407 <div class="sect2">
\r
1408 <h3 id="_word_main_args">Word: MAIN-ARGS</h3>
\r
1409 <div class="literalblock">
\r
1410 <div class="content">
\r
1411 <pre><code>Data stack: ( -- p[argv** argc] )</code></pre>
\r
1413 <div class="paragraph"><p>"ARGS" is a value word that holds a pointer to the command line data
\r
1414 block which consists of a count cell followed by that many asciiz
\r
1415 pointers and then a 0 cell. That is next followed by the environment
\r
1416 as a number of asciiz pointers and a 0 cell.</p></div>
\r
1417 <div class="exampleblock">
\r
1418 <div class="content">
\r
1419 <div class="listingblock">
\r
1420 <div class="title">Usage example 2: the command line argument block</div>
\r
1421 <div class="content">
\r
1422 <pre><code>ARGS -> 8 bytes: count of non-zero asciiz pointers following
\r
1423 8 bytes: command name string
\r
1424 8* bytes: argument strings
\r
1425 8 bytes: zero cell
\r
1426 8* bytes: envirnment strings
\r
1427 8 bytes: zero cell</code></pre>
\r
1430 <div style="text-align:center">
\r
1431 _______________________________________________________
\r
1433 <div class="paragraph"><p><a id="p_base"></a></p></div>
\r
1435 <div class="sect2">
\r
1436 <h3 id="_word_base">Word: BASE</h3>
\r
1437 <div class="literalblock">
\r
1438 <div class="content">
\r
1439 <pre><code>Data stack: ( -- a )</code></pre>
\r
1441 <div class="paragraph"><p>"BASE" is a variable word for the numerical base used by input and
\r
1442 output functions, <a href="#p_number">NUMBER</a> and <a href="#p_dot">[p_dot]</a>, when
\r
1443 translating numbers between cell value form and text form. The
\r
1444 numerical base is set to 10 or 16 by <a href="#p_decimal">DECIMAL</a> and
\r
1445 <a href="#p_hex">HEX</a> respectively, and those are the only two bases currently
\r
1446 supported.</p></div>
\r
1447 <div class="paragraph"><p>See also <a href="#p_digits">DIGITS</a>, which holds the mapping table from
\r
1448 digits to text.</p></div>
\r
1449 <div style="text-align:center">
\r
1450 _______________________________________________________
\r
1452 <div class="paragraph"><p><a id="p_begin"></a></p></div>
\r
1454 <div class="sect2">
\r
1455 <h3 id="_word_begin">Word: BEGIN</h3>
\r
1456 <div class="literalblock">
\r
1457 <div class="content">
\r
1458 <pre><code>Data stack: Compiling: ( -- a 0 )</code></pre>
\r
1460 <div class="paragraph"><p>"BEGIN" is an immediate function word that is used together with
\r
1461 <a href="#p_ifbreak">IFBREAK</a>, <a href="#p_ifagain">IFAGAIN</a> and <a href="#p_end">END</a> to
\r
1462 implement structured execution control. BEGIN simply places the
\r
1463 address for resolving branches back to this point during execution,
\r
1464 and then a 0 as a marker so as to allow for an unknown number of block
\r
1465 exit points.</p></div>
\r
1466 <div class="exampleblock">
\r
1467 <div class="content">
\r
1468 <div class="listingblock">
\r
1469 <div class="title">Usage example 3:</div>
\r
1470 <div class="content">
\r
1471 <pre><code>: WTELL ( tfa -- ; Print word pname )
\r
1472 24 + DUP 8 + SWAP @ TELL SP EMIT
\r
1475 : WORDS ( wordlist -- ; Print all words of word list )
\r
1485 <div style="text-align:center">
\r
1486 _______________________________________________________
\r
1488 <div class="paragraph"><p><a id="p_bracketed_quote"></a></p></div>
\r
1490 <div class="sect2">
\r
1491 <h3 id="_word">Word: [']</h3>
\r
1492 <div class="literalblock">
\r
1493 <div class="content">
\r
1494 <pre><code>Data stack: ( -- cfa ) Input stream: word</code></pre>
\r
1496 <div class="paragraph"><p>"[']" is an immediate function word that reads the next word on the
\r
1497 input stream and pushes its cfa.</p></div>
\r
1498 <div class="exampleblock">
\r
1499 <div class="content">
\r
1500 <div class="sidebarblock">
\r
1501 <div class="content">
\r
1502 <div class="title">Definition concept for [']</div>
\r
1503 <div class="paragraph"><p>: ['] IMMEDIATE ' ;</p></div>
\r
1506 <div style="text-align:center">
\r
1507 _______________________________________________________
\r
1509 <div class="paragraph"><p><a id="p_branch"></a></p></div>
\r
1511 <div class="sect2">
\r
1512 <h3 id="_word_branch">Word: BRANCH</h3>
\r
1513 <div class="literalblock">
\r
1514 <div class="content">
\r
1515 <pre><code>Data stack: ( -- )</code></pre>
\r
1517 <div class="paragraph"><p>"BRANCH" is a function word that implements execution transfer by
\r
1518 means of adding the subsequent branch offset to the point of
\r
1519 execution.</p></div>
\r
1520 <div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a
\r
1521 definition take up a cell of 8 bytes. The offset is relative to the
\r
1522 cell address immediately subsequent to the offset cell. In other
\r
1523 words, offset 0 is not branching anywhere and an offset of -16 would
\r
1524 make a tight loop back to the branch instruction itself. The latter
\r
1525 would pull data stack values until and including the first zero value.</p></div>
\r
1526 <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
1527 <a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>
\r
1528 <div style="text-align:center">
\r
1529 _______________________________________________________
\r
1531 <div class="paragraph"><p><a id="p_break"></a></p></div>
\r
1533 <div class="sect2">
\r
1534 <h3 id="_word_break">Word: BREAK</h3>
\r
1535 <div class="paragraph"><p>"BREAK" is an immediate function word that lays out an unconditional
\r
1536 branch out of an enclosing xef:p_begin[BEGIN]-<a href="#p_end">END</a> block.
\r
1537 Similar to <a href="#p_ifbreak">IFBREAK</a> it lays out the branch cell
\r
1538 followed by a reserved cell for the branch offset, and inserts the
\r
1539 resolution address just above the required 0 on the data stack.</p></div>
\r
1540 <div class="exampleblock">
\r
1541 <div class="content">
\r
1542 <div class="listingblock">
\r
1543 <div class="title">Usage example 4: unconditional break with a condition.</div>
\r
1544 <div class="content">
\r
1545 <pre><code>: WTELL ( tfa -- ; Print word pname )
\r
1546 24 + DUP 8 + SWAP @ TELL SP EMIT
\r
1549 : WORDS ( wordlist -- ; Print all words of word list )
\r
1551 @ DUP IF DUP WTELL ELSE BREAK THEN
\r
1559 <div class="paragraph"><p>See also <a href="#p_branch">BRANCH</a>, <a href="#p_0branch">0BRANCH</a>,
\r
1560 <a href="#p_1branch">1BRANCH</a>, <a href="#p_if">IF</a>, <a href="#p_else">ELSE</a>,
\r
1561 <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>
\r
1562 <div style="text-align:center">
\r
1563 _______________________________________________________
\r
1565 <div class="paragraph"><p><a id="p_calltrace"></a></p></div>
\r
1567 <div class="sect2">
\r
1568 <h3 id="_word_calltrace">Word: [calltrace]</h3>
\r
1569 <div class="paragraph"><p>"[calltrace]" is a variable word that ccontains a small assembly
\r
1570 snippet that may be used for debugging when running under <code>gdb</code>.</p></div>
\r
1571 <div style="text-align:center">
\r
1572 _______________________________________________________
\r
1574 <div class="paragraph"><p><a id="p_cfa2flags_get"></a></p></div>
\r
1576 <div class="sect2">
\r
1577 <h3 id="_word_cfa_gt_flags">Word: CFA>FLAGS@</h3>
\r
1578 <div class="literalblock">
\r
1579 <div class="content">
\r
1580 <pre><code>Data stack: ( cfa -- flags )</code></pre>
\r
1582 <div class="paragraph"><p>"CFA>FLAGS@" is a function word that pushes word flags of the given cfa.</p></div>
\r
1583 <div class="exampleblock">
\r
1584 <div class="content">
\r
1585 <div class="sidebarblock">
\r
1586 <div class="content">
\r
1587 <div class="title">Defintion concept for CFA>FLAGS@</div>
\r
1588 <div class="paragraph"><p>: CFA>FLAGS@ 16 - @ 16 + ;</p></div>
\r
1591 <div style="text-align:center">
\r
1592 _______________________________________________________
\r
1594 <div class="paragraph"><p><a id="p_clear_stream"></a></p></div>
\r
1596 <div class="sect2">
\r
1597 <h3 id="_word_clear_stream">Word: CLEAR-STREAM</h3>
\r
1598 <div class="literalblock">
\r
1599 <div class="content">
\r
1600 <pre><code>Data stack: ( stream -- )</code></pre>
\r
1602 <div class="paragraph"><p>"CLEAR-STREAM" is a function word that discards whatever is currently
\r
1603 remaining in the buffer for the stream, so that a subsequent read will
\r
1604 pull in more data from its source.</p></div>
\r
1605 <div class="paragraph"><p>See also <a href="#p_read_stream_char">READ-STREAM-CHAR</a>.</p></div>
\r
1606 <div style="text-align:center">
\r
1607 _______________________________________________________
\r
1609 <div class="paragraph"><p><a id="p_colon"></a></p></div>
\r
1611 <div class="sect2">
\r
1612 <h3 id="_word_3">Word: :</h3>
\r
1613 <div class="literalblock">
\r
1614 <div class="content">
\r
1615 <pre><code>Data stack: ( -- ) Input stream: word</code></pre>
\r
1617 <div class="paragraph"><p>":" (colon) is a function word that starts a new forth definition.
\r
1618 This includes reading the next word for making a new dictionary entry
\r
1619 and setting evaluation state to compiling mode.</p></div>
\r
1620 <div class="exampleblock">
\r
1621 <div class="content">
\r
1622 <div class="sidebarblock">
\r
1623 <div class="content">
\r
1624 <div class="title">Definition concept for :</div>
\r
1625 <div class="paragraph"><p>: : doFORTH READ-WORD CREATE TFA>CFA ! ] ;</p></div>
\r
1628 <div class="paragraph"><p>See also <a href="#p_doforth">doFORTH</a>, <a href="#p_read_word">READ-WORD</a>,
\r
1629 <a href="#p_create">CREATE</a>, <a href="#p_tfa2cfa">TFA>CFA</a>, <a href="#p_put">!</a>,
\r
1630 <a href="#p_left_bracket">]</a> and <a href="#p_semicolon">;</a>.</p></div>
\r
1631 <div style="text-align:center">
\r
1632 _______________________________________________________
\r
1634 <div class="paragraph"><p><a id="p_comma"></a></p></div>
\r
1636 <div class="sect2">
\r
1637 <h3 id="_word_4">Word: ,</h3>
\r
1638 <div class="literalblock">
\r
1639 <div class="content">
\r
1640 <pre><code>Data stack: ( v -- )</code></pre>
\r
1642 <div class="paragraph"><p>"," (comma) is a function word that puts a cell value on the
\r
1643 <a href="#p_here">HERE</a> heap.</p></div>
\r
1644 <div class="exampleblock">
\r
1645 <div class="content">
\r
1646 <div class="sidebarblock">
\r
1647 <div class="content">
\r
1648 <div class="title">Definition concept for ,</div>
\r
1649 <div class="paragraph"><p>: , HERE @ 8 ALLOT ! ; ( v — ; Claim 8 bytes and put value there )</p></div>
\r
1652 <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
1653 <a href="#p_allot">ALLOT</a>, <a href="#p_put">!</a> and <a href="#p_semicolon">;</a>.</p></div>
\r
1654 <div style="text-align:center">
\r
1655 _______________________________________________________
\r
1657 <div class="paragraph"><p><a id="p_create"></a></p></div>
\r
1659 <div class="sect2">
\r
1660 <h3 id="_word_create">Word: CREATE</h3>
\r
1661 <div class="literalblock">
\r
1662 <div class="content">
\r
1663 <pre><code>Data stack: ( char* n -- tfa )</code></pre>
\r
1665 <div class="paragraph"><p>"CREATE" is a function word that allocates a "word header" with the
\r
1666 indicated [n:char*] print name, and returns the "TFA" (Token Field
\r
1667 Address) of the word. The header memory layout is as follows:</p></div>
\r
1668 <div class="exampleblock">
\r
1669 <div class="content">
\r
1670 <div class="listingblock">
\r
1671 <div class="title">Layout 1: rrqforth word structure</div>
\r
1672 <div class="content">
\r
1673 <pre><code>struct WORD
\r
1674 TFA 8 link ; tfa of previous word
\r
1675 pCFA 8 cfap ; CFA = Code Field Address of this word
\r
1677 PFA 8 length ; length of pname representation
\r
1678 ? pname ; the pname bytes
\r
1679 1 nul ; a forced nul byte following the pname
\r
1680 pTFA 8 tfap ; TFA = Token Field Address of this word
\r
1681 OFF 8 doff ; entry offset for FORTH level execution
\r
1682 CFA 8 doer ; word execution semantics
\r
1683 DFA 0 content ; DFA = Data Field Address
\r
1684 end_struct</code></pre>
\r
1687 <div class="paragraph"><p>A "word" is generally understod as a marker in memory for some content
\r
1688 as held in the memory space following the DFA (Data Field Address).</p></div>
\r
1689 <div class="paragraph"><p>The words CFA (Code Field Address) is the most important field for
\r
1690 RRQFORTH execution, as holding a jump address to the assembly code
\r
1691 that implements the particular execution semantics for the word.
\r
1692 "CREATE" will assign this as "dovariable", which makes the word push
\r
1693 its DFA when executed. This is changed to "doforth" for RRQFORTH
\r
1694 function words initiated by ":" (aka "COLON") or changed to "dovalue"
\r
1695 for RRQFORTH constants created by "CONSTANT".</p></div>
\r
1696 <div class="exampleblock">
\r
1697 <div class="content">
\r
1698 <div class="sidebarblock">
\r
1699 <div class="content">
\r
1700 <div class="title">Definition concept for CREATE</div>
\r
1701 <div class="paragraph"><p>HERE @ R> ( save tfa on RS )
\r
1702 R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )
\r
1703 DUP 49 + R@ + , ( pCFA )
\r
1706 HERE @ ROT ROT MEMCPY 0 C, ( pname + NUL )
\r
1709 doVARIABLE ( CFA, default semantics )</p></div>
\r
1712 <div class="exampleblock">
\r
1713 <div class="content">
\r
1714 <div class="listingblock">
\r
1715 <div class="title">Usage example 5: a possible definition of CONSTANT</div>
\r
1716 <div class="content">
\r
1717 <pre><code>: CONSTANT READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! ! ;</code></pre>
\r
1720 <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
1721 <a href="#p_Ccomma">[p_Ccomma]</a>, <a href="#p_current_word">CURRENT-WORD</a>, <a href="#p_dup">DUP</a>,
\r
1722 <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
1723 and <a href="#p_dovariable">doVARIABLE</a>,
\r
1724 as well as <a href="#p_execute">EXECUTE</a>
\r
1725 about the range of "doer" assignments and their meanings.</p></div>
\r
1726 <div style="text-align:center">
\r
1727 _______________________________________________________
\r
1729 <div class="paragraph"><p><a id="p_current_wordlist"></a></p></div>
\r
1731 <div class="sect2">
\r
1732 <h3 id="_word_current_wordlist">Word: CURRENT-WORDLIST</h3>
\r
1733 <div class="literalblock">
\r
1734 <div class="content">
\r
1735 <pre><code>Data stack: ( -- a )</code></pre>
\r
1737 <div class="paragraph"><p>"CURRENT-WORDLIST" is a variable word that points out the DFA of the
\r
1738 current word list word for <a href="#p_find">FIND</a> to use finding words. The
\r
1739 word list word content is as follows:</p></div>
\r
1740 <div class="exampleblock">
\r
1741 <div class="content">
\r
1742 <div class="listingblock">
\r
1743 <div class="title">Layout 2: word list word content</div>
\r
1744 <div class="content">
\r
1745 <pre><code> 8 TFA of latest word in the word list
\r
1746 8 DFA of the/a subsequent word list to search through</code></pre>
\r
1749 <div class="paragraph"><p>Note that word lists are chained by "extension" and in general it ends
\r
1750 with the <a href="#p_forth">FORTH</a> word list. Initially the
\r
1751 <a href="#p_system">SYSTEM</a> word list is the only other word list.</p></div>
\r
1752 <div style="text-align:center">
\r
1753 _______________________________________________________
\r
1755 <div class="paragraph"><p><a id="data_stack"></a></p></div>
\r
1757 <div class="sect2">
\r
1758 <h3 id="_word_data_stack">Word: DATA-STACK</h3>
\r
1759 <div class="literalblock">
\r
1760 <div class="content">
\r
1761 <pre><code>Data stack: ( -- a )</code></pre>
\r
1763 <div class="paragraph"><p>"DATA-STACK" is a variable word that harbours the data stack.</p></div>
\r
1764 <div style="text-align:center">
\r
1765 _______________________________________________________
\r
1767 <div class="paragraph"><p><a id="p_decimal"></a></p></div>
\r
1769 <div class="sect2">
\r
1770 <h3 id="_word_decimal">Word: DECIMAL</h3>
\r
1771 <div class="literalblock">
\r
1772 <div class="content">
\r
1773 <pre><code>Data stack: ( -- )</code></pre>
\r
1775 <div class="paragraph"><p>"DECIMAL" is a function word that sets <a href="#p_base">BASE</a> to 10.</p></div>
\r
1776 <div class="exampleblock">
\r
1777 <div class="content">
\r
1778 <div class="sidebarblock">
\r
1779 <div class="content">
\r
1780 <div class="title">Definition concept for DECIMAL</div>
\r
1781 <div class="paragraph"><p>: DECIMAL 10 BASE ! ;</p></div>
\r
1784 <div style="text-align:center">
\r
1785 _______________________________________________________
\r
1787 <div class="paragraph"><p><a id="p_definitions"></a></p></div>
\r
1789 <div class="sect2">
\r
1790 <h3 id="_word_definitions">Word: DEFINITIONS</h3>
\r
1791 <div class="literalblock">
\r
1792 <div class="content">
\r
1793 <pre><code>Data stack: ( wordlist -- )</code></pre>
\r
1795 <div class="paragraph"><p>"DEFINITIONS" is a function word that installs the given wordlist as
\r
1796 the <a href="#p_current_wordlist">CURRENT-WORDLIST</a> one.</p></div>
\r
1797 <div class="exampleblock">
\r
1798 <div class="content">
\r
1799 <div class="sidebarblock">
\r
1800 <div class="content">
\r
1801 <div class="title">Definition concept for DEFINITIONS</div>
\r
1802 <div class="paragraph"><p>: DEFINITIONS CURRENT-WORDLIST ! ;</p></div>
\r
1805 <div style="text-align:center">
\r
1806 _______________________________________________________
\r
1808 <div class="paragraph"><p><a id="p_depth"></a></p></div>
\r
1810 <div class="sect2">
\r
1811 <h3 id="_word_depth">Word: DEPTH</h3>
\r
1812 <div class="literalblock">
\r
1813 <div class="content">
\r
1814 <pre><code>Data stack: ( -- v )</code></pre>
\r
1816 <div class="paragraph"><p>"DEPTH" is a function word that pushes the count of data stack cells
\r
1817 onto the data stack.</p></div>
\r
1818 <div style="text-align:center">
\r
1819 _______________________________________________________
\r
1821 <div class="paragraph"><p><a id="p_dfa2tfa"></a></p></div>
\r
1823 <div class="sect2">
\r
1824 <h3 id="_word_dfa_gt_tfa">Word: DFA>TFA</h3>
\r
1825 <div class="literalblock">
\r
1826 <div class="content">
\r
1827 <pre><code>Data stack: ( dfa -- tfa )</code></pre>
\r
1829 <div class="paragraph"><p>"DFA>TFA" is a function word that pushes word tfa of the given dfa.</p></div>
\r
1830 <div class="exampleblock">
\r
1831 <div class="content">
\r
1832 <div class="sidebarblock">
\r
1833 <div class="content">
\r
1834 <div class="title">Definition concept for DFA>TFA</div>
\r
1835 <div class="paragraph"><p>: DFA>TFA 24 - @ ;</p></div>
\r
1838 <div style="text-align:center">
\r
1839 _______________________________________________________
\r
1841 <div class="paragraph"><p><a id="p_digits"></a></p></div>
\r
1843 <div class="sect2">
\r
1844 <h3 id="_word_digits">Word: DIGITS</h3>
\r
1845 <div class="literalblock">
\r
1846 <div class="content">
\r
1847 <pre><code>Data stack: ( -- a )</code></pre>
\r
1849 <div class="paragraph"><p>"DIGITS" is a variable word that holds the character array for mapping
\r
1850 digit values to characters. It contains the 16 characters 0-9 and a-f.</p></div>
\r
1851 <div style="text-align:center">
\r
1852 _______________________________________________________
\r
1854 <div class="paragraph"><p><a id="p_div"></a></p></div>
\r
1856 <div class="sect2">
\r
1857 <h3 id="_word_5">Word: /</h3>
\r
1858 <div class="literalblock">
\r
1859 <div class="content">
\r
1860 <pre><code>Data stack: ( v1 v2 -- q )</code></pre>
\r
1862 <div class="paragraph"><p>"/" (div) is a function word that replaces a pair of values with the
\r
1863 results of signed integer division of the first, v1, divided by the
\r
1864 second, v2. To that end, the values are 64-bit signed integers. The
\r
1865 result is the integer quotient, q, and the discarded remainder, r,
\r
1866 where q and r are the respectively largest and smallest integers to
\r
1867 satisfy the formula:</p></div>
\r
1868 <div class="literalblock">
\r
1869 <div class="content">
\r
1870 <pre><code> v1 = q * v2 + r</code></pre>
\r
1872 <div style="text-align:center">
\r
1873 _______________________________________________________
\r
1875 <div class="paragraph"><p><a id="p_divmod"></a></p></div>
\r
1877 <div class="sect2">
\r
1878 <h3 id="_word_mod">Word: /MOD</h3>
\r
1879 <div class="literalblock">
\r
1880 <div class="content">
\r
1881 <pre><code>Data stack: ( v1 v2 -- q r )</code></pre>
\r
1883 <div class="paragraph"><p>"/MOD" (div-mod) is a function word that replaces a pair of values
\r
1884 with the results of signed integer division of the first, v1, divided
\r
1885 by the second, v2. To that end, the values are 64-bit signed integers.
\r
1886 The result is the integer quotient, q, and the remainder, r, where q
\r
1887 and r are the respectively largest and smallest integers to satisfy
\r
1888 the formula:</p></div>
\r
1889 <div class="literalblock">
\r
1890 <div class="content">
\r
1891 <pre><code> v1 = q * v2 + r</code></pre>
\r
1893 <div style="text-align:center">
\r
1894 _______________________________________________________
\r
1896 <div class="paragraph"><p><a id="p_dodoes"></a></p></div>
\r
1898 <div class="sect2">
\r
1899 <h3 id="_word_dodoes">Word: doDOES</h3>
\r
1900 <div class="literalblock">
\r
1901 <div class="content">
\r
1902 <pre><code>Data stack: ( -- a )</code></pre>
\r
1904 <div class="paragraph"><p>"doDOES" is a variable word whose value is the implementation of the
\r
1905 <a href="#p_does">[p_does]</a> execution semantics. This is the same as
\r
1906 <a href="#p_doforth">doFORTH</a> but it starts at an offset into the word
\r
1907 concerned.</p></div>
\r
1908 <div style="text-align:center">
\r
1909 _______________________________________________________
\r
1911 <div class="paragraph"><p><a id="p_does"></a></p></div>
\r
1913 <div class="sect2">
\r
1914 <h3 id="_word_does_gt">WORD: DOES></h3>
\r
1915 <div class="literalblock">
\r
1916 <div class="content">
\r
1917 <pre><code>Data stack: ( -- )</code></pre>
\r
1919 <div class="paragraph"><p>"DOES>" is a function that in execution mode does nothing but in
\r
1920 compilation mode it changes the execution semantics assignments for
\r
1921 the most recent word to use the <code>dodoes</code> sematics with adjustment
\r
1922 offset to the current heap address. I.e., the word being defined will
\r
1923 have its execution start at whatever comes after "DOES>".</p></div>
\r
1924 <div class="exampleblock">
\r
1925 <div class="content">
\r
1926 <div class="sidebarblock">
\r
1927 <div class="content">
\r
1928 <div class="title">Defintion concept for DOES></div>
\r
1929 <div class="paragraph"><p>: DOES> IMMEDIATE
\r
1930 STATE @ != IF ( only for compilation mode )
\r
1931 CURRENT-WORDLIST @ @ TFA>CFA ( cfa of current word )
\r
1932 doDOES OVER ! ( set up doer )
\r
1933 HERE @ OVER 8 + - SWAP 8 - ! ( set up offset
\r
1938 <div class="paragraph"><p>See also
\r
1939 <a href="#p_put">!</a>,
\r
1940 <a href="#p_unequal">!⇒></a>,
\r
1941 <a href="#p_minus">→></a>,
\r
1942 <a href="#p_get">@</a>,
\r
1943 <a href="#p_current_wordlist">CURRENT-WORDLIST</a>,
\r
1944 <a href="#p_here">HERE</a>,
\r
1945 <a href="#p_if">IF</a>,
\r
1946 <a href="#p_immediate">IMMEDIATE</a>,
\r
1947 <a href="#p_over">OVER</a>,
\r
1948 <a href="#p_state">STATE</a>,
\r
1949 <a href="#p_swap">SWAP</a>,
\r
1950 <a href="#p_tfa2cfa">TFA>CFA</a>,
\r
1951 <a href="#p_then">THEN</a>,
\r
1952 <a href="#p_dodoes">doDOES</a>,
\r
1953 as well as <a href="#p_execute">EXECUTE</a>
\r
1954 about the range of "doer" assignments and their meanings.</p></div>
\r
1955 <div style="text-align:center">
\r
1956 _______________________________________________________
\r
1958 <div class="paragraph"><p><a id="p_dofasm"></a></p></div>
\r
1960 <div class="sect2">
\r
1961 <h3 id="_word_dofasm">Word: doFASM</h3>
\r
1962 <div class="literalblock">
\r
1963 <div class="content">
\r
1964 <pre><code>Data stack: ( -- a )</code></pre>
\r
1966 <div class="paragraph"><p>"doFASM" is a variable word whose value is the implementation of the
\r
1967 execution semantics for assembly code content.</p></div>
\r
1968 <div style="text-align:center">
\r
1969 _______________________________________________________
\r
1971 <div class="paragraph"><p><a id="p_doforth"></a></p></div>
\r
1973 <div class="sect2">
\r
1974 <h3 id="_word_doforth">Word: doFORTH</h3>
\r
1975 <div class="literalblock">
\r
1976 <div class="content">
\r
1977 <pre><code>Data stack: ( -- a )</code></pre>
\r
1979 <div class="paragraph"><p>"doFORTH" is a variable word whose value is the implementation of the
\r
1980 RRQFORTH execution semantics.</p></div>
\r
1981 <div style="text-align:center">
\r
1982 _______________________________________________________
\r
1984 <div class="paragraph"><p><a id="p_dostring"></a></p></div>
\r
1986 <div class="sect2">
\r
1987 <h3 id="_word_dostring">Word: doSTRING</h3>
\r
1988 <div class="literalblock">
\r
1989 <div class="content">
\r
1990 <pre><code>Data stack: ( -- a )</code></pre>
\r
1992 <div class="paragraph"><p>"doFASM" is a variable word whose value is the implementation of the
\r
1993 execution semantics for assembly code implemented words. In those
\r
1994 cases the execution leads to the word content.</p></div>
\r
1995 <div class="paragraph"><p>The register context at entry to an assembly code implemented word is
\r
1996 as follows:</p></div>
\r
1997 <div class="listingblock">
\r
1998 <div class="content">
\r
1999 <pre><code> rax = cfa* of word to execute
\r
2000 rsi = cell* in the calling definition, after calling cell
\r
2001 rsp = data stack pointer
\r
2002 rbp = return stack pointer</code></pre>
\r
2004 <div class="paragraph"><p>The assembly code must ensure that <code>rsi</code> is preserved and that <code>rsp</code>
\r
2005 and <code>rbp</code> are used according to their roles.</p></div>
\r
2006 <div style="text-align:center">
\r
2007 _______________________________________________________
\r
2009 <div class="paragraph"><p><a id="p_dot"></a></p></div>
\r
2011 <div class="sect2">
\r
2012 <h3 id="_word_6">Word: .</h3>
\r
2013 <div class="literalblock">
\r
2014 <div class="content">
\r
2015 <pre><code>Data stack: ( v -- )</code></pre>
\r
2017 <div class="paragraph"><p>"." is a function word that prints the top stack value to stdout using
\r
2018 the current <a href="#p_base">BASE</a> (either <a href="#p_decimal">DECIMAL</a> or
\r
2019 <a href="#p_hex">HEX</a>).</p></div>
\r
2020 <div style="text-align:center">
\r
2021 _______________________________________________________
\r
2023 <div class="paragraph"><p><a id="p_dot_temp"></a></p></div>
\r
2025 <div class="sect2">
\r
2026 <h3 id="_word_temp">Word: .TEMP</h3>
\r
2027 <div class="literalblock">
\r
2028 <div class="content">
\r
2029 <pre><code>Data stack: ( v -- char* n )</code></pre>
\r
2031 <div class="paragraph"><p>".TEMP" is a function word that renders a cell value as an integer
\r
2032 using the current <a href="#p_base">BASE</a>, which is either
\r
2033 <a href="#p_decimal">DECIMAL</a> or <a href="#p_hex">HEX</a>. In <a href="#p_decimal">DECIMAL</a>
\r
2034 <a href="#p_base">BASE</a>, a negative value is rendered as such with a leading
\r
2035 minus sign, whereas <a href="#p_hex">HEX</a> <a href="#p_base">BASE</a> rendering is
\r
2036 unsigned.</p></div>
\r
2037 <div style="text-align:center">
\r
2038 _______________________________________________________
\r
2040 <div class="paragraph"><p><a id="p_double_quote"></a></p></div>
\r
2042 <div class="sect2">
\r
2043 <h3 id="_word_7">Word: "</h3>
\r
2044 <div class="literalblock">
\r
2045 <div class="content">
\r
2046 <pre><code>data stack: ( -- char n ) Input stream: ...."</code></pre>
\r
2048 <div class="paragraph"><p>""" (double quote) is a function word that copies the input stream
\r
2049 text up to next double quote to <a href="#p_pad">PAD</a>, and returns the
\r
2050 [n:char*] cell pair for that string.</p></div>
\r
2051 <div style="text-align:center">
\r
2052 _______________________________________________________
\r
2054 <div class="paragraph"><p><a id="p_dovalue"></a></p></div>
\r
2056 <div class="sect2">
\r
2057 <h3 id="_word_dovalue">Word: doVALUE</h3>
\r
2058 <div class="literalblock">
\r
2059 <div class="content">
\r
2060 <pre><code>Data stack: ( -- a )</code></pre>
\r
2062 <div class="paragraph"><p>"doVALUE" is a variable word whose value is the implementation of the
\r
2063 execution semantics for cell values, which are variables with a single
\r
2064 64-bit cell holding the value.</p></div>
\r
2065 <div class="paragraph"><p>The execution of this result in pushing the value:</p></div>
\r
2066 <div class="literalblock">
\r
2067 <div class="content">
\r
2068 <pre><code>Resulting data stack: ( -- v )</code></pre>
\r
2070 <div style="text-align:center">
\r
2071 _______________________________________________________
\r
2073 <div class="paragraph"><p><a id="p_dovariable"></a></p></div>
\r
2075 <div class="sect2">
\r
2076 <h3 id="_word_dovariable">Word: doVARIABLE</h3>
\r
2077 <div class="literalblock">
\r
2078 <div class="content">
\r
2079 <pre><code>Data stack: ( -- a )</code></pre>
\r
2081 <div class="paragraph"><p>"doVARIABLE" is a variable word whose value is the implementation of
\r
2082 the execution semantics for "variables", which basically are markers
\r
2083 into the heap for some number block of memory.</p></div>
\r
2084 <div class="paragraph"><p>The execution of a variable results in pushing its content address:</p></div>
\r
2085 <div class="literalblock">
\r
2086 <div class="content">
\r
2087 <pre><code>Resulting data stack: ( -- a )</code></pre>
\r
2089 <div style="text-align:center">
\r
2090 _______________________________________________________
\r
2092 <div class="paragraph"><p><a id="p_drop"></a></p></div>
\r
2094 <div class="sect2">
\r
2095 <h3 id="_word_drop">Word: DROP</h3>
\r
2096 <div class="literalblock">
\r
2097 <div class="content">
\r
2098 <pre><code>Data stack: ( v -- )</code></pre>
\r
2100 <div class="paragraph"><p>"DROP" is a function word that discards the top stack cell.</p></div>
\r
2101 <div style="text-align:center">
\r
2102 _______________________________________________________
\r
2104 <div class="paragraph"><p><a id="p_dup"></a></p></div>
\r
2106 <div class="sect2">
\r
2107 <h3 id="_word_dup">Word: DUP</h3>
\r
2108 <div class="literalblock">
\r
2109 <div class="content">
\r
2110 <pre><code>Data stack: ( v -- v v )</code></pre>
\r
2112 <div class="paragraph"><p>"DUP" is a function word that duplicates the top stack cell.</p></div>
\r
2113 <div style="text-align:center">
\r
2114 _______________________________________________________
\r
2116 <div class="paragraph"><p><a id="p_else"></a></p></div>
\r
2118 <div class="sect2">
\r
2119 <h3 id="_word_else">Word: ELSE</h3>
\r
2120 <div class="literalblock">
\r
2121 <div class="content">
\r
2122 <pre><code>Data stack: Compiling: ( a -- a )</code></pre>
\r
2124 <div class="paragraph"><p>"ELSE" is an immediate function word that is used together with
\r
2125 <a href="#p_if">IF</a> and <a href="#p_then">THEN</a> to implement structured execution
\r
2126 control. ELSE lays out an unresolved unconditional branch as an ending
\r
2127 for the "then-part" of the structured statement, and it then performs
\r
2128 the branch resolution for the "else-part". To that end it replaces the
\r
2129 stacked address which pin-points the foot address the branch offset to
\r
2130 resolve, so that at execution time there is an appropriate conditional
\r
2131 branch past the "then-part" and the "else-part" of the "structured
\r
2132 statement".</p></div>
\r
2133 <div style="text-align:center">
\r
2134 _______________________________________________________
\r
2136 <div class="paragraph"><p><a id="p_emit"></a></p></div>
\r
2138 <div class="sect2">
\r
2139 <h3 id="_word_emit">Word: EMIT</h3>
\r
2140 <div class="literalblock">
\r
2141 <div class="content">
\r
2142 <pre><code>Data stack: ( c -- )</code></pre>
\r
2144 <div class="paragraph"><p>"EMIT" is a function word that puts the given character code to
\r
2145 standard output (file descriptor 1). The character is the least
\r
2146 significant byte of the top cell.</p></div>
\r
2147 <div style="text-align:center">
\r
2148 _______________________________________________________
\r
2150 <div class="paragraph"><p><a id="p_end"></a></p></div>
\r
2152 <div class="sect2">
\r
2153 <h3 id="_word_end">Word: END</h3>
\r
2154 <div class="literalblock">
\r
2155 <div class="content">
\r
2156 <pre><code>Data stack: Compiling: ( a 0 * -- )</code></pre>
\r
2158 <div class="paragraph"><p>"END" is an immediate function word that is used together with
\r
2159 <a href="#p_begin">BEGIN</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a> to
\r
2160 implement structured execution control. END processes the data stack
\r
2161 to resolve any dangling <a href="#p_ifbreak">IFBREAK</a> branch offset for the
\r
2162 block of the matching <a href="#p_begin">BEGIN</a>.</p></div>
\r
2163 <div style="text-align:center">
\r
2164 _______________________________________________________
\r
2166 <div class="paragraph"><p><a id="p_equal"></a></p></div>
\r
2168 <div class="sect2">
\r
2169 <h3 id="_word_8">Word: =</h3>
\r
2170 <div class="literalblock">
\r
2171 <div class="content">
\r
2172 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>
\r
2174 <div class="paragraph"><p>"=" is a function word that replaces a pair of values with -1 of the
\r
2175 values are equal, and 0 otherwise.</p></div>
\r
2176 <div style="text-align:center">
\r
2177 _______________________________________________________
\r
2179 <div class="paragraph"><p><a id="p_erase"></a></p></div>
\r
2181 <div class="sect2">
\r
2182 <h3 id="_word_erase">Word: ERASE</h3>
\r
2183 <div class="literalblock">
\r
2184 <div class="content">
\r
2185 <pre><code>Data stack: ( a n -- )</code></pre>
\r
2187 <div class="paragraph"><p>"ERASE" is a function word that stores n NUL bytes at address a an up.</p></div>
\r
2188 <div style="text-align:center">
\r
2189 _______________________________________________________
\r
2191 <div class="paragraph"><p><a id="p_evaluate_stream"></a></p></div>
\r
2193 <div class="sect2">
\r
2194 <h3 id="_word_evaluate_stream">Word: EVALUATE-STREAM</h3>
\r
2195 <div class="literalblock">
\r
2196 <div class="content">
\r
2197 <pre><code>Data stack: ( stream -- ??? 0/1 ) Input stream: ......</code></pre>
\r
2199 <div class="paragraph"><p>"EVALUATE-STREAM" is a function word that reads words separated by
\r
2200 whitespace from the stream until it discovers an unknown word, or the
\r
2201 stream is exhausted. Depending on <a href="#p_state">STATE</a>, the words are
\r
2202 either executed or compiled, and all ther stack and heap effects are
\r
2203 preserved. "EVALUATE-STREAM" returns with an additional 0 or 1 on the
\r
2204 stack to respectively indicate that the last word was unkown, i.e. not
\r
2205 found (<a href="#p_find">FIND</a>) in the current word list
\r
2206 (<a href="#p_current_wordlist">CURRENT-WORDLIST</a>) and not a
\r
2207 <a href="#p_number">NUMBER</a> of the current <a href="#p_base">BASE</a>.</p></div>
\r
2208 <div class="paragraph"><p>Note that numbers in the current <a href="#p_base">BASE</a> are treated as known
\r
2209 words that are parsed into cell values. If interpreting, then the
\r
2210 value is left on the stack. If compiling, then the value is added to
\r
2211 the heap subsequent to first adding <a href="#p_literal">LIT</a>, which is done
\r
2212 so as to make that value be push to the data stack upon a later
\r
2213 execution.</p></div>
\r
2214 <div class="paragraph"><p>In the <a href="#p_decimal">DECIMAL</a> base, the number word may begin with a
\r
2215 minus sign.</p></div>
\r
2216 <div class="paragraph"><p>The words are read and executed one by one, accounting for whether its
\r
2217 a number word or not, whether it is an <a href="#p_immediate">IMMEDIATE</a> word
\r
2218 or not, and whether the state at the time of execution indicates
\r
2219 "compiling" of "interpreting". Immediate words are executed in both
\r
2220 interpreting and compiling state, while other words have their CFA get
\r
2221 added to the heap so as to gain their execution effect upon a later
\r
2222 execution.</p></div>
\r
2223 <div class="paragraph"><p>Note that "EVALUATE-STREAM" keeps the stream (pointer) on the return
\r
2224 stack while reading, parsing and executing.</p></div>
\r
2225 <div class="paragraph"><p>If "EVALUATE-STREAM" ends with 0, then <a href="#p_this_word">THIS-WORD</a> holds
\r
2226 the [n:chars] reference of the offending word in the stream buffer.</p></div>
\r
2227 <div style="text-align:center">
\r
2228 _______________________________________________________
\r
2230 <div class="paragraph"><p><a id="p_execute"></a></p></div>
\r
2232 <div class="sect2">
\r
2233 <h3 id="_word_execute">Word: EXECUTE</h3>
\r
2234 <div class="literalblock">
\r
2235 <div class="content">
\r
2236 <pre><code>Data stack: ( cfa -- )</code></pre>
\r
2238 <div class="paragraph"><p>"EXECUTE" is a function word that transfers the execution to the
\r
2239 indicated "Code Field Address", which typically is the CFA of an
\r
2240 RRQFORTH word with the CFA cell containing a jump address for the code
\r
2241 that implements the execution semnatics of the word.</p></div>
\r
2242 <div class="paragraph"><p>The following execution semantics are predefined:</p></div>
\r
2243 <div class="ulist"><ul>
\r
2246 assembler implemented words constitute their own execution
\r
2252 <a href="#p_doforth">[p_doforth]</a> implements the FORTH machine. This treats the word
\r
2253 content as a succession of cells that hold the cfa pointers for the
\r
2254 words that make of the definition. As is customary in FORTH
\r
2255 machines, the advance through that succession is provided by each
\r
2256 word code ending making an explicit jump to its successor. The
\r
2257 <a href="#p_return_stack">RETURN-STACK</a> serves as a call stack for tracking
\r
2258 the nesting of FORTH executions by saving the "addresses" of the
\r
2264 <a href="#p_dodoes">[p_dodoes]</a> implements the variation of starting the FORTH
\r
2265 execution somewhere within a definition rather than at the
\r
2271 <a href="#p_dostring">[p_dostring]</a>, <a href="#p_dovalue">[p_dovalue]</a> and <a href="#p_dovariable">[p_dovariable]</a> implement
\r
2272 different common ways of using word content other the as FORTH
\r
2277 <div style="text-align:center">
\r
2278 _______________________________________________________
\r
2280 <div class="paragraph"><p><a id="p_exit"></a></p></div>
\r
2282 <div class="sect2">
\r
2283 <h3 id="_word_exit">Word: EXIT</h3>
\r
2284 <div class="literalblock">
\r
2285 <div class="content">
\r
2286 <pre><code>Data stack: ( v -- )</code></pre>
\r
2288 <div class="paragraph"><p>"EXIT" is a function word that terminates the <code>rrqforth</code> process
\r
2289 immediately with the given exit code.</p></div>
\r
2290 <div style="text-align:center">
\r
2291 _______________________________________________________
\r
2293 <div class="paragraph"><p><a id="p_false"></a></p></div>
\r
2295 <div class="sect2">
\r
2296 <h3 id="_word_false">Word: FALSE</h3>
\r
2297 <div class="literalblock">
\r
2298 <div class="content">
\r
2299 <pre><code>Data stack: ( -- 0 )</code></pre>
\r
2301 <div class="paragraph"><p>"FALSE" is a value word representing logical false.</p></div>
\r
2302 <div style="text-align:center">
\r
2303 _______________________________________________________
\r
2305 <div class="paragraph"><p><a id="p_fdemit"></a></p></div>
\r
2307 <div class="sect2">
\r
2308 <h3 id="_word_fdemit">Word: FDEMIT</h3>
\r
2309 <div class="literalblock">
\r
2310 <div class="content">
\r
2311 <pre><code>Data stack: ( c fd -- )</code></pre>
\r
2313 <div class="paragraph"><p>"FDEMIT" is a function word that puts the given character code to the
\r
2314 given file descriptor. The character is the least significant byte of
\r
2315 the data stack cell.</p></div>
\r
2316 <div style="text-align:center">
\r
2317 _______________________________________________________
\r
2319 <div class="paragraph"><p><a id="p_fdtell"></a></p></div>
\r
2321 <div class="sect2">
\r
2322 <h3 id="_word_fdtell">Word: FDTELL</h3>
\r
2323 <div class="literalblock">
\r
2324 <div class="content">
\r
2325 <pre><code>Data stack: ( char* n fd -- )</code></pre>
\r
2327 <div class="paragraph"><p>"FDTELL" is a function word that prints a string to the given file
\r
2328 descriptor.</p></div>
\r
2329 <div style="text-align:center">
\r
2330 _______________________________________________________
\r
2332 <div class="paragraph"><p><a id="p_find"></a></p></div>
\r
2334 <div class="sect2">
\r
2335 <h3 id="_word_find">Word: FIND</h3>
\r
2336 <div class="literalblock">
\r
2337 <div class="content">
\r
2338 <pre><code>Data stack: ( char* n -- [ char* n 0 ]/[ tfa ] )</code></pre>
\r
2340 <div class="paragraph"><p>"FIND" is a function word that searches the current word list search
\r
2341 path for the given [n:char*] word, and returns the TFA of the matching
\r
2342 word if any. Otherwise FIND preserves the initial data stack but adds
\r
2343 0 to it.</p></div>
\r
2344 <div class="paragraph"><p>The word is sought starting with the
\r
2345 <a href="#p_current_wordlist">CURRENT-WORDLIST</a> word list, for the first
\r
2346 occurence of a match. If not found, the search continues with the
\r
2347 subsequent word list, and so on.</p></div>
\r
2348 <div class="paragraph"><p>When a word is found, then the data stack is changed by discarding the
\r
2349 [n:char*] double cell string pointer and pushing (only) the TFA of the
\r
2350 matching word instead.</p></div>
\r
2351 <div style="text-align:center">
\r
2352 _______________________________________________________
\r
2354 <div class="paragraph"><p><a id="p_forth"></a></p></div>
\r
2356 <div class="sect2">
\r
2357 <h3 id="_word_forth">Word: FORTH</h3>
\r
2358 <div class="literalblock">
\r
2359 <div class="content">
\r
2360 <pre><code>data stack: ( -- a )</code></pre>
\r
2362 <div class="paragraph"><p>"FORTH" is a variable word for the FORTH word list, which does not
\r
2363 have any subsequent word list.</p></div>
\r
2364 <div style="text-align:center">
\r
2365 _______________________________________________________
\r
2367 <div class="paragraph"><p><a id="p_get"></a></p></div>
\r
2369 <div class="sect2">
\r
2370 <h3 id="_word_9">Word: @</h3>
\r
2371 <div class="literalblock">
\r
2372 <div class="content">
\r
2373 <pre><code>Data stack: ( a -- v )</code></pre>
\r
2375 <div class="paragraph"><p>"@" is a function word that pushes the value v from the address a.</p></div>
\r
2376 <div style="text-align:center">
\r
2377 _______________________________________________________
\r
2379 <div class="paragraph"><p><a id="p_get_n_decrement"></a></p></div>
\r
2381 <div class="sect2">
\r
2382 <h3 id="_word_n">Word: @n--</h3>
\r
2383 <div class="literalblock">
\r
2384 <div class="content">
\r
2385 <pre><code>Data stack: ( a n -- v )</code></pre>
\r
2387 <div class="paragraph"><p>"@n--" is a function word that pushes the value from the address, a,
\r
2388 then decrements the cell at that address by n.</p></div>
\r
2389 <div class="exampleblock">
\r
2390 <div class="content">
\r
2391 <div class="sidebarblock">
\r
2392 <div class="content">
\r
2393 <div class="title">Defintion concept for @n++</div>
\r
2394 <div class="paragraph"><p>: @n++ OVER @ DUP ROT - ROT ! ;</p></div>
\r
2397 <div style="text-align:center">
\r
2398 _______________________________________________________
\r
2400 <div class="paragraph"><p><a id="p_get_n_increment"></a></p></div>
\r
2402 <div class="sect2">
\r
2403 <h3 id="_word_n_2">Word: @n++</h3>
\r
2404 <div class="literalblock">
\r
2405 <div class="content">
\r
2406 <pre><code>Data stack: ( a n -- v )</code></pre>
\r
2408 <div class="paragraph"><p>"@n++" is a function word that pushes the value from the address, a,
\r
2409 then increments the cell at that address by n.</p></div>
\r
2410 <div class="exampleblock">
\r
2411 <div class="content">
\r
2412 <div class="sidebarblock">
\r
2413 <div class="content">
\r
2414 <div class="title">Defintion concept for @n++</div>
\r
2415 <div class="paragraph"><p>( a n — v ) : @n++ OVER @ DUP ROT + ROT ! ;</p></div>
\r
2418 <div style="text-align:center">
\r
2419 _______________________________________________________
\r
2421 <div class="paragraph"><p><a id="p_greaterequal"></a></p></div>
\r
2423 <div class="sect2">
\r
2424 <h3 id="_word_gt">Word: >=</h3>
\r
2425 <div class="literalblock">
\r
2426 <div class="content">
\r
2427 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>
\r
2429 <div class="paragraph"><p>">=" is a function word that replaces a pair of values with -1 if the
\r
2430 first, v1, is greater than or equal to the second, v1, otherwise 0. To
\r
2431 that end, the values are 64-bit signed integers.</p></div>
\r
2432 <div style="text-align:center">
\r
2433 _______________________________________________________
\r
2435 <div class="paragraph"><p><a id="p_greaterthan"></a></p></div>
\r
2437 <div class="sect2">
\r
2438 <h3 id="_word_gt_2">Word: ></h3>
\r
2439 <div class="literalblock">
\r
2440 <div class="content">
\r
2441 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>
\r
2443 <div class="paragraph"><p>">" is a function word that replaces a pair of values with -1 if the
\r
2444 first, v1, is greater than the second, v1, otherwise 0. To that end,
\r
2445 the values are 64-bit signed integers.</p></div>
\r
2446 <div style="text-align:center">
\r
2447 _______________________________________________________
\r
2449 <div class="paragraph"><p><a id="p_gtR"></a></p></div>
\r
2451 <div class="sect2">
\r
2452 <h3 id="_word_gt_r">Word: >R</h3>
\r
2453 <div class="literalblock">
\r
2454 <div class="content">
\r
2455 <pre><code>Data stack: ( v -- ) Return stack: ( -- v )</code></pre>
\r
2457 <div class="paragraph"><p>">R" is a function word that "moves" the top data stack value onto the
\r
2458 return stack.</p></div>
\r
2459 <div style="text-align:center">
\r
2460 _______________________________________________________
\r
2462 <div class="paragraph"><p><a id="p_here"></a></p></div>
\r
2464 <div class="sect2">
\r
2465 <h3 id="_word_here">Word: HERE</h3>
\r
2466 <div class="literalblock">
\r
2467 <div class="content">
\r
2468 <pre><code>Data stack: ( -- a )</code></pre>
\r
2470 <div class="paragraph"><p>"HERE" is a variable word that keeps the lowest address of the free
\r
2471 allocation space. It get updated by all words that allocate memory.</p></div>
\r
2472 <div class="exampleblock">
\r
2473 <div class="content">
\r
2474 <div class="sidebarblock">
\r
2475 <div class="content">
\r
2476 <div class="title">allocate 1024 bytes on the heap</div>
\r
2477 <div class="paragraph"><p>1024 HEAP @ + HEAP !</p></div>
\r
2480 <div class="paragraph"><p>See also <a href="#p_allot">ALLOT</a>.</p></div>
\r
2481 <div style="text-align:center">
\r
2482 _______________________________________________________
\r
2484 <div class="paragraph"><p><a id="p_hex"></a></p></div>
\r
2486 <div class="sect2">
\r
2487 <h3 id="_word_hex">Word: HEX</h3>
\r
2488 <div class="literalblock">
\r
2489 <div class="content">
\r
2490 <pre><code>Data stack: ( -- )</code></pre>
\r
2492 <div class="paragraph"><p>"HEX" is a function word that sets <a href="#p_base">BASE</a> to 16, which uses
\r
2493 letters a-f as additional digits. (Uppercase letter are also accepted
\r
2494 on input).</p></div>
\r
2495 <div class="exampleblock">
\r
2496 <div class="content">
\r
2497 <div class="sidebarblock">
\r
2498 <div class="content">
\r
2499 <div class="title">Definition concept for HEX</div>
\r
2500 <div class="paragraph"><p>: HEX 16 BASE ! ;</p></div>
\r
2503 <div style="text-align:center">
\r
2504 _______________________________________________________
\r
2506 <div class="paragraph"><p><a id="p_if"></a></p></div>
\r
2508 <div class="sect2">
\r
2509 <h3 id="_word_if">Word: IF</h3>
\r
2510 <div class="literalblock">
\r
2511 <div class="content">
\r
2512 <pre><code>Data stack: Compiling: ( -- a )</code></pre>
\r
2514 <div class="paragraph"><p>"IF" is an immediate function word that is used together with
\r
2515 <a href="#p_else">ELSE</a> and <a href="#p_then">THEN</a> to implement structured execution
\r
2516 control. IF results in layout of a <a href="#p_0branch">0BRANCH</a> instruction
\r
2517 with an unresolved branch offset, and places the address for resolving
\r
2518 this instruction on the datastack. This address will then be resolved
\r
2519 and asssigned by a subsequent <a href="#p_else">ELSE</a> or <a href="#p_then">THEN</a> so
\r
2520 that at execution time there is an appropriate conditional branch past
\r
2521 the "then-part" of the "structured statement".</p></div>
\r
2522 <div style="text-align:center">
\r
2523 _______________________________________________________
\r
2525 <div class="paragraph"><p><a id="p_ifagain"></a></p></div>
\r
2527 <div class="sect2">
\r
2528 <h3 id="_word_ifagain">Word: IFAGAIN</h3>
\r
2529 <div class="literalblock">
\r
2530 <div class="content">
\r
2531 <pre><code>Data stack: Compiling: ( -- a )</code></pre>
\r
2533 <div class="paragraph"><p>"IFAGAIN" is an immediate function word that is used together with
\r
2534 <a href="#p_begin">BEGIN</a>, <a href="#p_ifbreak">BREAK</a> and <a href="#p_end">END</a> to implement
\r
2535 structured execution control. IFAGAIN scans the datastack for the
\r
2536 nearest preceding BEGIN marker and lays out a branch from this point
\r
2537 the beginning of the block during execution.</p></div>
\r
2538 <div style="text-align:center">
\r
2539 _______________________________________________________
\r
2541 <div class="paragraph"><p><a id="p_ifbreak"></a></p></div>
\r
2543 <div class="sect2">
\r
2544 <h3 id="_word_ifbreak">Word: IFBREAK</h3>
\r
2545 <div class="literalblock">
\r
2546 <div class="content">
\r
2547 <pre><code>Data stack: Compiling: ( -- a )</code></pre>
\r
2549 <div class="paragraph"><p>"IFBREAK" is an immediate function word that is used together with
\r
2550 <a href="#p_begin">BEGIN</a>, <a href="#p_ifagain">IFAGAIN</a> and <a href="#p_end">END</a> to
\r
2551 implement structured execution control. IFBREAK simply places the
\r
2552 address for resolving branches from this point the end of the block
\r
2553 during execution.</p></div>
\r
2554 <div style="text-align:center">
\r
2555 _______________________________________________________
\r
2557 <div class="paragraph"><p><a id="p_immediate"></a></p></div>
\r
2559 <div class="sect2">
\r
2560 <h3 id="_word_immediate">Word: IMMEDIATE</h3>
\r
2561 <div class="literalblock">
\r
2562 <div class="content">
\r
2563 <pre><code>Data stack: ( -- )</code></pre>
\r
2565 <div class="paragraph"><p>"IMMEDIATE" is an immediate function word that sets the flags field of
\r
2566 the most recent word to 1, thereby making that word an immediate word.</p></div>
\r
2567 <div class="exampleblock">
\r
2568 <div class="content">
\r
2569 <div class="sidebarblock">
\r
2570 <div class="content">
\r
2571 <div class="title">Definition concept for IMMEDIATE</div>
\r
2572 <div class="paragraph"><p>: IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;</p></div>
\r
2575 <div class="paragraph"><p>See also <a href="#p_colon">:</a>, <a href="#p_current_wordlist">CURRENT-WORDLIST</a>,
\r
2576 <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
2577 <div style="text-align:center">
\r
2578 _______________________________________________________
\r
2580 <div class="paragraph"><p><a id="p_input"></a></p></div>
\r
2582 <div class="sect2">
\r
2583 <h3 id="_word_input">Word: INPUT</h3>
\r
2584 <div class="literalblock">
\r
2585 <div class="content">
\r
2586 <pre><code>Data stack: ( -- a )</code></pre>
\r
2588 <div class="paragraph"><p>"INPUT" is a variable word for the input stream buffer used by
\r
2589 <a href="#p_evaluate_stream">EVALUATE-STREAM</a>.</p></div>
\r
2590 <div style="text-align:center">
\r
2591 _______________________________________________________
\r
2593 <div class="paragraph"><p><a id="p_left_bracket"></a></p></div>
\r
2595 <div class="sect2">
\r
2596 <h3 id="_word_10">Word: [</h3>
\r
2597 <div class="literalblock">
\r
2598 <div class="content">
\r
2599 <pre><code>Data stack: ( -- )</code></pre>
\r
2601 <div class="paragraph"><p>"[" (left bracket) is a function word that sets the stream evaluation
\r
2602 mode to be intepreting. In this mode, words are executed immediately
\r
2603 after parsing, by invoking their "doer".</p></div>
\r
2604 <div class="exampleblock">
\r
2605 <div class="content">
\r
2606 <div class="sidebarblock">
\r
2607 <div class="content">
\r
2608 <div class="title">Definition concept for [</div>
\r
2609 <div class="paragraph"><p>: [ IMMEDIATE 0 STATE ! ;</p></div>
\r
2612 <div style="text-align:center">
\r
2613 _______________________________________________________
\r
2615 <div class="paragraph"><p><a id="p_lessequal"></a></p></div>
\r
2617 <div class="sect2">
\r
2618 <h3 id="_word_lt">Word: <=</h3>
\r
2619 <div class="literalblock">
\r
2620 <div class="content">
\r
2621 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>
\r
2623 <div class="paragraph"><p>"<=" is a function word that replaces a pair of values with -1 if the
\r
2624 first, v1, is less than or equal to the second, v1, otherwise 0. To
\r
2625 that end, the values are 64-bit signed integers.</p></div>
\r
2626 <div style="text-align:center">
\r
2627 _______________________________________________________
\r
2629 <div class="paragraph"><p><a id="p_lessthan"></a></p></div>
\r
2631 <div class="sect2">
\r
2632 <h3 id="_word_lt_2">Word: <</h3>
\r
2633 <div class="literalblock">
\r
2634 <div class="content">
\r
2635 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>
\r
2637 <div class="paragraph"><p>"<" is a function word that replaces a pair of values with -1 if the
\r
2638 first, v1, is less than the second, v1, otherwise 0. To that end, the
\r
2639 values are 64-bit signed integers.</p></div>
\r
2640 <div style="text-align:center">
\r
2641 _______________________________________________________
\r
2643 <div class="paragraph"><p><a id="p_literal"></a></p></div>
\r
2645 <div class="sect2">
\r
2646 <h3 id="_word_lit">Word: LIT</h3>
\r
2647 <div class="literalblock">
\r
2648 <div class="content">
\r
2649 <pre><code>Data stack: ( -- v )</code></pre>
\r
2651 <div class="paragraph"><p>"LIT" is a function word that pushes the cell subsequent and moves
\r
2652 excution past that. The literal value is thus layed out as if a
\r
2653 subsequent CFA pointer in the containing definition, and the LIT
\r
2654 execution will make the execution skip past that and instead contine
\r
2655 with the CFA pointer following the value.</p></div>
\r
2656 <div class="paragraph"><p>It’s not a good idea to use "LIT" interactively.</p></div>
\r
2657 <div class="exampleblock">
\r
2658 <div class="content">
\r
2659 <div class="sidebarblock">
\r
2660 <div class="content">
\r
2661 <div class="title">Definition concept for LIT</div>
\r
2662 <div class="paragraph"><p>: LIT R> DUP 8 + >R @ ;</p></div>
\r
2665 <div style="text-align:center">
\r
2666 _______________________________________________________
\r
2668 <div class="paragraph"><p><a id="p_literal_string"></a></p></div>
\r
2670 <div class="sect2">
\r
2671 <h3 id="_word_lit_string">Word: LIT-STRING</h3>
\r
2672 <div class="literalblock">
\r
2673 <div class="content">
\r
2674 <pre><code>Data stack: ( -- chars* n )</code></pre>
\r
2676 <div class="paragraph"><p>"LIT-STRING" is a function word that pushes the char* and length n of
\r
2677 a subsequent inline string, then advances execution to continue after
\r
2678 the string. This is similar to <a href="#p_lit">LIT</a> but for a block literal.</p></div>
\r
2679 <div class="paragraph"><p>Note that the inlined byte count includes the terminating NUL byte.</p></div>
\r
2680 <div class="exampleblock">
\r
2681 <div class="content">
\r
2682 <div class="sidebarblock">
\r
2683 <div class="content">
\r
2684 <div class="title">Definition concept for LIT-STRING</div>
\r
2685 <div class="paragraph"><p>: LIT-STRING R@ DUP @ 8 + R@ @ 2DUP + R> + >R 1 - ;</p></div>
\r
2688 <div style="text-align:center">
\r
2689 _______________________________________________________
\r
2691 <div class="paragraph"><p><a id="p_literal_string_compile"></a></p></div>
\r
2693 <div class="sect2">
\r
2694 <h3 id="_word_s">Word: S"</h3>
\r
2695 <div class="literalblock">
\r
2696 <div class="content">
\r
2697 <pre><code>Data stack: ( -- ) Input stream: " chars"</code></pre>
\r
2699 <div class="paragraph"><p>"S"" is an immediate function word that compiles the subseqent
\r
2700 characters up to terminating double-quote into the current definition,
\r
2701 preceded by a <a href="#p_literal_string">LIT-STRING</a> cell, and the count of
\r
2702 bytes scanned. The inline text includes a terminating NUL character
\r
2703 which also is included in the inlined count.</p></div>
\r
2704 <div class="paragraph"><p>Note that "S"" uses <a href="#p_double_quote">"</a> for reading the string.</p></div>
\r
2705 <div style="text-align:center">
\r
2706 _______________________________________________________
\r
2708 <div class="paragraph"><p><a id="p_load_buffer_size"></a></p></div>
\r
2710 <div class="sect2">
\r
2711 <h3 id="_word_load_buffer_size">Word: LOAD-BUFFER-SIZE</h3>
\r
2712 <div class="literalblock">
\r
2713 <div class="content">
\r
2714 <pre><code>data stack: ( -- a )</code></pre>
\r
2716 <div class="paragraph"><p>"LOAD-BUFFER-SIZE" is a variable word telling the buffer size in bytes
\r
2717 that <a href="#p_load_file">LOAD-FILE</a> should use.</p></div>
\r
2718 <div style="text-align:center">
\r
2719 _______________________________________________________
\r
2721 <div class="paragraph"><p><a id="p_load_file"></a></p></div>
\r
2723 <div class="sect2">
\r
2724 <h3 id="_word_load_file">Word: LOAD-FILE</h3>
\r
2725 <div class="literalblock">
\r
2726 <div class="content">
\r
2727 <pre><code>data stack: ( chaz* -- * 0/1 )</code></pre>
\r
2729 <div class="paragraph"><p>"LOAD-FILE" is a function word that evaluates a text file. It opens a
\r
2730 file via <a href="#p_open_file">OPEN-FILE</a> and sets up a stream with a
\r
2731 buffer of <a href="#p_load_buffer_size">LOAD-BUFFER-SIZE</a> bytes for
\r
2732 reading it. The stream is passed to
\r
2733 <a href="#p_evaluate_stream">EVALUATE-STREAM</a> for processing its words. Upon
\r
2734 its return the file is closed and the stream memory is reclaimed, and
\r
2735 then the function returns whatever
\r
2736 <a href="#p_evaluate_stream">EVALUATE-STREAM</a> returns.</p></div>
\r
2737 <div style="text-align:center">
\r
2738 _______________________________________________________
\r
2740 <div class="paragraph"><p><a id="p_lparen"></a></p></div>
\r
2742 <div class="sect2">
\r
2743 <h3 id="_word_11">Word: (</h3>
\r
2744 <div class="literalblock">
\r
2745 <div class="content">
\r
2746 <pre><code>Data stack: ( -- )</code></pre>
\r
2748 <div class="paragraph"><p>"(" (left parenthesis) is a function word that scans and ignores words
\r
2749 until the next right parenthesis, or the end of the stream. This is
\r
2750 used for comments in RRQFORTH code.</p></div>
\r
2751 <div class="paragraph"><p>Note that the terminating right parenthesis is a word, i.e. must have
\r
2752 whitespace before and after it.</p></div>
\r
2753 <div style="text-align:center">
\r
2754 _______________________________________________________
\r
2756 <div class="paragraph"><p><a id="p_malloc"></a></p></div>
\r
2758 <div class="sect2">
\r
2759 <h3 id="_word_malloc">Word: MALLOC</h3>
\r
2760 <div class="literalblock">
\r
2761 <div class="content">
\r
2762 <pre><code>Data stack: ( n -- a )</code></pre>
\r
2764 <div class="paragraph"><p>"MALLOC" is a word that allocates memory using mmap of at least n
\r
2765 bytes and returns the lowest address of the allocated block.</p></div>
\r
2766 <div class="paragraph"><p>Note that this makes new page allocations for the process from the
\r
2767 kernel, and the granularity is in pages, i.e. a multiple of 4 kb.</p></div>
\r
2768 <div class="paragraph"><p>The memory is allocated with READ and WRITE access but not EXEC
\r
2769 access, and flagged as PRIVATE, ANONYMOUS and LOCKED. See the "man
\r
2770 page" of mmap for details.</p></div>
\r
2771 <div class="paragraph"><p>See also <a href="#p_stream">STREAM</a></p></div>
\r
2772 <div style="text-align:center">
\r
2773 _______________________________________________________
\r
2775 <div class="paragraph"><p><a id="p_minus"></a></p></div>
\r
2777 <div class="sect2">
\r
2778 <h3 id="_word_12">Word: -</h3>
\r
2779 <div class="literalblock">
\r
2780 <div class="content">
\r
2781 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>
\r
2783 <div class="paragraph"><p>"-" (minus) is a function word that replaces a pair of values with the
\r
2784 result of reducing the first, v1, with the second, v2. To that end,
\r
2785 the values are 64-bit signed integers.</p></div>
\r
2786 <div style="text-align:center">
\r
2787 _______________________________________________________
\r
2789 <div class="paragraph"><p><a id="p_mult"></a></p></div>
\r
2791 <div class="sect2">
\r
2792 <h3 id="_word_13">Word: *</h3>
\r
2793 <div class="literalblock">
\r
2794 <div class="content">
\r
2795 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>
\r
2797 <div class="paragraph"><p>"*" is a function word that replaces a pair of values with the result
\r
2798 of multiplying them. To that end, the values are 64-bit signed
\r
2799 integers, and clipping the result to the least signifcant 64 bits.</p></div>
\r
2800 <div style="text-align:center">
\r
2801 _______________________________________________________
\r
2803 <div class="paragraph"><p><a id="p_negate"></a></p></div>
\r
2805 <div class="sect2">
\r
2806 <h3 id="_word_negate">Word: NEGATE</h3>
\r
2807 <div class="literalblock">
\r
2808 <div class="content">
\r
2809 <pre><code>Data stack: ( v1 -- v2 )</code></pre>
\r
2811 <div class="paragraph"><p>"NEGATE" is a function word that replaces a value with its
\r
2812 2’s-complement negation. To that end, the values are 64-bit signed
\r
2813 integers.</p></div>
\r
2814 <div style="text-align:center">
\r
2815 _______________________________________________________
\r
2817 <div class="paragraph"><p><a id="p_nip"></a></p></div>
\r
2819 <div class="sect2">
\r
2820 <h3 id="_word_nip">Word: NIP</h3>
\r
2821 <div class="literalblock">
\r
2822 <div class="content">
\r
2823 <pre><code>Data stack: ( v1 v2 -- v2 )</code></pre>
\r
2825 <div class="paragraph"><p>"NIP" is a function word that discards the second of the top two cells
\r
2826 on the data stack.</p></div>
\r
2827 <div class="exampleblock">
\r
2828 <div class="content">
\r
2829 <div class="sidebarblock">
\r
2830 <div class="content">
\r
2831 <div class="title">Definition concept for NIP</div>
\r
2832 <div class="paragraph"><p>: NIP SWAP DROP ;</p></div>
\r
2835 <div style="text-align:center">
\r
2836 _______________________________________________________
\r
2838 <div class="paragraph"><p><a id="p_nl"></a></p></div>
\r
2840 <div class="sect2">
\r
2841 <h3 id="_word_nl">Word: NL</h3>
\r
2842 <div class="literalblock">
\r
2843 <div class="content">
\r
2844 <pre><code>Data stack: ( -- v )</code></pre>
\r
2846 <div class="paragraph"><p>"NL" is a value word pushing a newline character onto the data stack.</p></div>
\r
2847 <div style="text-align:center">
\r
2848 _______________________________________________________
\r
2850 <div class="paragraph"><p><a id="p_not"></a></p></div>
\r
2852 <div class="sect2">
\r
2853 <h3 id="_word_not">Word: NOT</h3>
\r
2854 <div class="literalblock">
\r
2855 <div class="content">
\r
2856 <pre><code>Data stack: ( v1 -- v2 )</code></pre>
\r
2858 <div class="paragraph"><p>"NOT" is a function word that replaces a value with its bitwise
\r
2859 complement; each bit is zero if non-zero, and non-zero if zero.</p></div>
\r
2860 <div class="paragraph"><p>Compare with <<p_0equal,0⇒>.</p></div>
\r
2861 <div style="text-align:center">
\r
2862 _______________________________________________________
\r
2864 <div class="paragraph"><p><a id="p_number"></a></p></div>
\r
2866 <div class="sect2">
\r
2867 <h3 id="_word_number">Word: NUMBER</h3>
\r
2868 <div class="literalblock">
\r
2869 <div class="content">
\r
2870 <pre><code>Data stack: ( char n -- [ 0 ]/[ v 1 ] )</code></pre>
\r
2872 <div class="paragraph"><p>"NUMBER" is a function word that parses a text number using
\r
2873 <a href="#p_base">BASE</a> as numerical base, then returns the result number and
\r
2874 a 1 on top, or just a 0 if the word didn’t parse.</p></div>
\r
2875 <div class="paragraph"><p>A number consists of, first an optional minus sign, if in
\r
2876 <a href="#p_decimal">DECIMAL</a> base, then digits 0-9 and, if in <a href="#p_hex">HEX</a>
\r
2877 base, letters a-f or A-F for values 10-15. I.e. the normal positive or
\r
2878 negative decimal integers or normal (positive only) hexadecimal
\r
2879 integers.</p></div>
\r
2880 <div style="text-align:center">
\r
2881 _______________________________________________________
\r
2883 <div class="paragraph"><p><a id="p_open_file"></a></p></div>
\r
2885 <div class="sect2">
\r
2886 <h3 id="_word_open_file">Word: OPEN-FILE</h3>
\r
2887 <div class="literalblock">
\r
2888 <div class="content">
\r
2889 <pre><code>Data stack: ( chaz* -- fd )</code></pre>
\r
2891 <div class="paragraph"><p>"OPEN-FILE" is a function word that opens the file named by the zero
\r
2892 terminated character string and returns the file descriptor, or if
\r
2893 less than 0, the system call error code.</p></div>
\r
2894 <div style="text-align:center">
\r
2895 _______________________________________________________
\r
2897 <div class="paragraph"><p><a id="p_or"></a></p></div>
\r
2899 <div class="sect2">
\r
2900 <h3 id="_word_or">Word: OR</h3>
\r
2901 <div class="literalblock">
\r
2902 <div class="content">
\r
2903 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>
\r
2905 <div class="paragraph"><p>"OR" is a function word that replaces a value pair with their bitwise
\r
2906 disjunction; each bit is 1 if the corresponding bits of any operand
\r
2907 is 1 and 0 if not.</p></div>
\r
2908 <div style="text-align:center">
\r
2909 _______________________________________________________
\r
2911 <div class="paragraph"><p><a id="p_over"></a></p></div>
\r
2913 <div class="sect2">
\r
2914 <h3 id="_word_over">Word: OVER</h3>
\r
2915 <div class="literalblock">
\r
2916 <div class="content">
\r
2917 <pre><code>Data stack: ( v1 v2 -- v1 v2 v1 )</code></pre>
\r
2919 <div class="paragraph"><p>"OVER" is a function word that duplicates the second top stack cell on
\r
2920 the data stack.</p></div>
\r
2921 <div style="text-align:center">
\r
2922 _______________________________________________________
\r
2924 <div class="paragraph"><p><a id="p_pad"></a></p></div>
\r
2926 <div class="sect2">
\r
2927 <h3 id="_word_pad">Word: PAD</h3>
\r
2928 <div class="literalblock">
\r
2929 <div class="content">
\r
2930 <pre><code>Data stack: ( -- a )</code></pre>
\r
2932 <div class="paragraph"><p>"PAD" is a variable word for a 1 kb data space that is used by
\r
2933 <a href="#p_double_quote">[p_double_quote]</a> (only), and otherwise free for temporary use.</p></div>
\r
2934 <div style="text-align:center">
\r
2935 _______________________________________________________
\r
2937 <div class="paragraph"><p><a id="p_pick"></a></p></div>
\r
2939 <div class="sect2">
\r
2940 <h3 id="_word_pick">Word: PICK</h3>
\r
2941 <div class="literalblock">
\r
2942 <div class="content">
\r
2943 <pre><code>Data stack: ( vu...v1 v0 u -- vu...v1 v0 vu )</code></pre>
\r
2945 <div class="paragraph"><p>"PICK" is a function word that pushes the u:th data stack cell down
\r
2946 from top onto the data stack. 0 indicates the top cell making it the
\r
2947 same as <a href="#p_dup">DUP</a>, and 1 indicates the second top cell making it
\r
2948 the same as <a href="#p_over">OVER</a>.</p></div>
\r
2949 <div style="text-align:center">
\r
2950 _______________________________________________________
\r
2952 <div class="paragraph"><p><a id="p_plus"></a></p></div>
\r
2954 <div class="sect2">
\r
2955 <h3 id="_word_43">Word: +</h3>
\r
2956 <div class="literalblock">
\r
2957 <div class="content">
\r
2958 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>
\r
2960 <div class="paragraph"><p>"+" (plus) is a function word that replaces a pair of values with the
\r
2961 result of adding them. To that end, the values are 64-bit signed
\r
2962 integers.</p></div>
\r
2963 <div style="text-align:center">
\r
2964 _______________________________________________________
\r
2966 <div class="paragraph"><p><a id="p_program_version"></a></p></div>
\r
2968 <div class="sect2">
\r
2969 <h3 id="_word_program_version">Word: PROGRAM_VERSION</h3>
\r
2970 <div class="literalblock">
\r
2971 <div class="content">
\r
2972 <pre><code>Data stack: ( -- char* length )</code></pre>
\r
2974 <div class="paragraph"><p>"PROGRAM_VERSION" is a string variable hilding the version string.</p></div>
\r
2975 <div style="text-align:center">
\r
2976 _______________________________________________________
\r
2978 <div class="paragraph"><p><a id="p_put"></a></p></div>
\r
2980 <div class="sect2">
\r
2981 <h3 id="_word_14">Word: !</h3>
\r
2982 <div class="literalblock">
\r
2983 <div class="content">
\r
2984 <pre><code>Data stack: ( v a -- )</code></pre>
\r
2986 <div class="paragraph"><p>"!" is a function word that stores the cell value v at the address a.</p></div>
\r
2987 <div style="text-align:center">
\r
2988 _______________________________________________________
\r
2990 <div class="paragraph"><p><a id="p_put_plus"></a></p></div>
\r
2992 <div class="sect2">
\r
2993 <h3 id="_word_15">Word: !+</h3>
\r
2994 <div class="literalblock">
\r
2995 <div class="content">
\r
2996 <pre><code>Data stack: ( a n -- )</code></pre>
\r
2998 <div class="paragraph"><p>"!+" is a function word that adds n to the cell value at a.</p></div>
\r
2999 <div class="exampleblock">
\r
3000 <div class="content">
\r
3001 <div class="sidebarblock">
\r
3002 <div class="content">
\r
3003 <div class="title">definition concept for !+</div>
\r
3004 <div class="paragraph"><p>( a n — ) : !+ OVER @ + SWAP ! ;</p></div>
\r
3007 <div style="text-align:center">
\r
3008 _______________________________________________________
\r
3010 <div class="paragraph"><p><a id="p_quit"></a></p></div>
\r
3012 <div class="sect2">
\r
3013 <h3 id="_word_quit">Word: QUIT</h3>
\r
3014 <div class="literalblock">
\r
3015 <div class="content">
\r
3016 <pre><code>Data stack: ??</code></pre>
\r
3018 <div class="paragraph"><p>"QUIT" is a function word that implements the root execution loop of
\r
3019 RRQFORTH. First it resets the stacks to their original settings, and
\r
3020 thereafter it enters loop of reading words from <a href="#p_stdin">STDIN</a> and
\r
3021 executing them.</p></div>
\r
3022 <div style="text-align:center">
\r
3023 _______________________________________________________
\r
3025 <div class="paragraph"><p><a id="p_quote"></a></p></div>
\r
3027 <div class="sect2">
\r
3028 <h3 id="_word_16">Word: '</h3>
\r
3029 <div class="literalblock">
\r
3030 <div class="content">
\r
3031 <pre><code>data stack: ( -- cfa ) Input stream: word</code></pre>
\r
3033 <div class="paragraph"><p>"'" (single quote) is a function word that reads and find the next
\r
3034 word on the input stream and pushes its cfa.</p></div>
\r
3035 <div style="text-align:center">
\r
3036 _______________________________________________________
\r
3038 <div class="paragraph"><p><a id="p_rbp"></a></p></div>
\r
3040 <div class="sect2">
\r
3041 <h3 id="_word_rsp">Word: RSP</h3>
\r
3042 <div class="literalblock">
\r
3043 <div class="content">
\r
3044 <pre><code>Data stack: ( -- a )</code></pre>
\r
3046 <div class="paragraph"><p>"RSP" is a function word that pushes the return stack pointer value
\r
3047 onto the data stack.</p></div>
\r
3048 <div style="text-align:center">
\r
3049 _______________________________________________________
\r
3051 <div class="paragraph"><p><a id="p_rbpn"></a></p></div>
\r
3053 <div class="sect2">
\r
3054 <h3 id="_word_r_n">Word: R[n]</h3>
\r
3055 <div class="literalblock">
\r
3056 <div class="content">
\r
3057 <pre><code>Data stack: ( n -- a )</code></pre>
\r
3059 <div class="paragraph"><p>"R[n]" is a function word that pushes the address for the n:th cell of
\r
3060 the return stack onto the data stack.</p></div>
\r
3061 <div class="exampleblock">
\r
3062 <div class="content">
\r
3063 <div class="sidebarblock">
\r
3064 <div class="content">
\r
3065 <div class="title">Defintion concept for R[n]</div>
\r
3066 <div class="paragraph"><p>( n — a ) : R[n] 8 * RSP + ;</p></div>
\r
3069 <div style="text-align:center">
\r
3070 _______________________________________________________
\r
3072 <div class="paragraph"><p><a id="p_read_stream_char"></a></p></div>
\r
3074 <div class="sect2">
\r
3075 <h3 id="_word_read_stream_char">Word: READ-STREAM-CHAR</h3>
\r
3076 <div class="literalblock">
\r
3077 <div class="content">
\r
3078 <pre><code>Data stack: ( stream -- c )</code></pre>
\r
3080 <div class="paragraph"><p>"READ-STREAM-CHAR" is a function word that gets the next character
\r
3081 from the given stream buffer, possibly refilling the buffer if it is
\r
3082 backed by a file descriptor. The refill is done by a SYS_READ call
\r
3083 when more characters are needed. The next character is pushed on the
\r
3084 stack, unless the stream is exhausted in which case the -1 is pushed
\r
3085 instead.</p></div>
\r
3086 <div class="paragraph"><p>See also <a href="#p_stream">STREAM</a>.</p></div>
\r
3087 <div style="text-align:center">
\r
3088 _______________________________________________________
\r
3090 <div class="paragraph"><p><a id="p_read_stream_line"></a></p></div>
\r
3092 <div class="sect2">
\r
3093 <h3 id="_word_read_stream_line">Word: READ-STREAM-LINE</h3>
\r
3094 <div class="literalblock">
\r
3095 <div class="content">
\r
3096 <pre><code>Data stack: ( stream -- n )</code></pre>
\r
3098 <div class="paragraph"><p>"READ-STREAM-LINE" is a function word that gets the next line from the
\r
3099 given stream buffer into PAD and returns number of characters. If the
\r
3100 stream is backed by a file descriptor, the stream buffer is refilled
\r
3101 from there as needed, by a SYS_READ call when more characters are
\r
3103 <div style="text-align:center">
\r
3104 _______________________________________________________
\r
3106 <div class="paragraph"><p><a id="p_read_word"></a></p></div>
\r
3108 <div class="sect2">
\r
3109 <h3 id="_word_read_word">Word: READ-WORD</h3>
\r
3110 <div class="literalblock">
\r
3111 <div class="content">
\r
3112 <pre><code>Data stack: ( stream -- char* n )</code></pre>
\r
3114 <div class="paragraph"><p>"READ-WORD" is a function word that "reads" the next whitespace
\r
3115 separated word from the given stream and returns the [n:char*] duoble
\r
3116 cell pointer for it. The characters of the word are copied to
\r
3117 <a href="#p_pad">PAD</a>, and there is a limit of 1024 characters.</p></div>
\r
3118 <div class="paragraph"><p>At the end of the stream READ-WORD returns 0 length.</p></div>
\r
3119 <div class="exampleblock">
\r
3120 <div class="title">Special syntax 1: Whitespace</div>
\r
3121 <div class="content">
\r
3122 <div class="paragraph"><p>All character codes less or equal to 32 are regarded as "whitespace".</p></div>
\r
3124 <div class="exampleblock">
\r
3125 <div class="title">Special syntax 2: Rest-of-line comment</div>
\r
3126 <div class="content">
\r
3127 <div class="paragraph"><p>The "#" character following whitespace starts a line comment and the
\r
3128 rest of the line is ignored. Note that this is also recognised with
\r
3129 <a href="#p_lparen">parethesis commenting</a>.</p></div>
\r
3131 <div style="text-align:center">
\r
3132 _______________________________________________________
\r
3134 <div class="paragraph"><p><a id="p_realloc"></a></p></div>
\r
3136 <div class="sect2">
\r
3137 <h3 id="_word_realloc">Word: REALLOC</h3>
\r
3138 <div class="literalblock">
\r
3139 <div class="content">
\r
3140 <pre><code>Data stack: ( a m n -- a )</code></pre>
\r
3142 <div class="paragraph"><p>"REALLOC" is a word that reallocates memory using mremap of address a
\r
3143 of size m to be size n bytes and returns the lowest address of the
\r
3144 allocated block.</p></div>
\r
3145 <div class="paragraph"><p>Note that this makes new page allocations for the process from the
\r
3146 kernel, and the granularity is in pages, i.e. a multiple of 4 kb.</p></div>
\r
3147 <div class="paragraph"><p>The memory is reampped using the MREMAP_MAYMOVE flag,</p></div>
\r
3148 <div class="paragraph"><p>See also <a href="#p_malloc">MALLOC</a></p></div>
\r
3149 <div style="text-align:center">
\r
3150 _______________________________________________________
\r
3152 <div class="paragraph"><p><a id="p_return"></a></p></div>
\r
3154 <div class="sect2">
\r
3155 <h3 id="_word_return">Word: RETURN</h3>
\r
3156 <div class="literalblock">
\r
3157 <div class="content">
\r
3158 <pre><code>Data stack: ( -- )</code></pre>
\r
3160 <div class="paragraph"><p>"RETURN" is a function word that implements the ending of a FORTH
\r
3161 definition and make execution return to the next step in the calling
\r
3162 definition.</p></div>
\r
3163 <div style="text-align:center">
\r
3164 _______________________________________________________
\r
3166 <div class="paragraph"><p>compile.asm: WORD p_right_bracket,<em>]</em>,fasm</p></div>
\r
3167 <div class="paragraph"><p><a id="p_right_bracket"></a></p></div>
\r
3169 <div class="sect2">
\r
3170 <h3 id="_word_17">Word: ]</h3>
\r
3171 <div class="literalblock">
\r
3172 <div class="content">
\r
3173 <pre><code>Data stack: ( -- )</code></pre>
\r
3175 <div class="paragraph"><p>"]" (right bracket) is a function word that sets the stream evaluation
\r
3176 mode to be compiling. In this mode words parsed into CFA pointers
\r
3177 which are placed on the heap in the given order, unless the word is
\r
3178 flagged as <a href="#p_immediate">IMMEDIATE</a> or a <a href="#p_number">NUMBER</a>. An
\r
3179 immediate word is executed immediately, and a number is parsed and
\r
3180 left on the stack.</p></div>
\r
3181 <div class="paragraph"><p>Note that a word is parsed as a number only if it is not found in the
\r
3182 wordlist; i.e., the word list may contain definitions for numbers.</p></div>
\r
3183 <div class="exampleblock">
\r
3184 <div class="content">
\r
3185 <div class="sidebarblock">
\r
3186 <div class="content">
\r
3187 <div class="title">Definition concept for ]</div>
\r
3188 <div class="paragraph"><p>: ] 1 STATE ! ;</p></div>
\r
3191 <div style="text-align:center">
\r
3192 _______________________________________________________
\r
3194 <div class="paragraph"><p><a id="p_roll"></a></p></div>
\r
3196 <div class="sect2">
\r
3197 <h3 id="_word_roll">Word: ROLL</h3>
\r
3198 <div class="literalblock">
\r
3199 <div class="content">
\r
3200 <pre><code>Data stack: ( vu...v1 v0 u -- ...v1 v0 vu )</code></pre>
\r
3202 <div class="paragraph"><p>"ROLL" is a function word that "moves" the u:th data stack cell down
\r
3203 from top onto the data stack while discarding it. 0 indicates the top
\r
3204 cell; 1 indicates the second top cell making it the same as
\r
3205 <a href="#p_swap">SWAP</a>; 2 indicates the third top cell making it the same as
\r
3206 <a href="#p_rot">ROT</a>.</p></div>
\r
3207 <div style="text-align:center">
\r
3208 _______________________________________________________
\r
3210 <div class="paragraph"><p><a id="p_rot"></a></p></div>
\r
3212 <div class="sect2">
\r
3213 <h3 id="_word_rot">Word: ROT</h3>
\r
3214 <div class="literalblock">
\r
3215 <div class="content">
\r
3216 <pre><code>Data stack: ( v1 v2 v3 -- v2 v3 v1 )</code></pre>
\r
3218 <div class="paragraph"><p>"ROT" is a function word that "rotates" the top three data stack cells
\r
3219 such that the third becomes the first while the second becomes third
\r
3220 and the first becomes the second.</p></div>
\r
3221 <div class="paragraph"><p>See also <a href="#p_roll">ROLL</a>.</p></div>
\r
3222 <div style="text-align:center">
\r
3223 _______________________________________________________
\r
3225 <div class="paragraph"><p><a id="p_semicolon"></a></p></div>
\r
3227 <div class="sect2">
\r
3228 <h3 id="_word_18">Word: ;</h3>
\r
3229 <div class="literalblock">
\r
3230 <div class="content">
\r
3231 <pre><code>Data stack: ( -- )</code></pre>
\r
3233 <div class="paragraph"><p>";" (semi-colon) is an immediate function word that ends a new forth
\r
3234 definition by means of adding an <a href="#p_exit">EXIT</a> cell, then changing
\r
3235 <<p_state,STATE> to interpreting.</p></div>
\r
3236 <div class="exampleblock">
\r
3237 <div class="content">
\r
3238 <div class="sidebarblock">
\r
3239 <div class="content">
\r
3240 <div class="title">Definition concept for ;</div>
\r
3241 <div class="paragraph"><p>: ; IMMEDIATE ' EXIT , ;</p></div>
\r
3244 <div style="text-align:center">
\r
3245 _______________________________________________________
\r
3247 <div class="paragraph"><p><a id="p_setup_signals"></a></p></div>
\r
3249 <div class="sect2">
\r
3250 <h3 id="_word_p_setup_signals">Word: [p_setup_signals]</h3>
\r
3251 <div class="literalblock">
\r
3252 <div class="content">
\r
3253 <pre><code>Data stack: ( -- a )</code></pre>
\r
3255 <div class="paragraph"><p>"[p_setup_signals]" is a variable word that contains the assembly code
\r
3256 sniippet for setting up the signal handling. rrqforth handles SEGV by
\r
3257 restarting the interpreter loop on <a href="#p_stdin">STDIN</a>.</p></div>
\r
3258 <div style="text-align:center">
\r
3259 _______________________________________________________
\r
3261 <div class="paragraph"><p><a id="p_shift_left"></a></p></div>
\r
3263 <div class="sect2">
\r
3264 <h3 id="_word_lt_lt">Word: <<</h3>
\r
3265 <div class="literalblock">
\r
3266 <div class="content">
\r
3267 <pre><code>Data stack: ( v1 n -- v2 )</code></pre>
\r
3269 <div class="paragraph"><p>"<<" is a function word that shifts value v1 n steps left (i.e.
\r
3270 "moving" bits towards more significant bits) to form value v2.</p></div>
\r
3271 <div style="text-align:center">
\r
3272 _______________________________________________________
\r
3274 <div class="paragraph"><p><a id="p_shift_right"></a></p></div>
\r
3276 <div class="sect2">
\r
3277 <h3 id="_word_gt_gt">Word: >></h3>
\r
3278 <div class="literalblock">
\r
3279 <div class="content">
\r
3280 <pre><code>Data stack: ( v1 n -- v2 )</code></pre>
\r
3282 <div class="paragraph"><p>">>" is a function word that shifts value v1 n steps right (i.e.
\r
3283 "moving" bits towards less significant bits) to form value v2.</p></div>
\r
3284 <div style="text-align:center">
\r
3285 _______________________________________________________
\r
3287 <div class="paragraph"><p><a id="p_shift_signed_right"></a></p></div>
\r
3289 <div class="sect2">
\r
3290 <h3 id="_word_s_gt_gt">Word: s>></h3>
\r
3291 <div class="literalblock">
\r
3292 <div class="content">
\r
3293 <pre><code>Data stack: ( v1 n -- v2 )</code></pre>
\r
3295 <div class="paragraph"><p>"s>>" is a function word that shifts value v1 n steps right (i.e.
\r
3296 "moving" bits towards less significant bits) to form value v2, but
\r
3297 preserving (and copying) the sign bit.</p></div>
\r
3298 <div style="text-align:center">
\r
3299 _______________________________________________________
\r
3301 <div class="paragraph"><p><a id="p_sp"></a></p></div>
\r
3303 <div class="sect2">
\r
3304 <h3 id="_word_sp">Word: SP</h3>
\r
3305 <div class="literalblock">
\r
3306 <div class="content">
\r
3307 <pre><code>Data stack: ( -- v )</code></pre>
\r
3309 <div class="paragraph"><p>"SP" is a value word pushing a space character onto the data stack.</p></div>
\r
3310 <div style="text-align:center">
\r
3311 _______________________________________________________
\r
3313 <div class="paragraph"><p><a id="p_state"></a></p></div>
\r
3315 <div class="sect2">
\r
3316 <h3 id="_word_state">Word: STATE</h3>
\r
3317 <div class="literalblock">
\r
3318 <div class="content">
\r
3319 <pre><code>Data stack: ( -- a )</code></pre>
\r
3321 <div class="paragraph"><p>"STATE" is a variable word marking whether the stream evaluator is in
\r
3322 compiling mode (1) or interpreting (0) mode.</p></div>
\r
3323 <div style="text-align:center">
\r
3324 _______________________________________________________
\r
3326 <div class="paragraph"><p><a id="p_stdin"></a></p></div>
\r
3328 <div class="sect2">
\r
3329 <h3 id="_word_stdin">Word: STDIN</h3>
\r
3330 <div class="literalblock">
\r
3331 <div class="content">
\r
3332 <pre><code>Data stack: ( -- stream )</code></pre>
\r
3334 <div class="paragraph"><p>"STDIN" is a value word referring to the stream buffer for the
\r
3335 standard input file descriptor.</p></div>
\r
3336 <div style="text-align:center">
\r
3337 _______________________________________________________
\r
3339 <div class="paragraph"><p><a id="p_stream"></a></p></div>
\r
3341 <div class="sect2">
\r
3342 <h3 id="_word_stream">Word: STREAM</h3>
\r
3343 <div class="literalblock">
\r
3344 <div class="content">
\r
3345 <pre><code>Data stack: ( fd size -- addr ) or ( block -1 -- addr )</code></pre>
\r
3347 <div class="paragraph"><p>"STREAM" is a function word that sets up a buffer for an input file
\r
3348 descriptor or for a memory block (of size+data).</p></div>
\r
3349 <div class="sect3">
\r
3350 <h4 id="_file_descriptor_backed_stream">File descriptor backed STREAM</h4>
\r
3351 <div class="paragraph"><p>A file descriptor backed STREAM gains a buffer of the given size
\r
3352 prefixed by a 32 byte STREAM header of the following layout:</p></div>
\r
3353 <div class="exampleblock">
\r
3354 <div class="content">
\r
3355 <div class="listingblock">
\r
3356 <div class="title">Layout 3: file descriptor stream</div>
\r
3357 <div class="content">
\r
3358 <pre><code> 8 bytes = size of buffer (excluding the 32 byte header)
\r
3359 8 bytes source file descriptor
\r
3360 8 bytes current fill
\r
3361 8 current read position</code></pre>
\r
3365 <div class="sect3">
\r
3366 <h4 id="_memory_block_backed_stream">Memory block backed STREAM</h4>
\r
3367 <div class="paragraph"><p>A memory block stream is only the header (though allocated via
\r
3368 <a href="#p_malloc">MALLOC</a> which reserves a full kernel page) with the
\r
3369 following layout:</p></div>
\r
3370 <div class="exampleblock">
\r
3371 <div class="content">
\r
3372 <div class="listingblock">
\r
3373 <div class="title">Layout 4: memory block stream</div>
\r
3374 <div class="content">
\r
3375 <pre><code> 8 bytes = block address
\r
3376 8 -1 (indicates memory block)
\r
3377 8 size of block (taken from the block's first 8 bytes)
\r
3378 8 current read position</code></pre>
\r
3381 <div style="text-align:center">
\r
3382 _______________________________________________________
\r
3384 <div class="paragraph"><p><a id="p_stream_nchars"></a></p></div>
\r
3387 <div class="sect2">
\r
3388 <h3 id="_word_stream_nchars">Word: STREAM-NCHARS</h3>
\r
3389 <div class="literalblock">
\r
3390 <div class="content">
\r
3391 <pre><code>Data stack: ( stream -- n )</code></pre>
\r
3393 <div class="paragraph"><p>"STREAM-NCHARS" is a function word that scans ahead in the stream
\r
3394 buffer for the next non-whitespace character, and returns its position
\r
3395 relative to the end of the buffer. This is done without changing the
\r
3396 stream (or filling it by reading the backing file).</p></div>
\r
3397 <div style="text-align:center">
\r
3398 _______________________________________________________
\r
3400 <div class="paragraph"><p><a id="p_str2temp"></a></p></div>
\r
3402 <div class="sect2">
\r
3403 <h3 id="_word_str_gt_temp">Word: STR>TEMP</h3>
\r
3404 <div class="sidebarblock">
\r
3405 <div class="content">
\r
3406 <div class="paragraph"><p>Data stack: ( char* n — char* n )</p></div>
\r
3408 <div class="paragraph"><p>"STR>TEMP" is a function word that copies a given string plus a
\r
3409 terminating NUL character into a <a href="#p_tempspace">TEMPSPACE</a> snippet,
\r
3410 all preceded by a length cell. It returns a pointer for to the text in
\r
3411 the snippet and its length, excluding the NUL character at end and the
\r
3412 length cell before tie text.</p></div>
\r
3413 <div class="listingblock">
\r
3414 <div class="title">Layout for copied string</div>
\r
3415 <div class="content">
\r
3416 <pre><code> length: 8 bytes
\r
3417 returned char*: n bytes
\r
3418 nul: 1 byte</code></pre>
\r
3420 <div style="text-align:center">
\r
3421 _______________________________________________________
\r
3423 <div class="paragraph"><p><a id="p_strlen"></a></p></div>
\r
3425 <div class="sect2">
\r
3426 <h3 id="_word_strlen">Word: STRLEN</h3>
\r
3427 <div class="literalblock">
\r
3428 <div class="content">
\r
3429 <pre><code>Data stack: ( s -- n )</code></pre>
\r
3431 <div class="paragraph"><p>"STRLEN" is a function words that counts how many bytes there are from
\r
3432 s to the first NUL byte and returns that count, n, not including the
\r
3433 NUL byte.</p></div>
\r
3434 <div style="text-align:center">
\r
3435 _______________________________________________________
\r
3437 <div class="paragraph"><p><a id="p_strncmp"></a></p></div>
\r
3439 <div class="sect2">
\r
3440 <h3 id="_word_strncmp">Word: STRNCMP</h3>
\r
3441 <div class="literalblock">
\r
3442 <div class="content">
\r
3443 <pre><code>Data stack: ( s1 s2 n -- v )</code></pre>
\r
3445 <div class="paragraph"><p>"STRNCMP" is a function words that compares up to n characters of
\r
3446 character sequences s1 and s2, and returns the difference of the first
\r
3447 differing characters, as in <code>s2[i] - s1[i]</code>, or 0 if all n characters
\r
3448 are the same.</p></div>
\r
3449 <div class="paragraph"><p>I.e., the value v is less than 0 if string [n:s1] is alpha-numerically
\r
3451 v is greater than 0 if [n:s1] is greater than [n:s2],
\r
3452 and v is 0 if [n:s1] and [n:s2] are equal.</p></div>
\r
3453 <div style="text-align:center">
\r
3454 _______________________________________________________
\r
3456 <div class="paragraph"><p><a id="p_strncpy"></a></p></div>
\r
3458 <div class="sect2">
\r
3459 <h3 id="_word_strncpy">Word: STRNCPY</h3>
\r
3460 <div class="literalblock">
\r
3461 <div class="content">
\r
3462 <pre><code>Data stack: ( s1 s2 n -- )</code></pre>
\r
3464 <div class="paragraph"><p>"STRNCPY" is a function words that copies n bytes of byte sequence s1
\r
3466 <div style="text-align:center">
\r
3467 _______________________________________________________
\r
3469 <div class="paragraph"><p><a id="p_swap"></a></p></div>
\r
3471 <div class="sect2">
\r
3472 <h3 id="_word_swap">Word: SWAP</h3>
\r
3473 <div class="literalblock">
\r
3474 <div class="content">
\r
3475 <pre><code>Data stack: ( v1 v2 -- v2 v1 )</code></pre>
\r
3477 <div class="paragraph"><p>"SWAP" is a function word the swaps the top two data stack cells.</p></div>
\r
3478 <div style="text-align:center">
\r
3479 _______________________________________________________
\r
3481 <div class="paragraph"><p><a id="p_system"></a></p></div>
\r
3483 <div class="sect2">
\r
3484 <h3 id="_word_system">Word: SYSTEM</h3>
\r
3485 <div class="literalblock">
\r
3486 <div class="content">
\r
3487 <pre><code>Data value: ( -- a )</code></pre>
\r
3489 <div class="paragraph"><p>"SYSTEM" is a variable that holds the word list data for the system
\r
3490 calls. This is set up as separate word list from <a href="#p_forth">FORTH</a>
\r
3491 merely as a matter of segregation.</p></div>
\r
3492 <div style="text-align:center">
\r
3493 _______________________________________________________
\r
3495 <div class="paragraph"><p><a id="p_tell"></a></p></div>
\r
3497 <div class="sect2">
\r
3498 <h3 id="_word_tell">Word: TELL</h3>
\r
3499 <div class="literalblock">
\r
3500 <div class="content">
\r
3501 <pre><code>Data stack: ( char* n -- )</code></pre>
\r
3503 <div class="paragraph"><p>"TELL" is a function word that prints a string to stdout (file
\r
3504 descriptor 1).</p></div>
\r
3505 <div style="text-align:center">
\r
3506 _______________________________________________________
\r
3508 <div class="paragraph"><p><a id="p_temp"></a></p></div>
\r
3510 <div class="sect2">
\r
3511 <h3 id="_word_temp_2">Word: TEMP</h3>
\r
3512 <div class="sidebarblock">
\r
3513 <div class="content">
\r
3514 <div class="paragraph"><p>Data stack: ( size — addr )</p></div>
\r
3516 <div class="paragraph"><p>"TEMP" is a function word that "allocates" a <a href="#p_tempspace">TEMPSPACE</a>
\r
3517 area of given size and returns its base address. The allocation is
\r
3518 temporary and only valid until there is a later allocation that
\r
3519 overruns this area.</p></div>
\r
3520 <div class="paragraph"><p>Allocations are done in succession until the requested size overruns
\r
3521 the <a href="#p_tempspace">TEMPSPACE</a>. If so, the allocation pointer is reset
\r
3522 and the space is allocated from start again. This is all intended for
\r
3523 small and short-lived data areas.</p></div>
\r
3524 <div style="text-align:center">
\r
3525 _______________________________________________________
\r
3527 <div class="paragraph"><p><a id="p_tempheld"></a></p></div>
\r
3529 <div class="sect2">
\r
3530 <h3 id="_word_tempheld">Word: TEMPHELD</h3>
\r
3531 <div class="literalblock">
\r
3532 <div class="content">
\r
3533 <pre><code>Data stack: ( -- a )</code></pre>
\r
3535 <div class="paragraph"><p>"TEMPHELD" is a variable word that keeps the lowest offset of the
\r
3536 <a href="#p__tempspace">TEMPSPACE</a> space to reuse upon cycling. The space
\r
3537 below TEMPHELD is "held" in the sense of not being reused upon
\r
3538 cycling. An application may change the TEMPSPACE offset as needed to
\r
3539 dynamically preserve memory longer term.</p></div>
\r
3540 <div style="text-align:center">
\r
3541 _______________________________________________________
\r
3543 <div class="paragraph"><p><a id="p_tempspace"></a></p></div>
\r
3545 <div class="sect2">
\r
3546 <h3 id="_word_tempspace">Word: TEMPSPACE</h3>
\r
3547 <div class="literalblock">
\r
3548 <div class="content">
\r
3549 <pre><code>Data stack: ( -- a )</code></pre>
\r
3551 <div class="paragraph"><p>"TEMPSPACE" is a variable word that holds three cells the for managing
\r
3552 "temporary memory":</p></div>
\r
3553 <div class="ulist"><ul>
\r
3556 the size of the temporary memory space (default 104857600 bytes)
\r
3561 the base address for whole temporary memory area
\r
3566 the amount currently used
\r
3570 <div class="paragraph"><p>This memory is intended to be used by requesting snippets of memory in
\r
3571 a cyclic fashion via <a href="#p_temp">TEMP</a> without concern about it possibly
\r
3572 overlapping a prior request.</p></div>
\r
3573 <div style="text-align:center">
\r
3574 _______________________________________________________
\r
3576 <div class="paragraph"><p><a id="p_terminate0"></a></p></div>
\r
3578 <div class="sect2">
\r
3579 <h3 id="_word_terminate0">Word: TERMINATE0</h3>
\r
3580 <div class="literalblock">
\r
3581 <div class="content">
\r
3582 <pre><code>Data stack: ( -- )</code></pre>
\r
3584 <div class="paragraph"><p>"TERMINATE0" is a function word that terminates the program with exit
\r
3586 <div style="text-align:center">
\r
3587 _______________________________________________________
\r
3589 <div class="paragraph"><p><a id="p_tfa2cfa"></a></p></div>
\r
3591 <div class="sect2">
\r
3592 <h3 id="_word_tfa_gt_cfa">Word: TFA>CFA</h3>
\r
3593 <div class="literalblock">
\r
3594 <div class="content">
\r
3595 <pre><code>Data stack: ( tfa -- cfa )</code></pre>
\r
3597 <div class="paragraph"><p>"TFA>CFA" is a function word that pushes word cfa of the given tfa.</p></div>
\r
3598 <div class="exampleblock">
\r
3599 <div class="content">
\r
3600 <div class="sidebarblock">
\r
3601 <div class="content">
\r
3602 <div class="title">Definition concept for TFA>CFA</div>
\r
3603 <div class="paragraph"><p>: TFA>CFA 8 + @ ;</p></div>
\r
3606 <div style="text-align:center">
\r
3607 _______________________________________________________
\r
3609 <div class="paragraph"><p><a id="p_tfa2dfa"></a></p></div>
\r
3611 <div class="sect2">
\r
3612 <h3 id="_word_tfa_gt_dfa">Word: TFA>DFA</h3>
\r
3613 <div class="literalblock">
\r
3614 <div class="content">
\r
3615 <pre><code>Data stack: ( tfa -- dfa )</code></pre>
\r
3617 <div class="paragraph"><p>"TFA>DFA" is a function word that pushes word dfa of the given tfa.</p></div>
\r
3618 <div class="exampleblock">
\r
3619 <div class="content">
\r
3620 <div class="sidebarblock">
\r
3621 <div class="content">
\r
3622 <div class="title">Definition concept for TFA>DFA</div>
\r
3623 <div class="paragraph"><p>: TFA>DFA TFA>CFA 8 + ;</p></div>
\r
3626 <div style="text-align:center">
\r
3627 _______________________________________________________
\r
3629 <div class="paragraph"><p><a id="p_tfa2flags_get"></a></p></div>
\r
3631 <div class="sect2">
\r
3632 <h3 id="_word_tfa_gt_flags">Word: TFA>FLAGS@</h3>
\r
3633 <div class="literalblock">
\r
3634 <div class="content">
\r
3635 <pre><code>Data stack: ( tfa -- flags )</code></pre>
\r
3637 <div class="paragraph"><p>"TFA>FLAGS@" is a function word that pushes word flags of the given tfa.</p></div>
\r
3638 <div class="exampleblock">
\r
3639 <div class="content">
\r
3640 <div class="sidebarblock">
\r
3641 <div class="content">
\r
3642 <div class="title">Defintion concept for TFA>FLAGS@</div>
\r
3643 <div class="paragraph"><p>: TFA>FLAGS@ 16 + @ ;</p></div>
\r
3646 <div style="text-align:center">
\r
3647 _______________________________________________________
\r
3649 <div class="paragraph"><p><a id="p_tfa2namez"></a></p></div>
\r
3651 <div class="sect2">
\r
3652 <h3 id="_word_tfa_gt_namez">Word: TFA>NAMEZ</h3>
\r
3653 <div class="literalblock">
\r
3654 <div class="content">
\r
3655 <pre><code>Data stack: ( tfa -- char* )</code></pre>
\r
3657 <div class="paragraph"><p>"TFA>NAMEZ" is a function word that pushes changes a tfa pointer to a
\r
3658 pointer to the word pname’s character sequence, which is zero
\r
3659 terminated as well as preceded by a length cell.</p></div>
\r
3660 <div class="exampleblock">
\r
3661 <div class="content">
\r
3662 <div class="sidebarblock">
\r
3663 <div class="content">
\r
3664 <div class="title">Defintion concept for TFA>NAMEZ</div>
\r
3665 <div class="paragraph"><p>: TFA>NAMEZ 32 + ;</p></div>
\r
3668 <div style="text-align:center">
\r
3669 _______________________________________________________
\r
3671 <div class="paragraph"><p><a id="p_then"></a></p></div>
\r
3673 <div class="sect2">
\r
3674 <h3 id="_word_then">Word: THEN</h3>
\r
3675 <div class="literalblock">
\r
3676 <div class="content">
\r
3677 <pre><code>Data stack: Compiling: ( a -- )</code></pre>
\r
3679 <div class="paragraph"><p>"THEN" is an immediate function word that is used together with
\r
3680 <a href="#p_if">IF</a> and <a href="#p_else">ELSE</a> to implement structured execution
\r
3681 control. THEN performs the branch resolution for the stacked address
\r
3682 which pinpoints the foot address the branch offset to resolve, so that
\r
3683 at execution time there is an appropriate conditional branch past the
\r
3684 "then-part" or the "else-part" of the "structured statement".</p></div>
\r
3685 <div style="text-align:center">
\r
3686 _______________________________________________________
\r
3688 <div class="paragraph"><p><a id="p_this_word"></a></p></div>
\r
3690 <div class="sect2">
\r
3691 <h3 id="_word_this_word">Word: THIS-WORD</h3>
\r
3692 <div class="literalblock">
\r
3693 <div class="content">
\r
3694 <pre><code>Data stack: ( -- a )</code></pre>
\r
3696 <div class="paragraph"><p>"THIS-WORD" is a variable word used in
\r
3697 <a href="#p_evaluate_stream:EVALUATE-STREAM">[p_evaluate_stream:EVALUATE-STREAM]</a> as cache for the [n:char*]
\r
3698 values of the successive words being evaluated. This typically points
\r
3699 into the input stream buffer and remain valid until further stream
\r
3700 buffering functions are used.</p></div>
\r
3701 <div style="text-align:center">
\r
3702 _______________________________________________________
\r
3704 <div class="paragraph"><p><a id="p_true"></a></p></div>
\r
3706 <div class="sect2">
\r
3707 <h3 id="_word_true">Word: TRUE</h3>
\r
3708 <div class="literalblock">
\r
3709 <div class="content">
\r
3710 <pre><code>Data stack: ( -- -1 )</code></pre>
\r
3712 <div class="paragraph"><p>"TRUE" is a value word representing logical true.</p></div>
\r
3713 <div style="text-align:center">
\r
3714 _______________________________________________________
\r
3716 <div class="paragraph"><p><a id="p_tuck"></a></p></div>
\r
3718 <div class="sect2">
\r
3719 <h3 id="_word_tuck">Word: TUCK</h3>
\r
3720 <div class="literalblock">
\r
3721 <div class="content">
\r
3722 <pre><code>Data stack ( v1 v2 -- v2 v1 v2 )</code></pre>
\r
3724 <div class="paragraph"><p>"TUCK" is a function word that "inserts" the top cell below the second
\r
3725 cell on the data stack.</p></div>
\r
3726 <div class="exampleblock">
\r
3727 <div class="content">
\r
3728 <div class="sidebarblock">
\r
3729 <div class="content">
\r
3730 <div class="title">Definition concept for TUCK</div>
\r
3731 <div class="paragraph"><p>: TUCK SWAP OVER ;</p></div>
\r
3734 <div style="text-align:center">
\r
3735 _______________________________________________________
\r
3737 <div class="paragraph"><p><a id="p_unequal"></a></p></div>
\r
3739 <div class="sect2">
\r
3740 <h3 id="_word_19">Word: !=</h3>
\r
3741 <div class="literalblock">
\r
3742 <div class="content">
\r
3743 <pre><code>Data stack: ( v1 v2 -- 0/-1 )</code></pre>
\r
3745 <div class="paragraph"><p>"!=" is a function word that replaces a pair of values with -1 of the
\r
3746 values are unequal, and 0 otherwise.</p></div>
\r
3747 <div style="text-align:center">
\r
3748 _______________________________________________________
\r
3750 <div class="paragraph"><p><a id="p_unstream"></a></p></div>
\r
3752 <div class="sect2">
\r
3753 <h3 id="_word_unstream">Word: UNSTREAM</h3>
\r
3754 <div class="literalblock">
\r
3755 <div class="content">
\r
3756 <pre><code>Data stack: ( stream* -- )</code></pre>
\r
3758 <div class="paragraph"><p>"UNSTREAM" is a function word that releases the memory allocated for a
\r
3759 stream, and closes the associated file if it’s a file stream.</p></div>
\r
3760 <div class="sect3">
\r
3761 <h4 id="_file_descriptor_backed_stream_2">File descriptor backed stream</h4>
\r
3762 <div class="paragraph"><p>This kind of stream has the stream header as a prefix within the
\r
3763 allocated memory. Thus, stream* is the base address for the memory to
\r
3764 reclaim, and the size of this is determined from the cell at (stream*
\r
3765 + 16) plus the 32 bytes head itself.</p></div>
\r
3767 <div class="sect3">
\r
3768 <h4 id="_memory_block_backed_stream_2">Memory block backed STREAM</h4>
\r
3769 <div class="paragraph"><p>This kind of stream has a separate header which points at the memory
\r
3770 area to reclaim. The cell at stream* is the base address, and the cell
\r
3771 at (stream* + 16) is its size.</p></div>
\r
3772 <div style="text-align:center">
\r
3773 _______________________________________________________
\r
3775 <div class="paragraph"><p><a id="p_use"></a></p></div>
\r
3778 <div class="sect2">
\r
3779 <h3 id="_word_use">Word: USE</h3>
\r
3780 <div class="literalblock">
\r
3781 <div class="content">
\r
3782 <pre><code>Data value: ( wordlist -- ) Input stream: word</code></pre>
\r
3784 <div class="paragraph"><p>"USE" is a function word that looks up next word given the wordlist.
\r
3785 It reads next word on <a href="#p_input">INPUT</a> via <a href="#p_read_word">READ-WORD</a>,
\r
3786 then temporarily changes <a href="#p_current_wordlist">CURRENT-WORDLIST</a> to
\r
3787 <a href="#p_find">FIND</a> the word via the given wordlist, and returns the TFA
\r
3788 of that word, or just 0 if the word coudn’t be found.</p></div>
\r
3789 <div style="text-align:center">
\r
3790 _______________________________________________________
\r
3792 <div class="paragraph"><p><a id="p_verboseQ"></a></p></div>
\r
3794 <div class="sect2">
\r
3795 <h3 id="_word_verbose">Word: VERBOSE?</h3>
\r
3796 <div class="literalblock">
\r
3797 <div class="content">
\r
3798 <pre><code>Data stack: ( -- a )</code></pre>
\r
3800 <div class="paragraph"><p>"VERBOSE?" is a variable word that is assigned at start up to -1 or 0
\r
3801 signify whether or not the command line arguments includes "-v". When
\r
3802 non-zero (i.e. running rrqforth with "-v") the evaluation loop is more
\r
3803 verbose.</p></div>
\r
3804 <div style="text-align:center">
\r
3805 _______________________________________________________
\r
3807 <div class="paragraph"><p><a id="p_within"></a></p></div>
\r
3809 <div class="sect2">
\r
3810 <h3 id="_word_within">Word: WITHIN</h3>
\r
3811 <div class="literalblock">
\r
3812 <div class="content">
\r
3813 <pre><code>Data stack: ( v lo hi -- 0/-1</code></pre>
\r
3815 <div class="paragraph"><p>"WITHIN" is a function word that replaces a triple of values with -1
\r
3816 of the the first, v, is within the value range spanned by the second,
\r
3817 lo, inclusive and third, hi, exclusive.</p></div>
\r
3818 <div class="exampleblock">
\r
3819 <div class="content">
\r
3820 <div class="sidebarblock">
\r
3821 <div class="content">
\r
3822 <div class="title">Definition concept for WITHIN</div>
\r
3823 <div class="paragraph"><p>: WITHIN 2 PICK > ROT ROT ⇐ AND ;</p></div>
\r
3826 <div style="text-align:center">
\r
3827 _______________________________________________________
\r
3829 <div class="paragraph"><p><a id="p_words"></a></p></div>
\r
3831 <div class="sect2">
\r
3832 <h3 id="_word_words">Word: WORDS</h3>
\r
3833 <div class="literalblock">
\r
3834 <div class="content">
\r
3835 <pre><code>Data stack: ( wl -- )</code></pre>
\r
3837 <div class="paragraph"><p>"WORDS" is a function word that prints all words of teh given word
\r
3838 list to stdout (file descriptor 1).</p></div>
\r
3839 <div style="text-align:center">
\r
3840 _______________________________________________________
\r
3842 <div class="paragraph"><p><a id="p_xor"></a></p></div>
\r
3844 <div class="sect2">
\r
3845 <h3 id="_word_xor">Word: XOR</h3>
\r
3846 <div class="literalblock">
\r
3847 <div class="content">
\r
3848 <pre><code>Data stack: ( v1 v2 -- v3 )</code></pre>
\r
3850 <div class="paragraph"><p>"XOR" is a function word that replaces a value pair with their bitwise
\r
3851 exclusion; each bit is 1 if the corresponding bits of the two operands
\r
3852 differ and 0 if not.</p></div>
\r
3853 <div style="text-align:center">
\r
3854 _______________________________________________________
\r
3856 <div class="paragraph"><p><a id="return_stack"></a></p></div>
\r
3858 <div class="sect2">
\r
3859 <h3 id="_word_return_stack">Word: RETURN-STACK</h3>
\r
3860 <div class="literalblock">
\r
3861 <div class="content">
\r
3862 <pre><code>Data stack: ( -- a )</code></pre>
\r
3864 <div class="paragraph"><p>"RETURN-STACK" is a variable word harbouring the return stack.</p></div>
\r
3868 <div class="sect1">
\r
3869 <h2 id="_system_calls">System calls</h2>
\r
3870 <div class="sectionbody">
\r
3871 <div class="paragraph"><p>RRQFORTH includes function wrapping for all "Linux syscalls", which
\r
3872 generally are described in their "man pages. This wrapping takes the
\r
3873 arguments fro the data stack in reverse order, i.e. the first argument
\r
3874 is deepest.</p></div>
\r
3875 <div class="paragraph"><p>Use <code>SYSTEM WORDS</code> to get a list of all (321) available syscalls.</p></div>
\r
3879 <div id="footnotes"><hr /></div>
\r
3881 <div id="footer-text">
\r
3883 2021-06-15 14:28:03 AEST
\r
projects / rrq / rrqforth.git / blob