OpenBoot 3.x Command Reference Manual

Using Defining Words

The dictionary contains all the available Forth words. Forth defining words create new Forth words.

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

Table 4-14 lists the defining words that you can use to create new Forth words.

If a Forth command is created with the same name as an existing command, the new command will be created normally. Depending on the implementation, a warning message "new-name isn't unique" may be displayed. Previous uses of that command name will be unaffected. Subsequent uses of that command name will use the latest definition of that command name. (To correct the original definition such that all uses of the command name get the corrected behavior, make the correction with patch. (See "Using patch and (patch)")

Table 4-14 Defining Words

Command 

Stack Diagram 

Description 

: name

( -- ) (E: ... -- ??? ) 

Begin creation of a colon definition. 

;

( -- ) 

End creation of a colon definition. 

alias new-name old-name

( -- ) (E: ... -- ??? ) 

Create new-name with the same behavior as old-name.

buffer: name

( size -- ) (E: -- a-addr )  

Create a named data buffer. name returns a-addr. 

constant name

( x -- ) (E: -- x )  

Create a constant (for example, 3 constant bar).

2constant name

( x1 x2 -- ) (E: -- x1 x2 )  

Create a 2-number constant. 

create name

( -- ) (E: -- a-addr )  

Create a new command whose behavior will be set by further commands. 

$create

( name-str name-len -- ) 

Call create with the name specified by name-string.

defer name

( -- ) (E: ... -- ??? )  

Create a command with alterable behavior. Alter with to.

does>

( ... -- ... a-addr ) 

(E: ... -- ??? )  

Specify the run-time behavior of a created word.

field name

( offset size -- offset+size ) (E: addr -- addr+offset ) 

Create a field offset pointer named name. 

struct

( -- 0 ) 

Start a structfield definition.

value name

( x -- ) (E: -- x )  

Create a named variable. Change with to.

variable name

( -- ) (E: -- a-addr )  

Create a named variable. name returns a-addr. 

value lets you create a name for a numerical value that can be changed. Later execution of that name leaves the assigned value on the stack. The following example creates a word named foo with an initial value of 22, and then calls foo to use its value in an arithmetic operation.


ok 22 value foo
ok foo 3 + .
25
ok 

The value can be changed with the word to. For example:


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

Words created with value are convenient, because you do not have to use @ to retrieve their values.

The defining word variable creates a name with an associated one-cell memory location. Later execution of that name leaves the address of the memory on the stack. @ and ! are used to read or write to that address. For example:


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

The defining word defer creates a word whose behavior can be changed later, by creating a slot which can be loaded with different behaviors 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