The Dictionary and Vocabularies

You don't really need to know much about the dictionary other than that it contains the words and vocabularies. As has already been said, a word is Forth's terminology for a command. Why call it a word? Because Forth also implements a method of hiding data called vocabularies. A vocabulary contains a list of related words and variables. For example, the forth vocabulary contains almost all of the words available in a basic Forth distribution. To create a new vocabulary you use the word called vocabulary (confused yet?):

vocabulary ( "name" -- ) creates a new vocabulary.

Words in one vocabulary do not have immediate access to words in other vocabularies. This is how you can hide data from other parts of the program. In order to get access to words in a vocabulary other than the one you are currently in, you must place the vocabulary in the search path.

    ok order
    context: forth forth root     current: forth 
    ok vocabulary <test>
    ok <test> also
    ok order
    context: <test> <test> forth root     current: forth

This creates the vocabulary <test> (we bound our vocabulary names with < and >) and then places it in the vocabulary search path. The order command displays the vocabularies which Forth will search when word is executed.

also ( -- ) duplicates the top vocabulary in the search path.

order ( -- ) displays the current vocabulary search path.

We use also after placing the vocabulary in the search path because placing a new vocabulary in the search path overwrites the vocabulary previously on top. By duplicating the vocabulary's entry, we avoid accidently removing it from the search path.

If you wish to create a word, you must tell Forth which vocabulary you wish it to be a member of. Your words are placed in the current dictionary, forth by default and <dsp> when in the dspsys program. Setting your current dictionary is done with the definitions command.

    ok order
    context: <test> <test> forth root     current: forth
    ok <test> definitions
    ok order
    context: <test> <test> forth root     current: <test>

You can see that the current: field changed from forth to <test>. This means that whatever word you define will be placed in the <test> vocabulary. The default vocabulary for your words would normally be forth, but in our dspsys program the default is <dsp>.

definitions ( -- ) sets the compilation vocabulary to be the vocabulary currently on top of the search path.

Defining Words

Now you know enough to start learning about how to define words. Defining a word is very easy. First you use a colon (:) to tell Forth you are going to define a word and then the name you want the command to have. Now enter the commands you want the new word to execute and finish the definition with a semi-colon (;).

    ok : 2dup over over ;

This is exactly how the 2dup command is defined in Forth. This type of word is called a "colon-defined" word.

In our lab, we provide a little more information so that help can be extracted from the source files.

    : 2dup ( n1 n2 -- n1 n2 n1 n2 ) \ Duplicate two numbers.
                                    \ Pronounced: two-dupe.
        over over  ;

This introduces two methods of commenting your source code. The first uses the "( " (paren-space) word to start a comment which continues until reaching a closing paren ")". This is the way we comment stack notation, but it is not limited to just stack comments. The second commenting method uses "\ " (backslash-space). This causes the rest of the line to be considered a comment. We use these comments to tell future programmers and users what the word actually does.

NOTE: If you are just defining a word directly in Forth and not in the source code file, you can forgo all this commenting.

Top: Forth Index

Prev: The Stack

Next: Arithmetic