upgrade

diff --git a/reference.html b/reference.html
index 988e55177cc3476fd286dc94d7b0324a2893bef9..04da3738999684d452c0701a1335e93ede9ccd18 100644 (file)
--- a/reference.html
+++ b/reference.html
@@ -776,7 +776,7 @@ asciidoc.install();
 <a href="#p_get_n_increment">@n&#43;&#43;</a> &#160;\r
 <a href="#p_get_n_decrement">@n--</a> &#160;\r
 <a href="#p_Ccomma">C,</a> &#160;\r
-<a href="#p_literal_string">S"</a> &#160;\r
+<a href="#p_literal_string_compile">S"</a> &#160;\r
 <a href="#p_gtR">&gt;R</a> &#160;\r
 <a href="#p_Rget">R@</a> &#160;\r
 <a href="#p_Rgt">R&gt;</a> &#160;\r
@@ -840,6 +840,7 @@ asciidoc.install();
 <a href="#p_immediate">IMMEDIATE</a> &#160;\r
 <a href="#p_input">INPUT</a> &#160;</p></div>\r
 <div class="paragraph"><p><a href="#p_literal">LIT</a> &#160;\r
+<a href="#p_literal_string">LIT-STRING</a> &#160;\r
 <a href="#p_load_buffer_size">LOAD-BUFFER-SIZE</a> &#160;\r
 <a href="#p_load_file">LOAD-FILE</a> &#160;</p></div>\r
 <div class="paragraph"><p><a href="#p_args">MAIN-ARGS</a> &#160;\r
@@ -868,6 +869,7 @@ asciidoc.install();
 <a href="#p_stdin">STDIN</a> &#160;\r
 <a href="#p_stream">STREAM</a> &#160;\r
 <a href="#p_stream_nchars">STREAM-NCHARS</a> &#160;\r
+<a href="#p_str2temp">STR&gt;TEMP</a> &#160;\r
 <a href="#p_strlen">STRLEN</a> &#160;\r
 <a href="#p_strncmp">STRNCMP</a> &#160;\r
 <a href="#p_strncpy">STRNCPY</a> &#160;\r
@@ -875,6 +877,8 @@ asciidoc.install();
 <a href="#p_system">SYSTEM</a> &#160;</p></div>\r
 <div class="paragraph"><p><a href="#p_tell">TELL</a> &#160;\r
 <a href="#p_dot_temp">.TEMP</a> &#160;\r
+<a href="#p_temp.adoc">TEMP</a> &#160;\r
+<a href="#p_tempspace">TEMPSPACE</a> &#160;\r
 <a href="#p_terminate0">TERMINATE0</a> &#160;\r
 <a href="#p_tfa2cfa">TFA&gt;CFA</a> &#160;\r
 <a href="#p_tfa2dfa">TFA&gt;DFA</a> &#160;\r
@@ -2542,25 +2546,43 @@ _______________________________________________________
 <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="sidebarblock">\r
 <div class="content">\r
-<div class="title">Definition concept for LIT</div>\r
-<div class="paragraph"><p>: LIT R&gt; DUP @ 2DUP + 8 + &gt;R SWAP 8 + SWAP ;</p></div>\r
+<div class="title">Definition concept for LIT-STRING</div>\r
+<div class="paragraph"><p>: LIT-STRING  R@ DUP @ 8 +  R@ @  2DUP + R&gt; + &gt;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_literal_string_compile"></a></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_word_s">Word: S"</h3>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>Data stack: ( -- )  Input stream: " chars"</code></pre>\r
+</div></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
@@ -3070,8 +3092,9 @@ _______________________________________________________
 <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
+&lt;&lt;p_state,STATE&gt; to interpreting.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
 <div class="sidebarblock">\r
@@ -3236,6 +3259,29 @@ stream (or filling it by reading the backing file).</p></div>
 <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&gt;TEMP</h3>\r
+<div class="sidebarblock">\r
+<div class="content">\r
+<div class="paragraph"><p>Data stack: ( char* n&#8201;&#8212;&#8201;char* n )</p></div>\r
+</div></div>\r
+<div class="paragraph"><p>"STR&gt;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
@@ -3321,6 +3367,58 @@ descriptor 1).</p></div>
 <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&#8201;&#8212;&#8201;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
@@ -3628,7 +3726,7 @@ is deepest.</p></div>
 <div id="footer">\r
 <div id="footer-text">\r
 Last updated\r
- 2021-06-06 23:19:36 AEST\r
+ 2021-06-11 19:04:48 AEST\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/rrqforth b/rrqforth
index a5f2ecf8218b961efe3b78e8188ff50e5e32b67d..729f1bb4f4f0e974915eceba48699c6dda0a0dca 100755 (executable)
Binary files a/rrqforth and b/rrqforth differ