Next: , Previous: The Input Stream, Up: Words


5.15 Word Lists

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), 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 ANS 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 ANS Forth.

forth-wordlist       – wid         search       “forth-wordlist”

Constantwid 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.

definitions              search       “definitions”

Set the compilation word list to be the same as the word list that is currently at the top of the search order.

get-current       – wid         search       “get-current”

wid is the identifier of the current compilation word list.

set-current       wid –         search       “set-current”

Set the compilation word list to the word list identified by wid.

get-order       – widn .. wid1 n         search       “get-order”

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.

set-order       widn .. wid1 n –         search       “set-order”

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.

wordlist       – wid         search       “wordlist”

Create a new, empty word list represented by wid.

table       – wid         gforth       “table”

Create a case-sensitive wordlist.

>order       wid –         gforth       “to-order”

Push wid on the search order.

previous              search-ext       “previous”

Drop the wordlist at the top of the search order.

also              search-ext       “also”

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.

Forth              search-ext       “Forth”

Replace the wid at the top of the search order with the wid associated with the word list forth-wordlist.

Only              search-ext       “Only”

Set the search order to the implementation-defined minimum search order (for Gforth, this is the word list Root).

order              search-ext       “order”

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.

find       c-addr – xt +-1 | c-addr 0         core,search       “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 ANS Forth 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).

search-wordlist       c-addr count wid – 0 | xt +-1         search       “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 is immediate) or -1 (if the definition is not immediate) together with the xt. In Gforth, the xt returned represents the interpretation semantics. ANS Forth does not specify clearly what xt represents.

words              tools       “words”

Display a list of all of the definitions in the word list at the top of the search order.

vlist              gforth       “vlist”

Old (pre-Forth-83) name for WORDS.

Root              gforth       “Root”

Add the root wordlist to the search order stack. This vocabulary makes up the minimum search order and contains only a search-order words.

Vocabulary       "name" –         gforth       “Vocabulary”

Create a definition "name" and associate a new word list with it. The run-time effect of "name" is to replace the wid at the top of the search order with the wid associated with the new word list.

seal              gforth       “seal”

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.

vocs              gforth       “vocs”

List vocabularies and wordlists defined in the system.

current       – addr         gforth       “current”

Variable – holds the wid of the compilation word list.

context       – addr         gforth       “context”

context @ is the wid of the word list at the top of the search order.