update

diff --git a/reference.html b/reference.html
index 609c422d1f31238ff88134fad393ef226287787e..9900bbd6523455f03232be79b6944e426f725a5e 100644 (file)
--- a/reference.html
+++ b/reference.html
@@ -780,7 +780,7 @@ asciidoc.install();
 <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
-<a href="#p_rsp">R[n]</a> &#160;</p></div>\r
+<a href="#p_rbpn">R[n]</a> &#160;</p></div>\r
 <div class="paragraph"><p><a href="#data_stack">DATA-STACK</a> &#160;\r
 <a href="#return_stack">RETURN-STACK</a> &#160;\r
 &#160;\r
@@ -826,6 +826,8 @@ asciidoc.install();
 <a href="#p_execute">EXECUTE</a> &#160;\r
 <a href="#p_exit">EXIT</a> &#160;</p></div>\r
 <div class="paragraph"><p><a href="#p_false">FALSE</a> &#160;\r
+<a href="#p_fdemit">FDEMIT</a> &#160;\r
+<a href="#p_fdtell">FDTELL</a> &#160;\r
 <a href="#p_find">FIND</a> &#160;\r
 <a href="#p_forth">FORTH</a> &#160;</p></div>\r
 <div class="paragraph"><p><a href="#p_here">HERE</a> &#160;\r
@@ -836,7 +838,8 @@ 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_load_file_quote">LOAD-FILE"</a> &#160;</p></div>\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
 <a href="#p_malloc">MALLOC</a> &#160;</p></div>\r
 <div class="paragraph"><p><a href="#p_negate">NEGATE</a> &#160;\r
@@ -844,7 +847,7 @@ asciidoc.install();
 <a href="#p_nl">NL</a> &#160;\r
 <a href="#p_not">NOT</a> &#160;\r
 <a href="#p_number">NUMBER</a> &#160;</p></div>\r
-<div class="paragraph"><p><a href="#p_open_file_quote">OPEN-FILE"</a> &#160;\r
+<div class="paragraph"><p><a href="#p_open_file">OPEN-FILE</a> &#160;\r
 <a href="#p_or">OR</a> &#160;\r
 <a href="#p_over">OVER</a> &#160;</p></div>\r
 <div class="paragraph"><p><a href="#p_pad">PAD</a> &#160;\r
@@ -855,7 +858,8 @@ asciidoc.install();
 <a href="#p_read_word">READ-WORD</a> &#160;\r
 <a href="#p_realloc">REALLOC</a> &#160;\r
 <a href="#p_roll">ROLL</a> &#160;\r
-<a href="#p_rot">ROT</a> &#160;</p></div>\r
+<a href="#p_rot">ROT</a> &#160;\r
+<a href="#p_rbp">RSP</a> &#160;</p></div>\r
 <div class="paragraph"><p><a href="#p_sp">SP</a> &#160;\r
 <a href="#p_state">STATE</a> &#160;\r
 <a href="#p_stdin">STDIN</a> &#160;\r
@@ -876,6 +880,7 @@ asciidoc.install();
 <a href="#p_this_word">THIS-WORD</a> &#160;\r
 <a href="#p_true">TRUE</a> &#160;\r
 <a href="#p_tuck">TUCK</a> &#160;</p></div>\r
+<div class="paragraph"><p><a href="#p_unstream">UNSTREAM</a> &#160;</p></div>\r
 <div class="paragraph"><p><a href="#p_verboseQ">VERBOSE?</a> &#160;</p></div>\r
 <div class="paragraph"><p><a href="#p_within">WITHIN</a> &#160;\r
 <a href="#p_words">WORDS</a> &#160;</p></div>\r
@@ -2109,6 +2114,33 @@ _______________________________________________________
 <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
@@ -2467,19 +2499,35 @@ similar to <a href="#p_lit">LIT</a> but for a string literal.</p></div>
 <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_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
+<h3 id="_word_load_file">Word: LOAD-FILE</h3>\r
 <div class="literalblock">\r
 <div class="content">\r
-<pre><code>data stack: ( "name" -- )</code></pre>\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 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>"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
@@ -2626,17 +2674,17 @@ integers.</p></div>
 <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
@@ -2781,6 +2829,40 @@ word on the input stream and pushes its cfa.</p></div>
 <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&#8201;&#8212;&#8201;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
@@ -2812,6 +2894,18 @@ separated word from the given stream and returns the [n:char*] duoble
 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
@@ -2892,19 +2986,6 @@ and the first becomes the second.</p></div>
 <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
@@ -3338,8 +3419,34 @@ values are unequal, and 0 otherwise.</p></div>
 <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&#8217;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_verboseQ"></a></p></div>\r
 </div>\r
+</div>\r
 <div class="sect2">\r
 <h3 id="_word_verbose">Word: VERBOSE?</h3>\r
 <div class="literalblock">\r
@@ -3429,7 +3536,7 @@ is deepest.</p></div>
 <div id="footer">\r
 <div id="footer-text">\r
 Last updated\r
- 2021-06-04 18:26:45 AEST\r
+ 2021-06-05 17:42:39 AEST\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/rrqforth b/rrqforth
index 8c3fc39aa6bb367e89d836a8087b234aa7885bea..e3085861b8c6286da854bac80b728994aa1d9c5d 100755 (executable)
Binary files a/rrqforth and b/rrqforth differ