<a href="#p_put">!</a>  \r
<a href="#p_Cget">C@</a>  \r
<a href="#p_Cput">C!</a>  \r
+<a href="#p_Wget">W@</a>  \r
+<a href="#p_Wput">W!</a>  \r
+<a href="#p_Dget">D@</a>  \r
+<a href="#p_Dput">D!</a>  \r
<a href="#p_2get">2@</a>  \r
<a href="#p_2put">2!</a>  \r
<a href="#p_put_plus">!+</a>  \r
<a href="#p_get_n_increment">@n++</a>  \r
<a href="#p_get_n_decrement">@n--</a>  \r
<a href="#p_Ccomma">C,</a>  \r
-<a href="#p_literal_string">S"</a>  \r
+<a href="#p_Wcomma">W,</a>  \r
+<a href="#p_Dcomma">D,</a>  \r
+<a href="#p_literal_string_compile">S"</a>  \r
<a href="#p_gtR">>R</a>  \r
<a href="#p_Rget">R@</a>  \r
<a href="#p_Rgt">R></a>  \r
-<a href="#p_rsp">R[n]</a>  </p></div>\r
+<a href="#p_rbpn">R[n]</a>  </p></div>\r
<div class="paragraph"><p><a href="#data_stack">DATA-STACK</a>  \r
<a href="#return_stack">RETURN-STACK</a>  \r
 \r
