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:
: NEW-WORD \ a b -- a b
OVER DROP
;
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:
: and \ n1 n2 -- n3 6.1.0720
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.
: and \ x1 x2 -- x3 ; bitwise and
This is a "quick reference" comment.
When you read MPE source code, you will see that most words are written in the style:
: foo \ n1 n2 -- n3
\ *G This is the first glossary description line.
\ ** These are following glossary description lines.
...
;
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.
Stack Number Range Field
Abbreviation Type (Decimal) (Bits)
flag boolean 0=false, nz=true 32
true boolean -1 (as a result) 32
false boolean 0 32
char character {0..255} 8
b byte {0..255} 8
w word {0..65535} 16
here word means a 16 bit item, not a Forth word
n number {-2,147,483,648 32
..2,147,483,647
x 32 bits N/A 32
+n +ve int {0..2,147,483,647} 32
u unsigned {0..4,294,967,295} 32
addr address {0..4,294,967,295} 32
a-addr address {0..4,294,967,295} 32
the address is aligned to a CELL
boundary
c-addr address {0..4,294,967,295} 32
the address is aligned to a character boundary
32b 32 bits not applicable 32
d signed {-9.2e18..9.2e18} 64
double
+d positive {0..9.2e18} 64
double
ud unsigned {0..1.8e19} 64
double
sys 0, 1, or more system dependent entries
char character {0..255} 8
"text" text read from the input stream
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 |
M |
Affected by multi-tasking |
U |
A user variable. |