Using Defining Words

The dictionary contains all the available Forth commands. Defining words are used to create new Forth commands.

Defining words require two stack diagrams. The first diagram shows the stack effect when the new command is created. The second (or "Usage:") diagram shows the stack effect when that command is later executed.

Table 4-7 lists the defining words that you can use to create dictionary entries.

Table 4-7 Defining Words

Command	Stack Diagram	Description
: name	( -- ) Usage: ( ??? -- ? )	Start creating a new colon definition.
;	( -- )	Finish creating a new colon definition.
alias new-name old-name	( -- ) Usage: ( ??? -- ? )	Create new-name with the same behavior as old-name.
buffer: name	( size -- ) Usage: ( -- a-addr )	Create a named array in temporary storage.
constant name	( n -- ) Usage: ( -- n )	Define a constant (for example, 3 constant bar).
2constant name	( n1 n2 -- ) Usage: ( -- n1 n2 )	Define a 2-number constant.
create name	( -- ) Usage: ( -- waddr )	Generic defining word.
defer name	( -- ) Usage: ( ??? -- ? )	Define a word for forward references or execution vectors using execution token.
does>	( -- waddr )	Start the run-time clause for defining words.
field name	( offset size -- offset+size ) Usage: ( addr -- addr+offset )	Create a named offset pointer.
struct	( -- 0 )	Initialize for field creation.
value name	( n -- ) Usage: ( -- n )	Create a changeable, named 32-bit quantity.
variable name	( -- ) Usage: ( -- waddr )	Define a variable.

You can use the defining word constant to create a name whose value will not change. A simple colon definition : foo 22 ; accomplishes a similar result.

---

ok 72 constant red 
ok
ok red . 
72
ok 

---

value lets you assign a name to any number. Later execution of that name leaves the assigned value on the stack. The following example assigns a value of 22 to a word named foo, and then calls foo to use its assigned value in an arithmetic operation.

---

ok 22 value foo
ok foo 3 + .
25
ok 

---

The value can be changed with the dictionary compiling word is. For example:

---

ok 43 value thisval
ok thisval .
43
ok 10 to thisval
ok thisval .
10
ok 

---

Commands created with value are convenient, because you do not have to use @ every time you want the number.

The defining word variable assigns a name to a 32-bit region of memory, which you can use to hold values as needed. Later execution of that name leaves the address of the memory on the stack. Typically, @ and ! are used to read or write at that address. For example:

---

ok variable bar
ok 33 bar !
ok bar @ 2 + .
35
ok 

---

The defining word defer lets you change the execution of previously defined commands, by creating a slot which can be loaded with different functions at different times. For example:

---

ok hex
ok defer printit
ok ['] .d  to  printit
ok ff printit
255
ok : myprint ( n -- ) ." It is " .h
] ." in hex " ;
ok ['] myprint to printit
ok ff printit
It is ff in hex
ok 

---