Define a one-byte variable. Execution of name will return the address of its data space. Typically available only on embedded systems. “C-variable”

References @, !, 2@, and 2!, Section 2.1.2

ALIGN, Section 4.3.2

4.2.3 CONSTANTs and VALUEs

The purpose of a CONSTANT is to provide a name for a value which is referenced often but may be changed seldom or never. There are both singleand double-precision versions. Figure 10 shows an example of a dictionary entry built by CONSTANT.

Figure 10. Dictionary entry built by CONSTANT

The syntax for defining constants is:

<value> CONSTANT <name>

For example, you may define:

1000 CONSTANT LIMIT

0 5000 2CONSTANT LIMITS

3141593. 2CONSTANT PI

When a CONSTANT is referenced by name, its value (not its address) is pushed onto the stack. Similarly, when a 2CONSTANT is referenced, two stack items

136 The Forth Interpreter and Compiler

Forth Programmer’s Handbook

are pushed onto the stack. In the case where a 2CONSTANT is used for two values (as in LIMITS, above), the values are placed on the stack in the order specified (e.g., 5000 on top, 0 below). In the case of a double-precision number, the high-order part of the number is on top of the stack.

In order to change a CONSTANT you must first obtain its address. This is done by using ' in interpretive mode or ['] inside a colon definition, in either case followed by the name of the CONSTANT and >BODY to get its data space address. The command ! will store into the address of a CONSTANT thus obtained, and 2! stores into the fetched address of a 2CONSTANT.

For example, you might type this:

100 CONSTANT SIZE

500 ' SIZE >BODY !

The first phrase creates a CONSTANT named SIZE whose value is 100. The second phrase changes the value to 500.

In many systems, such as those with a mix of RAM and ROM, you may not be

!permitted to store into constants at all. For example, the value of a CONSTANT may be in ROM.

The purpose of a VALUE is to provide a name for a single-precision value which is referenced often and but which may need to change. On systems with a mix of RAM and ROM, VALUEs are compiled into RAM. The procedure for defining values is to declare:

<initial value> VALUE <name>

For example, you may define:

1000 VALUE LIMIT

When a VALUE is referenced by name, its current value is pushed onto the stack. The word TO is used to change a value. The syntax is:

<new value> TO < name>

For example, you might type this:

The Forth Interpreter and Compiler 137

Forth Programmer’s Handbook

The first phrase creates a VALUE named LIMIT whose value when defined is 1000. The second phrase changes the value to 500.

VALUE combines the convenience of a CONSTANT—it returns its value without requiring an explicit @—with the writeability of a VARIABLE.

Define a double-cell constant name whose value may be a double-precision number or a pair of single-precision numbers. “two-constant”

Define a single-precision data object name whose initial value is x.

4.2.4 Colon Definitions

The defining word : (colon) is discussed briefly in Section 1.1.7, and numerous examples appear in other sections. In this section, we describe the use and behavior of this important defining word.

The basic form of a : definition is:

When the colon is executed, the system enters a compilation state. A dictionary entry is created for the word name. action represents a list of previously defined words that will be executed in sequence whenever name is invoked. The ; terminates the definition and returns the system to interpretation state.

The variable STATE contains the compilation-state flag. The value of STATE is true (non-zero) when compiling (e.g., between : and ;), and is false (zero) when

138 The Forth Interpreter and Compiler

Forth Programmer’s Handbook

interpreting. STATE is only changed by the following seven Standard words: :, ;, ABORT, QUIT, :NONAME, [, and ]. Programs that comply with Standard Forth may not modify STATE directly.

Each of the words : and ; has two types of behavior, one for compile time and another for run time.

At compile time, : constructs a dictionary entry (e.g., by using CREATE) and begins compiling. It also smudges the name so the word will not inadvertently compile a reference to itself. (The word RECURSE may be used where the definition of a word must call itself.)

The run-time behavior of a word defined by : is to execute the words whose execution tokens form the body of the definition.

The ; ends compilation and compiles the run-time code for ; (the word EXIT on most indirect-threaded implementations). This code pops the address on top of the return stack into the VM’s instruction pointer. The effect is to return to the calling environment.

Most of the words that make up the content of a definition are not executed during compilation; instead, references to them are compiled in the parameter field of the definition. The exception to this procedure are the words which are compiler directives or literals. These generally have both compile-time and run-time behaviors, just as : and ; do.

Every colon definition requires a minimum of three components: a colon, a name, and a semicolon. Such a minimum definition (commonly called a null definition) will execute properly, but will do no work. It does have useful purposes; for example, to provide placeholder definitions for routines to be written later, or to mark a location in the dictionary as the beginning of an overlay area.

It is possible to create high-level Forth definitions without associated names. This is an advanced technique, not commonly used in a Forth application (but see the example in Section 2.5.6). The word that makes nameless definitions is :NONAME, and the syntax is simply:

:NONAME <action> ;

A piece of code created this way is an isolated fragment; it cannot be found in the dictionary and has no referenceable name to cause it to execute. To obtain

The Forth Interpreter and Compiler 139

Forth Programmer’s Handbook

access to it, a :NONAME definition returns its execution token on the stack at the time it is created. The compiling program must take action at that time to store the execution token in a useful place, such as in a table or other data structure. :NONAME is mainly used to build definitions attached (via their execution tokens) to special mechanisms such as execution vectors or a push buttons.

140 The Forth Interpreter and Compiler