[ ] conforms to ANS Forth. WF32 (Alex McDonald) Gforth (Anton Ertl) SwiftForth (Leon Wagner) [ ] already implements the proposal in full since release [ ]. WF32 0.3 [ ] implements the proposal in full in a development version. Gforth [ ] will implement the proposal in full in release [ ]. [ ] will implement the proposal in full in some future release. [ ] There are no plans to implement the proposal in full in [ ]. SwiftForth [ ] will never implement the proposal in full. Mark Wills' system (Mark Wills)
[ ] I have used (parts of) this proposal in my programs. Alex McDonald Anton Ertl [ ] I would use (parts of) this proposal in my programs if the systems I am interested in implemented it. Timothy Knox [ ] I would use (parts of) this proposal in my programs if this proposal was in the Forth standard. Timothy Knox [ ] I would not use (parts of) this proposal in my programs. Brad Eckert Roelf Toxopeus Mark Wills
This proposal is oriented more toward tool writers than application writers. For applications, it's too weak to be useful. My last application that needed to traverse a wordlist simply compiled its own links to the dictionary and traversed forward instead of backward. Tool writers can port their pet tools to the different Forths.David Harralson writes:
The sentence "Although names of definitions are required to be at least 31 characters in length" should read "Although the maximum length of names of definitions are required to be at least 31 characters in length"Anton Ertl writes:
The glossary entry for NAME>INTERPRET should probably refer to interpretation semantics, not execution semantics, i.e.: NAME>INTERPRET returns an xt (execution token) as discussed in DPANS 3.4.3 Semantics. This xt represents the interpretation semantics of the definition. It may be zero if there are no interpretation semantics.
20120120 First version 20120124 Minor typos, added section "Order of node visits" Added to section "Remarks" 20120125 Minor typos, cleanup and added remarks 20120203 Changed order of stack for TRAVERSE-WORDLIST to place the xt rightmost. Removed return value from TRAVERSE-WORDLIST. Changed xt-node halt flag to a continue flag. Note that if xt-node modifies the wordlist, the results are undefined. Specify NAME>... supporting words in section 2.2. Tidy up & correction of 4. Remarks 20120228 Section 2.1 and 2.2 moved and renumbered. Rename NAME>... to NAME>... to more clearly indicate a name token rather than a name. Tidy up table in section 3. Experience, and add note re NAME>... names. Corrected Bruce McFarling's moniker 20120904 Updates based on comments by Anton Ertl, Peter Knaggs, Bruce McFarling 20130725 Corrected stack signatures & reduce verbage 20130812 Updates based on commentary on CLF; NT>.. changed to NAME>...; justification for name token
Such a capability is needed to provide some kinds of advanced programming tools. For example, the programmer may want to determine all instances of word name overlaps in all of the wordlists in the current search order; or count, display or modify words contained in a specific wordlist.
Many systems provide the TOOLS word WORDS that provides human- readable output from the current wordlists in CONTEXT. TRAVERSE- WORDLIST is a usable factor for the implementation of WORDS.
The new type is a "name token" or nt. This is an opaque type returned by TRAVERSE-WORDLIST, which enables the programmer to enumerate the contents of a wordlist (which are organised by name). Auxilliary words allow the name token to be inspected, and to retrieve the name string, and any associated intererpret and comiplation execution tokens (xt).
Since this proposal introduces the concept of an opaque nt (name token), the following words allow system independent reference to specific parts of the node: NAME>STRING NAME>INTERPRET and NAME>COMPILE .
: WORDS-COUNT ( x nt -- x' f ) DROP 1+ TRUE ; 0 ' WORDS-COUNT WID TRAVERSE-WORDLIST . ( count of nodes visited)prints x', where x' is a count of the total number of nodes in the wordlist WID.
: ALL-WORDS NAME>STRING CR TYPE TRUE ; ' ALL-WORDS GET-CURRENT TRAVERSE-WORDLISTprints 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-WORDLISTprints the name of a word containing the string "COM", if it exists, and then terminates.
TRAVERSE-WORDLIST ( i*x xt wid -- i*x' ) "traverse-wordlist" TOOLS-EXTRemove wid and xt from the stack. Traverse the wordlist wid, executing xt (a user-specified word) once for every word in the wordlist.
The invoked xt has the stack diagram ( i*x nt -- i*x' f ).
A non-zero value for f will invoke the xt again with a new nt until all the nodes in the wordlist have been exhausted. Setting f to zero (FALSE) terminates this traversal, and xt will not be invoked again.
xt will not be invoked if the wordlist wid is empty.
nt is a system-specific name token for the node. The xt can use this token to display, count, modify or perform any other action on the node that the system providing nt permits. The format of nt is opaque, but it is guaranteed to be unique for each word in the wordlist.
TRAVERSE-WORDLIST therefore gives no guarantee as to any specific order of node visits to each word through the invoked xt with one exception.
If a wordlist contains duplicate entries, SEARCH-WORDLIST and FIND for a duplicated name will return the execution token of the last temporally defined name. For instance
: SAMPLE ... ( 1 ) ; : TEST ... ; : RETURNS ... ; : SAMPLE ... ( 2 ) ; : SAMPLE ... ( 3 ) ;defines five words, one of which, SAMPLE, is defined three times. SEARCH-WORDLIST and FIND will only return the last definition (3). Whether duplicated nodes are visited or not by TRAVERSE-WORDLIST is undefined. TRAVERSE-WORDLIST is only obliged to visit the nodes TEST, RETURNS and SAMPLE (3) from the wordlist, and can do so in any order.
Some systems may permit visiting the node for the second and subsequent definitions of SAMPLE. Exceptionally in this case, TRAVERSE-WORDLIST must visit multiply defined nodes in the order newest to oldest (but not necessarily consecutively); that is, SAMPLE (3) must be returned before (2), and (2) before (1).
The remaining unique nodes can appear in any order, and may be interspersed between the duplicately named and ordered words. If this ordering is not possible, then TRAVERSE-WORDLIST must call xt with only the FINDable definition of SAMPLE.
TRAVERSE-WORDLIST is affected by the operation of FORGET or MARKER, and the results of a traversal must not return words that are unFINDable after execution of FORGET or MARKER. Additionally, any operation during the execution of xt-node that modifies the structure of the wordlist (that is, defining words such as : (colon) or CREATE, or execution of FORGET or MARKER) results in undefined behaviour.
Because TRAVERSE-WORDLIST is returning name tokens, it is perfectly possible that the nt shares an xt with some other word. Consider:
SYNONYM NEW OLD
If NEW and OLD are both defined in wordlist wid, then nts for NEW and OLD will be returned by TRAVERSE-WORLDLIST, and NAME>INTERPRET and NAME>COMPILE may, depending on the implementation, return the same corresponding xt for both NEW and OLD.
NAME>STRING ( nt -- addr count ) "name-to-string" TOOLS-EXT
NAME>STRING returns the string addr count, the definition name of the word represented by nt. Case is dependent on the case-sensitivity of the Forth system (see DPANS 22.214.171.124 Definition names). For restrictions see /3.1 NAME>STRING Restrictions/
NAME>INTERPRET ( nt -- xt ) "name-to-interpret" TOOLS-EXTNAME>INTERPRET returns an xt (execution token) as discussed in DPANS 3.4.3 Semantics. This xt represents the execution semantics of the definition. It may be zero if there are no execution semantics.
NAME>COMPILE ( nt -- w xt ) "name-to-compile" TOOLS-EXTxt has the following stack effect: ( i*x w -- j*x ). EXECUTEing it consumes w and performs the compilation semantics of the word represented by xt.
Extend DPANS Table 3.1 Data Types
Symbol Data type Size on stack nt name token 1 cellAdd section DPANS 126.96.36.199 Name tokens
Different definitions have different name tokens, although information obtainable from the token may be identical for different name tokens; for instance, NAME>STRING for different values of nt may return the same string.
: traverse-wordlist ( i*x xt wid -- i*x' ) begin @ dup while 2dup 2>r cell + swap execute ( i*x nt -- i*x' f ) 2r> rot while repeat then 2drop ;
WF32 TRAVERSE-WORDLIST Win32Forth VOC-ITERATE VFX WalkWordList iForth doWORDS ciForth FOR-WORDS lxf/ntf WALK-WORDLISTCommonly used to implement WORDS, these functions and others are individual solutions with conflicting stack requirements and names. However, all provided similar functionality to the proposed TRAVERSE-WORDLIST, namely, the ability to inspect the individual entries in a wordlist.
Note that you can be both a system implementor and a programmer, so you can submit both kinds of ballots.
[ ] conforms to ANS Forth. [ ] already implements the proposal in full since release [ ]. [ ] implements the proposal in full in a development version. [ ] will implement the proposal in full in release [ ]. [ ] will implement the proposal in full in some future release. [ ] There are no plans to implement the proposal in full in [ ]. [ ] will never implement the proposal in full.If you want to provide information on partial implementation, please do so informally, and I will aggregate this information in some way.
[ ] I have used (parts of) this proposal in my programs. [ ] I would use (parts of) this proposal in my programs if the systems I am interested in implemented it. [ ] I would use (parts of) this proposal in my programs if this proposal was in the Forth standard. [ ] I would not use (parts of) this proposal in my programs.If you feel that there is closely related functionality missing from the proposal (especially if you have used that in your programs), make an informal comment, and I will collect these, too. Note that the best time to voice such issues is the RfD stage.