2. FORTH FUNDAMENTALS

This section defines the major elements of the Forth language. These words are grouped into categories. Except where noted as deriving from “common usage,” all words are found in, and comply with, the American National Standard for the Forth language (ANSI X3.215:1994, equivalent to ISO/IEC 15145:1997), commonly referred to here as Standard Forth. Appendix A,“Glossary & Notation” on page 203 provides definitions of many of the terms used in this section, as well as a detailed description of the notation conventions.

2.1 STACK OPERATIONS

Forth is based on an architecture incorporating push-down stacks (last-in, first-out lists). The data stack is used primarily for passing parameters between procedures. The return stack is used primarily for system functions, such as procedure return addresses, loop parameters, etc.

Stack operators work on data that are on one or more of the stacks. The words defined in this section use the stack as the major source and destination for their operands. Many other Forth words also result in modification of the stack, and are described in the sections of this manual that deal with their primary functions. Besides the stack operators discussed in this manual, stack manipulation words that relate to assembly language are covered in Section 5 and in your Forth system’s documentation.

2.1.1 Stack Notation

Stack parameters used as input to and output from a procedure are described using the notation:

Forth Fundamentals 31

Forth Programmer’s Handbook

( stack-id before — after )

Operations that use the stack usually require that a certain number of items be present on the stack, and then leave another number of items on the stack as results. Most operations remove their operands, leaving only the results. To help see an operation’s effect on the number and type of items on the stack, each word has a stack notation.

Individual stack items are depicted using the notation in Table 11, Section B.3. Any other, special notation will be explained when used. Where several arguments are of the same type, and clarity demands that they be distinguished, numeric subscripts are used.

If you type several numbers on a line, the rightmost will end up on top of the stack. As a result, we show multiple stack arguments with the top element to the right. If alternate conditions may exist, they are separated by a vertical bar (|), meaning “or.” For example, the notation ( — n1 | n2 n3 ) indicates a word that may leave either one or two stack items; and ( — addr | 0 ) indicates that the procedure takes no input and returns either a valid address or zero.

Please remember that the items shown in a word’s stack notation are relative to the top of the stack and do not affect any stack items that may be below the lowest stack item referenced by the operation. For example, ( x1 x2 — x3 ) describes an operation that uses the top two stack items and leaves a different, one-item result. Therefore, if the stack initially contained three items, execution would result in a stack of two items, with the bottom item unchanged and the top item derived as a result of the operation.

Some procedures have stack effects both when they are compiled and when they are executed. The stack effects shown in this manual refer to the execu- tion-time behavior unless specifically noted, because this is usually the behavior of most interest to a programmer.

Where an operation is described that uses more than one stack, the data stack stack-id is S: and the return stack stack-id is R:. When no confusion is possible, the data stack stack-id may be omitted.

With the addition of the floating-point stack (see Section 3.8), it becomes necessary to document its contents, as well. Floating-point stack comments follow the data stack comments, and are indicated by F:. If a command does not affect

32 Forth Fundamentals

Forth Programmer’s Handbook

the floating-point stack, only the data stack comments are shown, and vice versa. If neither stack is affected, a null data stack comment is shown.

For example:

: SF@ ( a-addr — ) ( F: — r )

indicates that an address is removed from the data stack, and a floating-point number is pushed on the floating-point stack by the execution of SF@.

: F. ( F: r — )

indicates that there are no data stack arguments, and that a floating-point number is removed from the floating-point stack by the execution of F..

References Data stack, Section 1.1.3

Data types in stack notation, Section B.3

2.1.2 Data Stack Manipulation Operations

This category of stack operations contains words which manipulate the contents of the data stack without performing arithmetic, logical, or memory reference operations.

Rotate the top three cell pairs on the stack, bringing cell pair x1 x2 to the top of

Forth Fundamentals 33

Forth Programmer’s Handbook

34 Forth Fundamentals