A wordlist is a list of named words; you can add new words and look up
words by name (and you can remove words in a restricted way with
markers). Every named (and revealed) word is in one wordlist.
The text interpreter searches the wordlists present in the search order (a stack of wordlists, see User-defined Stacks), from the top to the bottom. Within each wordlist, the search starts conceptually at the newest word; i.e., if two words in a wordlist have the same name, the newer word is found.
New words are added to the compilation wordlist (aka current wordlist).
A word list is identified by a cell-sized word list identifier (wid) in much the same way as a file is identified by a file handle. The numerical value of the wid has no (portable) meaning, and might change from session to session.
The Standard Forth “Search order” word set is intended to provide a set of
low-level tools that allow various different schemes to be
implemented. Gforth also provides vocabulary, a traditional Forth
word. compat/vocabulary.fs provides an implementation in Standard
Forth.
Constant – wid identifies the word list that includes
all of the standard words provided by Gforth. When Gforth is
invoked, this word list is the compilation word list and is at
the top of the search order.
Set the compilation word list to be the same as the word list that is currently at the top of the search order.
wid is the identifier of the current compilation word list.
Set the compilation word list to the word list identified by wid.
execute defining-word with wordlist as one-shot current
directory. Example: gui-wordlist in-wordlist : init-gl ... ;
will define init-gl in the gui-wordlist wordlist.
execute defining-word with voc as one-shot current
directory. Example: in gui : init-gl ... ; will define
init-gl in the gui vocabulary.
Copy the search order to the data stack. The current search order has n entries, of which wid1 represents the wordlist that is searched first (the word list at the top of the search order) and widn represents the wordlist that is searched last.
If n=0, empty the search order. If n=-1, set the
search order to the implementation-defined minimum search order
(for Gforth, this is the word list Root). Otherwise,
replace the existing search order with the n wid entries
such that wid1 represents the word list that will be
searched first and widn represents the word list that will
be searched last.
Create a new, empty word list represented by wid.
Create a lookup table (case-sensitive, no warnings).
Create a case-sensitive wordlist.
Create a case-sensitive vocabulary
Push wid on the search order.
Drop the wordlist at the top of the search order.
Like DUP for the search order. Usually used before a
vocabulary (e.g., also Forth); the combined effect is to push
the wordlist represented by the vocabulary on the search order.
Replace the wid at the top of the search order with the
wid associated with the word list forth-wordlist.
Set the search order to the implementation-defined minimum search
order (for Gforth, this is the word list Root).
Print the search order and the compilation word list. The word lists are printed in the order in which they are searched (which is reversed with respect to the conventional way of displaying stacks). The compilation word list is displayed last.
print the name of the wordlist represented by wid. Can
only print names defined with vocabulary or
wordlist constant, otherwise prints ‘address’.
We recommend to use find-name instead of find.
Search all word lists in the current search order for the
definition named by the counted string at c-addr. If the
definition is not found, return 0. If the definition is found,
return 1 (if the definition has non-default compilation
semantics) or -1 (if the definition has default compilation
semantics). The xt returned in interpret state represents
the interpretation semantics. The xt returned in compile
state represented either the compilation semantics (for
non-default compilation semantics) or the run-time semantics
that the compilation semantics would compile, (for
default compilation semantics). The Forth-2012 standard does
not specify clearly what the returned xt represents (and
also talks about immediacy instead of non-default compilation
semantics), so this word is questionable in portable programs.
If non-portability is ok, find-name and friends are
better (see Name token).
We recommend to use find-name-in instead of
search-wordlist.
Search the word list identified by wid for the definition
named by the string at c-addr count. If the definition is
not found, return 0. If the definition is found return 1 (if
the definition has non-default compilation semantics) or -1 (if
the definition has default compilation semantics) together with
the xt. In Gforth, the xt returned represents the
interpretation semantics. Forth-2012 does not specify clearly
what xt represents.
Display a list of all of the definitions in the word list at the top of the search order.
Old (pre-Forth-83) name for WORDS.
Display the contents of the wordlist wid.
List all words in the word list on top of the search order. If
a pattern is given, show only the words matching pattern.
Words are listed old to new (reverse from words). By
default search is used to determine matching. You can
switch to globbing as used by shells for files with '
mword-filename-match is mword-match.
Replace the top of the search order by the root wordlist. This vocabulary makes up the minimum search order and contains only a few search-order words.
Create a definition "name" and associate a new word list wid1 with it.
name execution: ( – ) replace the wid2 at the
top of the search order with wid1.
Remove all word lists from the search order stack other than the word list that is currently on the top of the search order stack.
List vocabularies and wordlists defined in the system.
Variable – holds the wid of the compilation word list.
context @ is the wid of the word list at the
top of the search order.
Perform xt ( ... wid – ... ) for all wordlists (including tables and cs-wordlists) in the system.