<!-- Forthmacs Formatter generated HTML output -->
<html>
<head>
<title>Glossary Notation</title>
</head>
<body>
<h1>Glossary Notation</h1>
<hr>
<p>
This chapter describes the notation used in the Master Glossary.  This chapter 
is based on the ANS manual.  
<p>
<p>
<h2>Order</h2>
<p>
The glossary definitions are listed in ASCII alphabetical order.  
<p>
<br><code>         Example Glossary Line:</code><br>
<p>
<br><code>            Name       Stack     Input Stream   Attributes    Pronunciation</code><br>
<p>
<br><code>            ABORT"     flag --        ccc"        C,I           abort-quote</code><br>
<p>
<p>
<h2>Capitalization</h2>
<p>
Depending on the device you are reading this manual on, Forth keywords will be 
printed bold, capitilized or just as typed.  However, in actual use, the word 
names should always be typed in lower case.  
<p>
<p>
<h2>Stack Notation</h2>
<p>
The stack parameters input to and output from a definition are described using 
the notation: 
<p>
<br><code>                 before -- after</code><br>
<br><code>    </code><br>
<br><code>                         before  stack parameters before execution</code><br>
<br><code>                         after   stack parameters after execution</code><br>
<p>
In this notation, the top of the stack is to the right.  
<p>
Unless otherwise noted, all stack notation describes what happens at execution 
time.  If it applies at compile time, the line is followed by: compiling .  
<p>
<p>
<h2>Input Stream Text</h2>
<p>
Text collected from the input stream, if any, is shown in italics following the 
stack parameters.  The character which marks the end of the input text is the 
"delimiter".  If the delimiter is the space character, it is not shown.  If the 
delimiter is any character other than space, it is shown at the end of the input 
text field.  In the example above, the Input Text field is shown as ccc" and the 
delimiter is the " character.  
<p>
<p>
<h2>Attributes</h2>
<p>
<p><pre>
        Annotations indicate attributes of the defined words:
                C  The word may only be used during compilation of a colon
                   definition
                I  Indicates that the word is IMMEDIATE and will execute
                   during compilation, unless special action is taken.
                M  This word has potential multiprogramming impact.
                   See:  "Multitasking"
                System  The word appears in the SYSTEM vocabulary.
                Hidden  The word appears in the HIDDEN vocabulary.
                83Std   The word is part of the 83 Standard.
                ANS     The word is part of the ANS standard
                F83 The word is not part of the 83 Standard, but it
                   appears in the public domain F83 model, from
                   which this system is loosely derived.
                Deferred  The word is "deferred"; it's behavior may
                   be altered by installing a different implementation
                   of the word.  See: DEFER IS
                Default   The word is the normal or "default" implementation
                   of some other "deferred" word.
</pre><p>
<p>
<p>
<h2>Pronunciation</h2>
<p>
Then natural language pronunciation of the word name is shown at the right-hand 
side of the line.  
<p>
<p>
<h2>Stack Parameters</h2>
<p>
The Risc-OS Forthmacs stacks contain 32-bit integers for both stacks.  
<p>
Unless otherwise stated, all references to numbers apply to "normal" numbers.  
The implied range of values is shown as {from..to}.  The content of an address 
is shown by double braces, particularly for the contents of variables, i.e.,  <code><A href="_smal_AJ#159"> base </A></code> 
{{2..72}}.  
<p>
The following are the stack parameter abbreviations and types of numbers used 
throughout the glossary.  These abbreviations may be suffixed with a digit to 
differentiate multiple parameters of the same type.  
<p>
<p><pre>
                Stack   Number                  Range in           Field
                Abbrv.  Type                    Decimal            Width
                flag    boolean                 0=false, else=true normal
                true    boolean                 -1 (as a result)   normal
                false   boolean                 0                  normal
                b       bit                     {0..1}             1
                char    char                    {0..255}           7
                8b      8 arbitrary bits        not applicable     8
                16b     16 arbitrary bits       not applicable     16
                32b     32 arbitrary bits       not applicable     32
                n       number (normal)
                                   {-2,147,483,648..2,147,483,647} 32
                +n      positive number         {0..2,147,483,647} 32
                u       unsigned number         {0..4,294,967,295} 32
                d       double                  {                } 64
		ud      unsigned double         {                } 64
                adr     address                 {0..4,294,967,295} 32
                sys     0, 1, or more system
                        dependent stack entries not applicable     na
                acf     compilation address     {origin..here}     32
                anf     name field address      {origin..here}     32
                alf     link field address      {origin..here}     32
                apf     parameter field address {origin..here}     32
                pstr    address of packed string 
                                                {0..4,294,967,295} 32
        Any other symbol refers to a "normal", the same as n above.