<a href="#p_2over">2OVER</a>  \r
<a href="#p_2swap">2SWAP</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_abs">ABS</a>  \r
+<a href="#p_again">AGAIN</a>  \r
<a href="#p_allot">ALLOT</a>  \r
<a href="#p_and">AND</a>  \r
<a href="#inline_code">[ASM]</a>  </p></div>\r
<a href="#p_begin">BEGIN</a>  \r
<a href="#p_break">BREAK</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_cfa2flags_get">CFA>FLAGS@</a>  \r
+<a href="#p_cfa2tfa">CFA>TFA</a>  \r
<a href="#p_clear_stream">CLEAR-STREAM</a>  \r
<a href="#p_create">CREATE</a>  \r
<a href="#p_current_wordlist">CURRENT-WORDLIST</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_decimal">DECIMAL</a>  \r
+<a href="#p_definitions">DEFINITIONS</a>  \r
<a href="#p_depth">DEPTH</a>  \r
<a href="#p_digits">DIGITS</a>  \r
<a href="#p_divmod">/MOD</a>  \r
<a href="#p_execute">EXECUTE</a>  \r
<a href="#p_exit">EXIT</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_false">FALSE</a>  \r
+<a href="#p_fdemit">FDEMIT</a>  \r
+<a href="#p_fdtell">FDTELL</a>  \r
<a href="#p_find">FIND</a>  \r
<a href="#p_forth">FORTH</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_here">HERE</a>  \r
<div class="paragraph"><p><a href="#p_if">IF</a>  \r
<a href="#p_ifagain">IFAGAIN</a>  \r
<a href="#p_ifbreak">IFBREAK</a>  \r
-<a href="#p_immediate">IMMEDIATE</a>  </p></div>\r
+<a href="#p_immediate">IMMEDIATE</a>  \r
+<a href="#p_input">INPUT</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_literal">LIT</a>  \r
-<a href="#p_load_file_quote">LOAD-FILE"</a>  </p></div>\r
+<a href="#p_literal_string">LIT-STRING</a>  \r
+<a href="#p_load_buffer_size">LOAD-BUFFER-SIZE</a>  \r
+<a href="#p_load_file">LOAD-FILE</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_args">MAIN-ARGS</a>  \r
<a href="#p_malloc">MALLOC</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_negate">NEGATE</a>  \r
<a href="#p_nl">NL</a>  \r
<a href="#p_not">NOT</a>  \r
<a href="#p_number">NUMBER</a>  </p></div>\r
-<div class="paragraph"><p><a href="#p_open_file_quote">OPEN-FILE"</a>  \r
+<div class="paragraph"><p><a href="#p_open_file">OPEN-FILE</a>  \r
<a href="#p_or">OR</a>  \r
<a href="#p_over">OVER</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_pad">PAD</a>  \r
<div class="paragraph"><p><a href="#p_read_stream_char">READ-STREAM-CHAR</a>  \r
<a href="#p_read_word">READ-WORD</a>  \r
<a href="#p_realloc">REALLOC</a>  \r
+<a href="#p_return">RETURN</a>  \r
<a href="#p_roll">ROLL</a>  \r
-<a href="#p_rot">ROT</a>  </p></div>\r
+<a href="#p_rot">ROT</a>  \r
+<a href="#p_rbp">RSP</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_sp">SP</a>  \r
<a href="#p_state">STATE</a>  \r
<a href="#p_stdin">STDIN</a>  \r
<a href="#p_stream">STREAM</a>  \r
<a href="#p_stream_nchars">STREAM-NCHARS</a>  \r
+<a href="#p_str2temp">STR>TEMP</a>  \r
<a href="#p_strlen">STRLEN</a>  \r
<a href="#p_strncmp">STRNCMP</a>  \r
<a href="#p_strncpy">STRNCPY</a>  \r
<a href="#p_swap">SWAP</a>  \r
<a href="#p_system">SYSTEM</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_tell">TELL</a>  \r
+<a href="#p_dot_temp">.TEMP</a>  \r
+<a href="#p_temp.adoc">TEMP</a>  \r
+<a href="#p_tempspace">TEMPSPACE</a>  \r
<a href="#p_terminate0">TERMINATE0</a>  \r
<a href="#p_tfa2cfa">TFA>CFA</a>  \r
<a href="#p_tfa2dfa">TFA>DFA</a>  \r
<a href="#p_this_word">THIS-WORD</a>  \r
<a href="#p_true">TRUE</a>  \r
<a href="#p_tuck">TUCK</a>  </p></div>\r
+<div class="paragraph"><p><a href="#p_unstream">UNSTREAM</a>  \r
+<a href="#p_use">USE</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_verboseQ">VERBOSE?</a>  </p></div>\r
<div class="paragraph"><p><a href="#p_within">WITHIN</a>  \r
<a href="#p_words">WORDS</a>  </p></div>\r
forthcode:</code></pre>\r
</div></div>\r
</div></div>\r
+<div class="paragraph"><p>Note that the FORTH compiler does not invoke an assembler so any\r
+inline assembly code must be provided in its binary form.</p></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
the point of execution. If the value, v, is 0 then the branch offset\r
is added, and otherwise execution continues with the cell following\r
the branch offset in the definition.</p></div>\r
+<div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a\r
+definition take up a cell of 8 bytes. The offset is relative to the\r
+cell address immediately subsequent to the offset cell. In other\r
+words, offset 0 is not branching anywhere and an offset of -16 would\r
+make a tight loop back to the branch instruction itself. The latter\r
+would pull data stack values until and including the first non-zero\r
+value.</p></div>\r
+<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
+<a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
<div class="paragraph"><p>"0=" is a function word that replaces a value with its logical\r
complement; the result is zero if the value non-zero, and the result\r
is non-zero if the value is zero.</p></div>\r
-<div class="paragraph"><p>
Compare with <a href="#p_not">NOT</a>.</p></div>
\r+<div class="paragraph"><p>
This is the same function as <a href="#p_not">NOT</a>.</p></div>
\r <div style="text-align:center">\r
_______________________________________________________\r
</div>\r
less than 0, and 0 otherwise.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 1: Word: 0<</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: 0= 0 SWAP < ;</code></pre>\r
+<div class="title">Definition concept for 0<</div>\r
+<div class="paragraph"><p>( v — 0/1 ) : 0= 0 SWAP < ;</p></div>\r
</div></div>\r
</div></div>\r
-<div class="paragraph"><p>See also <a href="#p_swap">SWAP</a> and\r
-<a href="#p_lessthan"><</a>.</p></div>\r
+<div class="paragraph"><p>See also <a href="#p_swap">SWAP</a> and <a href="#p_lessthan"><</a>.</p></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
the point of execution. If the value, v, is non-zero then the branch\r
offset is added, and otherwise execution continues with the cell\r
following the branch offset in the definition.</p></div>\r
+<div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a\r
+definition take up a cell of 8 bytes. The offset is relative to the\r
+cell address immediately subsequent to the offset cell. In other\r
+words, offset 0 is not branching anywhere and an offset of -16 would\r
+make a tight loop back to the branch instruction itself. The latter\r
+would pull data stack values until and including the first zero value.</p></div>\r
+<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
+<a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
stack.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 2: Word: 2DUP</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: 2DUP OVER OVER ;</code></pre>\r
+<div class="title">Definition concept for 2DUP</div>\r
+<div class="paragraph"><p>( v1 v2 — v1 v2 v1 v2 ) : 2DUP OVER OVER ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
working with cell pairs rather than single cells.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 3: Word: 2OVER</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: 2OVER 3 PICK 3 PICK ;</code></pre>\r
+<div class="title">Definition concept for 2OVER</div>\r
+<div class="paragraph"><p>( v1 v2 v3 v4 — v1 v2 v3 v4 v1 v2 ) : 2OVER 3 PICK 3 PICK ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
working with cell pairs rather than single cells.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 4: Word: 2SWAP</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: 2SWAP 3 ROLL 3 ROOL ;</code></pre>\r
+<div class="title">Definition concept for 2SWAP</div>\r
+<div class="paragraph"><p>( v1 v2 v3 v4 — v3 v4 v1 v2 ) : 2SWAP 3 ROLL 3 ROLL ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
at the current free head address, which also is incremented.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 5: Word: C,</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: C, HERE @ 1 ALLOT C! ; ( v -- ; Claim 1 byte and put lsb value there )</code></pre>\r
+<div class="title">Definition concept for C,</div>\r
+<div class="paragraph"><p>: C, HERE @ 1 ALLOT C! ; ( v — ; Claim 1 byte and put lsb value there )</p></div>\r
</div></div>\r
</div></div>\r
<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
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_Wcomma"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_w">Word: W,</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( v -- )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"W," (W-comma) is a function word that puts a "word" (double-byte) on\r
+the <a href="#p_here">HERE</a> heap. The two least significant bytes of the value\r
+are put at the current free head address, which also is incremented\r
+accordingly.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="sidebarblock">\r
+<div class="content">\r
+<div class="title">Definition concept for W,</div>\r
+<div class="paragraph"><p>: W, HERE @ 2 ALLOT W! ;</p></div>\r
+</div></div>\r
+</div></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
+<div class="paragraph"><p><a id="p_Dcomma"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_d">Word: D,</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( v -- )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"D," (D-comma) is a function word that puts a "double word"\r
+(double-byte) on the <a href="#p_here">HERE</a> heap. The four least significant\r
+bytes of the value are put at the current free head address, which\r
+also is incremented accordingly.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="sidebarblock">\r
+<div class="content">\r
+<div class="title">Definition concept for D,</div>\r
+<div class="paragraph"><p>: D, HERE @ 4 ALLOT D! ;</p></div>\r
+</div></div>\r
+</div></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
+<div class="paragraph"><p><a id="p_cfa2tfa"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_cfa_gt_tfa">Word: CFA>TFA</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( cfa -- tfa )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"CFA>TFA" is a function word that pushes word tfa of the given cfa.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="sidebarblock">\r
+<div class="content">\r
+<div class="title">Definition concept for CFA>TFA</div>\r
+<div class="paragraph"><p>: CFA>TFA 14 - @ ;</p></div>\r
+</div></div>\r
+</div></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p><a id="p_Cget"></a></p></div>\r
</div>\r
<div class="sect2">\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_Wget"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_w_2">Word: W@</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( a -- v )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"W@" is a function word that pushes the "word" (double-byte) value v\r
+from the address a.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
+<div class="paragraph"><p><a id="p_Rget"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_r">Word: R@</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( -- v ) Return stack: ( v -- v )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"R@" is a function word that "copies" the top return stack value onto\r
+the data stack.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p><a id="p_Cput"></a></p></div>\r
</div>\r
<div class="sect2">\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_Wput"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_w_3">Word: W!</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( v a -- )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"W!" is a function word that stores the "word" (2-byte) value v (the\r
+two least significant bytes of the cell) at the address a.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
+<div class="paragraph"><p><a id="p_Dput"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_d_2">Word: D!</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( v a -- )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"D!" is a function word that stores the "doublw word" (4-byte) value v\r
+(the four least significant bytes of the cell) at the address a.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p><a id="p_Rget"></a></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_word_r">Word: R@</h3>\r
+<h3 id="_word_r_2">Word: R@</h3>\r
<div class="literalblock">\r
<div class="content">\r
<pre><code>Data stack: ( -- v ) Return stack: ( v -- v )</code></pre>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_again"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_again">Word: AGAIN</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: Compiling: ( -- a )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"AGAIN" is an immediate function word that is used together with\r
+<a href="#p_begin">BEGIN</a> and instead of <a href="#p_end">END</a> to implement structured\r
+execution control. AGAIN scans the datastack for the nearest preceding\r
+BEGIN marker and lays out an unconditional branch from this point the\r
+beginning of the block during execution. It thereafter performs the\r
+<a href="#p_end">END</a> compile action to end the block.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p><a id="p_allot"></a></p></div>\r
</div>\r
<div class="sect2">\r
supported.</p></div>\r
<div class="paragraph"><p>See also <a href="#p_digits">DIGITS</a>, which holds the mapping table from\r
digits to text.</p></div>\r
-<div class="exampleblock">\r
-<div class="content">\r
-<div class="paragraph"><div class="title">Usage example 3: claim 16 bytes for variable FOO</div><p>CREATE FOO BASE</p></div>\r
-</div></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
address for resolving branches back to this point during execution,\r
and then a 0 as a marker so as to allow for an unknown number of block\r
exit points.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="listingblock">\r
+<div class="title">Usage example 3:</div>\r
+<div class="content">\r
+<pre><code>: WTELL ( tfa -- ; Print word pname )\r
+ 24 + DUP 8 + SWAP @ TELL SP EMIT\r
+;\r
+\r
+: WORDS ( wordlist -- ; Print all words of word list )\r
+ BEGIN\r
+ @ DUP 0= IFBREAK\r
+ DUP WTELL\r
+ END\r
+ DROP\r
+ NL EMIT\r
+;</code></pre>\r
+</div></div>\r
+</div></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
</div></div>\r
<div class="paragraph"><p>"[']" is an immediate function word that reads the next word on the\r
input stream and pushes its cfa.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="sidebarblock">\r
+<div class="content">\r
+<div class="title">Definition concept for [']</div>\r
+<div class="paragraph"><p>: ['] IMMEDIATE ' ;</p></div>\r
+</div></div>\r
+</div></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
<div class="paragraph"><p>"BRANCH" is a function word that implements execution transfer by\r
means of adding the subsequent branch offset to the point of\r
execution.</p></div>\r
+<div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a\r
+definition take up a cell of 8 bytes. The offset is relative to the\r
+cell address immediately subsequent to the offset cell. In other\r
+words, offset 0 is not branching anywhere and an offset of -16 would\r
+make a tight loop back to the branch instruction itself. The latter\r
+would pull data stack values until and including the first zero value.</p></div>\r
+<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
+<a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
Similar to <a href="#p_ifbreak">IFBREAK</a> it lays out the branch cell\r
followed by a reserved cell for the branch offset, and inserts the\r
resolution address just above the required 0 on the data stack.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="listingblock">\r
+<div class="title">Usage example 4: unconditional break with a condition.</div>\r
+<div class="content">\r
+<pre><code>: WTELL ( tfa -- ; Print word pname )\r
+ 24 + DUP 8 + SWAP @ TELL SP EMIT\r
+;\r
+\r
+: WORDS ( wordlist -- ; Print all words of word list )\r
+ BEGIN\r
+ @ DUP IF DUP WTELL ELSE BREAK THEN\r
+ 1 IFAGAIN\r
+ END\r
+ DROP\r
+ NL EMIT\r
+;</code></pre>\r
+</div></div>\r
+</div></div>\r
+<div class="paragraph"><p>See also <a href="#p_branch">BRANCH</a>, <a href="#p_0branch">0BRANCH</a>,\r
+<a href="#p_1branch">1BRANCH</a>, <a href="#p_if">IF</a>, <a href="#p_else">ELSE</a>,\r
+<a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
and setting evaluation state to compiling mode.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 6: Word: :</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: : doFORTH READ-WORD CREATE TFA>CFA ! ] ;</code></pre>\r
+<div class="title">Definition concept for :</div>\r
+<div class="paragraph"><p>: : doFORTH READ-WORD CREATE TFA>CFA ! ] ;</p></div>\r
</div></div>\r
</div></div>\r
<div class="paragraph"><p>See also <a href="#p_doforth">doFORTH</a>, <a href="#p_read_word">READ-WORD</a>,\r
<a href="#p_here">HERE</a> heap.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept7: Word: ,</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: , HERE @ 8 ALLOT ! ; ( v -- ; Claim 8 bytes and put value there )</code></pre>\r
+<div class="title">Definition concept for ,</div>\r
+<div class="paragraph"><p>: , HERE @ 8 ALLOT ! ; ( v — ; Claim 8 bytes and put value there )</p></div>\r
</div></div>\r
</div></div>\r
<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
<div class="exampleblock">\r
<div class="content">\r
<div class="listingblock">\r
+<div class="title">Layout 1: rrqforth word structure</div>\r
<div class="content">\r
<pre><code>struct WORD\r
TFA 8 link ; tfa of previous word\r
for RRQFORTH constants created by "CONSTANT".</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 8: Word: CREATE</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>HERE @ R> ( save tfa on RS )\r
+<div class="title">Definition concept for CREATE</div>\r
+<div class="paragraph"><p>HERE @ R> ( save tfa on RS )\r
R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )\r
DUP 49 + R@ + , ( pCFA )\r
0 , ( flags )\r
HERE @ ROT ROT MEMCPY 0 C, ( pname + NUL )\r
R@ , ( pTFA )\r
0 , ( OFF )\r
- doVARIABLE ( CFA, default semantics )</code></pre>\r
+ doVARIABLE ( CFA, default semantics )</p></div>\r
</div></div>\r
</div></div>\r
-<div class="sidebarblock">\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="listingblock">\r
+<div class="title">Usage example 5: a possible definition of CONSTANT</div>\r
<div class="content">\r
-<div class="title">Usage example: a possible definition of CONSTANT</div>\r
-<div class="paragraph"><p>: CONSTANT READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! ! ;</p></div>\r
+<pre><code>: CONSTANT READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! ! ;</code></pre>\r
+</div></div>\r
</div></div>\r
<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
<a href="#p_Ccomma">[p_Ccomma]</a>, <a href="#p_current_word">CURRENT-WORD</a>, <a href="#p_dup">DUP</a>,\r
<div class="exampleblock">\r
<div class="content">\r
<div class="listingblock">\r
-<div class="title">Layout 1: word list word content</div>\r
+<div class="title">Layout 2: word list word content</div>\r
<div class="content">\r
<pre><code> 8 TFA of latest word in the word list\r
8 DFA of the/a subsequent word list to search through</code></pre>\r
<div class="paragraph"><p>"DECIMAL" is a function word that sets <a href="#p_base">BASE</a> to 10.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 9: Word: DECIMAL</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: DECIMAL 10 BASE ! ;</code></pre>\r
+<div class="title">Definition concept for DECIMAL</div>\r
+<div class="paragraph"><p>: DECIMAL 10 BASE ! ;</p></div>\r
+</div></div>\r
+</div></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
+<div class="paragraph"><p><a id="p_definitions"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_definitions">Word: DEFINITIONS</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( wordlist -- )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"DEFINITIONS" is a function word that installs the given wordlist as\r
+the <a href="#p_current_wordlist">CURRENT-WORDLIST</a> one.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="sidebarblock">\r
+<div class="content">\r
+<div class="title">Definition concept for DEFINITIONS</div>\r
+<div class="paragraph"><p>: DEFINITIONS CURRENT-WORDLIST ! ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
have its execution start at whatever comes after "DOES>".</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Word: DOES></div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: DOES> IMMEDIATE\r
+<div class="title">Defintion concept for DOES></div>\r
+<div class="paragraph"><p>: DOES> IMMEDIATE\r
STATE @ != IF ( only for compilation mode )\r
CURRENT-WORDLIST @ @ TFA>CFA ( cfa of current word )\r
doDOES OVER ! ( set up doer )\r
HERE @ OVER 8 + - SWAP 8 - ! ( set up offset\r
THEN\r
-;</code></pre>\r
+;</p></div>\r
</div></div>\r
</div></div>\r
<div class="paragraph"><p>See also\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_dot_temp"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_temp">Word: .TEMP</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( v -- char* n )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>".TEMP" is a function word that renders a cell value as an integer\r
+using the current <a href="#p_base">BASE</a>, which is either\r
+<a href="#p_decimal">DECIMAL</a> or <a href="#p_hex">HEX</a>. In <a href="#p_decimal">DECIMAL</a>\r
+<a href="#p_base">BASE</a>, a negative value is rendered as such with a leading\r
+minus sign, whereas <a href="#p_hex">HEX</a> <a href="#p_base">BASE</a> rendering is\r
+unsigned.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p><a id="p_double_quote"></a></p></div>\r
</div>\r
<div class="sect2">\r
stack while reading, parsing and executing.</p></div>\r
<div class="paragraph"><p>If "EVALUATE-STREAM" ends with 0, then <a href="#p_this_word">THIS-WORD</a> holds\r
the [n:chars] reference of the offending word in the stream buffer.</p></div>\r
-<div class="exampleblock">\r
-<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 10: Word: EVALUATE-STREAM</div>\r
-<div class="content">\r
-<pre><code>( too complex to include here )</code></pre>\r
-</div></div>\r
-</div></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
<h3 id="_word_exit">Word: EXIT</h3>\r
<div class="literalblock">\r
<div class="content">\r
-<pre><code>Data stack: ( -- )</code></pre>\r
+<pre><code>Data stack: ( v -- )</code></pre>\r
</div></div>\r
-<div class="paragraph"><p>"EXIT" is a function word that implements the ending of a FORTH\r
-definition and its threading to the subsequent step of the calling\r
-definition.</p></div>\r
+<div class="paragraph"><p>"EXIT" is a function word that terminates the <code>rrqforth</code> process\r
+immediately with the given exit code.</p></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_fdemit"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_fdemit">Word: FDEMIT</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( c fd -- )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"FDEMIT" is a function word that puts the given character code to the\r
+given file descriptor. The character is the least significant byte of\r
+the data stack cell.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
+<div class="paragraph"><p><a id="p_fdtell"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_fdtell">Word: FDTELL</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( char* n fd -- )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"FDTELL" is a function word that prints a string to the given file\r
+descriptor.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p><a id="p_find"></a></p></div>\r
</div>\r
<div class="sect2">\r
then decrements the cell at that address by n.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Defintion concept 11Word: @n++</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: @n++ OVER @ DUP ROT - ROT ! ;</code></pre>\r
+<div class="title">Defintion concept for @n++</div>\r
+<div class="paragraph"><p>: @n++ OVER @ DUP ROT - ROT ! ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
</div></div>\r
<div class="paragraph"><p>"HERE" is a variable word that keeps the lowest address of the free\r
allocation space. It get updated by all words that allocate memory.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
<div class="sidebarblock">\r
<div class="content">\r
-<div class="title">Usage example</div>\r
-<div class="paragraph"><p>1024 HEAP @ + HEAP ! ( allocate 1024 bytes on the heap )</p></div>\r
+<div class="title">allocate 1024 bytes on the heap</div>\r
+<div class="paragraph"><p>1024 HEAP @ + HEAP !</p></div>\r
+</div></div>\r
</div></div>\r
<div class="paragraph"><p>See also <a href="#p_allot">ALLOT</a>.</p></div>\r
<div style="text-align:center">\r
on input).</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 12: Word: HEX</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: HEX 16 BASE ! ;</code></pre>\r
+<div class="title">Definition concept for HEX</div>\r
+<div class="paragraph"><p>: HEX 16 BASE ! ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
the most recent word to 1, thereby making that word an immediate word.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 13:Word: IMMEDIATE</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;</code></pre>\r
+<div class="title">Definition concept for IMMEDIATE</div>\r
+<div class="paragraph"><p>: IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;</p></div>\r
</div></div>\r
</div></div>\r
<div class="paragraph"><p>See also <a href="#p_colon">:</a>, <a href="#p_current_wordlist">CURRENT-WORDLIST</a>,\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_input"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_input">Word: INPUT</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( -- a )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"INPUT" is a variable word for the input stream buffer used by\r
+<a href="#p_evaluate_stream">EVALUATE-STREAM</a>.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p><a id="p_left_bracket"></a></p></div>\r
</div>\r
<div class="sect2">\r
after parsing, by invoking their "doer".</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 14: Word: [</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: [ IMMEDIATE 0 STATE ! ;</code></pre>\r
+<div class="title">Definition concept for [</div>\r
+<div class="paragraph"><p>: [ IMMEDIATE 0 STATE ! ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
<div class="paragraph"><p>It’s not a good idea to use "LIT" interactively.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 15: Word: LIT</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: LIT R> DUP 8 + >R @ ;</code></pre>\r
+<div class="title">Definition concept for LIT</div>\r
+<div class="paragraph"><p>: LIT R> DUP 8 + >R @ ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
<div class="paragraph"><p><a id="p_literal_string"></a></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_word_s">Word: S"</h3>\r
+<h3 id="_word_lit_string">Word: LIT-STRING</h3>\r
<div class="literalblock">\r
<div class="content">\r
<pre><code>Data stack: ( -- chars* n )</code></pre>\r
</div></div>\r
-<div class="paragraph"><p>"S"" is a function word that pushes the [n:char] pointer for a string\r
-inlined subsequently to it in the containing definition. This is\r
-similar to <a href="#p_lit">LIT</a> but for a string literal.</p></div>\r
+<div class="paragraph"><p>"LIT-STRING" is a function word that pushes the char* and length n of\r
+a subsequent inline string, then advances execution to continue after\r
+the string. This is similar to <a href="#p_lit">LIT</a> but for a block literal.</p></div>\r
+<div class="paragraph"><p>Note that the inlined byte count includes the terminating NUL byte.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 16: Word: LIT</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: LIT R> DUP @ 2DUP + 8 + >R SWAP 8 + SWAP ;</code></pre>\r
+<div class="title">Definition concept for LIT-STRING</div>\r
+<div class="paragraph"><p>: LIT-STRING R@ DUP @ 8 + R@ @ 2DUP + R> + >R 1 - ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
-<div class="paragraph"><p><a id="p_load_file_quote"></a></p></div>\r
+<div class="paragraph"><p><a id="p_literal_string_compile"></a></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_word_load_file">Word: LOAD-FILE"</h3>\r
+<h3 id="_word_s">Word: S"</h3>\r
<div class="literalblock">\r
<div class="content">\r
-<pre><code>data stack: ( "name" -- )</code></pre>\r
+<pre><code>Data stack: ( -- ) Input stream: " chars"</code></pre>\r
</div></div>\r
-<div class="paragraph"><p>"LOAD-FILE"" is a function word that opens a file via\r
-<a href="#p_open_file_quote">OPEN-FILE"</a>, allocates a stream buffer of 15000\r
-bytes for reading it, saves the stream pointer as value for the newly\r
-created filename variable, and then it invokes\r
-<a href="#p_evaluate_stream">EVALUATE-STREAM</a> for processing the file.</p></div>\r
+<div class="paragraph"><p>"S"" is an immediate function word that compiles the subseqent\r
+characters up to terminating double-quote into the current definition,\r
+preceded by a <a href="#p_literal_string">LIT-STRING</a> cell, and the count of\r
+bytes scanned. The inline text includes a terminating NUL character\r
+which also is included in the inlined count.</p></div>\r
+<div class="paragraph"><p>Note that "S"" uses <a href="#p_double_quote">"</a> for reading the string.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
+<div class="paragraph"><p><a id="p_load_buffer_size"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_load_buffer_size">Word: LOAD-BUFFER-SIZE</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>data stack: ( -- a )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"LOAD-BUFFER-SIZE" is a variable word telling the buffer size in bytes\r
+that <a href="#p_load_file">LOAD-FILE</a> should use.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
+<div class="paragraph"><p><a id="p_load_file"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_load_file">Word: LOAD-FILE</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>data stack: ( chaz* -- * 0/1 )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"LOAD-FILE" is a function word that evaluates a text file. It opens a\r
+file via <a href="#p_open_file">OPEN-FILE</a> and sets up a stream with a\r
+buffer of <a href="#p_load_buffer_size">LOAD-BUFFER-SIZE</a> bytes for\r
+reading it. The stream is passed to\r
+<a href="#p_evaluate_stream">EVALUATE-STREAM</a> for processing its words. Upon\r
+its return the file is closed and the stream memory is reclaimed, and\r
+then the function returns whatever\r
+<a href="#p_evaluate_stream">EVALUATE-STREAM</a> returns.</p></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
on the data stack.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 17: Word: NIP</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: NIP SWAP DROP ;</code></pre>\r
+<div class="title">Definition concept for NIP</div>\r
+<div class="paragraph"><p>: NIP SWAP DROP ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
base, letters a-f or A-F for values 10-15. I.e. the normal positive or\r
negative decimal integers or normal (positive only) hexadecimal\r
integers.</p></div>\r
-<div class="exampleblock">\r
-<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 18: Word: NUMBER</div>\r
-<div class="content">\r
-<pre><code>( too complex to include here )</code></pre>\r
-</div></div>\r
-</div></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
-<div class="paragraph"><p><a id="p_open_file_quote"></a></p></div>\r
+<div class="paragraph"><p><a id="p_open_file"></a></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_word_open_file">Word: OPEN-FILE"</h3>\r
+<h3 id="_word_open_file">Word: OPEN-FILE</h3>\r
<div class="literalblock">\r
<div class="content">\r
-<pre><code>Data stack: ( "name" -- fd )</code></pre>\r
+<pre><code>Data stack: ( chaz* -- fd )</code></pre>\r
</div></div>\r
-<div class="paragraph"><p>"OPEN-FILE"" is a function word that reads the intputstream for a\r
-filename, adds that to the dictionary as a no-content variable, opens\r
-that file and returns the input file descriptor.</p></div>\r
+<div class="paragraph"><p>"OPEN-FILE" is a function word that opens the file named by the zero\r
+terminated character string and returns the file descriptor, or if\r
+less than 0, the system call error code.</p></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_rbp"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_rsp">Word: RSP</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( -- a )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"RSP" is a function word that pushes the return stack pointer value\r
+onto the data stack.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
+<div class="paragraph"><p><a id="p_rbpn"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_r_n">Word: R[n]</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( n -- a )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"R[n]" is a function word that pushes the address for the n:th cell on\r
+the top return stack value onto the data stack.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="sidebarblock">\r
+<div class="content">\r
+<div class="title">Defintion concept for R[n]</div>\r
+<div class="paragraph"><p>( n — a ) : R[n] 8 * RSP + ;</p></div>\r
+</div></div>\r
+</div></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p><a id="p_read_stream_char"></a></p></div>\r
</div>\r
<div class="sect2">\r
cell pointer for it. The characters of the word are copied to\r
<a href="#p_pad">PAD</a>, and there is a limit of 1024 characters.</p></div>\r
<div class="paragraph"><p>At the end of the stream READ-WORD returns 0 length.</p></div>\r
+<div class="exampleblock">\r
+<div class="title">Special syntax 1: Whitespace</div>\r
+<div class="content">\r
+<div class="paragraph"><p>All character codes less or equal to 32 are regarded as "whitespace".</p></div>\r
+</div></div>\r
+<div class="exampleblock">\r
+<div class="title">Special syntax 2: Rest-of-line comment</div>\r
+<div class="content">\r
+<div class="paragraph"><p>The "#" character following whitespace starts a line comment and the\r
+rest of the line is ignored. Note that this is also recognised with\r
+<a href="#p_lparen">parethesis commenting</a>.</p></div>\r
+</div></div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_return"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_return">Word: RETURN</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( -- )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"RETURN" is a function word that implements the ending of a FORTH\r
+definition and make execution return to the next step in the calling\r
+definition.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p>compile.asm: WORD p_right_bracket,<em>]</em>,fasm</p></div>\r
<div class="paragraph"><p><a id="p_right_bracket"></a></p></div>\r
</div>\r
wordlist; i.e., the word list may contain definitions for numbers.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 19: Word: ]</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: ] 1 STATE ! ;</code></pre>\r
+<div class="title">Definition concept for ]</div>\r
+<div class="paragraph"><p>: ] 1 STATE ! ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
-<div class="paragraph"><p><a id="p_rsp"></a></p></div>\r
-</div>\r
-<div class="sect2">\r
-<h3 id="_word_r_n">Word: R[n]</h3>\r
-<div class="literalblock">\r
-<div class="content">\r
-<pre><code>Data stack: ( n -- a )</code></pre>\r
-</div></div>\r
-<div class="paragraph"><p>"R[n]" is a function word that pushes the address for the n:th cell on\r
-the top return stack value onto the data stack.</p></div>\r
-<div style="text-align:center">\r
-_______________________________________________________\r
-</div>\r
<div class="paragraph"><p><a id="p_semicolon"></a></p></div>\r
</div>\r
<div class="sect2">\r
<div class="content">\r
<pre><code>Data stack: ( -- )</code></pre>\r
</div></div>\r
-<div class="paragraph"><p>";" (semi-colon) is a function word that ends a new forth definition\r
-by means of adding an <a href="#p_exit">EXIT</a></p></div>\r
+<div class="paragraph"><p>";" (semi-colon) is an immediate function word that ends a new forth\r
+definition by means of adding an <a href="#p_exit">EXIT</a> cell, then changing\r
+<<p_state,STATE> to interpreting.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 20: Word: :</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: ; IMMEDIATE ' EXIT , ;</code></pre>\r
+<div class="title">Definition concept for ;</div>\r
+<div class="paragraph"><p>: ; IMMEDIATE ' EXIT , ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
<div class="exampleblock">\r
<div class="content">\r
<div class="listingblock">\r
-<div class="title">Stream layout 2, for file descriptor</div>\r
+<div class="title">Layout 3: file descriptor stream</div>\r
<div class="content">\r
<pre><code> 8 bytes = size of buffer (excluding the 32 byte header)\r
8 bytes source file descriptor\r
<div class="exampleblock">\r
<div class="content">\r
<div class="listingblock">\r
-<div class="title">Stream layout 3, for memory block</div>\r
+<div class="title">Layout 4: memory block stream</div>\r
<div class="content">\r
<pre><code> 8 bytes = block address\r
8 -1 (indicates memory block)\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_str2temp"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_str_gt_temp">Word: STR>TEMP</h3>\r
+<div class="sidebarblock">\r
+<div class="content">\r
+<div class="paragraph"><p>Data stack: ( char* n — char* n )</p></div>\r
+</div></div>\r
+<div class="paragraph"><p>"STR>TEMP" is a function word that copies a given string plus a\r
+terminating NUL character into a <a href="#p_tempspace">TEMPSPACE</a> snippet,\r
+all preceded by a length cell. It returns a pointer for to the text in\r
+the snippet and its length, excluding the NUL character at end and the\r
+length cell before tie text.</p></div>\r
+<div class="listingblock">\r
+<div class="title">Layout for copied string</div>\r
+<div class="content">\r
+<pre><code> length: 8 bytes\r
+returned char*: n bytes\r
+ nul: 1 byte</code></pre>\r
+</div></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p><a id="p_strlen"></a></p></div>\r
</div>\r
<div class="sect2">\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_temp"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_temp_2">Word: TEMP</h3>\r
+<div class="sidebarblock">\r
+<div class="content">\r
+<div class="paragraph"><p>Data stack: ( size — addr )</p></div>\r
+</div></div>\r
+<div class="paragraph"><p>"TEMP" is a function word that "allocates" a <a href="#p_tempspace">TEMPSPACE</a>\r
+area of given size and returns its base address. The allocation is\r
+temporary and only valid until there is a later allocation that\r
+overruns this area.</p></div>\r
+<div class="paragraph"><p>Allocations are done in succession until the requested size overruns\r
+the <a href="#p_tempspace">TEMPSPACE</a>. If so, the allocation pointer is reset\r
+and the space is allocated from start again. This is all intended for\r
+small and short-lived data areas.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
+<div class="paragraph"><p><a id="p_tempspace"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_tempspace">Word: TEMPSPACE</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( -- a )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"TEMPSPACE" is a variable word that holds three cells the for managing\r
+"temporary memory":</p></div>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+the size of the temporary memory space (default 104857600 bytes)\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+the base address for whole temporary memory area\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+the amount currently used\r
+</p>\r
+</li>\r
+</ul></div>\r
+<div class="paragraph"><p>This memory is intended to be used by requesting snippets of memory in\r
+a cyclic fashion via <a href="#p_temp">TEMP</a> without concern about it possibly\r
+overlapping a prior request.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p><a id="p_terminate0"></a></p></div>\r
</div>\r
<div class="sect2">\r
<div class="paragraph"><p>"TFA>FLAGS@" is a function word that pushes word flags of the given tfa.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Defintion concept 21Word: TFA>FLAGS@</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: TFA>FLAGS@ 16 + @ ;</code></pre>\r
+<div class="title">Defintion concept for TFA>FLAGS@</div>\r
+<div class="paragraph"><p>: TFA>FLAGS@ 16 + @ ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
terminated as well as preceded by a length cell.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Defintion concept for TFA>NAMEZ</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: TFA>NAMEZ 32 + ;</code></pre>\r
+<div class="title">Defintion concept for TFA>NAMEZ</div>\r
+<div class="paragraph"><p>: TFA>NAMEZ 32 + ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
cell on the data stack.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 22: Word: TUCK</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: TUCK SWAP OVER ;</code></pre>\r
+<div class="title">Definition concept for TUCK</div>\r
+<div class="paragraph"><p>: TUCK SWAP OVER ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
<div style="text-align:center">\r
_______________________________________________________\r
</div>\r
+<div class="paragraph"><p><a id="p_unstream"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_unstream">Word: UNSTREAM</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( stream* -- )</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"UNSTREAM" is a function word that releases the memory allocated for a\r
+stream, and closes the associated file if it’s a file stream.</p></div>\r
+<div class="sect3">\r
+<h4 id="_file_descriptor_backed_stream_2">File descriptor backed stream</h4>\r
+<div class="paragraph"><p>This kind of stream has the stream header as a prefix within the\r
+allocated memory. Thus, stream* is the base address for the memory to\r
+reclaim, and the size of this is determined from the cell at (stream*\r
++ 16) plus the 32 bytes head itself.</p></div>\r
+</div>\r
+<div class="sect3">\r
+<h4 id="_memory_block_backed_stream_2">Memory block backed STREAM</h4>\r
+<div class="paragraph"><p>This kind of stream has a separate header which points at the memory\r
+area to reclaim. The cell at stream* is the base address, and the cell\r
+at (stream* + 16) is its size.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
+<div class="paragraph"><p><a id="p_use"></a></p></div>\r
+</div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_use">Word: USE</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data value: ( wordlist -- ) Input stream: word</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>"USE" is a function word that looks up next word given the wordlist.\r
+It reads next word on <a href="#p_input">INPUT</a> via <a href="#p_read_word">READ-WORD</a>,\r
+then temporarily changes <a href="#p_current_wordlist">CURRENT-WORDLIST</a> to\r
+<a href="#p_find">FIND</a> the word via the given wordlist, and returns the TFA\r
+of that word, or just 0 if the word coudn’t be found.</p></div>\r
+<div style="text-align:center">\r
+_______________________________________________________\r
+</div>\r
<div class="paragraph"><p><a id="p_verboseQ"></a></p></div>\r
</div>\r
<div class="sect2">\r
lo, inclusive and third, hi, exclusive.</p></div>\r
<div class="exampleblock">\r
<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 23: Word: WITHIN</div>\r
+<div class="sidebarblock">\r
<div class="content">\r
-<pre><code>: WITHIN 2 PICK > ROT ROT <= AND ;</code></pre>\r
+<div class="title">Definition concept for WITHIN</div>\r
+<div class="paragraph"><p>: WITHIN 2 PICK > ROT ROT ⇐ AND ;</p></div>\r
</div></div>\r
</div></div>\r
<div style="text-align:center">\r
<div id="footer">\r
<div id="footer-text">\r
Last updated\r
- 2021-06-02 01:27:44 AEST\r
+ 2021-06-12 22:46:13 AEST\r
</div>\r
</div>\r
</body>\r
projects / rrq / rrqforth.git / blobdiff