Forth Programmer’s Handbook

1.1.3 Data Stack

Every Forth system contains at least one data stack. In a multitasked system, each task may have its own data stack. The stack is a cell-wide, push-down LIFO (last-in, first-out) list; its purpose is to contain numeric operands for Forth commands. Commands commonly expect their input parameters on this stack and leave their output results there. The stack’s size is indefinite. Usually it is located at a relatively high memory address and grows downward towards areas allocated for other purposes; see your product documentation for your system’s particular layout. The data stack rarely grows beyond 10–20 entries in a well-written application.

When numbers are pushed onto or popped off the stack, the remaining numbers are not moved. Instead, a pointer is adjusted to indicate the last used cell in a static memory array. On most implementations, the top-of-stack pointer is kept in a register.

Stacks typically extend toward low memory for reasons of implementation efficiency, but this is by no means required or universally true. On implementations on which the stack grows toward low memory, a push operation involves decrementing the stack pointer, while a pop involves incrementing it.

A number encountered by the text interpreter will be converted to binary and pushed onto the stack. Forth data objects such as VARIABLEs and CONSTANTs are defined to push their addresses or values onto the stack. Thus, the stack provides a medium of communication not only between routines but between a person and the computer. You may, for example, place numbers or addresses on the stack and then type words which act on them to produce a desired result. For example, typing:

12 2400 * 45 / .

(a) pushes the number 12 on the stack; (b) pushes 2400 over it (see Figure 4); (c) executes the multiply routine * which replaces both numbers by their product;

(d) pushes 45 on the stack; (e) executes the divide routine / which divides the product by 45; and (f) executes the output routine . (“dot”), which removes and displays the top stack item (the quotient). All numbers put on the stack are removed, leaving the stack as it was before typing 12.

Introduction 7

Forth Programmer’s Handbook

"Bottom" of stack 0

12

Next stack item

2400

Top stack item

Stacks usually grow toward low memory.

Figure 4. Items on the data stack

The standard Forth dictionary provides words for simple manipulation of singleand double-length operands on the stack: SWAP, DUP, DROP, 2SWAP, etc. (covered in detail in Section 2.1).

The push-down stack simplifies the internal structure of Forth and produces naturally re-entrant routines. Passing parameters via the stack means fewer variables must be named, reducing the amount of memory required for named variables (as well as reducing the programmer’s associated housekeeping).

A pointer to the top (i.e., the latest entry) of the user’s stack is maintained by the system. There is also a pointer to the “bottom” of the stack, so that stackempty or underflow conditions can be detected, and to aid in clearing the stack if an abort condition is detected.

Most Forth systems check for stack underflow only after executing (or attempting to execute) a word from the input stream. Underflows that occur in the process of execution will not be detected at that time (see Figure 5).

The usual result of a detected stack underflow is the message:

Stack empty

followed by a system abort.

8 Introduction

Forth Programmer’s Handbook

References Forth re-entrancy, Section 2.5

Stack manipulation, Section 2.1

System abort routines, Section 2.6

Data types in stack notation, Section B.3

Stack operations, Section 2.1

1.1.4 Return Stack

Every Forth system also has a return stack. In a multitasked system, each task has its own return stack, usually located above its data stack in memory. Like the data stack, the return stack is a cell-wide LIFO list. It is used for system functions, but may also be accessed directly by an application program. It serves the following purposes:

!It holds return addresses for nested definitions.

!It holds loop parameters.

!It saves temporary data, such as file and record pointers for database support.

!It saves interpreter pointers when loading source text blocks.

Because the return stack has multiple uses, care must be exercised to avoid conflicts when accessing it directly.

There are no commands for directly manipulating the return stack, except those for moving one or two parameters between the data stack and the return stack.

The maximum size of the return stack for each task is specified at the time the task is defined, and remains fixed during operation; a typical size is 128 cells.

References Loading, Sections 3.4.3, 3.5.1

