Forth Programmer’s Handbook

[ELSE] is only executed if the flag for the associated [IF] was true; therefore, it always discards the words between [ELSE] and [THEN]. “bracket-else”

[THEN] ( — ) Tools Ext

Take no action. [THEN] has no function by itself, but must exist in the source code in order to mark the end of the parsing for [IF] or [ELSE]. “bracket-then”

References REFILL, Section 3.5.3

4.2 DEFINING WORDS

Forth provides a basic set of words used to define objects of various kinds. As with other features of Forth, the set of such commands may be expanded. Here we will present those which are standard in all Forth systems, exclusive of the defining words that are part of database support options and the assembler defining words (see your product documentation).

4.2.1 Creating a Dictionary Entry

A word is defined when an entry is created in the dictionary. CREATE is the basic word that does this; it may be used by :, CODE, VARIABLE, CONSTANT, and other defining words to perform the initial functions of setting up the dictionary entry. CREATE behaves as follows:

1.Memory is checked to see if a minimum amount remains. If not, there may be an abort. At the same time, the data-space pointer is aligned to an even cell address, if the system being used requires it.

2.WORD fetches the next word in the input stream. A dictionary entry is created for this word, with a pointer to the previous entry in this word list.

3.The code field of the new word is set to point to the run-time code of CREATE, which will push the address of this word’s parameter field onto the stack when the word is executed. However, no data space is allocated by CREATE.

Other defining words that use CREATE may reset the new word’s code field to define different run-time behavior by using the words ;CODE or DOES>. Fig-

132 The Forth Interpreter and Compiler

Forth Programmer’s Handbook

ure 9 shows an example of a dictionary entry built by CREATE.

CREATE is often used to mark the beginning of an array. The space for the rest of the array is reserved by incrementing the dictionary pointer with ALLOT, as in this example:

CREATE DATA 100 CELLS ALLOT

The example reserves a total of 100 cells for an array named DATA. When DATA is used in a colon definition, the address of the first byte of DATA will be pushed on the stack by the run-time behavior of CREATE. The array is not initialized. If you wish to set all the elements of the array to zero, you may use ERASE as in the following example:

DATA 100 CELLS ERASE

Figure 9. Dictionary entry built by CREATE

The word UNUSED places on the stack the number of bytes left in the memory area where dictionary entries are constructed. On some systems, this region of memory is also used for other purposes, with the dictionary starting at the bottom and growing towards high memory, and with something else starting at the top and growing towards low memory. On such systems, UNUSED may give different answers at different times, even though the dictionary pointer is not changed.

The Forth Interpreter and Compiler 133

Forth Programmer’s Handbook

and n is a multiple of the cell size, the data space pointer will remain aligned after the ALLOT.

4.2.2 Variables

A VARIABLE is a named memory location whose value may be fetched onto the stack or stored into, with equal ease.

The definition of a VARIABLE takes the form:

VARIABLE <name>

This constructs a definition for name, with one cell allotted for a value. A singlecell value may be stored into the parameter field of the definition. For example:

VARIABLE DATA 6 DATA !

will store 6 in the parameter field of DATA.

When a VARIABLE is referenced by name, the address of its parameter field is pushed onto the stack. This address may be used with @ or ! to fetch or store, respectively, the variable’s current value.

134 The Forth Interpreter and Compiler

Forth Programmer’s Handbook

Similarly, the word 2VARIABLE defines a variable whose parameter field is two cells long. Such a variable may contain one double-precision number or a pair of single-precision numbers (such as x,y coordinates), or even two unrelated values. 2VARIABLE differs from VARIABLE only in the number of bytes allotted. The operators 2@ and 2! are used with this format.

On some eight-bit and 16-bit CPUs, such as those used in embedded systems in which data space is limited, CVARIABLE defines a variable that is one byte long. The operators C@ and C! are used with this format. Note that since CVARIABLE allots only one byte, it will leave the data space pointer unaligned. If you are concerned about alignment, you should either group CVARIABLEs so as to leave the space aligned, or use ALIGN afterwards.

In summary, to place the value of a VARIABLE on the stack, invoke its name and a fetch instruction. For example, you could type:

<variable name> @ or <variable name> 2@

To store a value into a variable, invoke its name and a store instruction. For example:

<value> <variable name> !

or <value1> <value2> <variable name> 2!

In a read-only-memory environment, VARIABLE is re-defined to allot space in read/write memory rather than in name’s parameter field; in this case, the assigned read/write memory address is compiled into the parameter field. The run-time behavior of a variable in ROM is to return the contents of its ROM parameter field (like a constant does); that value is the address of the variable's data space in RAM.

Define a two-cell variable. Execution of name will return the address of its data

The Forth Interpreter and Compiler 135