149 lines
6.6 KiB
HTML
149 lines
6.6 KiB
HTML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
|
<title>doc/book/techniques/dictionary</title>
|
|
<style type="text/css">
|
|
|
|
* { color: #000; background: #fff; max-width: 700px; }
|
|
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
|
white-space: pre; display: block; width: 100%; }
|
|
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
|
.codeblock {
|
|
background: #dedede; color: #111; font-family: monospace;
|
|
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
|
padding: 7px;
|
|
display: block;
|
|
}
|
|
|
|
.indentedlist { margin-left: 2em; color: #000; }
|
|
|
|
span { white-space: pre; }
|
|
.text { color: #000; white-space: pre; background: #dedede; }
|
|
.colon { color: #000; background: #dedede; }
|
|
.note { color: #000; background: #dedede; }
|
|
.str { color: #000; text-decoration: underline; background: #dedede; }
|
|
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
|
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
|
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
|
.fetch { color: #000; font-style: italic; background: #dedede; }
|
|
.store { color: #000; font-style: italic; background: #dedede; }
|
|
.char { color: #000; background: #dedede; }
|
|
.inst { color: #000; background: #dedede; }
|
|
.defer { color: #000; background: #dedede; }
|
|
.imm { color: #000; font-weight: bold; background: #dedede; }
|
|
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
|
|
|
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
|
|
|
.h1, .h2, .h3, .h4 { white-space: normal; }
|
|
.h1 { font-size: 125%; }
|
|
.h2 { font-size: 120%; }
|
|
.h3 { font-size: 115%; }
|
|
.h4 { font-size: 110%; }
|
|
.hr { display: block; height: 2px; background: #000000; }
|
|
</style>
|
|
</head><body>
|
|
<p><span class="h1">Working With The Dictionary</span>
|
|
<br/><br/>
|
|
The Dictionary is a linked list containing the dictionary
|
|
headers.
|
|
<br/><br/>
|
|
<span class="h2">Namespace</span>
|
|
<br/><br/>
|
|
Words operating on the dictionary are in the <span class="tt">d:</span> namespace.
|
|
<br/><br/>
|
|
<span class="h2">Variables</span>
|
|
<br/><br/>
|
|
<span class="tt">Dictionary</span> is a variable holding a pointer to the most recent
|
|
header.
|
|
<br/><br/>
|
|
<span class="h2">Header Structure</span>
|
|
<br/><br/>
|
|
Each entry follows the following structure:
|
|
<br/><br/>
|
|
<tt class='indentedcode'>Offset Contains</tt>
|
|
<tt class='indentedcode'>------ ---------------------------</tt>
|
|
<tt class='indentedcode'>0000 Link to Prior Header</tt>
|
|
<tt class='indentedcode'>0001 Link to XT</tt>
|
|
<tt class='indentedcode'>0002 Link to Class Handler</tt>
|
|
<tt class='indentedcode'>0003 Source Identifier</tt>
|
|
<tt class='indentedcode'>0004+ Word name (null terminated)</tt>
|
|
<br/><br/>
|
|
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.
|
|
<br/><br/>
|
|
<span class="h2">Accessing Fields</span>
|
|
<br/><br/>
|
|
Given a pointer to a header, you can use <span class="tt">d:xt</span>, <span class="tt">d:class</span>,
|
|
and <span class="tt">d:name</span> to access the address of each specific field.
|
|
There is no <span class="tt">d:link</span>, as the link will always be the first
|
|
field.
|
|
<br/><br/>
|
|
<span class="h2">Shortcuts For The Latest Header</span>
|
|
<br/><br/>
|
|
RETRO provides several words for operating on the most recent
|
|
header.
|
|
<br/><br/>
|
|
<span class="tt">d:last</span> returns a pointer to the latest header. <span class="tt">d:last.xt</span>
|
|
will give the contents of the <span class="tt">d:xt</span> field for the latest
|
|
header. There are also <span class="tt">d:last.class</span> and <span class="tt">d:last.name</span>.
|
|
<br/><br/>
|
|
<span class="h2">Adding Headers</span>
|
|
<br/><br/>
|
|
Two words exist for making new headers. The easy one is
|
|
<span class="tt">d:create</span>. This takes a string for the name and makes a
|
|
new header with the class set to <span class="tt">class:data</span> and the XT
|
|
field pointing to <span class="tt">here</span>.
|
|
<br/><br/>
|
|
Example:
|
|
<br/><br/>
|
|
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='str'>'Base</span> d:create </span><br/>
|
|
<span class="tt">```</span></span><br/><br/>
|
|
The other is <span class="tt">d:add-header</span>. This takes a string, a pointer
|
|
to the class handler, and a pointer for the XT field and
|
|
builds a new header using these.
|
|
<br/><br/>
|
|
Example:
|
|
<br/><br/>
|
|
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='str'>'Base</span> <span class='ptr'>&class:data</span> <span class='num'>#10000</span> d:add-header </span><br/>
|
|
<span class="tt">```</span></span><br/><br/>
|
|
<span class="h2">Searching</span>
|
|
<br/><br/>
|
|
RETRO provides two words for searching the dictionary.
|
|
<br/><br/>
|
|
<span class="tt">d:lookup</span> 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.
|
|
<br/><br/>
|
|
<span class="tt">d:lookup-xt</span> takes a pointer and will return the dictionary
|
|
header that has this as the <span class="tt">d:xt</span> field, or zero if no match
|
|
is found.
|
|
<br/><br/>
|
|
<span class="h2">Iteration</span>
|
|
<br/><br/>
|
|
You can use the <span class="tt">d:for-each</span> combinator to iterate over all
|
|
entries in the dictionary. For instance, to display the names
|
|
of all words:
|
|
<br/><br/>
|
|
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='imm'>[</span> d:name s:put sp <span class='imm'>]</span> d:for-each </span><br/>
|
|
<span class="tt">```</span></span><br/><br/>
|
|
For each entry, this combinator will push a pointer to the
|
|
entry to the stack and call the quotation.
|
|
<br/><br/>
|
|
<span class="h2">Listing Words</span>
|
|
<br/><br/>
|
|
Most Forth systems provide WORDS for listing the names of all
|
|
words in the dictionary. RETRO does as well, but this is named
|
|
<span class="tt">d:words</span>.
|
|
<br/><br/>
|
|
This isn't super useful as looking through several hundred
|
|
names is annoying. RETRO also provides <span class="tt">d:words-with</span> to help
|
|
in filtering the results.
|
|
<br/><br/>
|
|
Example:
|
|
<br/><br/>
|
|
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='str'>'class:</span> d:words-with </span><br/>
|
|
<span class="tt">```</span></span><br/><br/>
|
|
</p>
|
|
</body></html>
|