Loop parameters, Section 2.5.2

Data stack, Section 1.1.3

Transfers between stacks, Section 2.1.4

Introduction 9

Forth Programmer’s Handbook

1.1.5 Text Interpreter

The text interpreter serves these critical functions:

!It executes the commands users type.

!It executes commands in source code stored on disk.

!It executes commands in a string whose address and length are supplied to the word EVALUATE.

The operator’s terminal is the default text source. The keyboard input interrupt handler will accept characters into a text buffer called the terminal input buffer until a user event occurs, such as a Return or Enter keypress, function keypress, mouse click, etc. When such an event is detected, the text interpreter will process the text in the buffer. If interpretation is from source code on disk, it is buffered separately in an implementation-dependent fashion. In general, the place where the text resides that the text interpreter is parsing is called the parse area.

Text interpretation repeats the following steps until the parse area is exhausted or an error has occurred:

1.Starting at the beginning of the parse area, skip leading spaces and extract a word from the input string using the space character (ASCII 32) as a delimiter. Set the interpreter pointer to point to the first character beyond the delimiter. If there was no delimiter (end of input buffer was reached), set the interpreter pointer to the end of the parse area, to complete the operation. If the text is coming from a text file, the interpreter will treat any non-graphic characters as “whitespace” (equivalent to a space character).

2.Search the dictionary for a definition’s name matching the input word (including case sensitivity, if applicable). If a matching definition is found, perform the interpretation behavior of the definition (if currently in interpretation mode), or perform the compilation behavior of the definition (if currently in compiling mode). Then check for stack underflow and, if no error, return to step (1). If there was a stack underflow, abort.

3.If a definition name matching the input word is not found, attempt to convert the word to a binary number (see next section). If this is successful, place the number on the data stack (if currently in interpretation mode); or, if in compiling mode, compile code that, when executed, will place this number on the

10 Introduction

Forth Programmer’s Handbook

data stack (see the definition of LITERAL). Then return to step 1.

4.If neither the dictionary search nor the number conversion is successful, abort. For example, on a block-based system (see Section 3.4), typing:

100 LOAD

causes these two words to be interpreted from the text input buffer. The string 100 is converted as a number and LOAD is found in the dictionary. This particular phrase re-directs the interpreter to the 1024-byte string stored in Block 100. This string is brought into memory from mass storage.

To let one block load another, LOAD saves and restores the interpreter pointers. So, in the middle of a LOAD of one block, that block may LOAD a different block and return to complete the first block. INCLUDE and INCLUDE-FILE work similarly on source code in text files (Section 3.5).

When the text interpreter executes a defining word (e.g., CONSTANT, VARIABLE, or :), a definition is compiled into the dictionary.

A flow diagram for the interpreting process is shown in Figure 5.

The commands SAVE-INPUT and RESTORE-INPUT are available if you wish to manually direct the text interpreter to a different area. These are not required around standard words that control the interpreter, such as LOAD, INCLUDE, and EVALUATE, because they handle this internally.

References Disk blocks, Section 3.4

Text files for program source, Section 3.5

System abort routines, Section 2.6

Text interpreter words, Section 4.1

The LOADing process, Sections 3.4.3, 3.5.3

Using EXIT to leave a load block, Section 3.4.3.1

Introduction 11

Forth Programmer’s Handbook

			INTERPRET
			BEGIN
		Get next string of characters,
		delimited by blanks, and try to
		look it up in the dictionary.
		No	Found?	Yes
	Try to convert the			Execute the word
				(interpretation or
	string to a number.
				compilation behavior).
	Yes	Success?	No	Stack	No
				underflow?
				Yes
	Push the number	Issue "unknown		Issue "stack
	onto the stack	word" message.		empty" message.
	(interpreting), or
	compile literal.
			Reset the stacks and
			interpreter.
				ABORT
		AGAIN
			Endless loop back to BEGIN

Figure 5. Flow diagram of the text interpreter

12 Introduction