15.6.2.2297
TRAVERSE-WORDLIST
 
TOOLS EXT
 
( i * x xt wid -- j * x )

Remove wid and xt from the stack. Execute xt once for every word in the wordlist wid, passing the name token nt of the word to xt, until the wordlist is exhausted or until xt returns false.

The invoked xt has the stack effect ( k * x nt -- l * x flag ).

If flag is true, TRAVERSE-WORDLIST will continue with the next name, otherwise it will return. TRAVERSE-WORDLIST does not put any items other than nt on the stack when calling xt, so that xt can access and modify the rest of the stack.

TRAVERSE-WORDLIST may visit words in any order, with one exception: words with the same name are called in the order newest-to-oldest (possibly with other words in between).

An ambiguous condition exists if words are added to or deleted from the wordlist wid during the execution of TRAVERSE-WORDLIST.

See:
A.15.6.2.2297 TRAVERSE-WORDLIST, 15.6.2.1909.40 NAME>STRING,
15.6.2.1909.20 NAME>INTERPRET, 15.6.2.1909.10 NAME>COMPILE.

Rationale:
Typical use:

: WORDS-COUNT ( x nt -- x' f ) DROP 1+ TRUE ;
0 ' WORDS-COUNT FORTH-WORDLIST TRAVERSE-WORDLIST .

prints a count of the number of words in the FORTH-WORDLIST.

: ALL-WORDS NAME>STRING CR TYPE TRUE ;
' ALL-WORDS GET-CURRENT TRAVERSE-WORDLIST
prints the names of words in the current compilation wordlist.

: CONTAINS-STRING
   NAME>STRING 2OVER SEARCH IF CR TYPE THEN FALSE ;
S" COM" ' CONTAINS-STRING GET-CURRENT TRAVERSE-WORDLIST
prints the name of a word containing the string "COM", if it exists, and then terminates.