</pre><p>
<p>
<p>
<h2>Input Text Examples</h2>
<p>
<p><pre>
        name
                An arbitrary FORTH word accepted from the input stream.
                This notation refers to text from the input stream, not
                to values on the data stack.  Such a word never contains
                blank characters.
        ccc
                A sequence of arbitrary characters accepted from the input
                stream until the first occurrence of a specified delimiting
                character.  The delimiter is accepted (removed) from the
                input stream, but is not one of the characters ccc and is
                therefore not otherwise processed.  This notation refers to
                text from the input stream, not to values on the data stack.
                Unless noted otherwise, the number of characters accepted
                may be from 0 to 255.
        filename
                The name of a disk file.  See the chapter "Files" for
                more information about file names.
        pattern
                A filename with "wildcards" used to specify several file
                names at once.  See the chapter "Files" for more
                information about patterns.
        directory
                A list of names specifying how to find a particular
                disk directory (also known as a "folder"). See the chapter
                "Files" for more information about directories.
</pre><p>
<p>
<p>
<h2>References to other words and definitions</h2>
<p>
Glossary definitions may refer to other glossary definitions or to definitions 
of terms.  Such references are made using "See:".  
<p>
<p>
<h2>Definitions of terms</h2>
<p>
<p>
<h2>Input Stream</h2>
<p>
Risc-OS Forthmacs, because of it's emphasis on files, does not follow the Forth 
83 Standard with respect to the Input Stream.  
<p>
Here's what the Standard has to say about the Input Stream: 
<p>
The input stream is a sequence of characters available to the system, for 
processing by the text interpreter.  The input stream conventionally may be 
taken from the current input device (via the text input buffer) and mass storage 
(via a block buffer).   <code><A href="_smal_AU#164"> blk </A>,</code>  <code><A href="_smal_AB#121"> &gt;in </A>,</code>  <code><A href="_smal_BM#2f4"> tib </A>,</code> 
and  <code><A href="_smal_BL#83"> #tib </A></code> specify the input stream.  
Words using or altering  <code><A href="_smal_AU#164"> blk </A>,</code>  <code><A href="_smal_AB#121"> &gt;in </A>,</code>  <code><A href="_smal_BM#2f4"> tib </A>,</code> 
and  <code><A href="_smal_BL#83"> #tib </A></code> are responsible for 
maintaining and restoring control of the input stream.  
<p>
The input steam extends from the offset value of  <code><A href="_smal_AB#121"> &gt;in </A></code> 
to the size of the input stream.  If  <code><A href="_smal_AU#164"> blk </A></code> 
is zero the input stream is contained within the area addressed by  <code><A href="_smal_BM#2f4"> tib </A></code> 
and is  <code><A href="_smal_BL#83"> #tib </A></code> bytes long.  If  <code><A href="_smal_AU#164"> blk </A></code> 
is non-zero the input stream is contained within the block buffer specified by  <code><A href="_smal_AU#164"> blk </A></code> 
and is 1024 bytes long.  
<p>
Here's how Risc-OS Forthmacs really implements the Input Stream: 
<p>
The input stream is a sequence of characters available to the system, for 
processing by the text interpreter.  The variable IN-FILE contains the file 
descriptor of the file supplying the characters of the input stream.  That file 
may be a disk file or some other "special file".  
<p>
The most important kind of special file is the "Expect File".  The Expect File 
supplies characters received from the keyboard as read by the word  <code><A href="_smal_AQ#1f0"> expect </A></code> 
.  
<p>
All of the operations which apply to files also apply to the input stream, i.e.   <code><A href="_smal_AX#1f7"> fgetc </A></code>  <code><A href="_smal_BB#1f9"> fgets </A></code>  <code><A href="_smal_AF#215"> ftell </A></code>  <code><A href="_smal_AA#210"> fseek </A></code> 
etc.  
<p>
The variables  <code><A href="_smal_AU#164"> blk </A></code> and  <code><A href="_smal_AB#121"> &gt;in </A></code> 
are not implemented.  The Expect File does indeed store the current keyboard 
line in the buffer starting at  <code><A href="_smal_BM#2f4"> tib </A></code> 
and containing  <code><A href="_smal_BL#83"> #tib </A></code> @ bytes, but the 
normal file operations should be used to access that keyboard line, rather than 
using  <code><A href="_smal_BM#2f4"> tib </A></code> and  <code><A href="_smal_BL#83"> #tib </A></code> 
.  
<p>
<p>
<h2>division, floored</h2>
<p>
Integer division in which the remainder carries the sign of the divisor or is 
zero, and the quotient is rounded to its arithmetic floor.  Note that, except 
for error conditions, n1 n2  <code><A href="_smal_AW#2e6"> swap </A></code>  <code><A href="_smal_BH#28f"> over </A></code>  <code><A href="_smal_AD#f3"> /mod </A></code>  <code><A href="_smal_BA#2b8"> rot </A></code> 
* + is identical to n1.  
<p>
<br><code>         Examples:</code><br>
<br><code>             dividend  divisor      remainder  quotient</code><br>
<br><code>                 10      7               3       1</code><br>
<br><code>                -10      7               4      -2</code><br>
<br><code>                 10     -7              -4      -2</code><br>
<br><code>                -10     -7              -3       1</code><br>
<p>
<p>
<h2>Return Stack</h2>
<p>
A last in, first out list which contains the addresses of word definitions whose 
execution has not been completed by the address interpreter.  As a word 
definition passes control to another definition, the return point is placed on 
the return stack.  
<p>
The return stack may cautiously be used for other values, with the following 
restrictions: 
<p>
<br><code>         a) The return stack may not be accessed inside a do-loop for</code><br>
<br><code>            values placed on the return stack before the loop was entered.</code><br>
<br><code>         b) Neither I nor J may be used to obtain the index of a loop if</code><br>
<br><code>            values are placed and remain on the return stack within the</code><br>
<br><code>            loop.</code><br>
<br><code>         c) When the do-loop is executed all values placed on the return</code><br>
<br><code>            stack within that loop must be removed before LOOP , +LOOP ,</code><br>
<br><code>            or LEAVE is executed.</code><br>
<br><code>         d) All values placed on the return stack within a colon definition</code><br>
<br><code>            must be removed before the colon definition is terminated at ;</code><br>
<br><code>            or before EXIT is executed.</code><br>
<p>
<br><code>         Examples of INCORRECT return stack usage:</code><br>
<p>
<br><code>         : FOO  &gt;R  1 0  DO  R&gt; .  LOOP  ;       \ violates restriction (a)</code><br>
<br><code>         : FOO  1 0  DO  &gt;R I . R&gt;  LOOP ;       \ violates restriction (b)</code><br>
<br><code>         : FOO  1 0  DO  I .  &gt;R  LOOP  R&gt; ;     \ violates restriction (c)</code><br>
<br><code>         : FOO  &gt;R  ;                            \ violates restriction (d)</code><br>
<p>
</body>
</html>
