What are word lists?

[SirWumpus]

I've been reading section 16 The optional Search-Order word set and it talks about word lists. As this is an optional word set, what are word lists, what are they good for, and why do I want one (or more)?

[mgcaret]

Word lists are basically multiple dictionaries. Some Forth systems refer to an overlapping concept as "vocabularies". A basic Forth has one word list where definitions are compiled to and searched for. If you implement the Search-Order word set, you get multiple word lists. The word list where new definitions are compiled, and the word lists that are searched for definitions become separate concerns.

Word lists can be used to do various things, like grouping related words or namespace applications with conflicting word names. They are one way of implementing environmental queries. You can also use them as the basis for more advanced things like object-oriented extensions.

[ruv]

what are word lists, what are they good for, and why do I want one (or more)?

Even if a Forth system does not provide the Search-Order word set, it does have at least one word list behind the scenes.

Word lists are used to resolve names. They keep associations of Forth word names with their execution tokens and other attributes. Formally, a word list is an ordered list of pairs (name, attributes). A word list is identified by a value of the data type "word list identifier" (wid), a word list element is identified by a value of the data type "name token" (nt).

Word lists are a kind of namespace. They are also used to separating concerns, separating interface from implementation, hiding implementation details, separating one module from another module, implementing OOP, etc.

For example, a word for placing definitions in a separate new wordlist when including a file could be implemented as follows:

: push-order ( wid -- ) >r get-order r> swap 1+ set-order ;
: pop-order ( -- wid ) get-order swap >r 1- set-order r> ;
: drop-order ( -- ) pop-order drop ;

: execute-in-wordlist  ( i*x wid xt -- j*x )
  \ xt ( i*x -- j*x )
  \ xt shall left unchanged the compilation word list and the search order.
  get-current >r get-order n>r
  swap dup set-current push-order
  catch
  nr> set-order r> set-current
  throw
;
: include-wordlist( ( i*x "name" "filename" "<rparen>" -- j*x )
  wordlist dup >r constant
  parse-name  parse-name s" )" compare abort" (expected ')')"
  r> ['] included execute-in-wordlist
; immediate

\ Usage example
\   include-wordlist( foo /work/forth/2024/foo.fth )

A word to show words from a specified word list:

: words-in ( wid -- ) push-order words drop-order ;