% -*- Mode:Text -*- 
% tt 5-5-94

\begin{thesaurus}

\chapter{Forth thesaurus}\sectlabel{Forth thesaurus}

\section{Arithmetic and logic operations}

\entry{Addition and subtraction}
\word{+}{n1 n2 \= n3}{}\say{plus}\ss
\word{-}{n1 n2 \= n3}{}\say{minus}\ss
\word{1+}{n \= n'}{}\say{one-plus}\ss
\word{1-}{n \= n'}{}\say{one-minus}\ss
\word{2+}{n \= n'}{}\say{two-plus}\ss
\word{2-}{n \= n'}{}\say{two-minus}\ss
\WORD{+!}{+"!}{+"!}{n addr \=}{}\say{plus-store}\ss

\id|+| returns the arithmetic sum of \ag{n1} and \ag{n2};
\id|-| returns their difference \ag{n1}$-$\ag{n2}.

\id|1+| increments by 1 the top stack entry; \id|1-| decrements it by 1.

\id|2+| increments by 2 the top stack entry; \id|2-| decrements it by 2.

\id|+!| increments by \ag{n} the Forth cell at \ag{addr}.


\entry{Negation}

\word{negate}{n \= $-$n}{}\ss
\WORD{?negate}{negate ?}{?negate}{n flag \= n \OR\ $-$n}{}
\word{abs}{n \= u}{}\say{absolute}\ss

Returns the absolute value of \ag{n}. The maximum negative number (hex {\tt
-8000}), which has no positive counterpart, is left unchanged.

\id|negate| returns $-$\ag{n} (i.e., the {\em opposite}, {\em additive
inverse}, {\em two's complement}, or {\em arithmetic negation} of
\ag{n}).

\id|?negate| negates \ag{n} if flag is \true.

\id|abs| returns the absolute value of \ag{n}. The maximum negative number
(hex {\tt -8000}), which has no positive counterpart, is left unchanged.

\entry{Signed comparison}

In signed comparison, a Forth cell is interpreted as ranging
from {\tt -80000000} to {\tt +7fffffff}.

\word{=}{n1 n2 \= flag}{}\say{equals}\ss
\word{<}{n1 n2 \= flag}{}\say{less-than}\ss
\word{<>}{n1 n2 \= flag}{}\say{not-equal}
\word{<=}{n1 n2 \= flag}{}\say{less-or-equal}
\word{>}{n1 n2 \= flag}{}\say{greater-than}\ss
\word{>=}{n1 n2 \= flag}{}\say{greater-or-equal}

These words return \true\ if the numbers \ag{n1}, \ag{n2}
stand in the following relation

	 {\centering
 \begin{tabular}{|l|c|}\hline
	word & relation\\\hline\hline
	\tt = & ${\tt n1}={\tt n2}$ \\\hline
	\tt < & ${\tt n1}<{\tt n2}$ \\\hline
	\tt <= & ${\tt n1}\leq{\tt n2}$ \\\hline
	\tt <> & ${\tt n1}\neq{\tt n2}$ \\\hline
	\tt > & ${\tt n1}>{\tt n2}$ \\\hline
	\tt >= & ${\tt n1}\geq{\tt n2}$ \\\hline
 \end{tabular}\par}


\entry{Unsigned comparison}

In unsigned comparison, a Forth cell is interpreted as ranging
from {\tt 0} to {\tt ffffffff}.

\word{u<}{ul u2 \= flag}{}\say{u-less-than}\ss
\word{u<=}{ul u2 \= flag}{}\say{u-less-or-equal}
\word{u>}{ul u2 \= flag}{}\say{u-greater}
\word{u>=}{ul u2 \= flag}{}\say{u-greater-or-equal}

These words return \true\ if the unsigned numbers
\ag{u1}, \ag{u2} stand in the following relation

	 {\centering
 \begin{tabular}{|l|c|}\hline
	word & relation\\\hline\hline
	\tt u< & ${\tt u1}<{\tt u2}$ \\\hline
	\tt u<= & ${\tt u1}\leq{\tt u2}$ \\\hline
	\tt u> & ${\tt u1}>{\tt u2}$ \\\hline
	\tt u>= & ${\tt u1}\geq{\tt u2}$ \\\hline
 \end{tabular}\par}


\entry{Comparison with zero}

\word{0=}{n \= flag}{}\say{zero-equals}\ss
\word{0<}{n \= flag}{}\say{zero-less}\ss
\word{0<=}{n \= flag}{}\say{zero-less-or-equal}
\word{0<>}{n \= flag}{}\say{zero-not-equal}
\word{0>}{n \= flag}{}\say{zero-greater}\ss
\word{0>=}{n \= flag}{}\say{zero-greater-or-equal}

These words return \true\ if the number \ag{n}
stands in the following relation with 0

	 {\centering
 \begin{tabular}{|l|c|}\hline
	word & relation\\\hline\hline
	\tt 0= & ${\tt n}=0$ \\\hline
	\tt 0< & ${\tt n}<0$ \\\hline
	\tt 0<= & ${\tt n}\leq0$ \\\hline
	\tt 0<> & ${\tt n}\neq$ \\\hline
	\tt 0> & ${\tt n}>0$ \\\hline
	\tt 0>= & ${\tt n}\geq0$ \\\hline
 \end{tabular}\par}


\entry{Min; max}

\word{min}{n1 n2 \= n3}{}\ss
\word{max}{n1 n2 \= n3}{}\ss
\word{umax}{u1 u2 \= u3}{}\say{u-max}
\word{umin}{u1 u2 \= u3}{}\say{u-min}
\word{between}{n lo hi \= f}{}\ff
\word{within}{n lo hi \= f}{}\ff

\id|min| returns the lesser of \ag{n1} and \ag{n2} according to the operation
of \id|<| (signed compare). Similarly, \id|max| returns the greater
between the two according to the operation of \id|>|.

\id|umin| returns the lesser of \ag{u1} and \ag{u2} according to the operation
of \id|u<| (unsigned compare). Similarly, \id|max| returns the greater
between the two according to the operation of \id|u>|.

\id|between| returns \true\ if \ag{lo}$\leq$\ag{n}$\leq$\ag{hi}.
\id|within|  returns \true\ if \ag{lo}$\leq$\ag{n}$<$\ag{hi}.
Thus, both 9 and 10 are ``{\tt between}'' 0 and 10, but only 9 is
``{\tt within}'' them.


\entry{Multiplication}

\word{*}{n1 n2 \= n3}{}\say{times}\ss
\word{u*}{n1 n2 \= n3}{}\say{u-times}

\id|*| returns the product of \ag{n1} and \ag{n2} treated as signed numbers.
In case of overflow, only the least significant 32 bits are kept.

Similarly, \id|u*| returns the unsigned product of \ag{n1} and \ag{n2}.


\entry{Division}

\word{/}{n1 n2 \= n3}{}\ss
\WORD{/mod}{mod /}{/mod}{n1 n2 \= u n3}{}\say{divide-mod}\ss
\word{u/mod}{u1 u2 \= u u3}{}\say{u-divide-mod}
\word{mod}{n1 n2 \= n3}{}\ss
\word{even}{n \= n'}{}

\id|/| returns the quotient \ag{n3} of \ag{n1} divided by \ag{n2}. An
error condition results if the divisor is zero. \id|/mod| also returns
the remainder in \ag{u}. \id|mod| only returns this remainder.

\id|u/mod|, which is the basic division word in Forth, performs {\em unsigned}
division and leaves quotient and remainder much as \id|/mod| does.

\id|even| returns \ag{n} itself if \ag{n} is even, and
one more than \ag{n} if \ag{n} is odd.

\word{*/}{n1 n2 n3 \= n4}{}\say{times-divide}\ss
\WORD{*/mod}{mod */}{*/mod}{n1 n2 n3 \= n4 n5}{}\say{times-divide-mod}\ss

\id|*/| multiplies \ag{n1} by \ag{n2} producing an intermediate result $n$, and
then divides $n$ by \ag{n3}, yielding the quotient \ag{n4}.
In addition, \id|*/mod| returns the remainder \ag{n5}.
See \id|/mod| for division exceptions.

In the 1983 Forth Standard, which is oriented toward 16-bit Forth cells, the
intermediate result $n$ is kept in a higher precision than the two factors,
and the division takes advantage of this higher precision. In this 32-bit
system, the intermediate result has the same 32-bit precision.


\entry{Shifts}

\word{<<}{n +n \= n'}{}\say{left-shift}
\word{>>}{n +n \= n'}{}\say{right-shift}
\WORD{>>a}{a >>}{>>a}{n +n \= n'}{}\say{right-shift-arithmetic}
\word{2*}{n \= n'}{}\say{two-times}\ss
\word{4*}{n \= n'}{}\say{four-times}\ff
\word{8*}{n \= n'}{}\say{eight-times}\ff
\word{2/}{n \= n'}{}\say{two-divide}\ss
\word{u2/}{n \= n'}{}\say{u-two-divide}

\id|<<| shifts \ag{n} left by \ag{+n} bit positions, filling least
significant bits with zeros; \ag{n'} is the result.

\id|>>| shifts \ag{n} right by \ag{+n} bit positions, filling the most
significant bits with zeros; \id|>>a| (arithmetic right shift) does the same,
but extends the sign of \ag{n} into the most significant bits.

\id|2*| is equivalent to \id|1 <<|; \id|4*|, to \id|2 <<|; \id|8*|, to 
\id|3 <<|.

\id|2/| is equivalent to \id|1 >>a|; \id|u2/|, to \id|1 >>|.

\entry{Logic operations}

\word{and}{n1 n2 \= n3}{}\ss
\word{or}{n1 n2 \= n3}{}\ss
\word{xor}{n1 n2 \= n3}{}\say{x-or}\ss
\word{not}{n \= n'}{}\ss
\word{cnot}{n \= n'}{}\say{c-not}

\id|and|, \id|or|, and \id|xor| respectively return the logical {\sc and},
{\sc or}, and {\sc xor} of \ag{n1} and \ag{n2}, operating
bitwise on all 32 bits.

\id|not| complements each bit of \ag{n}.  \id|cnot| complements only its
least-significant 8 bits.


\entry{Bit manipulation}

\word{creset}{byte-mask addr \=}{}\say{c-reset}
\word{cset}{byte-mask addr \=}{}\say{c-set}
\word{ctoggle}{byte-mask addr \=}{}\say{c-toggle}

These words respectively set, reset, or complement 
selected bits of the byte at \ag{addr}. The selection is performed
by the mask \ag{byte-mask}: only bit-positions where there is a 1
in the mask are affected.


\entry{Byte and word manipulations}

\word{flip}{wl \= w2}{}\say{flip}

w2 is the result of exchanging the bytes in the lower 16 bits of the
number wl.

\word{l-{\tt>}w}{}{n \= w}\say{l-to-w}

Converts the 32-bit number \ag{n} to a 16-bit number by
truncating the high order bits. 

\word{lwsplit}{n \= w0 w1}{}\say{l-w-split}
\word{wljoin}{w0 w1 \= n}{}\say{w-l-join}
\word{wflip}{n0 \= n1}{}\say{w-flip}

\id|lwsplit| Puts in \ag{w0}, \ag{w1} respectively the bottom and top 16-bit
halves of \ag{n}. Its inverse is \id|wljoin|, which concatenates into \ag{n}
two 16-bit numbers to form a 32-bit number.

\id|wflip| exchanges the two halves of \id|n0|, yielding \ag{n1}.


\section{Flow control}

\entry{Begin constructs}

\imm\cmp\word{begin}{}{}\ss
\imm\cmp\word{while}{flag \=}{}\ss
\imm\cmp\word{repeat}{}{}\ss
\imm\cmp\word{until}{flag \=}{}\ss
\imm\cmp\word{again}{}{}\ss

The \BEGIN\ constructs have the following form
	\oneliner{begin ... again}
	\oneliner{begin ... {\sl flag} until}
	\oneliner{begin ... {\sl flag} while ... repeat}

The {\sc begin--again} loop is re-executed indefinitely.

The {\sc begin--until} loop is re-executed as long as {\sl flag}
is \true.

The {\sc begin--while--repeat} loop is re-executed as long as {\sl flag}
is \true. When {\sl flag} becomes \false, the loop is exited from the
\id|while| position, skipping the portion between \id|while| and \id|repeat|.

The above constructs can be nested.


\entry{Case constructs}

\imm\cmp\word{case}{selector \= selector}{}
\imm\cmp\word{of}{selector test-value \=}{}
\cmp\word{endcase}{selector \=}{}
\cmp\word{endof}{}{}


These words implement Charles Eaker's \CASE\ construct,
illustrated by the following example
 \begin{verbatim}
                                : foo ( item -- )
                           case
      0 of ." it was 0" endof
      4 of ." it was 4" endof
      1 of ." it was 1" endof
    ( item)." it was " dup u.
                        endcase ;\end{verbatim}

The default clause, after the last \id|endof|, is optional.  When an
\id|of| clause is executed, \ag{item} is {\em not} on the stack.
When a default clause is executed, \ag{item} {\em is} on the stack.
The default clause may use the selector, but must not remove it from
the stack (it will be automatically removed by \id|endcase|). At run
time, \id|of| tests the top of the stack against \ag{item}. If they are
the same, \ag{item} is dropped and the following Forth code is
executed. If they are not the same, execution continues at the point
just following the matching \id|endof|.


\entry{If constructs}

\imm\cmp\word{if}{flag \=}{}\ss
\imm\cmp\word{then}{}{}\ss
\imm\cmp\word{else}{}{}\ss
\WORD{?pairs}{pairs ?}{?pairs}{n0 n1 \=}{}

The \IF\ construct has one of the following two forms
\oneliner{\FLAG\ if {\sl true-clause} else {\sl false-clause} then}
\oneliner{\FLAG\ if {\sl true-clause} then} If \FLAG\ is \true, the {\sl
true-clause} is executed and {\sl false-clause} (if any) is skipped.
Otherwise, {\sl false-clause} (if any) is executed.

\IF\ constructs may be nested.

\id|?pairs| aborts if \ag{n0}$\neq$\ag{n1}, printing the message ``{\tt
Conditionals not paired}''. This is used to ensure that conditionals such as
{\sc if--then} are properly matched and nested. The way this works
is the following.  The beginning word of a conditional (such as \id|if|)
leaves a magic number \ag{n0} on the stack; the ending word of the
conditional uses leaves its own number \ag{n1}, and calls \id|?pairs| to
check that the two numbers on the stack match.


\entry{Do constructs}

\imm\cmp\word{do}{limit base \=}{}\ss
\imm\cmp\WORD{?do}{do ?}{?do}{limit base \=}{}\ff
\WORD{(do)}{do) (}{(do)}{limit base \=}{}
\WORD{(?do)}{do) (?}{(?do)}{limit base \=}{}
\imm\cmp\word{loop}{}{}\ss
\WORD{(loop)}{loop) (}{(loop)}{}{}\say{paren-loop}
\imm\cmp\WORD{+loop}{loop +}{+loop}{n \=}{}\say{plus-loop}\ss
\WORD{(+loop)}{loop) (+}{(+loop)}{n \=}{}\say{paren-plus-loop}
\word{i}{\= n}{}\ff
\word{j}{\= n}{}\ff
\word{k}{\= n}{}\ff
\imm\cmp\word{leave}{}{}\ss
\WORD{(leave)}{leave) (}{(leave)}{}{}
\imm\cmp\WORD{?leave}{leave ?}{?leave}{flag \=}{}\ff
\WORD{(?leave)}{leave) (?}{(leave) ?}{flag \=}{}
\word{bounds}{addr len \= addr' addr}{}\ff

The the two basic formats of \DO\ construct are
	\oneliner{{\sl limit base} do ... loop}
	\oneliner{{\sl limit base} do ... {\sl incr} +loop}
 Briefly, the loop is executed a number of times, with an internal variable
{\em index} stepping from the value of {\sl base} to that of {\sl limit}. The
value of {\sl index} is available within the body of the loop.

\smallskip

With \id|do|, the loop {\sl body} is always executed at least once; with the
\id|?do| variation, the loop is not executed at all if {\sl base}={\sl
limit}.

On the first iteration, {\sl index}={\sl base}. At the end of the iteration,
{\sl index} is incremented by 1 (for \id|loop|) or by {\sl incr} (for
\id|+loop|). The value of {\sl incr} may be positive, negative, or zero. If
the increment moves {\sl index} across the boundary between {\sl limit}$-$1
and limit the loop is terminated.  For example, {\tt 10 0 do ... loop}
executes 10 times; {\tt 10 0 do ... loop} executes once. On the other hand,
{\tt 0 0 do ... loop} executes 4,294,967,295 (hex {\tt ffff}) times!

{\sc do} loops may be nested. However, note that they use the return stack to
store {\sl index} (one stack level per nesting level); cf.\ \id|exit|.

\smallskip

The words \id|i|, \id|j|, and \id|k| return the value of {\sl index}
from, respectively, the current {\sc do} level, the one right above it,
and the one immediately above.

\id|leave| terminates the loop immediately.
\id|?leave| is equivalent to {\tt if leave then}.

\id|(leave)| is the run-time word compiled by \id|leave|;
\id|(?leave)|, that compiled by \id|?leave|.

\id|(do)| is the run-time word word compiled by \id|do|. At run time,
\id|end| and \id|start| are removed from the stack and used to control the
execution of the {\sc do-loop} construct. The loop is always executed at
least once.

\id|(?do)| is the run-time word word compiled by \id|?do|. It works like
\id|(do)|, but if {\sl limit}={\sl base} the loop is not executed at all.

\id|(loop)| is the run-time word compiled by \id|loop|. At run time, the loop
index is incremented and compared to the end value saved by the previous
\id|do| or \id|?do|. If the index has reached or exceeded the ending value,
the loop is terminated, otherwise it is executed once more.

\id|(+loop)| is the run-time word compiled by \id|+loop|.
It works like \id|(loop)|, but increments the loop index by \ag{n}
instead of by 1.

\id|bounds| is a general utility word that derives its name from its most
frequent usage, i.e., to convert a starting address and a count into {\em
bounds} appropriate for the {\sc do} construct---an ending address under a
starting address. \ag{addr'} is the sum of \ag{addr} and \ag{len}.


\entry{Branches}

\cmp\word{branch}{}{}\ss
\cmp\WORD{?branch}{branch ?}{?branch}{flag \=}{}\ss
\cmp\WORD{<mark}{mark <}{<mark}{\= addr}{}\say{backward-mark}\ss
\cmp\WORD{>mark}{mark >}{>mark}{\= addr}{}\say{forward-mark}\ss
\cmp\WORD{<resolve}{resolve <}{<resolve}{addr \=}{}\say{backward-resolve}\ss
\cmp\WORD{>resolve}{resolve >}{>resolve}{addr \=}{}\say{forward-resolve}\ss


The ``branch'' words are compiled into the dictionary by flow-control
constructs such as {\sc do--loop}, {\sc begin--until}, etc. They may
also be coded explicitly by the programmer; this, however, requires
adequate care and knowledge.

\id|branch| is a literal: at execution time,
the dictionary cell following a \id|branch| instruction is used as a
branch address by the \id|branch| instruction itself.  In this system,
branch addresses are actually in the form of 16-bit offsets.
The only difference between \id|branch| and \id|?branch| is that the
first is unconditional, while the second is enabled only if there
is a \true\ value on the stack.

The ``mark'' words are used during compilation by the flow-control
constructs in order to mark the origin of forward branches (when the
branch destination is still not known) and the destination of backward
branches (when the branch origin is still not known).

The ``resolve'' words are used when the above origins and destinations
become known, to compute branch addresses and write them in the branch
literals.


\section{Dictionary}

\entry{Entry creation}

\dfr\word{create}{:name}{}\ss
\WORD{"create}{create ""}{""create}{pstr \=}{}\say{string-create}
\WORD{(create}{create (}{(create}{:name}{}
\word{last}{\= addr}{}
\word{warning}{\= addr}{}
\word{alias}{:name' name}{}

\id|create| creates a dictionary entry for {\sl name}; the
next available dictionary location is the first byte of {\sl name}\/'s
parameter field. No space is allocated at this time in the parameter field.
When {\sl name} is executed, the address of
the first byte of its parameter field is left on the stack.

\id|create| is deferred, so that the user may substitute another
implementation of it if desired; it defaults to \id|(create|.

\id|"create| has similar behavior, but takes the name token from
memory (typically from the stack) as a packed string at \ag{pstr} instead of
from the input stream.

\id|last| is a user variable containing the name field address of the last word
created.

\id|warning| is a user variable controlling the ``{\tt isn't Unique}''
message. If a word {\sl name} is created but there is already a word with the
same name in the {\sc current} vocabulary, the message ``{\sl name \tt isn't
Unique}'' is normally displayed. {\tt warning off} disables this message, and
{\tt warning on} re-enables it.

\id|alias| adds a new word, {\sl name'}, to the dictionary as a synonym for the
existing word {\sl name}. When {\sl name'} is later encountered,
the effect is the same as if {\sl name} had been encountered instead.
The replacement is done during text interpretation: the new
word {\sl name'} is always immediate.


\entry{Enclosing}

\tdf{Enclosing} is the process of incrementally adding material to
the Forth dictionary. A Forth word, as a dictionary construct,
typically consists of a \tdf{header} and a \tdf{body}. In turn, header
and body consist of collections of \tdf{fields} of various sizes. The
``comma'' words are the lowest-level primitives used to construct such fields.

\word{,}{n \=}{}\ss
\word{c,}{n \=}{}\say{c-comma}\ss
\word{w,}{n \=}{}\say{w-comma}

\id|,| encloses \ag{n} as a Forth cell in the dictionary.  \id|c,| encloses
the least-significant 8 bits of \ag{n} as a byte in the dictionary (only one
byte is allotted); similarly, \id|w,| encloses the least-significant 16 bits.


\cmp\WORD{,"}{,""}{,""}{:text\tt\char'042}{}\say{comma-string}
\WORD{",}{"",}{"",}{addr len \=}{}\say{string-comma}


\id|,"| encloses {\sl text} in the dictionary as a packed string.
With \id|",|, the text to be enclosed is taken from memory
at \ag{addr} for a length \ag{len}, instead of from the input stream.


\entry{Forgetting}

\word{forget}{:name}{}\ss
\WORD{(forget)}{forget) (}{(forget)}{acf \=}{}\say{paren-forget}\ff
\word{fence}{\= addr}{}\ff

If {\sl name} is found in the \current\ vocabulary, \id|forget| deletes
{\sl name} from it, as well as all words added to the dictionary after {\sl
name}, regardless of their vocabulary. If {\sl name} is not found, or the
name of the {sc current} vocabulary has been deleted, an error condition
occurs.

\id|forget| calls \id|(forget)|, which expects the \ag{acf} of a word from
the stack rather than its name from the input stream.  If the \ag{acf} of the
specified word is lover than the value of the user variable \id|fence|,
\id|(forget)| aborts with the message ``{\tt Below Fence}'' and no forgetting
will take place.  This is to prevent accidentally erasing critical parts of
the system.


\entry{Dictionary listing}

\word{words}{}{}\ss
\word{another?}{\= anf T \OR\ F}{}
\word{follow}{threads \=}{}\say{follow}

\id|words| lists the names of the words in the topmost {\sc context} vocabulary
starting with the most recent definition.

\id|another?| moves to the next word in the scanned vocabulary, leaving
its \ag{anf} and \true\ on the stack. If we are
already at the end of the vocabulary, only \false\ is left.

\id|follow| initializes vocabulary scanning so that subsequent uses of
\id|another?| will select words from the vocabulary whose threads are stored
at \ag{threads}.

Example: Here is a simple implementation of \id|words|, ignoring output
formatting. \id|words-in| is similar to \id|words|, but it takes an explicit
vocabulary name argument, as in {\tt words-in assembler}. \id|words-in|
illustrates the use of \id|>threads|.
 \begin{verbatim}
                        : (words ( threads -- )
          follow  begin
         another while
             .id repeat ;
                        : words 
       context @ (words ;
                        : words-in ( -- )
            [compile] '             \ vocabulary name
        >threads (words ;\end{verbatim}


\entry{Dictionary lookup}

\word{'}{\= acf:name}{}\say{tick}
\imm\word{[']}{:name}{}\say{bracket-tick}\ss
\word{(')}{\= acf}{}\say{paren-tick}

The word \id|'| looks up {\sl name} in the dictionary, using the current
search order. If {\sl name} is defined, it returns its compilation address
\ag{acf}; otherwise it aborts with an error message.  This is an ordinary
Forth word: if encountered during compilation, it is compiled; when the word
is executed, {\sl name} will be read from the input stream its \ag{acf}
returned.

The corresponding immediate word (normally to be used only during
compilation) is \id|[']|, which looks up {\sl name} and stores it
as a literal governed by \id|(')|.  When the latter executed, it
will leave \ag{acf} on the stack.

Also see \id|'user#|.

\word{find}{pstr \= addr n}{}\ss
\word{vfind}{pstr voc-ptr \= acf 1 \OR\ acf -1 \OR\ pstr F}{}\say{v-find}

\id|string| looks up in the current search order (see \id|order|) the word
whose name is given by \ag{pstr}. It the word is not found, \ag{addr} is the
string address, and \ag{n} is zero. If the word is found, \ag{addr} is its
compilation address and \ag{n} is set to 1 if the word has the immediate, and
to -1 if non-immediate.

\id|vfind| is similar to \id|find|, except that instead of searching every
vocabulary in the search order it only searches a single vocabulary,
pointed to by \id|voc-ptr|. (A vocabulary pointer is the number
which is stored in \id|context| by executing a vocabulary word.)

\word{defined}{\= pstr 0 \OR\ acf n:name}{}\ff

If {\sl name} is found in the currently active search order, it
returns its \ag{acf} that word, followed by 1 if the word is immediate or
-1 if the word is not immediate. If {\sl name} is not found,
it returns a packed string containing {\sl name} as it was actually
looked up (perhaps after case conversion, if this is enabled).


\entry{Dictionary pointer}

\word{here}{\= addr}{}\ss
\word{dp}{\= addr}{}\say{d-p}\ff
\word{allot}{n \=}{}

\id|here| returns the address of the next available dictionary location.
This address is kept in the variable \id|dp| ({\em dictionary
pointer}), which is adjusted whenever material is added to or
removed from the dictionary.

\id|allot| allocates \ag{n} bytes in the dictionary (\ag{n} may be negative).
The address of the next available dictionary location, stored in \id|dp|, is
adjusted accordingly.


\entry{Field traversing}

\WORD{>body}{body >}{>body}{}{acf \= apf}\say{to-body}\ss
\WORD{>data}{data >}{>data}{acf \= addr}{}\say{to-data}
\WORD{>link}{link >}{>link}{acf \= alf}{}\say{to-link}\ss
\WORD{>name}{name >}{>name}{acf \= anf}{}\say{to-name}\ss
\WORD{>threads}{threads >}{>threads}{acf \= addr}{}\say{to-threads}
\word{body>}{apf \= acf}{}\say{from-body}\ss
\WORD{>user}{user >}{>user}{apf \= user-var-addr}{}\say{to-user}\ff
\WORD{>user\char'043}{user\char'043 >}{>user\char'043}{acf \= user\char'043}{}\say{to-user-number}
\word{word-bounds}{acf \= apf addr}{}
\word{link>}{alf \= acf}{}\say{link-from}\ss
\word{l>name}{alf \= anf}{}\say{link-to-name}\ss
\word{n>link}{anf \= alf}{}\say{name-to-link}\ss
\word{name>}{anf \= acf}{}\say{from-name}\ss

Given a compilation address \ag{acf}, \id|>body| returns the corresponding
parameter field address \ag{apf}; \id|>data| returns the address
where the associated data are stored (the \id|pfa| for most words, but
an address in the user area for user variables); \id|>link| returns
the link-field address \id|alf|; \id|>name| returns the name-field address
\ag{anf}.

\id|>threads| assumes that \ag{acf} is the compilation address of a
vocabulary, and returns a pointer to where the threads are stored.

\id|body>| returns the \ag{acf} corresponding to the parameter field
address \ag{apf}.

\id|link>| returns the \ag{acf} corresponding to the given link field address.

\id|l>name| returns the name field address corresponding to the given link
field address. \id|n>link| returns the link field address corresponding to
the given name field address.

\id|name>| returns the compilation address corresponding to the given name
field address.

\id|>user| returns in \id|user-var-addr| the address of the data storage area
of the user variable whose parameter field address is \ag{apf}. In this
implementation, vocabularies and deferred words also keep their data in the
user area, so \id|>user| also works for them.

\id|user#| is the user number (the byte offset into the user area) of the
storage owned by the word at \ag{acf}. If the word
does not have any user area storage, the result is undefined.

\id|word-bounds|, given the \ag{acf} of a word, returns in \ag{apf} and
\ag{addr} the beginning and the end of the body of that word in the
dictionary.


\section{User area}

\entry{User area}

The {\bf user area} (or {\bf process control block}) contains important Forth
system variables for which different copies need to be kept for different
tasks.


\word{user}{offset \=:name}{}
\word{nuser}{:name}{}\say{n-user}
\word{tuser}{:name}{}\say{t-user}
\word{user-size}{\= n}{}\say{user-size}
\WORD{up@}{up"@}{up"@}{\= addr}{}\say{u-p-fetch}\ff
\WORD{up!}{up"!}{up"!}{addr \=}{}\say{u-p-store}
\word{up0}{\= addr}{}\say{u-p-zero}
\WORD{\char'043user}{user \char'043}{\char'043user}{\= addr}{}\say{number-user}
\WORD{'user\char'043}{user\char'043 '}{'user\char'043}{\= user\char'043:name}{}\say{tick-user-number}
\word{ualloc}{len \= new-user-number}{}\say{u-alloc}
\word{init-user}{}{}\say{init-user}

\id|user| is a defining word used in the form
	\oneliner{{\sl offset} user {\sl name}}
 When {\sl name} is later executed, it leaves the address of its data storage
area which is at the given offset in the user area. Space for this in
the user area is not allocated. The allocation must be done separately,
for instance with \id|ualloc|.

\id|up@| returns the  address of the currently active user area. 

\id|user-size| is the size in bytes of the user area.

\id|up0| is a user variable containing the starting address of the 
given user area.

\id|up!| assigns \ag{addr} as a new starting address of the user area.
The new user area must have been already initialized before \id|up!|
is executed, or the system may crash.

The variable \id|'user#| returns the user number (the byte offset into the
user area) of the storage associated with the word {\sl name}. If the word
does not have any user area storage, the result is undefined.

\id|#user| is the address of a user variable containing the
offset of the first location in the user area which has not yet been
allocated.

The phrase
	\oneliner{nuser {\sl name}}
 defines a word {\sl name} which, when
later executed, leaves the address of its data storage area---which is in the
user area. Enough space to store a 32-bit cell is allocated. 

Similarly, the word defined by
	\oneliner{tuser {\sl name}}
is associated to a data storage space large enough to contain an address.

\id|nuser| and \id|tuser| are similar to the standard word \id|user|, except
that one doesn't have to keep track of which user area locations have already
been allocated.

\id|ualloc| returns the next available user number, and allocates \ag{len} bytes
in the user area so that the next call to \id|ualloc| will return a number
past the bytes just allocated.

\id|init-user| initializes the user area; it is automatically called when Forth
is started.


\section{Data structures}

\entry{Variables; constants}

\word{variable}{:name}{}\ss
\word{off}{addr \=}{}
\word{on}{addr \=}{}
\word{constant}{n \=:name}{}\ss
\word{true}{\= $-$1}{}
\word{false}{\= 0}{}

\id|variable| creates a dictionary entry for {\sl name} and allots
one Forth cell in its parameter field. This parameter field is to
be used for the contents of the variable. The application is responsible for
initializing the contents of the variable which it creates. When {\sl name}
is later executed, the address of its parameter field is placed on the stack.

\id|off| and \id|on| store, respectively, \false{} and \true{} in the
data cell at \ag{addr}. They are often used to initialize a variable.

\smallskip

\id|constant| creates a dictionary entry for {\sl name} such that, when {\sl
name} is later executed, \ag{n} will be left on the stack.

\id|true| and \id|false| return respectively the values \true{} , which is
-1, or {\tt ffffffff} in hex, and \false{}, which is 0.

Small numbers, namely, those corresponding to the first 10 hex digits
{\tt 0 1 2 3 4 5 6 7 8 9 a b c d e f}, are defined as constants. Thus,
for instance, \id|f| will return 15 in decimal and \id|f| in hex.

\entry{Value}

\imm\cmp\word{is}{value \=:name}{}
\WORD{(is)}{is) (}{(is)}{value \=}{}
\WORD{(is}{is (}{(is}{value acf \=}{}

Many Forth words (e.g., word defined by \id|constant|) return {\em data}
without providing information as to the {\em address} where the data are
kept. On the other hand, it is sometimes desirable to modify the data at that
address. In many cases, the address in question can be figured from
information available at compile time.  The {\sc is} construct provides a
mechanism for saving this information as a literal at compile time, so that
it can later be used, at execute time, for accessing the location at that
address.

The construct
	\oneliner{{\sl value} is \sl name}
 is applicable only if {\sl name} is an already defined word and belongs to
one of certain classes (chiefly, \id|constant| and \id|defer|'ed words).
The value {\sl value} is stored in the appropriate data cell associated
with {\sl name}.

Examples:
	\oneliner{5 constant foo    23 is foo}
 Now \id|foo| returns 23 instead of 5.
	\oneliner{' (warm-code is warm-code}
 Assuming that \id|warm-code| is a deferred word, now \id|(warm-code|
is installed as the ``action word'' of this deferred word.

\id|is| is a ``state-smart'' word. In interpret mode, {\sl name} is
``ticked'' (see \id|'|) and the resulting \ag{acf} is passed to \id|(is|,
which does the work of storing {\sl value} in the appropriate location. In
compile mode, the word \id|(is)| is compiled and then the word {\sl name} is
compiled. When \id|(is)| is later executed, it treats the following
dictionary cell, containing the \ag{acf} of {\sl name}, as a literal, and
passes its value to \id|(is| who does the right thing.


\entry{Arrays}

An \tdf{array} word accepts the base address of an array of data and an
index; it performs the appropriate address arithmetic and returns the address
of the array element corresponding to that index.  

Many variations are possible. An array word that handles $n$-dimensional
arrays will expect the array element to be specified by an $n$-tuple of
indices.  For an array that is to be used exclusively as a lookup table
(i.e., read-only access), it may be more convenient to return the entry data
itself rather than its address.  To avoid proliferation of array words (for
different element sizes, numbers of dimensions, ways of initializing the
array, etc.), it is more practical to let the user define whatever array
words are needed in the application, using a {\bf \DOES\ construct} (see).
The current system provides a few array words as examples.

\word{array}{n:name}{}
\word{string-array}{:name}{}
\word{end-string-array}{}{}

\id|array| is a defining word. It associates with \ag{name} a buffer of
\ag{n} entries of Forth-cell size. When \ag{name} is later executed with
\ag{index} as an argument, it returns the address of the corresponding entry.

\id|string-array| is a defining word, defined by the following example
 \begin{verbatim}
              string-array mystrings ( n -- pstr )
            ," a string"
      ," another string"
          end-string-array\end{verbatim}
 The strings encountered in the body of the definition are saved in the
dictionary. When {\tt mystring} is later executed with \ag{n} as an argument, it
will return the address \ag{pstr} of the \ag{n}-th of those strings (counting
from 0).


\entry{User stacks}

\word{stack:}{n \=:name}{}\say{stack-colon}
\word{push}{n user-stack \=}{}
\word{pop}{user-stack \= n}{}
\WORD{top@}{top"@}{top"@}{user-stack \= n}{}\say{top-fetch}
\WORD{top!}{top"!}{top"!}{n user-stack \=}{}\say{top-store}
\word{clearstack}{user-stack \=}{}
\word{sdepth}{user-stack \= n}{}\say{s-depth}
\WORD{?empty}{empty ?}{?empty}{user-stack \= flag}{}

The expression
	\oneliner{n stack: {\sl name}}
 defines as a new user stack called
{\sl name} with \ag{n} bytes of storage allocated.  When later executed,
{\sl name} leaves the address of the data structure decribing that stack. Note
that the number of available items is \ag{n} divided by the size of a
cell (4 bytes).

\id|push| pushes \ag{n} on the given user stack; an error abort occurs if the
stack was already full. \id|pop| pops \ag{n} from this stack;
an error abort occurs if the stack waa already empty.

\id|top@| fetches the number which is on the top of the given user stack
without popping it; \id|top!| replaces the number which was on the top of
this stack. In either case, an error occurs if the stack was empty.

\id|empty?| returns \true{} if the given user stack is empty.
\id|sdepth| returns the number of items that are currently on the given user
stack. \id|clearstack| clears the given user stack.


\section{Memory}

Also see \en{Memory allocation}.

\entry{Fetch and store}

\WORD{@}{"@}{"@}{addr \= n}{}\say{fetch}\ss
\WORD{c@}{c"@}{c"@}{addr \= n}{}\say{c-fetch}\ss
\WORD{w@}{w"@}{w"@}{addr \= n}{}\say{w-fetch}
\WORD{2@}{2"@}{2"@}{addr \= n1 n2}{}\say{two-fetch}\ss

\id|@| returns the value \ag{n} at \ag{addr}. \id|2@| returns the value of
two consecutive cells starting at \ag{addr}.

\id|c@| fetches the byte at \ag{addr}, and returns it as a 32-bit stack
cell, padding the remaining 24 bits with zeros. Similarly, \id|w@|
fetches a 16-bit word.


\WORD{!}{"!}{"!}{n addr \=}{}\ss
\WORD{c!}{c"!}{c"!}{n addr \=}{}\say{c-store}\ss
\WORD{w!}{w"!}{w"!}{n addr \=}{}\say{w-store}
\WORD{2!}{2"!}{2"!}{n1 n2 addr \=}{}\say{two-store}\ss

\id|!| stores \ag{n} at \ag{addr}. \id|c!| stores the least significant 8
bits of \ag{n} in the byte at \ag{addr}. Similarly, \id|w!| stores
the least significant 16 bits.

\id|2!| stores \ag{n1} and \ag{n2} in consecutive locations starting at
\ag{addr}.


\entry{Block moves}

\word{move}{addr addr' u \=}{}\ss
\word{cmove}{addr addr' u \=}{}\say{c-move}\ss
\word{cmove>}{addr addr' u \=}{}\say{c-move-up}\ss

In the following words, nothing is moved if \ag{u}=0.

\id|move| copies the \ag{u} bytes at \ag{addr} to \ag{addr'}.  It performs
the correct operation even when the two string overlap: if
\ag{addr}$>$\ag{addr'}, then the first byte of \ag{addr} is moved first,
otherwise the last byte is moved first. The \ag{u} bytes remaining at address
\ag{addr'} are the same data as was originally at address \ag{addr}.

Depending on the which of \ag{addr} and \ag{addr'} is lower, \id|move|
performs the equivalent of one of the following ``dumb'' operations.

\id|cmove| moves \ag{u} bytes from \ag{addr} to \ag{addr'}. The move begins
by moving the byte at \ag{addr}+\ag{u}$-$1 to \ag{addr'}+\ag{u}$-$1 and
proceeds to successively lower addresses for \ag{u} bytes. Useful for sliding
a string towards higher addresses when the ranges overlap.

\id|cmove>| moves \ag{u} bytes from \ag{addr} to \ag{addr'}. The byte at
\ag{addr} is moved first, proceeding toward high memory. 

\word{fill}{addr u byte \=}{}\ss
\word{blank}{addr u \=}{}\ss
\word{erase}{addr u \=}{}\ss

\ag{u} bytes of memory beginning at \ag{addr} are set to \id|byte| by
\id|fill|, to 0 by \id|erase|, and to \id|bl| by \id|blank|.


\entry{Memory dump}

\word{dump}{addr len \=}{}\ss
\word{du}{addr \= addr+64}{}\say{d-u}

\id|dump| outputs a formatted hex/\ascii\ dump of memory, starting at
\ag{addr} and for at least \ag{len} bytes.  Dump lines are aligned on 16-byte
boundaries; a ``downarrow'' ({\tt\char'134/}) in the dump header marks the
first requested byte (that at \ag{addr}).

\id|du| is like \id|dump|, but assumes a length of 64 bytes. Moreover, it
leaves the next address after the dump on the stack, so that successive {\tt
du}'s will advance through memory.


\entry{Memory search}

\word{search}{n start end \= loc T \OR\ F}{}
\word{wsearch}{n start end \= loc T \OR\ F}{}\say{w-search}
\word{tsearch}{addr start end \= loc T \OR\ F}{}\say{t-search}

\id|search| searches memory between \ag{start} and \ag{end} for a 32-bit
word matching \ag{n}. If one is found, it returns the address of the first
matching word and \true{}; otherwise, just \false\ is returned.  Only
word-aligned locations are searched.

\id|wsearch| likewise searches memory for a 16-bit word matching \ag{n}.
\id|tsearch| searches memory for a tokenized address matching \ag{addr}.


\section{Data stack and return stack}

The {\bf data stack}, usually simply called the {\bf stack}, is the
standard channel through which Forth words exchange arguments.

The {\bf return stack} manages the recursive structure of words calling other
words; in this fuction, it is not to be tampered with by the user. As long as
control remains at the same recursion level, the return stack can be used
(with caution!)  as a ``third hand'' for temporarily holding a few data
items; this approach has severe limitations and should be avoided by the
casual user.

Also see \en{User stacks}

\entry{Stack operations}

\word{dup}{n \= n n}{}\say{dupe}\ss
\WORD{?dup}{dup ?}{?dup}{n \= n n \OR\ 0}{}\say{question-dupe}\ss
\WORD{2dup}{dup 2}{2dup}{a b \= a b a b}{}\say{two-dupe}\ff
\WORD{3dup}{dup 3}{3dup}{a b c \= a b c a b c}{}\say{three-dupe}\ff
\WORD{4dup}{dup {4dup}}{4dup}{a b c d \= a b c d a b c d}{}\say{four-dupe}\ff
\word{drop}{n \=}{}\ss
\word{swap}{n1 n2 \= n2 n1}{}\ss
\word{over}{n1 n2 \=  n1 n2 n1}{}\ss
\word{tuck}{n1 n2 \= n2 n1 n2}{}
\word{nip}{n1 n2 \= n2}{}\ff
\word{rot}{n1 n2 n3 \= n2 n3 n1}{}\say{rote}\ss
\WORD{-rot}{rot -}{-rot}{n1 n2 n3 \= n3 n1 n2}{}\say{minus-rote}
\word{pick}{+n \= n}{}\ss
\word{roll}{+n \=}{}

\id|dup| duplicates the top stack cell; \id|?dup| duplicates it only if it is non-zero.

\id|2dup|, \id|3dup|, and \id|4dup| duplicate, respectively, the top 2, 3, or 4
stack cells.

\id|drop| removes \ag{n} from the stack.

\id|swap| exchanges the top two stack entries.

\id|rot| rotates the top three stack entries, bringing the deepest to the
top.  \id|-rot| rotates the three entries in the opposite direction, putting
the top number underneath the other two.

\id|over| puts on the stack a copy of the next-to-top element.

\id|tuck|, equivalent to {\tt swap over}, copies the top of the stack
underneath the second item.

\id|nip| discards the next-to-the-top element of the  stack.

\id|pick| puts on the stack a copy of the \ag{+n}-th stack element, not
counting \ag{+n} itself. {\tt 0 pick} is equivalent to \id|dup|; {\tt 1 pick}
is equivalent to \id|over|

\id|roll| The \ag{+n}-th stack value (not counting \ag{+n} itself)
transferred to the top of the stack, moving the remaining values into the
vacated position. \ag{+n} must be between 0 and the number of elements on the
stack minus one.  {\tt 2 roll} is equivalent to {\tt rot}; {\tt1 roll} is
equivalent to \id|swap|; {\tt 0 roll} is a null operation.

Note: For readability's sake, the use of \id|pick| and \id|roll|
should be minimized.

\entry{Stack management}

\word{clear}{anything\=}{}
\WORD{.s}{s .}{.s}{}{}\say{print-stack}\ff
\WORD{(.s}{.s (}{(.s}{}{}\say{paren-print-stack}
\word{depth}{\= +n}{}\ss
\word{ps-size}{\= +n}{}\say{p-s-size}
\WORD{?enough}{enough ?}{?enough}{n \=}{}
\WORD{sp@}{sp"@}{sp"@}{\= addr}{}\say{s-p-fetch}\ss
\WORD{sp!}{sp"!}{sp"!}{addr \=}{}\say{s-p-store}
\word{sp0}{\= addr}{}\say{s-p-zero}

\id|clear| clears the  stack (by executing {\tt sp0 @ sp!}). \id|depth|
returns the number of entries contained in the  stack (not counting
\ag{+n} itself).

\id|.s| displays the contents of the  stack in unsigned format in the
current base; the top of the stack appears last. ``{\tt Empty}'' is displayed if
the stack is empty. \id|(.s|, a lower-level building block, does not display
``{\tt Empty}''.

\id|ps-size| returns the maximum size in bytes of the  stack (also called
the ``parameter stack'').

\id|?enough| aborts if the stack depth (not including \ag{n}) is less than
\ag{n}. A word may use this to make sure that it has been called with enough
arguments.

\id|sp@| returns the address that the top of the  stack had just before
that word was executed. \id|sp!| resets to \ag{addr} the address of the top
of the  stack. \id|sp0| is a variable which contains the address of the
bottom of the  stack.

\entry{Stack protection}

\WORD{!csp}{csp"!}{"!csp}{}{}\say{store-c-s-p}\ff
\WORD{?csp}{csp ?}{?csp}{}{}\say{question-c-s-p}\ff

\id|!csp| remembers the current value of the stack pointer. \id|?csp|
compares the current value with the previouly-remembered one,
and aborts if it has changed.  Together, they are used to make sure
that the stack depth does not change during the compilation of a word.


\entry{Return stack}

\cmp\word{exit}{}{}\ss
\word{unnest}{}{}\ff

When \id|exit| is encountered within a colon definition, the defined
word will return control to the word that called it.  This is done by
jumping to the return address at the top of the return stack and
popping the stack itself.  An error condition exists if the top of the
return stack does not contain a valid return point. Since a {\sc
do--loop} uses the return stack, \id|exit| cannot be used within it.

\id|unnest| is compiled at the end of a colon definition to make the
word terminate and return to the caller.
\id|unnest| behaves exactly like \id|exit|; it is used in this position
instead of \id|exit| so that the decompiler can easily distinguish the
syntactical end of the colon definition from an
\id|exit| that is explicitly compiled somewhere in the middle of the
definition.

\cmp\WORD{>r}{r >}{>r}{n \=}{}\say{to-r}\ss
\cmp\word{r>}{\= n}{}\say{r-from}\ss
\cmp\WORD{r@}{r"@}{r"@}{\= n}{}\say{r-fetch}\ss

\id|>r| pushes \ag{n} onto the return stack. \id|r>| pops the top
element of the return stack and returns it as \ag{n}; \id|r@|
returns a copy of the top of the return stack, without popping it.

\WORD{rp@}{rp"@}{rp"@}{\= addr}{}\say{r-p-fetch}\ff
\WORD{rp!}{rp"!}{rp"!}{addr \=}{}\say{r-p-store}
\word{rp0}{\= addr}{}\say{r-p-zero}

\id|rp@| returns the value of a system variable that points to the top of the
return stack. \id|rp!| replaces with \ag{addr} the value of this pointer
(this word may only be used inside of words which do not exit, such as
\id|quit|; in \id|quit|, it is used to clear the return stack with the phrase
{\tt rp0 @ rp!}). \id|rp0| is a user variable which contains the address of
the bottom of the return stack.


\section{Strings}

\entry{String size}

\word{count}{pstr \= addr +n}{}\ss
\WORD{+str}{str +}{+str}{pstr \= addr}{}\say{plus-string}
\WORD{-trailing}{trailing -}{-trailing}{addr len \= addr len'}{}\say{dash-trailing}\ss
\word{comp}{addr1 addr2 len \= n}{}\ff
\word{csearch}{c addr0 addr1 \= loc T \OR\ F}{}\say{c-search}
\word{substring?}{pstr1 pstr2 \= flag}{}

\id|count| returns the address \ag{addr} of the first character and the number
\ag{+n} of characters of the packed string at \ag{pstr}.

\id|+str| returns the address of the first available dictionary location
after the packed string at \ag{pstr}. \ag{addr} is aligned on a 32-bit word
boundary.

\id|-trailing| adjusts the character count \ag{len} of the string beginning
at \ag{addr} to exclude trailing spaces, returning the original address
\ag{addr} and the new count \id|len'|. If the entire string consists of
spaces, the latter is 0.

\id|comp| compares the byte arrays starting at \ag{addr1} and \ag{addr2} and
continuing for \ag{len} bytes. Returns 0 if the arrays are the same;
1 if the first array is lexicografically ``greater'' than the second,
and $-1$ in the opposite case.

\id|csearch| searches memory between \ag{addr0} and \ag{addr1} is searched for
a byte matching \id|c|. If one is found, it returns the address
\ag{loc} of the first matching byte and a \true{} flag.
Otherwise, it just returns a \false{} flag.

\id|substring?| returns \true\ if \ag{pstr1} is identical to the leading
portion of \ag{pstr2}.


\entry{String input}

\imm\WORD{"}{""}{""}{\= addr len:text\tt\char'042}{}\say{string}
\WORD{(")}{("")}{("")}{\= addr len}{}\say{paren-quote}
\imm\WORD{["]}{[""]}{[""]}{\= pstr:text\tt\char'042}{}\say{bracket-quote}
\WORD{("s}{s (""}{(""s)}{\= pstr}{}\say{paren-quote-s}
\WORD{"temp}{temp ""}{""temp}{\= addr}{}\say{quote-temp}

\id|"| reads text from the input stream and converts it to a string. It is
state-smart: When interpreting, it stores the string at address \ag{"temp},
leaving \ag{addr} and \ag{len} on the stack. When compiling, it saves {\sl
text} as a string-literal governed by \id|(")|; when this is later executed,
it leaves \ag{addr} and \ag{len} on the stack.

\id|["]| is like \id|"|, but saves \ag{text} under a string-literal
governed by \id|("s)| (moreover, it
is not state-smart, and is normally used only only
during compilation). When the latter is executed, it will leave
\ag{pstr} on the stack.


\WORD{""}{""""}{""""}{\= pstr:name}{}\say{quote-quote}
\imm\WORD{[""]}{[""""]}{[""""]}{\= pstr:name}{}\say{bracket-quote-quote}

\id|""| reads {\sl name} from the input stream and converts it to a packed
string, storing it at address \id|"temp| and leaving this address as
\ag{pstr} on the stack. It is an ordinary Forth word: when it occurs inside a
colon definition, it is compiled; when later executed, it will accept {\sl
name} from the input stream and leave \ag{pstr} on the stack.

\id|[""]| is an immediate counterpart to \id|""|; it is not state-smart and
should be used only inside a colon definition. It saves {\sl name} as a
string-literal governed by \id|("s)|; when the latter is later executed, it will
leave \ag{pstr} on the stack.

These words are convenient to use (in preference to words of the \id|"|
family) when the text to be assimilated is in token form,
i.e., has no spaces in it---for example, a filename.


\entry{String movement}

\word{pack}{addr len pstr \= pstr}{}\ff
\word{place}{addr len pstr \=}{}\ff
\WORD{"cat}{cat ""}{""cat}{pstr0 pstr1 \=}{}\say{string-cat}
\WORD{"copy}{copy ""}{""copy}{pstr0 pstr1 \=}{}\say{string-copy}
\word{save-string}{pstr \= pstr'}{}
\word{nullstring}{\= pstr}{}

\id|pack| copies the string specified by \ag{addr} and length \ag{len} to a
packed string at \ag{pstr}, returning \ag{pstr}. \id|place| does the same,
but does not return \ag{pstr}. \flag[Eliminate \id|place|?]

\id|"copy| copies the packed string at \ag{pstr0} to \ag{pstr1}.

\id|"cat| appends the packed string at \ag{pstr0} to the end of the packed
string at \ag{pstr1}. For example, after
 \begin{verbatim}
    create sbuf 100 allot
    "" hello, sbuf "copy
    "" world sbuf "cat\end{verbatim} \id|sbuf| will contain the packed string
`\id|hello,world|'.  The buffer at \ag{pstr0} is assumed to be long enough to
hold the concatenation of the two strings.

\id|save-string| copies the packed string at \ag{pstr} to a different place,
and returns the address of that place as \ag{pstr'}.  This may be used to
save a string returned by {\tt bl word} or \id|""| so that another string may
be immediately collected. Only one level of temporary string storage is
provided.

\id|nullstring| returns the address a packed string of length 0.


\entry{String output}

\imm\cmp\WORD{."}{.""}{.""}{:text\tt\char'042}{}\say{dot-quote}\ss
\imm\word{.(}{:text\tt)}{}\say{dot-paren}\ss
\WORD{(.")}{(."")}{(."")}{}{}\say{paren-dot-quote}
\word{skipstr}{\= addr len}{}\say{skip-s-t-r}

\id|."| is used inside a colon definitions in the form
	\oneliner{." {\sl text}"}
 (note that {\sl text} may contain spaces).
It saves {\sl text} as a string literal governed by \id|(.")|. When the
latter is executed, the saved text is displayed.

\id|.(| is like \id|."|, but displays the text immediately rather than save
it. It is useful for issuing messages at compile time (rather than run time).

\id|skipstr| is used to implement run-time words which govern
string literals. The address and length of the following
in-line string left on the stack, and the string is skipped. For
example, \id|(.")| is implemented as {\tt skipstr type}.


\entry{String parsing}

\dfr\word{word}{char \= pstr:text}{}\ss
\WORD{(word}{word (}{(word}{char \= pstr}{}\ss
\WORD{'word}{word '}{'word}{\= pstr}{}\say{tick-word}\ff
\word{blword}{\= pstr:text}{}\say{b-l-word}
\word{delimiter}{\= addr}{}
\WORD{>in}{in >}{>in}{\= addr}{}\say{to-in}\ss
\word{getcword}{pstr delim fd \= pstr}{}\say{get-c-word}
\word{getword}{pstr fd \= pstr}{}
\word{skipcword}{char fd \=}{}\say{skip-c-word}

The present words are concerned with segmenting the input stream by
scanning it while looking for particular delimiters. The most commonly
sought segments are word tokens---delimited by white space.  For the
purpose of the present discussion, a {\em white-space} or {\em white}
character is any character whose \ascii\ code is less than or equal to
\id|bl| (the code for space), including all control characters.  The
end of a line is treated like white space; scanning will continue into
the the next line if necessary. Given a character \ag{delim} as a
delimiter all other characters are {\em non-delimiter} characters.

\smallskip

\id|word| converts {\sl text} from the input stream (up to the first
occurrence of the delimiting character \ag{char}) into a packed string
\ag{pstr}. It defaults to \id|(word|. \id|blword| is the same as {\tt bl word}.

If \ag{char} is \id|bl|, \id|(word| skips leading white-space
characters, then collects non-white characters until another
white-space character is encountered. If \ag{char} is not \id|bl|,
\id|(word| collects characters from the input stream until it
encounters an occurence of \ag{char}, without skipping leading
occurences of it.

The actual delimiter encountered is left in the user
variable \id|delimiter|. If the end of the input stream was
encountered before a delimiter, \id|delimiter| contains the constant
\id|eof|.

The packed string returned by \id|(word| resides in the ``free'' dictionary
area a few bytes above \id|here|. Note that the text interpreter also uses
this area.

\smallskip

The variable \id|'word| stores the address returned by the previous
execution of \id|word|. It allows one to find the name of the last
word that was processed by the text interpreter.

\id|delimiter| is a user variable containing the actual delimiter character
which terminated the last call to \id|word|, \id|getword|, or \id|getcword|.

\id|>in| is a variable which contains the present character offset
within the input stream.

\smallskip

\id|getcword| accepts the next sequence of non-delimiter characters
from the file \ag{fd}, placing them as a packed string into memory
starting at \ag{pstr}. The pointer \ag{pstr} is left on the stack
unchanged. Leading delimiter characters are {\em not} skipped. If
there were no more acceptable characters in the file, the byte at
\ag{pstr} will contain zero, representing a string containing no
characters.

\id|getword| works in a similar way, but it skips leading white
characters and accepts the next sequence of non-white characters.  The
white character which terminates the scanned word is consumed and
stored in \id|delimiter|, where it may be inspected if necessary.  If
there were no more non-white characters in the file, the byte at
\ag{pstr} will contain zero and \id|delimiter| will contain \id|eof|.

The behavior of \id|getword| and \id|getcword| with respect to leading
delimiters is consistent with the way that they are actually used in
practice.  Specifically, {\tt bl word} is used to scan for the next
Forth word, and it is desirable to ignore leading spaces. Tabs,
newlines, and carriage returns may appear, and the system must be able
to deal with them. When \id|word| is used with some delimiter other
than \id|bl|, the intention is really that leading delimiters should
{\em not} be ignored! For example, when \id|word| is used to scan for
the `{\tt)}' which terminates a comment, it is desireable to find one
immediately in case of the null comment `{\tt( )}'. Similarly, \id|."|
and \id|abort"| should work with null strings, as in \id|." "| and
\id| abort" "|. The usual work-around is to explicitly check the input
stream to see if a delimiter is there before calling \id|word|. This just
points to the fact that there should be two different versions of
\id|word|, one which gets non-white characters, ignoring leading
white-space, and one which takes an explicit delimiter off the stack
and terminates as soon as it encounters a delimiter.

\smallskip

\id|skipcword| skips characters up to and including the next occurrence of
\ag{char} in the file whose descriptor is \ag{fd}.  This is used to implement
words such as `{\tt(}', which skips past the next `{\tt)}'.  This approach is
superior to the conventional approach of using {\tt ascii ) word drop},
because \id|skipcword| has no problem with strings longer than 255 bytes, nor
does it waste time by storing the skipped characters in a string that will be
ignored.


\section{Vocabularies}

\entry{Vocabulary creation}

\word{vocabulary}{:name}{}\ss
\word{vocs}{\= n}{}
\word{assembler}{\= n}{}\ss
\word{disassembler}{\= n}{}
\word{forth}{\= n}{}\ss
\word{hidden}{\= n}{}
\word{keys-forth}{\= n}{}
\word{system}{\= n}{}\say{system}
\imm\WORD{[assembler]}{assembler] [}{[assembler]}{\= n}{}\say{bracket-assembler}

\id|vocabulary| defines {\sl name} as a new vocabulary.
Subsequent execution of {\sl name} makes it the
first vocabulary in the search order. When {\sl name} is made
the {\sc current} vocabulary, new definitions will be appended to it.


\id|vocs| displays the names of all the vocabularies in the system (not just
the ones in the search order).

The following vocabularies are predefined

 {\centering
 \begin{tabular}{|l|p{2in}|}\hline
	\tt forth  & The primary vocabulary. Initially, it is the
{\sc current} vocabulary and the first vocabulary in {\sc context}
(see \id|order|). \\\hline
	\tt assembler & Contains words for assembling machine code.\\\hline
	\tt [assembler] & Like the previous, but immediate.\\\hline
	\tt disassembler & Contains helper word for the disassembler.\\\hline
	\tt hidden & Contains words which are used to
implement other words but are not intended to be
used by user programs and may not be documented. They are ``hidden''
so as not to clutter the dictionary.\\\hline
	\tt keys-forth & Contains keystroke definitions for the command line
editor. The definitions in this vocabulary name control keys and escape
sequences, and associate those keys with editing commands. The keys
used to invoke line editing commands may be changed by changing the
definitions in this vocabulary.\\\hline
	\tt system & Contains interface words which directly call \unix\
system routines.\\\hline
 \end{tabular}\par}


\word{over-vocabulary}{action-acf voc-acf \=}{}

Scans the vocabulary \id|voc-acf|. For each word in that vocabulary, the word
at \id|action-acf| is executed, with the link-field address of the vocabulary
word on the stack. This word must consume the name-field address.\flag

The following example displays the names of all the words in the
\id|assembler| vocabulary
 \begin{verbatim}
    : l.id l>name .id ;
    ' l.id ' assembler over-vocabulary\end{verbatim}
	The same result could be achieved more easily by \id|assembler
words|. \id|follow| and \id|another?| provide an alternate way of doing the
same thing.


\entry{Vocabulary links}

The following words are provided in order to make dictionary
manipulation utilities independent of the implementation of the
dictionary structure. Also see \id|link>|.

\word{voc-link}{\= addr}{}
\word{voc>}{alf \= acf}{}\say{from-voc}
\WORD{link@}{link"@}{link"@}{alf \= link}{}\say{link-fetch}
\WORD{link!}{link"!}{link"!}{link addr \=}{}\say{link-store}
\word{link,}{link \=}{}\say{link-comma}

\id|voc-link| is a user variable containing the address of the last
vocabulary created.  All the vocabularies are linked together in a
linked list whose head is contained in \id|voc-link|. Each link (which
is stored in the body of the vocabulary data structure) points to the
next link.  The compilation address \ag{acf} of the vocabulary
associated with a link \id|alf| is given by \id|voc>|.

\id|link@| returns the address of the word which is linked to the word whose
link field address is \id|alf|.

\id|link!| stores the address link at \ag{addr} in the correct format for a
dictionary link.

\id|link,| encloses the address \ag{link} into the dictionary in the correct
format for a dictionary link.

\WORD{\char'043threads}{threads \char'043}{\char'043threads}{\= n}{}\say{number-threads}

\id|#threads| is the number of threads used by the dictionary hashing scheme.
Currently \id|#threads|=4, that is, each vocabulary is represented by 4
linked lists of words.

\entry{Vocabulary search order}

\word{order}{}{}\ss
\word{also}{}{}
\word{only}{}{}
\word{previous}{}{}
\word{seal}{}{}\ss
\word{root}{}{}
\word{definitions}{}{}\ss
\WORD{\char'043vocs}{vocs \char'043}{\char'043vocs}{\= n}{}\say{number-vocs}
\word{context}{\= addr}{}\ss
\word{current}{\= addr}{}\ss

The search-order context consists of a {\em base} vocabulary (usually
{\sc root}) and a {\em search-order stack} of additional vocabularies.  The
number of elements on this stack may grow from 0 to a maximum of \id|#vocs|;
after this maximum, if more elements are pushed on the stack the oldest ones
fall off.  On a word search, the search-order stack is scanned from the top;
the base vocabulary is consulted last. A user variable, \id|context|,
points to the top vocabulary of the search stack. A separate user variable,
\id|current|, points to the {\sc current} vocabulary---the one to which new
definitions are to be added.

The search-order stack is made to grows by \id|also|, which duplicates the
top stack element (if any); it is made to shrink by \id|previous|, which
drops this element. Executing a vocabulary word such as {\sc forth} or {\sc
root} makes the corresponding vocabulary the top of the stack, superceding
the previous one (if any).

\id|order| displays the names of the vocabularies forming the current
context. It also displays the {\sc current} vocabulary.

{\sc Root} is the ``bootstrap'' vocabulary, containing nothing but words
necessary to extend the search order. Executing \id|root| makes {\sc root}
the top of the stack; executing \id|only| makes {\sc root} the {\em only}
vocabulary in the search-order stack, as well as the base vocabulary.

\id|seal| deletes all occurrences of {\sc root} from the search order, thus
removing the means to change the search order (except for changes of the
{\sc context} vocabulary, which are done by just mentioning a new
vocabulary).  This is useful in making turnkey systems in which ``everything
that is not explicitly allowed is forbidden.''

\id|#vocs| is the number of vocabularies that can be at one
time in the search order.

\id|definitions| changes the value of \id|current| to point to the
\context\ vocabulary.


\section{Character I/O}


\entry{Ascii codes}

\imm\word{ascii}{\= char:text}{}\say{azkey}
\imm\word{control}{\= char:text}{}
\word{bl}{\= char}{}\say{b-l}
\word{bs}{\= char}{}\say{b-s}
\word{carret}{\= char}{}
\word{eof}{\= char}{}\say{e-o-f}
\word{linefeed}{\= char}{}
\word{newline}{\= char}{}
\word{printable?}{char \= flag}{}

\id|ascii| is used in the form
	\oneliner{ascii \sl char}
 where {\sl text} typically consists of a single character. The \ascii\ code
for the first (or only) character of {\sl text} is returned on the stack
(when interpreting) or compiled as a literal (when compiling).

\id|control| works in analogous way, but produces the \ascii\ code for the
control character corresponding to the typed character.  This is but the
\ascii\ code for the typed character taken modulo hex {\tt 20} (decimal 32).
For example, since \id|ascii E| returns hex {\tt 45}, \id|control E| returns
{\tt 5}.

A few words return the \ascii\ code (or a special code) for selected
nonprinting characters, as follows

 {\centering
 \begin{tabular}{|l|r|r|l|}\hline
	word & hex & decimal & function\\\hline\hline
	\tt bl & \tt 20 & 32 & space\\\hline
	\tt bs & \tt  8 &  8 & backspace\\\hline
	\tt carret & \tt  0d &  13 & carriage return\\\hline
	\tt linefeed & \tt  0a &  10 & line feed\\\hline
	\tt newline & \tt  0a &  10 & ``new line''\\\hline
	\tt eof & \tt ffff & -1  & end-of-file\\\hline
 \end{tabular}\par}

\id|printable| returns \true{} if the character \ag{char} is printable.
Printable characters are those between hex {\tt40} and {\tt7e} inclusive.


\entry{Character input}

\dfr\word{key}{\= char}{}
\dfr\WORD{(key}{key (}{(key}{\= char}{}
\word{sys-key}{\= char}{}
\dfr\word{key?}{\= flag}{}\ff
\word{sys-(key?}{\= flag}{}

\id|key| reads the next \ascii\ character from the keyboard.  If no character
has been typed since \id|key| was last executed, \id|key| waits until a new
character is typed.  Characters received by \id|key| are not displayed.
\id|key| is deferred for convenience in reconfiguring the system; it defaults
to \id|(key|, which is itself deferred and defaults to \id|sys-key|.
The latter accepts all \ascii\ characters; control characters are not
processed by the system for any editing purpose. \flag[Are some control
character trapped by the system?]

\id|key?| returns \id|true| if a character has been typed on the keyboard
since the last time that \id|key| was executed. The keyboard character is not
consumed. It is a deferred word, defaulting to \id|sys-(key?|.

Also see {\bf interactive}.


\entry{Character output}

\dfr\word{emit}{char \=}{}\ss
\word{emit1}{char \=}{}\say{emit-one}\ss
\dfr\WORD{(emit}{emit (}{(emit}{char \=}{}
\word{sys-emit}{char \=}{}

The deferred word \id|emit| transfers the character \ag{char} to the output
stream. It defaults to \id|emit1|,
which updates \id|#out| to keep track of the cursor position and then calls
\id|(emit| to output the character. The latter is also deferred, and defaults
to \id|sys-emit|.

See Display control (\sect{Display control}) for individual characters
and character sequences. Also see ASCII codes (\sect{ASCII codes}).


\section{Line I/O}

\entry{Line input}

\dfr\word{expect}{addr +n \=}{}
\word{history-expect}{addr +n \=}{}
\word{sys-expect}{addr +n \=}{}
\WORD{(newexpect}{newexpect (}{(newexpect}{addr +n \=}{}
\word{span}{\= addr}{}\ss

\id|expect| receives a line of characters from the keyboard, performing line
editing as the characters are typed, and stores them into memory. The transfer
begins at \ag{addr} proceeding towards higher addresses one byte at a time
until either a {\sc return} is received or \ag{+n} characters have been
transferred. The {\sc return} is not stored into memory.  No characters are
received or transferred if \ag{+n} is zero. All characters actually received
and stored into memory are displayed. Though the Forth 83 Standard specifies
that the {\sc return} character be displayed as a space, here it is displayed
as a {\sc return}.

\id|span| is a user variable containing the count of characters
actually received and stored by the last execution of \id|expect|.

The default implementation of \id|expect| is \id|history-expect|; this calls
\id|sys-expect| when reading a file, and \id|(newexpect| (in the \id|hidden|
vocabulary) in interactive mode.  The latter provides extensive {\sc
emacs}-like line editing, with the ability to add, delete, or change
characters anywhere in the line being typed. It has a history mechanism which
allows the user to retrieve and edit a number of previously-typed lines, and
a command completion feature which can be used to reduce the amount of typing
necessary.

\word{tib}{\= addr}{}\say{t-i-b}\ss
\WORD{\char'043tib}{tib \char'043}{\char'043tib}{\= addr}{}\say{number-t-i-b}\ss
\WORD{'tib}{tib '}{'tib}{\= addr}{}\say{tick-t-i-b}\ff

\id|tib| is the address of the text input buffer, used to hold
characters when the input stream is coming from the current input
device. The capacity of text input buffer is 80 characters.

\id|#tib| is the address of a user variable containing the
length of the text currently in the text input buffer. \id|#tib| is accessed
by \id|word| when input is coming from the keyboard.

\id|'tib| is a user variable containing the address of
the text input buffer. One can temporarily change the text
input buffer by modifying \id|'tib|.


\entry{Line output}

\dfr\word{type}{addr +n \=}{}\ss
\word{type1}{addr +n \=}{}\say{type-one}
\dfr\WORD{(type}{type (}{(type}{addr +n \=}{}
\word{sys-type}{addr +n \=}{}
\WORD{>type}{type >}{>type}{addr +n \=}{}\say{greater-type}\ff
\WORD{".}{"".}{"".}{pstr \=}{}\say{string-print}

\id|type| transfers to the current output stream \ag{+n} consecutive
characters from memory, starting at \ag{addr}.  No action is taken if
\ag{+n}=0. It is a deferred word. It defaults to \id|type1|, which increments
\id|#out| and calls \id|(type|.  The latter defaults to \id|sys-type| (cf.\
\id|emit|).

\id|>type| transfers \ag{+n} consecutive characters to the current output
stream starting from memory address \ag{addr}. The characters are transferred
to the {\sc pad} before they are sent to the output stream.

\id|".| sends the packed string at \ag{pstr} to the output stream; it is
equivalent to {\tt count type}.


\section{Number I/O}

\entry{Number base}

\word{base}{\= addr}{}\ss
\word{binary}{}{}
\word{octal}{}{}
\word{decimal}{}{}\ss
\word{hex}{}{}\ss
\WORD{.d}{d .}{.d}{n \=}{}\say{dot-d}
\WORD{.h}{h .}{.h}{n \=}{}\say{dot-h}
\imm\word{b\char'043}{\= n:number}{}\say{binary-number}
\imm\word{d\char'043}{\= n:number}{}\say{decimal-number}
\imm\word{h\char'043}{\= n:number}{}\say{hex-number}

\id|base| is a user variable containing the current radix for interpretation
and conversion conversion of numeric input/output.  The range for this radix
is [2..40]. The corresponding digits are, besides {\tt 0}, the range {\tt 1}
through {\tt 9} followed by the range {\tt a} through {\tt\char"7E}.

\id|binary| sets \id|base| to two; \id|octal| sets it to eight; \id|decimal|,
to ten; \id|hex|, to sixteen.

\id|.d| displays \ag{n} in decimal without affecting the value of \id|base|;
similarly, \id|.h| displays \ag{n} in hex.

The words \id|b#|, \id|d#|, and \id|h#| interpret the next word in the input
stream with the numeric base temporarily 2, 10, or 16; this word may either
be a number or an executable word.  The value of \id|base| is not permanently
altered. For example, while working in base ten, \id|h# 100 10 +| will be
read as 266.

If a long segment of code needs to use, say, hexadecimal numerals, the
recommended sequence is
 \begin{verbatim}
    base @      \ save current base on stack
    hex         \ set base to 16
    ...	        \ code segment
    base !      \ restore original base\end{verbatim}
	For isolated numerals, or when it is desired to explicitly
indicate the desired base, use \id|b#|, \id|d#|, or
\id|h#|.


\entry{Number, input conversion}
	Numeric input conversion (from a text string to a number's
internal representation).

\dfr\word{number}{pstr \= n}{}
\WORD{(number}{number (}{(number}{pstr \= n}{}
\word{number?}{pstr \= n flag}{}\ff
\word{convert}{+n0 addr0 \= +n1 addr1}{}\ss
\word{digit}{char base \= +n T \OR\ char F}{}
\word{dpl}{\= addr}{}\say{d-p-l}\ff

\id|number| converts the string \ag{pstr} to a signed 32-bit number \ag{n},
using the value of \id|base|; it aborts if the string contains unconvertible
characters. It is deferred, defaulting to \id|(number|.

\id|number?| acts like \id|number|, but returns \true{} if the string
contained only convertible characters (digits in the current base, minus, and
period). If an unconvertible characters is found, \ag{flag} is \false{},
and \ag{n} is the number that was collected up to that point. For example, if
the string was \id|123xyzn|, \ag{n}=123 and \ag{flag}=\false{}.

\id|convert| performs numerical conversion of a text string. Assumes that
\ag{+n0} is the partial result of a conversion ending with the character at
\ag{addr0}. Continues the conversion from \ag{addr0}+1.  For each digit the
partial result of the conversion is multiplied by \id|base| and incremented
by the value of the digit.  Conversion continues until an unconvertible
character is encountered.  \ag{+n1} is the result of the conversion;
\ag{addr1} the location of the first unconvertible character.

\id|digit| returns the numeric value of \ag{char} in the specified base,
followed by a \true{} flag; if \ag{char} is not a digit, it returns the
character itself and \false{}. Appropriate characters are 0--9, a--z,
depending on \id|base|.

\id|dpl| is a variable containing information about the last number scanned
by the text interpreter. If \id|dpl| contains $-1$, the number did not contain
a decimal point. Otherwise, \id|dpl| represents the number to digits to the
right of the decimal point in the last number scanned.


\entry{Number literals}

\imm\cmp\word{literal}{n \=}{}\ss
\WORD{(lit)}{lit) (}{(lit)}{\= n}{}
\dfr\word{literal?}{pstr \= pstr F \OR\ n T}{}
\WORD{(literal?}{literal? (}{(literal?}{pstr \= pstr F \OR\ n T}{}

\id|literal| is typically used in the form
	\oneliner{[ {\sl number} ] literal}
 It saves the value \ag{n} of the expression {\sl number} as a literal
governed by \id|(lit)|. When the latter is executed, \ag{n} will be
left on the stack.

\id|literal?| is executed from \id|"compile| if the word under consideration
was not found in the dictionary. If the string \ag{pstr} is a recognizable
number \ag{n}, it returns \ag{n} and \true{}, otherwise returns
the original string and \false{}. This is a deferred word, defaulting
to \id|(literal?|.

See \id|do-literal|.


\entry{Number, output conversion}
	Numeric output conversion (from internal representation of a number
to a text string).

\word{\char'043}{+n \= +n'}{}\say{sharp}\ss
\word{<\char'043}{}{}\say{less-sharp}\ss
\WORD{\char'043s}{s \char'043}{\char'043s}{+n \= 0}{}\say{sharp-s}\ss
\WORD{\char'043>}{\char'043 >}{\char'043>}{n \= addr len}{}\say{sharp-greater}\ss
\word{hold}{char \=}{}
\word{sign}{n \=}{}

\id|<#| initializes the conversion, starting from the least significant digit
and storing characters in right-to-left order in a temporary buffer
(\id|#-buf|).  The number base may change during the conversion; thus, each
digit may refer to a different base.

\id|#| produces one more digit. It divides \ag{+n} divided by \ag{base},
converts the resulting number to an \ascii\ character, and appends it to the
buffer. \ag{+n'} is the quotient and is maintained for further processing.

\id|#s| is like \id|#|, but converts {\em all} of \ag{+n}, appending
digits into the buffer until the quotient is zero. A single zero is
added to the buffer if the number was initially zero.

\id|#>| terminates the numeric output conversion, dropping \ag{n}. 
The result of the conversion is a character string at \ag{addr}, of length
\ag{len}, suitable for \id|type|.

During the conversion, \id|hold| may be called to append a character
\ag{char} in the buffer. \id|sign| appends a - (minus sign) if \ag{n} is
negative.


\entry{Number printout}

\word{.}{n \=}{}\say{dot}\ss
\word{s.}{n \=}{}\say{signed-print}
\word{(.)}{n \= addr len}{}\say{paren-dot}\ff
\WORD{.r}{r .}{.r}{n +n \=}{}\say{dot-r}\ss
\word{u.}{u \=}{}\say{u-dot}\ss
\WORD{(u.)}{u.) (}{(u.)}{u \= addr len}{}\say{paren-u-dot}\ff
\word{u.r}{u +n \=}{}\say{u-dot-r}\ss
\word{?}{addr \=}{}\say{question-mark}\ff

\id|.| displays \ag{n} in {\em free field format}, i.e., the absolute value
of \ag{n} in the current base, preceded by a minus sign if \ag{n} is negative
and followed by a space.

Note: If the base is hex, \id|.| displays the number in {\em unsigned} format
(since signed hex display is hardly ever desired).  A more basic version of
this word, namely \id|s.|, {\em always} displays \ag{n} as a signed number.

\id|(.)| gives \ag{addr} and \ag{len} of the string (but without a space
at the end) that \id|s.| would display.

\id|u.| displays \ag{u} as an unsigned number in a free-field format. 
\id|(u.)| gives \ag{addr} and \ag{len} of the string (but without a space
at the end) that \id|u.| would display.

With \id|.r| and \id|u.r|, \ag{n} is displayed right aligned in a field
\ag{+n} characters wide, respectively in signed and unsigned form.
In this implementation, if the number of characters required to display
\ag{u}is greater than \ag{+n}, all the characters will be displayed, making
the resulting field larger than \ag{+n}.

\id|?| fetches the value at \ag{addr} (see \id|@|) and then displays it using
`{\tt .}'.


\section{Display formatting}

\entry{Display formatting}

\dfr\word{cr}{}{}\say{c-r}\ss
\WORD{(cr}{cr (}{(cr}{}{}\say{paren-c-r}
\word{lf}{}{}\say{l-f}\ff
\WORD{(lf}{lf (}{(lf}{}{}\say{paren-l-f}
\WORD{??cr}{cr ??}{??cr}{}{}\say{question-question-c-r}
\WORD{?cr}{cr ?}{?cr}{}{}\say{question-c-r}
\word{space}{}{}
\word{spaces}{+n \=}{}\ss
\word{backspaces}{+n \=}{}\ff
\WORD{?line}{line ?}{?line}{+n \=}{}
\WORD{\char'043columns}{columns \char'043}{\char'043columns}{\= n}{}\say{number-columns}
\WORD{\char'043line}{line \char'043}{\char'043line}{\= addr}{}\say{number-line}
\dfr\WORD{\char'043lines}{lines \char'043}{\char'043lines}{\= n}{}\say{number-lines}
\WORD{(\char'043lines}{lines ('043}{(\char'043lines}{\= n}{}\say{paren-number-lines}
\WORD{\char'043out}{out \char'043}{\char'043out}{\= addr}{}\say{number-out}
\WORD{.tab}{tab .}{.tab}{len \=}{}\say{dot-tab}
\word{tabstops}{\= addr}{}
\word{to-column}{column \=}{}
\WORD{?to-column}{to-column ?}{?to-column}{len col \=}{}
\word{at}{line column \=}{}
\word{insert-char}{char \=}{}
\word{insert-line}{}{}
\word{delete-char}{}{}
\word{delete-line}{}{}
\word{kill-line}{}{}
\word{kill-screen}{}{}
\word{erase-screen}{}{}
\word{dark}{}{}
\word{light}{}{}
\word{beep}{}{}\ff
\word{up}{}{}
\word{down}{}{}
\word{left}{}{}
\word{right}{}{}
\word{lmargin}{\= addr}{}\say{l-margin}\ff
\word{rmargin}{\= addr}{}\say{r-margin}

These words are concerned with display control.

\id|cr| is used to terminate the line on the display and go to the next line.
It defaults to \id|crlf|, which sends a carriage return and line feed to
the output stream, clears \id|#out|, and adds 1 to \id|#line|.

\id|(cr| sends just a carriage return character (hex {\tt0d}).

\id|lf| sends a linefeed character on the output stream and adds 1
to the variable \id|#line| to indicate that one more line has been printed on
the terminal.

\id|(lf| just sends a linefeed character (hex {\tt0a}).

\id|??cr| starts a new line if the current line is not empty. This
is used to ensure that output begins on a new line, without causing an
unnecessary blank line.

\id|?cr| starts a new line, spacing over to the left margin, if the length of
the current line is past the right margin. Equivalent to {\tt0 ?line}.

\id|?line| starts a new line if adding n more characters to the current
output line would cause the current line length to go past the right margin.

\id|#line| is a user variable which is incremented each time that \id|cr| is
executed. It may be used for control of pagination.

\id|#columns| returns the number of columns of text that are displayable on
the screen.  \flag[It probably has a bug. Returns 128.]

\id|#lines| returns the number \ag{n} of lines of text that are displayable
on the screen. It defaults to \id|(#lines|, which determines the number of
lines based on the current font parameters.

\id|#out| is a user variable containing the current column position on the
output device.  This is updated by \id|emit1| and some other words which
modify the cursor position. It is used for display formatting.

\id|.tab| advances to the column on the output device that is the next
multiple of the value contained in the variable \id|tabstops|. If there is
not enough room on the current line for \ag{len} characters, a new line is
started.  This is used to produce listings where successive items begin in
neat columns.

\id|to-columns| transmits enough spaces to the output stream to move to the
indicated column. If the current line is already at or past that column, only
1 space is transmitted. \id|?to-columns| is similar, but if printing \ag{len}
characters would cause the line length to exceed the right margin, a new line
is started at the left margin.

\id|at| moves the cursor to the indicated line in the range
[0..{\tt\char'043lines}) and column in the range [0..{\tt\char'043columns}) on the
screen.

\id|space| {\bf Warning:} The original Forth meaning of this word
(send a space character to the output stream) is pre-empted by a \SF\ word.

\id|spaces| sends \ag{+n} spaces to the current output device.
\id|backspaces| sends \ag{+n} backspace characters (hex 8).

\id|inser-char| insert \ag{char} at the cursor position, moving the rest of
the line to the right to make room.

\id|insert-line| inserts a new line on the screen at the cursor position. The
line that was underneath the cursor, and all lines below, are moved down to
make room. The bottom line falls off the bottom of the screen and is lost.
 
\id|delete-char| deletes the character under the cursor from the screen,
moving all the characters to the right leftward to fill in the gap.

\id|delete-line| deletes the current line from the screen, moving all the
lines below it up to fill in the gap.

\id|kill-line| clears the current line from the cursor position to the right
edge of the screen.

\id|kill-screen| clears the screen from the cursor position to the bottom of
the screen.

\id|erase-screen| clears the entire screen and the cursor is left at the
upper-left corner.

After \id|dark| is executed, ensuing text is displayed in {\em inverse} video
mode; after \id|light|, in {\em normal} video mode.  With the default color
tables, inverse gives white text on black background, and normal
gives black on white. 

(In F83, \id|dark| is used to erase the screen; in this system
this is done by \id|erase-screen|.)

\id|beep| transmits a bell character (hex 7) to the output stream, which causes
the system to make a sound.

\id|up| moves the cursor up one line, unless it is already on the top line.
\id|down| moves the cursor down one line, unless it is already on the bottom
line.

\id|left| moves the cursor left one column, unless it is already in the
leftmost column. \id|right| moves it right one column, unless it is already
in the rightmost column.

\id|lmargin| is a variable containing the column number of the left margin.
When the output formatting commands cause the automatic generation of a new
line, the new line begins in the column number contained herein.
\id|rmargin| is a variable containing the column number of the right margin.
The output formatting commands cause the automatic generation of a new line
when the current line length exceeds the column number contained herein.


\section{Files}

See \sect{Input stream} for loading Forth code from a file.

\entry{File, opening and closing}

\word{open}{pstr mode \= fd}{}
\WORD{\char'043fds}{fds \char'043}{\char'043fds}{\= n}{}\say{number-f-d-s}
\word{new-file}{pstr \=}{}
\word{write-open}{pstr \=}{}
\word{read-open}{pstr \=}{}
\word{append-open}{pstr \=}{}
\word{writing}{:name}{}
\word{reading}{:name}{}
\word{appending}{:name}{}
\word{to-file}{:name}{}
\word{append-to-file}{:name}{}
\word{read}{\= 0}{}
\word{write}{\= 1}{}
\word{modify}{\= 2}{}
\word{close}{fd \=}{}
\word{close-files}{}{}
\word{make}{pstr \= flag}{}
\word{file-exists?}{pstr \= flag}{}
\word{file-protection}{\= addr}{}
\word{ifd}{\= addr}{}\say{i-f-d}
\word{ofd}{\= addr}{}\say{o-f-d}
\word{file-output}{}{}
\word{undo-file-output}{}{}


\id|open| attempts to open the filed named by \ag{pstr}, with an access mode
({\sc read}, {\sc write}, or {\sc modify}) indicated by the access-mode code
\ag{mode}.  If the open operation is successful, it returns a file-descriptor
\ag{fd} different from 0, otherwise it returns 0.  A succesful open sets the
file pointer to 0, so that the next sequential access will occur at the
beginning of the file.

The constant \id|#fds| returns the number of file descriptors available,
currently 8. A file should be closed when it is no longer being used, so that
the file descriptor may be reused.

The three access-mode codes are given by the constants \id|read|=0,
\id|write|=1, and \id|modify|=2.\flag[\id|read| is pre-empted by a homonymous
word]

\id|reading| open for reading the file {\sl name}. If the file is
successfully opened, its file descriptor is stored in \id|ifd|; otherwise, a
message is displayed and the operation aborts. \id|read-open| is like
\id|reading|, but takes the file name from the packed string \ag{pstr}.

\id|writing| creates and opens for writing a file called {\sl name}.  If a
file with that name already exists, the old file is destroyed. If the file is
successfully opened, its file descriptor is stored in \id|ofd|; otherwise, a
message is displayed and the operation aborts. \id|new-file| is like
\id|writing|, but takes the file name from the packed string \ag{pstr}.
\id|write-open| does the same, but aborts if the file does not
already exist.

\id|appending| opens a file so that bytes subsequently written will be added
to the end; if the file doesn't exist, it is created. For the rest, it works
like \id|writing|. \id|append-open| takes the file name from \ag{pstr}.

\id|to-file| creates a new file with the given name, and redirects the output
stream to that file. With \id|append-to-file|, the output stream is
redirected and appended to the end of the named file (if the file does not
exist it is created). In both case, the output stream is restored to the
terminal just before the interpreter prompts for a new line of input.
For example, to decompile the words \id|words| and \id|order|
and put the output in a file called \id|words.lst|, one would
write
 \begin{verbatim}
    to-file words.lst  see words 
    append-to-file words.lst  see order\end{verbatim}

\id|close| closes the file described by \ag{fd} ar releases that file
descriptor.  \id|close-files| closes all the currently open files.

\id|make| is the basic file-creating word. It creates a new file created with
the name given by \ag{pstr}; it returns \true\ if the file is succesfully
created. If a file with that name already exists, the old file is destroyed.

\id|file-exists?| returns \true{} if the file named by \ag{pstr} already
exists.

\id|file-protection| is a variable containing the attributes for
newly-created files. When Forth creates a file with \id|make| or any other
word that uses \id|make|, the contents of \id|file-protection| are the
attributes that are assigned to the file. The standard octal \unix\ values
(used by \id|chmod|, etc.) are used. Note that the \unix\ \id|umask| value
may alter the protection level.

The variables \id|ifd| and \id|ofd| record the file descriptors of the file
last opened for input (by \id|reading| or \id|read-open|) or output (by
\id|writing|, \id|appending|, \id|new-file|, or \id|write-open|.  They exists
purely for convenience: none of the primitive file system operations use
them. In many applications involving files, no more than one input and one
output file are needed. In these cases, \id|ifd| and \id|ofd| provide
convenient predefined variables in which to store the file descriptors.

See \id|string-fopen|.

\flag[Describe \id|file-output|, \id|undo-file-output|. Currently they are
in the \id|hidden| vocabulary.]


\entry{File, read and write}

\word{fgetc}{fd \= byte}{}\say{f-get-c}
\word{fgets}{addr len fd \= len'}{}\say{f-gets}
\word{fflush}{fd \=}{}\say{f-flush}
\WORD{filec@}{filec"@}{filec"@}{l.addr fd \= byte}{}\say{file-c-fetch}
\WORD{filec!}{filec"!}{filec"!}{byte addr fd \=}{}\say{file-c-store}
\word{fseek}{addr fd \=}{}\say{f-seek}
\WORD{+fseek}{fseek }{+fseek}{n fd \=}{}\say{plus-f-seek}
\word{fputc}{byte fd \=}{}\say{f-put-c}
\word{fputs}{addr len fd \=}{}\say{f-puts}
\word{fseek-from-end}{addr fd \=}{}\say{f-seek-from-end}
\word{ftell}{fd \= addr}{}\say{f-tell}
\word{fsize}{fd \= size}{}\say{f-size}

The present words deal with things that can be done with an open file \ag{fd}
(more verbosely, a file identified by the file descriptor \ag{fd}). See
\id|open| for words concerned with opening and closing files.

\id|fflush| writes to disk (or whatever output device) any characters of the
file \ag{fd} that are still left in the file buffer.

\id|fgetc| returns a byte from the file \ag{fd}, from the
position specified by the file pointer. The file pointer is then
incremented. If there are no more bytes in the file, it returns \id|eof|.

\id|fgets| attempts to transfer \ag{len} bytes from the file \ag{fd} to
memory, starting at \ag{addr}. Fewer than \ag{len} bytes may be transfered if
not enough bytes are left in the file. \id|len'| is the number actually
transfered; if 0, it means that the file pointer was already at the end of
the file.

\id|filec!| stores \id|byte| into the file \ag{fd}, at the
position indicated by \ag{addr}; the file pointer is moved to \ag{addr}+1.
\id|filec@| gets \id|byte| from the file, and is otherwise analogous.

\id|+fseek| adds \ag{n} to the file pointer of the file \ag{fd}. This is a
good way to move around in a file without actually reading the bytes.

\id|fputc| writes \id|byte| (only the 8 low bits) to the file \ag{fd}, at the
position indicated by its file pointer, which is then incremented.

\id|fputs| writes \ag{len} bytes from memory starting at \ag{addr} to the
file \ag{fd}, starting from the current file pointer position. The file
pointer is left pointing to the byte just past the last byte put in the file.

\id|fseek| moves the file pointer for file \ag{fd} to the position indicated
by \ag{addr}.

\id|seek-from-end| moves the file pointer for file \ag{fd} to a position
\ag{addr} bytes from the end of the file.

\id|ftell| returns the current position of the file pointer for
file \ag{fd}.

\id|fsize| returns the size in bytes of file \ag{fd}


\section{Input stream}

\entry{Interactive}

Forth code can be loaded from a file, or can be entered from a terminal
and executed interactively. A number of words are provided for functions that
are meaningful only in the interactive context.

\dfr\word{interactive?}{\= flag}{}
\WORD{(interactive?}{interactive? (}{(interactive?}{\= flag}{}
\word{exit?}{\= flag}{}

\id|interactive| returns \true{} if the input stream is coming from the
keyboard intead of from a disk file. This is used, for example, to control
the type of message that is printed in case of an error, or to turning off
prompting if the input comes form a file.  It is a deferred word, defaulting
to \id|(interactive?|, which returns \true{} if the input stream is coming
from the keyboard through \id|expect|.

\id|exit?| checks the keyboard to see if anything has been typed. If no
character has been typed, it returns \false{}. If the character \id|q| has
been typed, it returns \true{}, and the calling word should stop any
output in progress. If any other character has been typed, the message ``{\tt
More?}'' is displayed and \id|exit?| waits for another key. If this is
\id|q|, \id|exit?| returns \true{} and the caller should stop;
otherwise, it returns \false{}.

This allows convenient interruption and resumption of listings.

\dfr\word{prompt}{}{}
\WORD{(prompt}{prompt (}{(prompt}{}{}
\word{status}{}{}\ff

The deferred word \id|prompt| is executed before input is read from the input
stream. It is conventionally used to display a prompt.  It defaults to
\id|(prompt|, which prints the prompt \id|ok| if the system is in interpret
state, and \id|]| if in compile state.

\id|status| is called whenever the system prompts for more input;
it defaults to \id|noop|. The system can be made to do
convenient thing before every prompt by installing an appropriate word
in \id|status|. For example,
	\oneliner{' .s is status}
 causes the stack contents to be printed before every prompt.

\word{ok}{}{}\say{o-k}

Does nothing. Defining \id|ok| to do nothing means that a previous Forth
command line may be picked up with an editor or a mouse and fed back to
the Forth interpreter without having to worry about stripping off an
\id|ok| prompt that may appear in it.

\dfr\word{error-output}{}{}
\dfr\word{restore-output}{}{}

\id|error-output| is called before an error message is printed.
\id|restore-output| is called after the message is printed. The
intention is to select a separate error stream for the message.


\entry{Loading from files}

\word{fload}{:filename}{}\say{f-load}
\WORD{"load}{load ""}{""load}{pstr \=}{}\say{string-load}
\WORD{(load}{load (}{(load}{fd \=}{}
\word{needs}{:name filename}{}
\word{fexit}{}{}\say{f-exit}

\flag[Why not simply \id|load|?]

\id|fload| saves the file descriptor for the current input stream, and
starts taking the
interpreter's input from the file {\sl filename}. When the
end of that file is reached, the previous interpreter input source is
restored.

With \id|"load|, the filename of the file to be loaded is taken from memory
(typically from the stack) as a packed string at \ag{pstr}, instead of from
the input stream.

With \id|(load|, the file to be loaded is identified by the file descriptor
\ag{fd}; after loading, the file is closed. This may be used to load a file
starting somewhere in the middle, or to load from some type of file other
than a disk file, as is done with the input stream which uses \id|expect| as
a kind of file.

\id|needs| loads the file {\sl filename} only if the word {\sl name} is not
already defined.  Typically, {\sl filename} is a file containing the source
code for {\sl name}.

\id|fexit| makes the interpreter ignore the rest of the input file in which
it appears. This is achieved by seeking to the end of the input file, so that
the next attempt to read it will return end-of-file.


\entry{Comments}

\imm\word{(}{:text\tt)}{}\ss
\imm\WORD{(s}{s (}{(s}{:text\tt)}{}
\imm\word{\char'134}{:rest-of-line\return}{}\say{backslash}\ff

After the word \id|(|, everything in the input stream up to and including the
terminating right parenthesis is treated as a comment and ignored.
There are no limits on the length of {\sl text}.

The word \id|(s| has an identical effect; it may be used to distinguish
stack comments from other comments.

After the word \id|\|, the remainder of the current input line is ignored.



\section{Error recovery}

Also see \id|error-output|, \id|restore-output|.


\entry{Abort}

\dfr\cmp\word{abort}{}{}\ss
\WORD{(abort}{abort (}{(abort}{}{}\ss
\imm\cmp\WORD{abort"}{abort""}{abort""}{:text\tt\char'042}{}\say{abort-quote}\ss
\WORD{(abort")}{abort") (}{(abort")}{(abort"")}{(abort"")}{flag \=}{}\say{paren-abort-quote}
\dfr\word{where}{}{}\ff
\WORD{(where}{where (}{(where}{}{}
\WORD{?missing}{missing ?}{?missing}{flag \=}{}\ff
\WORD{?stack}{stack ?}{?stack}{}{}

\id|abort| is called to stop the execution of a word, usually as a result of
an error condition. It defaults to \id|(abort|. This clears
the  stack and performs the function of \id|quit|; no message is printed.
A user-defined error handler may be installed instead of \id|(abort|, giving
the application better control over errors.

Used during compilation, \id|abort"| saves the error message {\sl text} in a
string literal governed by \id|(abort")|. When the latter is executed, if
\ag{flag} is \true{} it displays {\sl text} and then performs an error
recovery sequence, including the function of \id|abort|; if
\ag{flag} is \false{}, execution continues.

\id|where| is a deferred word which displays a message giving the current
location in the input stream. Called from \id|abort| and \id|abort"|.

\id|(where| is the default for \id|where|. If the input stream is interactive
(****see) no message is given. If the input comes from a file, it
displays the name of the word being compiled (if interpreting)
or the most recently defined word (if interpreting).

If \ag{flag} is \true, \id|?missing| aborts and prints the name of the
last word read from the input stream, followed by a question mark.

\id|?stack| aborts if the stack pointer is outside of the space allocated to
the  stack, printing either ``{\tt Stack Underflow}'' or ``{\tt Stack
Overflow}''.


\section{Operating system interface}

\entry{Shell commands}

\word{sh}{:rest-of-line\return}{}\say{s-h}
\word{cd}{:rest-of-line\return}{}\say{c-d}
\word{cp}{:rest-of-line\return}{}\say{c-p}
\word{df}{:rest-of-line\return}{}\say{d-f}
\word{ls}{:rest-of-line\return}{}\say{l-s}
\word{more}{:rest-of-line\return}{}
\word{mv}{:rest-of-line\return}{}\say{m-v}
\word{pwd}{:rest-of-line\return}{}\say{p-w-d}
\word{rm}{:rest-of-line\return}{}\say{r-m}
\word{command:}{:name0 name1}{}\say{command-colon}
\WORD{(cd}{cd (}{(cd}{pstr \=}{}\say{paren-c-d}
\WORD{(delete}{delete (}{(delete}{pstr \=}{}
\WORD{(files}{files (}{(files}{pstr \=}{}
\WORD{(md}{md (}{(md}{pstr \=}{}\say{paren-m-d}
\WORD{(rd}{rd (}{(rd}{pstr \=}{}\say{paren-r-d}
\WORD{(exec}{exec (}{(exec}{pstr0 pstr1 \=}{}
\WORD{(rename}{rename (}{(rename}{pstr0 pstr1 \=}{}
\WORD{(size}{size (}{(size}{pstr \=}{}
\word{child-status}{\= addr}{}

\flag[{\tt cd} and {\tt df} happen to be hex numbers!]

\id|sh| is used in the form
	\oneliner{sh \sl rest-of-line\return}
 The text {\sl rest-of-line} is executed as a \unix\ shell command.

Individual words are provided for the most common shell commands; with these
words, any text in {\sl rest-of-line} further qualifies a command.

 {\centering
 \begin{tabular}{|l|p{2.25in}|}\hline
	\tt cd & change directory\\\hline
	\tt cp & copy files to files or directories\\\hline
	\tt df & shows free space on drive\\\hline
	\tt ls & display a directory listing\\\hline
	\tt more & display the contents of the file, one page at a time\\\hline
	\tt mv & move or rename files\\\hline
	\tt rm & remove files from disk\\\hline
	\tt pwd & display current path\\\hline
 \end{tabular}\par}

New command words can be added to this list by means of the defining word
\id|command:|. {\sl name0} is the name of the new word, {\sl name1} the name
of the desired shell command. When executed, {\sl name0} will issue a shell
line consisting of {\sl name1} followed by the remainder of the input-stream
line.

Forth system words for some of the above functions are

 {\centering
 \begin{tabular}{|l|p{2.25in}|}\hline
	\tt (cd & Change the current directory to that named by {\tt pstr}.\\\hline
	\tt (delete & Delete the file named by {\tt pstr}.\\\hline
	\tt (exec & Execute the file named by {\tt pstr}, using
the string {\sl pstr'} as the program's command line.  When the
program exits, control returns to Forth.\\\hline
	\tt (files & Display all filenames matching the pattern {\tt pstr}.\\\hline
	\tt (md & Create a new directory named {\tt pstr}.\\\hline
	\tt (rd & Remove the directory named {\tt pstr}.\\\hline
	\tt (rename & Rename a file from {\tt pstr} to {\tt pstr'}.\\\hline
	\tt (size & Display name and size of all files whose names match {\tt
pstr}.\\\hline
 \end{tabular}\par}

\id|child-status| is a user variable containing the exit status returned by
the \unix\ command that was most recently executed from Forth.


\entry{Memory allocation}

\word{alloc-mem}{+n \= addr}{}\say{alloc-mem}
\word{free-mem}{addr +n \=}{}\say{free-mem}
\word{init-malloc}{}{}\say{init-malloc}
\word{next-free-mem}{\= addr}{}

\id|alloc-mem| allocates \ag{+n} bytes of memory in a space outside of the
dictionary, returning the starting address \ag{addr} of
the allocated area. The contents of allocated area is not saved when
a Forth system image is made on disk.

\id|free-mem| releases \ag{+n} bytes of previously allocated memeory starting
at \ag{addr}. In the current implementation, only the most-recently-allocated
buffer may be freed.

\id|init-malloc| initializes the simple memory allocator invoked by
\id|alloc-mem| and \id|free-mem|. It is automatically executed when Forth is
first started, if executed again subsequently, the system may crash.

\id|next-free-mem| is a variable containing the address of the end of free
memory, used by \id|alloc-mem| to allocate more memory. The dictionary grows
upward toward the address contained in \id|next-free-mem|, and memory is
allocated by \id|alloc-mem| by subracting the allocated amount from the address
contained in \id|next-free-mem|.


\section{System startup}

\entry{System startup}

\word{origin}{\= addr}{}

Returns the address of the start of the Forth system. This address
may change from run to run.

\word{title}{}{}\ff
\WORD{.version}{version .}{.version}{}{}\say{dot-version}

\id|title| displays the name and version of the Forth system.
Prints the version number of this Forth system.
\id|.version| displays the version.


\word{warm}{}{}
\dfr\word{warm-hook}{}{}
\WORD{(warm-hook}{warm-hook (}{(warm-hook}{}{}

\id|warm| is called when the Forth system is restarted after having been
interrupted. It executes \id|warm-hook| and then calls \id|quit|
to return control to the text interpreter.

A warm start differs from a cold start in that a cold start happens only
once, when the Forth system is first executed. A cold start brings up the
Forth system from scratch, reallocating data structures, buffers, etc. Warm
starts can happen many times after the system is started, and generally do
not greatly change the state of the Forth system. For example, definitions
that have recently been added to the dictionary and not saved to disk are not
destroyed by a warm start. Hardware errors such as Bus Error, Illegal
Instruction, and Address Error will cause a warm start.

The deferred word \id|warm-hook| does any cleanup necessary after a hardware
exception. It defaults to \id|(warm-hook|, which among other things clears
the stack. It can be reassigned to an application-specific exception
handler.

\word{cold}{}{}
\dfr\word{cold-hook}{}{}
\WORD{(cold-hook}{cold-hook (}{(cold-hook}{}{}

\id|cold| is called once when the Forth system is first starting up, to
initialize various aspects of the system.

\id|cold-hook| is the last thing called by \id|cold| before
starting to interpret commands from the keyboard.

\id|(cold-hook| is the word installed in the deferred word
\id|cold-hook|. It is redefined in the system several times; each
redefinition calls the previous version of the same word. This allows various
subsystems to be initialized without requiring them to be compiled together.
Each version of \id|(cold-hook|, after calling the previous version, performs
whatever initialization is appropriate for the system with which it is
associated. This mechanism may also be used to make an application
automatically start itself.

Packages loaded on top of the kernel can arrange to have their own
initialization code performed when the Forth system is started by
redefining \id|(cold-hook| and installing the new version in \id|cold-hook| as
follows
 \begin{verbatim}
    : (cold-hook (cold-hook new-init ;
    ' (cold-hook is cold-hook\end{verbatim}


\word{save-forth}{pstr \=}{}

Used in the form
	\oneliner{"" filename.exe save-forth}
 it saves into a file an executable image of the current
Forth system configuration.
From \unix, one can later re-enter that same Forth image with
	\oneliner{forth filename.exe}


\dfr\word{bye}{}{}
\WORD{(bye}{bye (}{(bye}{}{}

\id|bye| exits from Forth back to whatever program called it.
It defaults to \id|(bye|, which performs
some system-dependent cleanup before leaving Forth.

If an application needs to execute some further cleanup just before the
system exits, it may define a {\sl cleanup} word and attach it to \id|bye|
as follows
	\oneliner{: (bye {\sl cleanup} (bye ;   ' (bye is bye}


\section{Implementation-dependent parameters}

\entry{Storage size}

\WORD{/n}{n /}{/n}{\= value}{}\say{per-normal}
\WORD{/l}{l /}{/l}{\= value}{}\say{per-long}
\WORD{/w}{w /}{/w}{\= value}{}\say{per-word}
\WORD{/token}{token /}{/token}{\= value}{}\say{per-token}
\WORD{/link}{link /}{/link}{\= value}{}\say{per-link}
\WORD{/fbuf}{fbuf /}{/fbuf}{\= value}{}\say{per-f-buf}
\WORD{/fd}{fd /}{/fd}{\= value}{}\say{per-f-d}
\WORD{/n*}{n* /}{/n*}{n \= n'}{}\say{per-n-times}
\WORD{/l*}{l* /}{/l*}{n \= n'}{}\say{per-l-times}
\WORD{/w*}{w* /}{/w*}{n \= n'}{}\say{per-w-times}
\word{ca+}{addr n \= addr'}{}\say{character-address-plus}
\word{wa+}{addr n \= addr'}{}\say{word-address-plus}
\word{la+}{addr n \= addr'}{}\say{long-address-plus}
\word{na+}{addr n \= addr'}{}\say{normal-address-plus}
\word{ca1+}{addr \= addr'}{}\say{character-address-one-plus}
\word{wa1+}{addr \= addr'}{}\say{word-address-one-plus}
\word{la1+}{addr \= addr'}{}\say{long-address-one-plus}
\word{na1+}{addr \= addr'}{}\say{normal-address-one-plus}
\word{ta1+}{addr \= addr'}{}\say{token-address-one-plus}
\WORD{\#align}{align 043}{\#align}{\= n}{}\say{number-align}
\word{align}{}{}
\word{aligned}{addr \= addr'}{}

The present words return or make use of the values of certain
system implementation constants (such as word size, address size, etc.).

Words that return the value of a constant:

 {\centering
 \begin{tabular}{|l||r|l|}\hline
	word      & value & meaning\\\hline\hline
	\tt /n    &   4 & Bytes in a normal word.\\\hline
	\tt /l    &   4 & Bytes in a long word.\\\hline
	\tt /w    &   2 & Bytes in a half word.\\\hline
	\tt /token&   4 & Bytes in an address token.\\\hline
	\tt /link &   4 & Bytes in a dictionary link.\\\hline
	\tt /fbuf & 512 & Bytes in a file buffer.\\\hline
	\tt /fd   &  60 & Bytes in a file descriptor.\\\hline
%	\tt /n & &\\\hline
 \end{tabular}\par}

Words that multiply \ag{n} by a constant:

 {\centering
 \begin{tabular}{|l||r|}\hline
	word      & action\\\hline\hline
	\tt /n*   &\by\tt/n \\\hline
	\tt /l*   &\by\tt/l \\\hline
	\tt /w*   &\by\tt/w \\\hline
 \end{tabular}\par}

Words that increment a given address \ag{addr} by
a certain constant or by \ag{n} times that constant:

 {\centering
 \begin{tabular}{|l||r|}\hline
	word      & increment \\\hline\hline
	\tt /na1+ & \tt /n \\\hline
	\tt /ca1+ & \tt  1 \\\hline
	\tt /wa1+ & \tt /w \\\hline
	\tt /la1+ & \tt /l \\\hline
	\tt /ta1+ & \tt /token \\\hline
	\tt /na+ & \tt n\by/n \\\hline
	\tt /ca+ & \tt n\by/1 \\\hline
	\tt /wa+ & \tt n\by/w \\\hline
	\tt /la+ & \tt n\by/l \\\hline
 \end{tabular}\par}

\id|#align| returns the address granularity for the {\sc <cpu}, which is 4 for
a \sparcstation. \id|align| adjusts the dictionary pointer to the next
machine-word boundary; any bytes skipped are filled with 0.
\id|aligned| returns the address \ag{addr'} that would be obtained
by adjusting \ag{addr} as in \id|align|.


\entry{Tokenized addresses}

\WORD{token@}{token"@}{token"@}{addr1 \= addr2}{}\say{token-fetch}
\WORD{token!}{token"!}{token"!}{addr2 addr1 \=}{}\say{token-store}
\word{token,}{addr \=}{}\say{token-comma}

A {\em token} is an implementation-dependent
representation of an address when it is stored in memory. 
In this implementation, a token is a 32-bit absolute address.

\id|token@| fetches a tokenized address from \ag{addr1}
and returns it in ordinary form as \ag{addr2}.

\id|token!| stores the address \ag{addr2} at address \ag{addr1} as a token.

\id|token,| encloses the tokenized version of \ag{addr} in the dictionary.


\section{Interpretation}


\entry{Interpreter}

\dfr\word{interpret}{}{}\ss
\WORD{(interpret}{interpret (}{(interpret}{}{}\ss

\id|interpret| begins text interpretation at the current postion
within the input stream, continuing until this is exhausted.
It is deferred, and defaults to \id|(interpret|.

\WORD{"compile}{compile ""}{""compile}{pstr \=}{}\say{string-compile}

\id|"compile| will treat the packed string at \ag{pstr} as the name of a
Forth word.  According to the value of \id|state| and the immediate attribute
of the word, it will either interpret or compile this word.

\flag(A better name for this would be \id|"interpret|.)

\word{eval}{addr len \=}{}

Interpret Forth source code from a memory buffer beginning at \ag{addr} and
continuing for \ag{len} bytes. This works by setting up a file descriptor
that describes the memory buffer, and then using \id|(load| to interpret that
fake file. Same as \id|string-load|.

\word{execute}{acf \=}{}\ss
\word{perform}{addr-of-acf \=}{}\ff

\id|execute| executes the word definition at \ag{acf}. An
error condition exists if \ag{acf} is not a compilation address.

\id|perform| is equivalent to {\tt token@ execute}.

\word{string-load}{addr len \=}{}\say{string-load}
\word{string-fopen}{addr len \= fd}{}\say{string-f-open}

Given the address and length of a memory string, \id|string-fopen|
returns a file descriptor \ag{fd} for this string treated as a file.

\id|string-load| allows one to interpret a text string in memory.  The string
is specified by \ag{addr} and \ag{len}; a file descriptor for this string
is obtained, and then the file is loaded using \id|(load|. Same as \id|eval|.


\dfr\word{do-defined}{acf n \= ??}{}
\dfr\word{do-literal}{n \= ??}{}
\dfr\word{do-undefined}{pstr \=}{}
\itp\word{interpret-do-defined}{acf n \= ??}{}
\itp\word{interpret-do-literal}{n \= n}{}
\itp\word{interpret-do-undefined}{pstr \=}{}
\cmp\word{compile-do-defined}{acf n \=}{}
\cmp\word{compile-do-literal}{l \=}{}
\cmp\word{compile-do-undefined}{pstr \=}{}

When the text interpreter finds a new token in the input stream, it will give
it to \id|"compile| for execution. \id|"compile| will first look the token
up in the dictionary. If it is defined, it will execute \id|do-defined|
giving to it as parameters the \ag{acf} of the word and \ag{n}=1 if the word
is immediate or \ag{n}=$-$1 if it is not. If it not defined but can be read
as a number, it will execute \id|do-literal|, passing the number itself as a
parameter \ag{n}. Otherwise it will execute \id|do-undefined|, passing the
address \ag{pstr} of the packed string representing the word itself. These
three \id|do-...| words are deferred; in interpreting mode they are
implemented respectively as \id|interpret-do-defined|,
\id|interpret-do-literal|, and \id|interpret-do-undefined|; in compiling
mode, as \id|compile-do-defined|, \id|compile-do-literal|, and
\id|compile-do-undefined|.

Depending on the mode (interpret or compile), \id|do-compile| will either
directly execute the word or compile it in the dictionary; \id|do-literal|
will either push the number on the stack or compile it as a literal;
\id|do-undefined| will print the word followed by`{\tt ?}' and then either
abort or compile the word \id|lose| and continue with the compilation.

The \id|lose| provision (instead of aborting) allows one to catch many errors
with a single compilation pass.  If an error was just due to a mistyped word,
one can use \id|patch| to replace the compiled \id|lose| with the correct
word, without recompiling. At execute time, any occurrence of \id|lose| still
left in the compiled code will print the message ``{\tt Undefined word
encountered}'' and abort.

\dfr\word{quit}{}{}\ss
\WORD{(quit}{quit (}{(quit}{}{}\ss

\id|quit| is a deferred word which interprets commands from the keyboard.  It
defaults to \id|(quit|, which clears the return stack, sets interpret state,
accepts new input from the current input device, and begins text
interpretation. No message is displayed.

\id|quit| is called by \id|abort| to resume text interpretation.


\entry{Does constructs}

The \DOES\ construct allow the Forth user to specify the execution-time
action of the words that will be constructed by a given defining word.
In the \id|does>| form of this construct, this action is specified in
Forth; in the \id|code;| form (see {\em code}), the action is specified
in machine language.

\imm\cmp\word{does>}{\= addr}{}
\word{dodoesaddr}{\= addr}{}\say{do-does-adder}

\id|does>| defines the execution-time action of a word created by a high-level
defining word. It is used in the form:
 \oneliner{: {\sl namex} ... create ... does> ... ;}
 where {\sl namex} is  the defining word, which uses \id|create| or an
equivalent word to make a new dictionary entry.
At execution time, a word defined by {\sl namex} will execute
the code following \id|does>|; execution starts with the address left
by the \id|create|'d word on the stack.

\id|dodoesaddr| is a variable containing the address of the \id|dodoes|
routine. This is used by \id|does>| to assemble a JSR instruction to
\id|dodoes|.


\entry{Interpretive iteration}

\word{times}{n \=}{}
\word{many}{}{}\ff
\WORD{\char'043times}{times \char'043}{\char'043times}{\= addr}{}\say{number-times}

\id|times| re-interprets the text of the current command line (up to the
\id|times| command itself) \ag{n} times.  More precisely (since \ag{n} may be
a word that refers to a variable quantity---which may be changed during the
execution of \id|times|) the command line line will continue to execute until
the number contained in \id|#times| is greater than or equal to the current
value of \ag{n}. \id|times| only works from the keyboard, and cannot be used
within a file; it is slower than a compiled loop, since the command line is
re-interpreted each time.

\id|many| works like \id|times|, but does not have a target number of times.
The command line is continuously re-executed until a key is pressed.

\id|#times| is a variable containing the number of times that
the current command line has been executed.


\section{Compilation}

\entry{Compiler}

\word{:}{:name}{}\say{colon}\ss
\imm\cmp\word{;}{}{}\say{semi-colon}\ss
\word{lose}{}{}

\id|:| (colon) is Forth's chief defining word. The phrase
	\oneliner{: {\sl name} ... }
creates a word definition for {\sl name} in the {\sc current} vocabulary
and sets \compile\ mode. The search order is changed so
that the first vocabulary in the search order is replaced by the
\current\ vocabulary; the latter is left unchanged. The
text from the input stream is subsequently compiled.
The newly created word definition for {\sl name} cannot
be found in the dictionary until the corresponding \id|;| or \id|;code| is
successfully processed.

If during compilation of {\sl name} a word is not found and cannot be
converted to a number, the word \id|lose| is compiled.  This prints aborts
with the message ``{\tt Undefined word encountered}''.  This is in contrast to
some other Forth systems which abort right away when the compiler sees an
undefined word. Using the \id|lose| scheme, the compilation does not
terminate upon encountering the undefined word, but instead proceeds and
finds any other undefined words that may be in the file. This is a good
scheme if compilation is very fast. See \id|compile-do-undefined|.

An error arises if, during compilation from mass storage, the input stream is
exhausted before encountering \id|;| or \id|;code|.

\id|;| terminates compilation of a colon word, allows the name of
this word to be found in the dictionary, set \interpret\ mode and
compiles \id|unnest|.

See \id|immediate|.


\entry{Compilation control}

\cmp\word{compile}{}{}
\WORD{(compile)}{compile) (}{(compile)}{acf \=}{}
\imm\WORD{[compile]}{compile] [}{[compile]}{}{}

\id|compile| is typically used in the form
	\oneliner{: {\sl new-word} ... compile {\sl name} ... ;}
 When {\sl new-word} is compiled, the compilation address of word {\sl
name} is saved in the dictionary as a literal. When {\sl new-word}
is later executed, the address contained in the literal is compiled
in the dictionary.  {\sl new-word} is typically immediate and
{\sl name} is typically not immediate.

\id|(compile)| takes a word address \ag{acf} from the stack and compiles
it in the dictionary.

\id|[compile]| forces the compilation of the immediate word {\sl name}, which
otherwise would be executed.

\word{immediate}{}{}\ss
\word{immediate?}{acf \= flag}{}

\id|immediate| marks the most recently created dictionary entry as a word to be
executed rather than compiled when encountered during compilation.

\id|immediate?| returns \true{} if the word at \ag{acf} is immediate.


\word{state}{\= addr}{}\ss
\WORD{?comp}{comp ?}{?comp}{}{}\say{query-compiling}
\WORD{?exec}{exec ?}{?exec}{}{}
\word{]}{}{}\say{right-bracket}\ss
\imm\word{[}{}{}\say{left-bracket}\ss

\id|state| is a user variable containing the mode (\interpret\ or \compile)
of the text interpreter: \false\ for \interpret, \true\ for \compile.

\id|?comp| aborts if executed while not in \compile\ mode, printing the
message ``{\tt Compilation Only}''. \id|?exec| aborts if executed while not in
\interpret\ mode, printing the message {\tt Execution Only}; only useful
inside of immediate words.

The word \id|]| sets \interpret\ mode: subsequent text from the input stream
is executed. The word \id|[| reverts the interpreter to \compile\ mode:
Subsequent text from the input stream is compiled. For typical usage see
\id|literal|.


\word{hide}{}{}\ff
\word{reveal}{}{}\ff
\imm\cmp\word{recursive}{}{}\ff

\id|hide| makes the most recently created dictionary entry invisible, so that
it will not be found in the dictionary, regardless of whether the entry was
previously visible or invisible. Used to implement the behavior of \id|:|,
which ordinarily is not supposed to find a newly created word definition in
the dictionary until the matching \id|;| or \id|;code| is successfully
processed. The reason for making a word invisible while compiling it is so
that one can redefine a word in terms of its old definition.

\id|reveal| makes the most recently created dictionary entry visible, so that
it will be found in the dictionary, regarless of whether the entry was
previously visible or invisible. Used to implement the behavior of \id|;| and
\id|;code| which allow the newly created word to be found.

\id|recursive| makes the name of the colon definition being compiled visible,
so that it will be found in the dictionary. This allows the word to be used
recursively by compiling the name of the word inside of its own definition.
For example, here is a recursive definition of factorial
 \begin{verbatim}
                        : fact ( n -- n! ) recursive
                 dup if
     dup 1- fact * else
                1+ then ;\end{verbatim}


\entry{Deferred definition}

\word{defer}{:name}{}\ff
\word{crash}{}{}\ff

The construct
	\oneliner{defer {\sl name}} creates a dictionary entry for {\sl name}
and makes it an ``execution variable''. {\sl name} is similar to a variable
which contains the compilation address of another word; that other word is
executed when {\sl name} is executed. The other word to be executed is stored
into the data area of {\sl name} by \id|is| or \id|(is|. If {\sl name} is
executed before it has been thus initialized, an error message will be
printed. In this implementation, the address of the other word is stored in
the user area instead of in the parameter field.

\id|crash| is the word which is installed in a deferred word when it is first
defined. If the deferred word which contains \id|crash| is executed,
\id|crash| will abort with the message:
	\oneliner{{\sl name} <--deferred word not initialized}

{\bf Bug:} There is a case in which \id|crash| will print the wrong
{\sl name}. If the deferred word was executed from the command line by an
explicit \id|execute|, \id|crash| does not have enough information to find
the name of the deferred word; instead \id|crash| prints the name of the last
word interpreted from the input stream. Example:
 \begin{verbatim}
    defer xyz  	' xyz execute
  execute <--deferred word not initialized\end{verbatim}


\entry{Assembler}

\word{code}{:name}{}\ss
\word{label}{:name}{}\ff
\word{c;}{}{}\say{c-semi-colon}
\imm\WORD{;code}{code ;}{;code}{}{}\say{semi-colon-code}\ss
\WORD{(;code)}{code) (;}{(;code)}{}{}\say{paren-semicolon-code}
\word{end-code}{}{}\ss

These words deal with {\sl assembling} machine code rather than
{\sl compiling} Forth code.

\smallskip

\id|code| is a defining word used in  the form
	\oneliner{code {\sl name} ... end-code}
 or in the variant
	\oneliner{code {\sl name} ... c;}
 It creates a dictionary entry for {\sl name} to be defined by a following
sequence of assembly language words. This newly created word definition for
{\sl name} cannot be found in the dictionary until a matching
\id|end-code| or \id|c;| is successfully processed.
It executes \id|assembler|, thus bringing in all of the assembler's specialized
words. It does {\sl not} switch to \compile\ mode!

\id|end-code| terminates a code definition and allows the {\sl name} of the
corresponding word to be found in the dictionary. It sets the \context\
vocabulary to be the same as the \current\ vocabulary (this removes the
\id|assembler| vocabulary from the search order, unless you have explicitly
done something funny to the search order while assembling the code).

\id|c;| is a variant of \id|end-code|; before leaving assembly mode
it assembles the {\sc next} routine, which will return control to
the Forth inner interpreter. Both \id|c;| and \id|end-code| are defined
in the \id|assembler| vocabulary.

\id|;code| is used in the form:
 \oneliner{: {\sl namex} ... create ... ;code ... end-code}
 It is analogous to \id|does>|, except that the behavior of the word
created by {\sl namex} is specified in assembly language instead of
high-level Forth.

\id|(;code)| is the run-time word compiled by \id|;code| and \id|does>|. When
\id|(;code)| executes, it changes the code field of the most recently defined
word so that that word will execute the code immediately following \id|(;code)|.

\id|label| is a defining word used in the form
	\oneliner{label {\sl name} ... end-code}
 It creates a dictionary entry for {\sl name} under which it assembles the
following code until \id|end-code|.  When {\sl name} is later executed, it
will return the starting address of this code fragment.


\section{Decompilation and debugging aids}

\entry{Decompiler}

\word{see}{:name}{}
\WORD{(see)}{see) (}{(see)}{acf \=}{}
\word{cdis}{acf \=}{}\say{c-dis}
\word{dis}{:name}{}
\WORD{+dis}{dis +}{+dis}{:name}{}\say{plus-dis}
\word{sifting}{:name}{}
\word{sift}{pstr \=}{}
\WORD{.id}{id .}{.id}{anf \=}{}\say{dot-i-d}\ff
\WORD{.name}{name .}{.name}{acf}{}\say{dot-name}\ff
\WORD{.calls}{calls .}{.calls}{acf \=}{}\say{dot-calls}
\WORD{.current-word}{current-word}{.current-word}{addr \=}{}\say{dot-current-word}
	
\id|see| decompiles the word {\sl name}---or disassembles it if it is a code
definition. \id|(see)| does the same to the word at \ag{acf}.

\id|cdis| disassembles the code word at \ag{acf}.
\id|dis| disassembles the machine instruction starting at \ag{addr}, stopping
when a \id|jump|, \id|branch|, or \id|return| instruction is encountered.
\id|+dis| continues disassembling from the last stopping point.

\id|sifting| displays the names of all dictionary entries whose names contain
the string {\sl name}. With \id|sift|, {\sl name} is taken from memory
(typically from the stack) as a packed string at \ag{pstr}, instead of from
the input stream.

\id|name| displays the name of a word given its compilation address \ag{acf};
\id|.id| Prints the name of the word at the given name-field address \ag{anf}.

\id|.calls| list all the words which call the word whose compilation
address is \ag{acf}.

\.id|current-word| displays the name of the colon definition within the
address range of whose body the given address \ag{addr} lies.

\word{definer}{acf \= definer-acf}{}

\id|definer| returns the compilation address of the defining word which
defined the word at \ag{acf}.


\entry{Patching}

\word{noop}{}{}\say{no-op}\ff

Don't do anything. This can be used to waste time, or as a place-holder
for something that will be patched in later (cf.\ {\bf patch}).

\word{patch}{:name' name target}{}
\word{npatch}{n' n \=:target}{}\say{n-patch}
\WORD{(patch}{patch (}{(patch}{n' n acf \=}{}

\id|patch| is used in the form
	\oneliner{patch \sl name' name target} It replaces the first occurence
of the word {\sl name} with the word {\sl name'} in the definition of the
word {\sl target} as compiled in the dictionary.

\id|npatch| replaces the first occurrence of the number \ag{n} with \ag{n'}
in the word {\sl target}.

{\bf Warning.} If the number \ag{n} contained in the definition of
{\sl target} is expressed by a constant rather than a literal,
\id|npatch| won't work on it since the value
of this number does not appear within the body of the definition itself.
In this case, use \id|patch| with an appropriate word for {\sl name'}.

\id|(patch| is like \id|npatch|, but the target word is specified by its
\ag{acf} rather than by name.


\entry{Debugger}

\end{thesaurus}
