15.6.2.2297 TRAVERSE-WORDLIST TOOLS EXT
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:
15.6.2.1909.20 NAME>INTERPRET, 15.6.2.1909.10 NAME>COMPILE.
Rationale:
prints a count of the number of words in the FORTH-WORDLIST.
prints the name of a word containing the string "COM", if it exists, and then terminates.
ContributeContributions
GerryJackson
[19] TRAVERSE-WORDLIST is in the wrong word setComment2016-05-22 20:03:53
Despite TRAVERSE-WORDLIST being regarded as a programming tool it cannot be used or tested unless wordlists can be created which requires at least some of the words in the Search-Order word set. Therefore it belongs in the Search-Order word set.
AntonErtl
Yes, the search order wordset might have been a better place. However, given that TRAVERSE-WORDLIST is in Forth-2012 is in the TOOLS wordset, and there is little point in changing that (given that we don't have wordset queries for Forth-2012, it has no effect on programming). Also, the NAME>... words from the same proposal have nothing to do with the search-order wordset; should we distribute the words from this proposal over several wordsets?
GerryJackson
Ok but I don't see why the NAME>... words shouldn't also go in the Search-Order word set. They and TRAVERSE-WORDLIST are a family of words that belong together and wouldn't be much use without wordlists. Your argument could be used to exclude WORDLIST from the Search-Order wordset as it's only creating a wordlist not affecting the search order (I'm not seriously suggesting that).
AntonErtl
Once we have FIND-NAME, NAME>... makes perfect sense without search order words.
As for the programming tools, it contains two sets of words: words like SEE that are normally used just for debugging and not used inside colon definitions (except for debugging purposes); and words like AHEAD that some in the Forth community consider unnecessary for application programming; NAME>... is in the latter category.
ruv
[118] Unfindable definitionsComment2019-09-20 23:23:52
If a definition is available via TRAVERSE-WORDLIST, can we say that it is findable in the dictionary?
Perhaps, for clarity, we should mention that unfindable definitions (e.g. not ended, or nameless, or quotations) shall not be available via TRAVERSE-WORDLIST. Otherwise, among other issues, SEARCH-WORDLIST cannot be correctly implemented via TRAVERSE-WORDLIST factor.
AntonErtl
Addressed in this proposal.
ruv
[312] TRAVERSE-WORDLIST must not expose the current definitionSuggested Testcase2023-10-23 10:04:08
TRAVERSE-WORDLIST is not allowed to visit the current definition, unfinished or hidden definitions (see also the accepted proposal #153 Traverse-wordlist does not find unnamed/unfinished definitions).
Some systems place the current definition into the compilation word list and change its header in such a way that this definition cannot be found via FIND-NAME-IN or SEARCH-WORDLIST. By a mistake, nt for this definition can be exposed by TRAVERSE-WORDLIST.
This test ensured that the current definition is not exposed, and that the correct number of names is placed into the compilation word list.
: WORDLIST-LENGTH ( wid -- u )
>R 0 [: DROP 1+ TRUE ;] R> TRAVERSE-WORDLIST
;
: L ( -- u ) GET-CURRENT WORDLIST-LENGTH ;
T{ L :NONAME [ L ] LITERAL ; EXECUTE L = = -> TRUE }T
T{ L : TW1 [ L ] LITERAL ; TW1 OVER = SWAP 1+ L = AND -> TRUE }T
ruvNew Version: [312] TRAVERSE-WORDLIST must not expose the current definition
TRAVERSE-WORDLIST is not allowed to visit the current definition, unfinished or hidden definitions (see also the accepted proposal #153 Traverse-wordlist does not find unnamed/unfinished definitions).
Some systems place the current definition into the compilation word list and change its header in such a way that this definition cannot be found via FIND-NAME-IN or SEARCH-WORDLIST. By a mistake, nt for this definition can be exposed by TRAVERSE-WORDLIST.
This test ensured that the current definition is not exposed, and that the correct number of names is placed into the compilation word list.
: WORDLIST-LENGTH ( wid -- u )
>R 0 [: DROP 1+ TRUE ;] R> TRAVERSE-WORDLIST
;
: L ( -- u ) GET-CURRENT WORDLIST-LENGTH ;
T{ L :NONAME [ L ] LITERAL ; EXECUTE OVER = SWAP L = AND -> TRUE }T
T{ L : TW1 [ L ] LITERAL ; TW1 OVER = SWAP 1+ L = AND -> TRUE }T