The Forth words are described in this section in the glossary notation that has become a de-facto standard for Forth texts:
word Stack effect wordset pronunciation
Description
The name of the word.
The stack effect is written in the notation before --
after
, where before and after describe the top of
stack entries before and after the execution of the word. The rest of
the stack is not touched by the word. The top of stack is rightmost,
i.e., a stack sequence is written as it is typed in. Note that Gforth
uses a separate floating point stack, but a unified stack
notation. Also, return stack effects are not shown in stack
effect, but in Description. The name of a stack item describes
the type and/or the function of the item. See below for a discussion of
the types.
All words have two stack effects: A compile-time stack effect and a run-time stack effect. The compile-time stack-effect of most words is – . If the compile-time stack-effect of a word deviates from this standard behaviour, or the word does other unusual things at compile time, both stack effects are shown; otherwise only the run-time stack effect is shown.
Also note that in code templates or examples there can be comments in
parentheses that display the stack picture at this point; there is no
--
in these places, because there is no before-after situation.
How the word is pronounced.
The wordset specifies whether a word has been standardized, it is an
environmental query string, or if it is a Gforth-specific word. In
the latter case the wordset contains the string gforth
, other
wordset names are either environment
of refer to standard word
sets.
The Forth standard is divided into several word sets. In theory, a standard system need not support all of them, but in practice, serious systems on non-tiny machines support almost all standardized words (some systems require explicit loading of some word sets, however), so it does not increase portability in practice to be parsimonious in using word sets.
For the Gforth-specific words, we have the following categories:
gforth
gforth-<version>
We intend to permanently support this word in Gforth and it has been available since Gforth <version> (possibly not as supported word at that time).
gforth-experimental
This word is available in the present version and may turn into a permanent word or may be removed in a future release of Gforth. Feedback welcome.
gforth-internal
This word is an internal factor, not a supported word, and it may be removed in a future release of Gforth.
gforth-obsolete
This word will be removed in a future release of Gforth.
A description of the behaviour of the word.
The type of a stack item is specified by the character(s) the name starts with:
f
¶Boolean flags, i.e. false
or true
.
c
¶Char
w
¶Cell, can contain an integer or an address
n
¶signed integer
u
¶unsigned integer
d
¶double sized signed integer
ud
¶double sized unsigned integer
r
¶Float (on the FP stack)
a-
¶Cell-aligned address
c-
¶Char-aligned address (note that a Char may have two bytes in Windows NT)
f-
¶Float-aligned address
df-
¶Address aligned for IEEE double precision float
sf-
¶Address aligned for IEEE single precision float
xt
¶Execution token, same size as Cell
wid
¶Word list ID, same size as Cell
ior, wior
¶I/O result code, cell-sized. In Gforth, you can throw
iors.
f83name
¶Pointer to a name structure
"
¶string in the input stream (not on the stack). The terminating character
is a blank by default. If it is not a blank, it is shown in <>
quotes.