6.1 Notation ¶

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

word

The name of the word.

Stack effect ¶

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.

Gforth has several stacks, in particular, the data stack, return stack and floating-point stack. However, it uses a unified stack effect notation, where one stack effect description describes all three stack effects, and the name of the item indicates which stack the item is on: floating-point stack items start with r. Return stack items are prefixed with R:, but are otherwise the same as data stack items. E.g., in the stack effect ( w1 w2 -- R:w1 R:w2 ) w1 is a cell on the data stack, and R:w1 is a cell on the return stack with the same value. So a unified stack effect

( r1 n1 R:n2 -- R:n3 n4 r2 )

is equivalent to the separated stack effect notation

( n1 -- n4 ) ( R: n2 -- n3 ) ( F: r1 -- r2 )

The name of a stack item describes the type and/or the function of the item. See below for a discussion of the types.

Words generally have different stack effects in different contexts. If only one stack effect is shown, it’s the stack effect for the execution/interpretation semantics.⁹ The stack effect of default compilation semantics is ( -- ) and is not shown.

The stack-effects of non-default compilation semantics are shown if they are other than ( -- ). Such words usually also have a run-time semantics, and their stack effects are then shown as in this example

; ( compilation colon-sys -- ; run-time nest-sys -- )

Further stack effects, such as those of defined words, of passed xts, are shown in the description part of the glossary entry.

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.

pronunciation ¶

How the word is pronounced.

wordset ¶

The wordset specifies if a word has been standardized (indicated by a capitalized wordset name), it is an environmental query string (indicated by “environment”), or if it is a Gforth-specific word (lower case).

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 stable word at that time).

library

The word belongs to a library that is independent of Gforth, but is delivered with Gforth and documented in this manual. Gforth 1.0 includes libraries with the following wordset names: mini-oof mini-oof2 minos2 minos2-bidi objects oof regexp-cg regexp-pattern regexp-replace cilk

gforth-experimental

This word is available in the present version and may turn into a stable 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.

Description

A description of the behaviour of the word.

The type of a stack item is specified by the prefix of the name:

f ¶

Boolean flags, i.e. false or true.

c ¶

Char

w

x ¶

Cell, can contain an integer or an address

n ¶

signed integer

u ¶

unsigned integer

d ¶

signed double-cell integer

ud ¶

unsigned double-cell integer

r ¶

Float (on the FP stack)

addr

Address without further information

a- ¶

Cell-aligned address

c- ¶

Char-aligned address, address used to point to a character or start of a string.

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

nt

Name 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.

" ¶

String in the input stream (not on the stack), typically space-delimited.

' ¶

String in the input stream, delimited by the last character before the closing '. E.g., 'ccc"' indicates a string in the input stream that is terminated by ".