The Stack Diagram

To aid understanding, conventional coding style requires that a stack diagram of the form ( -- ) appear on the first line of every definition of a Forth word. The stack diagram specifies what the execution of the word does to the stack.

Entries to the left of -- represent those stack items that the word removes from the stack and uses during its operation. The right-most of these items is on top of the stack, with any preceding items beneath it. In other words, arguments are pushed onto the stack in left to right order, leaving the most recent one (the right-most one in the diagram) on the top.

Entries to the right of -- represent those stack items that the word leaves on the stack after it finishes execution. Again, the right-most item is on top of the stack, with any preceding items beneath it.

For example, a stack diagram for the word + is:

( nu1 nu2 -- sum )

Therefore, + removes two numbers (nu1 and nu2) from the stack and leaves their sum (sum) on the stack. As a second example, a stack diagram for the word. is:

( nu -- )

The word . removes the number on the top of the stack (nu) and displays it.

Words that have no effect on the contents of the stack (such as showstack or decimal), have a ( -- ) stack diagram.

Occasionally, a word will require another word or other text immediately following it on the command line. The word see, used in the form:

see thisword

is such an example.

Stack items are generally written using descriptive names to help clarify correct usage. See Table 4-2 for stack item abbreviations used in this manual.

Table 4-2 Stack Item Notation

Notation	Description
|	Alternate stack results shown with space, e.g. ( input -- addr len false | result true ).
???	Unknown stack item(s).
...	Unknown stack item(s). If used on both sides of a stack comment, means the same stack items are present on both sides.
< > <space>	Space delimiter. Leading spaces are ignored.
a-addr	Variable-aligned address.
addr	Memory address (generally a virtual address).
addr len	Address and length for memory region
byte bxxx	8-bit value (low order byte in a cell).
char	7-bit value (low order byte in a cell, high bit of low order byte unspecified).
cnt	Count.
len	Length.
size	Count or length.
dxxx	Double (extended-precision) numbers. 2 cells, most significant cell on top of stack.
<eol>	End-of-line delimiter.
false	0 (false flag).
n n1 n2 n3	Normal signed, one-cell values.
nu nu1	Signed or unsigned one-cell values.
<nothing>	Zero stack items.
o o1 o2 oct1 oct2	Octlet (64 bit signed value).
oaddr	Octlet (64-bit ) aligned address.
octlet	An eight-byte quantity.
phys	Physical address (actual hardware address).
phys.lo phys.hi	Lower / upper cell of physical address.
pstr	Packed string.
quad qxxx	Quadlet (32-bit value, low order four bytes in a cell).
qaddr	Quadlet (32-bit) aligned address.
true	-1 (true flag).
uxxx	Unsigned positive, one-cell values.
virt	Virtual address (address used by software).
waddr	Doublet (16-bit) aligned address.
word wxxx	Doublet (16-bit value, low order two bytes in a cell).
x x1	Arbitrary, one cell stack item.
x.lo x.hi	Low/high significant bits of a data item.
xt	Execution token.
xxx?	Flag. Name indicates usage (e.g. done? ok? error?).
xyz-str xyz-len	Address and length for unpacked string.
xyz-sys	Control-flow stack items, implementation-dependent.
( C: -- )	Compilation stack diagram.
( -- )( E: -- )	Execution stack diagram.
( R: -- )	Return stack diagram.