Searching the Dictionary

The dictionary contains all the available Forth words. Table 4-15 lists some useful tools you can use to search the dictionary. Please note that some of these tools work only with methods or commands while others work with all types of words (including, for example, variables and values).

Table 4-15 Dictionary Searching Commands

Command	Stack Diagram	Description
' name	( -- xt )	Find the named word in the dictionary. Returns the execution token. Use outside definitions.
['] name	( -- xt )	Similar to ' but is used either inside or outside definitions.
.calls	( xt -- )	Display a list of all commands which use the execution token xt.
$find	( str len -- xt true | str len false )	Search for word named by str,len. If found, leave xt and true on stack. If not found, leave name string and false on stack.
find	( pstr -- xt n | pstr false )	Search for word named by pstr. If found, leave xt and true on stack. If not found, leave name string and false on stack.  (We recommend using $find to avoid using packed strings.)
see thisword	( -- )	Decompile the specified word.
(see)	( xt -- )	Decompile the word whose execution token is xt.
$sift	( text-addr text-len -- )	Display all command names containing text-string.
sifting text	( -- )	Display all command names containing text. text contains no spaces.
words	( -- )	Display the names of words in the dictionary as described below.

Before you can understand the operation of the dictionary searching tools, you need to understand how words become visible. If there is an active package at the time a word is defined, the new word becomes a method of the active package, and is visible only when that package is the active package. The commands dev and find-device can be used to select or change the active package. The command device-end deselects the currently active package leaving no active package.

If there is no active package at the time a word is defined, the word is globally visible (i.e. not specific to a particular package and always available).

The dictionary searching commands first search through the words of the active package, if there is one, and then through the globally visible words.

---

Note -

The Forth commands only and also will affect which words are visible.

---

.calls can be used to locate all of the Forth commands that use a specified word in their definition. .calls takes an execution token from the stack and searches the entire dictionary to produce a listing of the names and addresses of every Forth command which uses that execution token. For example:

---

ok ' input .calls
	Called from input at 1e248d8
	Called from io at 1e24ac0
	Called from install-console at 1e33598
	Called from install-console at 1e33678
ok

---

see, used in the form:

see thisword

displays a "pretty-printed" listing of the source for thisword (without the comments, of course). For example:

---

ok see see
: see 
	¢ [¢] (see) catch if 
		drop 
	then 
; 
ok

---

For more details on the use of see, refer to "Using the Forth Language Decompiler".

sifting takes a string from the input stream and searches vocabularies in the dictionary search order to find every command name that contains the specified string as shown in the following screen.

---

ok sifting input

		In vocabulary options 
(1e333f8) input-device 
		In vocabulary forth 
(1e2476c) input							(1e0a9b4) set-input							(1e0a978) restore-input 
(1e0a940) save-input							(1e0a7f0) more-input?							(1e086cc) input-file 
ok

---

words displays all the visible word names in the dictionary, starting with the most recent definition. If a node is currently selected (as with dev), the list produced by words is limited to the words in that selected node.