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: forthThis 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.
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.