home *** CD-ROM | disk | FTP | other *** search
<!-- 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"> >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"> >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"> >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"> >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 >R 1 0 DO R> . LOOP ; \ violates restriction (a)</code><br> <br><code> : FOO 1 0 DO >R I . R> LOOP ; \ violates restriction (b)</code><br> <br><code> : FOO 1 0 DO I . >R LOOP R> ; \ violates restriction (c)</code><br> <br><code> : FOO >R ; \ violates restriction (d)</code><br> <p> </body> </html> 
