The Forth words in this manual are documented using a methodology based on that used for the ANS standard document. As this is not a standards document but a user manual, we have taken some liberties to make the text easier to read. We are not always as strict with our own in-house rules as we should be. If you find an error, have a complaint about the documentation or suggestions for improvement, please send us an email or contact us in some other way.
When you browse the words in the Forth dictinary using WORDS or when reading source code you may come across some words which are not documented. These words are undocumented because they are words which are only used in passing as part of other words (factors), or because these words may change or may not exist in later versions.
"Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing." - Dick Brandon
Word names in the text are capitalised or shown in a bold fixed-point font, e.g. SWAP or SWAP. Forth program examples are shown in a Courier font thus:
|
If you see a word of the form <name> it usually means that name is a placeholder for a name you will provide.
The notation for the glossary entries in this manual have two major parts:
The definition line varies depending on the definition type. For instance - a normal Forth word will look like:
|
The left most column describes the word NAME and type (colon) the center column describes the stack effect of the word and the far right column (if it exists) will specify either the ANS language reference number or an MPE reference to distinguish between ANS standard and MPE extension words.
The stack effect may be followed by an informal comment separated from the stack effect by a ';' character.
|
This is a "quick reference" comment.
When you read MPE source code, you will see that most words are written in the style:
|
Most MPE manuals are now written using the DocGen literate programming tool available and documented with all VFX Forths for Windows, Mac OS X and Linux. DocGen extracts documentation lines (ones that start "\ *X ") from the source code and produces HTML or PDF manuals.
before -- after
where before means the stack parameters before execution and after means stack parameters after execution. In this notation, the top of the stack is to the right. Words may also be shown in context when appropriate. Unless otherwise noted, all stack notations describe the action of the word at execution time. If it applies at compile time, the stack action is preceded by C: or followed by (compiling)
An action on the return stack whill be shown
R: before -- after
Similarly, actions on the separate float stack are marked by F: and on an exception stack by E:. The definition of >R would have the stack notation
x -- ; R: -- x
Defining words such as VARIABLE usually indicate the stack action of the defining word (VARIABLE) itself and the stack action of the child word. This is indicated by two stack actions separated by a ';' character, where the second action is that of the child word.
: VARIABLE \ -- ; -- addr
In cases where confusion may occur, you may also see the following notation:
: VARIABLE \ -- ; -- addr [child]
Unless otherwise stated all references to numbers apply to native signed integers. These will be 32 bits on 32 bit CPUs and 16 bits on embedded Forths for 8 and 16 bit CPUs. The implied range of values is shown as {from..to}. Braces show the content of an address, particularly for the contents of variables, e.g., BASE {2..72}.
The native size of an item on the Forth stack is referred to as a CELL. This is a 32 bit item on a 32 bit Forth, and on a byte-addressed CPU (the vast majority, most DSP chips excluded) this is a four-byte item. On many CPUs, these must be stored in memory on a four-byte address boundary for hardware or performance reasons. On 16 bit systems this is a two-byte item, and may also be aligned.
The following are the stack parameter abbreviations and types of numbers used in the documentation for 32 bit systems. On 16 bit systems the generic types will have a 16 bit range. These abbreviations may be suffixed with a digit to differentiate multiple parameters of the same type.
|
Any other symbol refers to an arbitrary signed 32-bit integer unless otherwise noted. Because of the use of two's complement arithmetic, the signed 32-bit number (n) -1 has the same bit representation as the unsigned number (u) 4,294,967,295. Both of these numbers are within the set of unspecified weighted numbers. On many occasions where the context is obvious, informal names are used to make the documentation easier to understand.
Some Forth words read text from the input stream (e.g the keyboard or a file). That text is read from the input stream is indicated by the identifiers "<name>" or "text". This notation refers to text from the input stream, not to values on the data stack.
Likewise, ccc indicates a sequence of arbitrary characters accepted from the input stream until the first occurrence of the specified delimiter character. The delimiter is accepted from the input stream, but it 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.
The following markers may appear after a word's stack comment. These markers indicate certain features and peculiarities of the word.
C |
The word may only be used during compilation of a colon definition. |
I |
The word is immediate. It will be executed even during compilation, unless special action is taken, e.g. by preceding it word with the word POSTPONE. |
M |
Affected by multi-tasking |
U |
A user variable. |