retroforth/doc/book/techniques/dictionary
crc ce91454df1 add in a "d:source" field to the dictionary header
FossilOrigin-Name: d6c27c49b054c022fad6d2898d173f0a2705925a97bb139c1c6fbdb48f896da7
2021-08-10 16:09:58 +00:00

110 lines
2.6 KiB
Text

# Working With The Dictionary
The Dictionary is a linked list containing the dictionary
headers.
## Namespace
Words operating on the dictionary are in the `d:` namespace.
## Variables
`Dictionary` is a variable holding a pointer to the most recent
header.
## Header Structure
Each entry follows the following structure:
Offset Contains
------ ---------------------------
0000 Link to Prior Header
0001 Link to XT
0002 Link to Class Handler
0003 Source Identifier
0004+ Word name (null terminated)
RETRO provides words for accessing the fields in a portable
manner. It's recommended to use these to allow for future
revision of the header structure.
## Accessing Fields
Given a pointer to a header, you can use `d:xt`, `d:class`,
and `d:name` to access the address of each specific field.
There is no `d:link`, as the link will always be the first
field.
## Shortcuts For The Latest Header
RETRO provides several words for operating on the most recent
header.
`d:last` returns a pointer to the latest header. `d:last.xt`
will give the contents of the `d:xt` field for the latest
header. There are also `d:last.class` and `d:last.name`.
## Adding Headers
Two words exist for making new headers. The easy one is
`d:create`. This takes a string for the name and makes a
new header with the class set to `class:data` and the XT
field pointing to `here`.
Example:
```
'Base d:create
```
The other is `d:add-header`. This takes a string, a pointer
to the class handler, and a pointer for the XT field and
builds a new header using these.
Example:
```
'Base &class:data #10000 d:add-header
```
## Searching
RETRO provides two words for searching the dictionary.
`d:lookup` takes a string and tries to find it in the
dictionary. It will return a pointer to the dictionary header
or a value of zero if the word was not found.
`d:lookup-xt` takes a pointer and will return the dictionary
header that has this as the `d:xt` field, or zero if no match
is found.
## Iteration
You can use the `d:for-each` combinator to iterate over all
entries in the dictionary. For instance, to display the names
of all words:
```
[ d:name s:put sp ] d:for-each
```
For each entry, this combinator will push a pointer to the
entry to the stack and call the quotation.
## Listing Words
Most Forth systems provide WORDS for listing the names of all
words in the dictionary. RETRO does as well, but this is named
`d:words`.
This isn't super useful as looking through several hundred
names is annoying. RETRO also provides `d:words-with` to help
in filtering the results.
Example:
```
'class: d:words-with
```