Dictionary Format in TurboForth (all versions)

[ This text is taken from an application note written on 9th february 2011. Recorded here just in case it's useful at some point... ]

The dictionary in TurboForth is a linked list, with the first entry in a dictionary entry being a pointer to the *previous* entry. The dictionary is searched (by FIND) from the most recent entry to the first entry, i.e the dictionary is searched in reverse order. The first entry in a dictionary entry is a pointer to the previous dictionary entry. It is a 16-bit word. The next 16-bit word in the dictionary entry contains:

Length of the name of the word (bits 12 to 15)
Block number that the word is defined in (bits 2 to 11)
Immediate flag (bit 0)
Hidden flag (bit 1)

as follows:

  MSB                           LSB
   x x x x x x x x x x x x x x x x
   | | ~~~~~~~~~~~~~~~~~~~ ~~~~~~~
   | |           |            |
   | |     block number     length
   | hidden
   immediate

The block number is encoded in the word by HEADER during LOADing of a block. This allows the word to be easily located (if it has been loaded) by use of the WHERE word. E.g. WHERE WILLS

You will note that since the name of the word can only be 4 bits, the maximum length of a word is 15 characters.

The next entry in the dictionary entry is the actual text of the word name. One byte per character, in normal ASCII (no offests or anything). The word is padded with a space if the word is an odd length.

The next entry is the CFA (Code Field Address). This is a pointer to machine code that will be executed when a word is executed. For primitive words, the value of the word will be address of word plus 2 (i.e it points to the word immediately following it). For Forth words, it points to DOCOL.

If the following words were entered at the keyboard immediately after booting (i.e RAM is empty):

: MARK ;
: WILLS ;

The dictionary entries would look like this:

   Address Value
   --------------
 +-> A000  7EB2 * POINTER TO PREVIOUS WORD IN CART ROM
 |   A002  0004 * LENGTH OF THE NAME 'MARK'
 |   A004  M
 |   A005  A
 ^   A006  R
 |   A007  K
 |   A008  8320 * POINTER TO DOCOL IN PAD RAM
 |   A00A  832E * POINTER TO EXIT IN PAD RAM
 |
 +-< A00C  A000 * POINTER TO PREVIOUS DICTIONARY ENTRY
     A00E  0005 * LENGTH OF WORD 'WILLS'
     A010  W
     A011  I
     A012  L
     A013  L
     A014  S
     A015  <space> * PADDING
     A016  8320 * POINTER TO DOCOL IN PAD RAM
     A018  832E * POINTER TO EXIT IN PAD RAM

Thats how dictionary entries work in TurboForth. Quite simple. The only complexity is the length word. But all you have to do is read the word and do a '15 AND' to get the real length and throw away the other bits.

[ TurboForth has a word - >LINK that returns the link address of a ticked word ]

Article uploaded 20th August 2015