Forth Programmer’s Handbook

4.2.6 Custom Defining Words

One of the most powerful capabilities in Forth is the ability to define new defining words. Thus, the programmer may create new data types with characteristics peculiar to the application, new generic types of words, and even new classes of words with a specified behavior that is common to each class.

In creating a custom defining word, the programmer must specify two separate behaviors:

!The compile-time behavior of the defining word (creating the dictionary entry, compiling parameters, etc.).

!The run-time behavior (the action to be performed by words created by the new defining word).

In the cases discussed in the next two sections, compile-time behavior is described in high-level Forth. Several methods for specifying run-time behavior are also discussed.

4.2.6.1 Basic Principles of Defining Words

There are two ways to create new defining words in Forth. In the one case (using DOES>), the run-time behavior is described in high-level Forth; in the other (using ;CODE), the run-time behavior is described in assembler code. The basic principles are the same.

In Forth, a defining word will create a new dictionary entry when executed. All words defined by the same defining word share a common compile-time and run-time behavior. For example, VARIABLE is a defining word; all words defined by VARIABLE share two common characteristics:

!Each has one cell allotted in which a value may be stored. These bytes may be initialized to zero in some systems.

!When executed, each of these words will push onto the stack the address of this one-cell reserved area.

On the other hand, all words defined by CONSTANT, which is another defining word, share two other behaviors:

142 The Forth Interpreter and Compiler

Forth Programmer’s Handbook

!Each has compiled into its parameter field a single-precision value, which was on the stack when CONSTANT was executed.

!When a word defined by CONSTANT executes, it puts its value on the stack.

In each of these examples, the first behavior (the compile-time action) relates to the physical construction of the word, which is determined when the word is compiled. The second behavior describes what all defined words of that type do when executed. All defining words must have a compile-time behavior and a run-time behavior.

The general definition of a defining word looks like:

:<name> <compile-time behavior> <transition word> <run-time behavior> <ending>

The transition word ends the specification of compile-time behavior and begins the specification of run-time behavior. There are two such transition words: ;CODE begins run-time behavior described in code (assembler), and DOES> begins run-time behavior described in high-level Forth. Each of the transition words requires a different ending; in the case of DOES>, it is ; (semi-colon); in the case of ;CODE, it is an implementation-defined code ending.

The exact behavior of these two words is discussed in the following sections. The description of compile-time behavior is the same, regardless of which transition word is used. In fact, if you change the transition word and runtime behavior from DOES> plus high-level to ;CODE plus equivalent code, no change to the compile-time behavior is necessary.

The compile-time portion of a defining word must contain CREATE (or a defining word that calls CREATE) to create the dictionary entry. If one or more parameters are to be compiled, or if space for variable data is to be allocated, it is convenient to use a previously defined defining word which takes care of that.

Every defining word must provide space for data or code belonging to each instance of the new class of words. For example, when a variable is defined, space is allotted for its parameter field. If more space is needed, the usual approach is to use CREATE followed by ALLOT.

After a new defining word has been created, it can be used to create specific instances of its class, with the syntax:

The Forth Interpreter and Compiler 143

Forth Programmer’s Handbook

<parameters> <defining word> <instance1> <parameters> <defining word> <instance2>

and so forth. The instance1 and instance2 are names that would be specified in an application. The parameters are optional, depending on the defining word, and are specific to each instance.

When a defining word is executed, it may be followed by any number of words—such as , (to compile a single-precision value) or C, (to compile an eight-bit value) to fill the allotted storage area with explicit values.

Glossary

References , and C,, Section 4.3.2

;CODE, Section 5.2

ALLOT, Section 4.3.1

CONSTANT, Section 4.2.3

CREATE, Section 4.2.1

DOES>, Section 4.2.6.2

VARIABLE, Section 4.2.2

4.2.6.2 High-level Defining Words

New defining words whose run-time behavior is specified in high-level Forth may be created by using a technique similar to that used for ;CODE. For these definitions, the word DOES> terminates the compile-time portion of the definition and introduces the run-time portion. The form of a DOES> definition is:

144 The Forth Interpreter and Compiler

Forth Programmer’s Handbook

After such a definition is compiled, name can be used to define a new instance of this class of words. Here, however, the run-time behavior of this class is described in high-level Forth.

At run time, the address of name’s parameter field is pushed onto the stack before the run-time words are executed. This provides easy access to the parameter field.

An example of a DOES> definition is the word MSG, which might be used to type short character sequences:

DOES> ( -- ) COUNT TYPE ;

Here is an example of how MSG would be used (assuming HEX base):

(CR) is a specific instance of the MSG class: it uses the same code (the DOES> phrase) as other words defined by MSG, but uses that code to emit its own unique character string.

Link to next definition

Control bits

Figure 11. Example of structures defined by using DOES>

The values that comprise the string are kept in the parameter field of the word—in this case, (CR)—defined by MSG. At execution time, the defining word’s DOES> puts the address of the instance’s parameter field (which, here, is used to store the string) on the stack to serve as the parameter for COUNT,

The Forth Interpreter and Compiler 145