Walking Wordlists

Wordlists are the building block of the dictionary. A wordlist is a single linked list of entries. Entries are compiled colon words, assembly words or data structures created with create. The link chain ends when the next pointer is zero. A wordlist grows usually upward in the flash memory, while the links point downwards.

The anchor of a wordlist is the stored in an EEPROM cell, which address is the wordlist identifier.

Walking a wordlist requires the following steps

  1. get the WID (e.g. environment)
  2. read the starting address from the EEPROM (line 2) It the name field address of the first word.
  3. start the loop until zero is reached (lines 4+5)
  4. keep the vital iterator data (line 6)
  5. do some work with the entry, consuming the NFA-copy from the previous line (line 7)
  6. go to the next entry (line 8)
  7. repeat the loop body

The implementation of the word show-wordlist may illustrate this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
: show-wordlist ( wid -- )
  @e
  begin
    ?dup
  while
    dup
    icount $ff and itype space
    nfa>lfa @i
  repeat
 ;

The sequence $ff and masks the entry flags (e.g. immediate) and extracts the actual string length for use with the following itype.

Way easier is using the traverse-wordlist available since amforth version 5.2. With it, the above changes to

\ print the name of a single wordlist entry
: show-word ( nt -- flag )
    name>string itype space
    true \ see spec of traverse-wordlist

: show-wordlist ( wid -- )
    ['] show-word swap traverse-wordlist
;