chapter7.tex

%% Thinking Forth
%% Copyright (C) 2004 Leo Brodie
%% Initial transcription by Nils M Holm
%% Based on OCR scans by Steve Fisher
%% -*-coding: iso-8859-1;-*-

\chapter{Handling~Data: Stacks~and~States}\Chapmark{7}

\expandafter\initial\Forth{} handles data in one of two ways: either
on the stack or in data structures. When to use which approach and how
to manage both the stack and data structures are the topics of this
chapter.

\section{The Stylish Stack}%
\index{D!Data stacks!concept of|(}

The simplest way for \Forth{} words to pass arguments to each other is
via the stack. The process is ``simple'' because all the work of pushing
and popping values to and from the stack is implicit.

\begin{interview}
\person{Moore}:\index{M!Moore, Charles|(}

\begin{tfquot}
The data stack uses this idea of ``hidden information.'' The arguments
being passed between subroutines are not explicit in the calling sequence.
The same argument might ripple through a whole lot of words quite invisibly,
even below the level of awareness of the programmer, simply because it
doesn't have to be referred to explicitly.
\end{tfquot}\index{M!Moore, Charles|)}
\end{interview}
One important result of this approach: Arguments are unnamed. They
reside on the stack, not in named variables. This effect is one of the
reasons for \Forth{}'s elegance. At the same time it's one of the reasons
badly written \Forth{} code can be unreadable. Let's explore this
paradox.

The invention of the stack is analogous to that of pronouns in
English. Consider the passage:

%!! indent paragraph
\begin{tfquot}
Take this gift, wrap it in tissue paper and put it in a box.
\end{tfquot}
Notice the word ``gift'' is mentioned only once. The gift is referred to
henceforth as ``it.''

The informality of the ``it'' construct makes English more readable
(provided the reference is unambiguous). So with the stack, the implicit
passing of arguments makes code more readable. We emphasize the
\emph{processes}, not the \emph{passing of arguments} to the processes.

Our analogy to pronouns suggests why bad \Forth{} can be so unreadable.
The spoken language gets confusing when too many things are
referred to with pronouns.

\begin{tfquot}
Take off the wrapping and open the box. Remove the gift and throw it
away.
\end{tfquot}
The problem with this passage is that we're using ``it'' to refer to too
many things at once. There are two solutions to this error. The easiest
solution is to supply a real name instead of ``it'':

\begin{tfquot}
Remove the wrapping and open the box. Take out the gift and throw
\emph{the box} away.
\end{tfquot}
Or we can introduce the words ``former'' and ``latter.'' But the best
solution is to redesign the passage:

\begin{tfquot}
Remove the wrapping and open the present. Throw away the box.
\end{tfquot}
So in \Forth{} we have analogous observations:

\begin{tip}
Simplify code by using the stack. But don't stack too deeply within any
single definition. Redesign, or, as a last resort, use a named variable.
\end{tip}
Some newcomers to \Forth{} view the stack the way a gymnast views a
trampoline: as a fun place to bounce around on. But the stack is meant for
data-passing, not acrobatics.

\index{D!Data stacks!depth of|(}%
So how deep is ``too deep?'' Generally, three elements on the stack is
the most you can manage within a single definition. (In double-length
arithmetic, each ``element'' occupies two stack positions but is logically
treated as a single element by operators such as \forthb{2DUP}, \forthb{2OVER},
etc.)

In your ordinary lexicon of stack operators, \forthb{ROT} is the only one
that gives you access to the third stack item. Aside from \forthb{PICK} and
\forthb{ROLL} (which we'll comment on soon), there's no easy way to get at
anything below that.

To stretch our analogy to the limit, perhaps three elements on the
stack corresponds to the three English pronouns ``this,'' ``that,'' and
``t'other.''%
\index{D!Data stacks!concept of|)}

\subsection{Redesign}

Let's witness a case where a wrong-headed approach leads to a messy
stack problem. Suppose we're trying to write the definition of \forth{+THRU}
(see \Chap{5}, ``Listing Organization'' section, ``Relative Loading''
subsection). We've decided that our loop body will be

\begin{Code}
...  DO  i load  LOOP ;
\end{Code}
that is, we'll put \forthb{LOAD} in a loop, then arrange for the index and
limit to correspond to the absolute screens being loaded.

On the stack initially we have:

\begin{Code}
lo hi
\end{Code}
where ``lo'' and ``hi'' are the \emph{offsets} from \forthb{BLK}.

We need to permute them for \forthb{DO}, like this:

\begin{Code}
hi+1+blk lo+blk
\end{Code}
Our biggest problem is adding the value of \forth{BLK} to both offsets.

We've already taken a wrong turn but we don't know it yet. So let's
proceed. We try:

\begin{Code}
lo hi
               blk @
lo hi blk
               swap
lo blk hi
               over
lo blk hi blk
               +
lo blk hi+blk
               1+
lo blk hi+blk+1
               rot rot
hi+blk+1 lo blk
               +
hi+blk+1 lo+blk
\end{Code}
We made it, but what a mess!

If we're gluttons for punishment, we might make two more stabs at
it arriving at:

\begin{Code}
blk @  dup rot + 1+  rot rot +
\end{Code}
and

\begin{Code}
blk @  rot over +  rot rot + 1+  swap
\end{Code}
All three sequences do the same thing, but the code seems to be getting
blurrier, not better.

With experience we learn to recognize the combination \forth{ROT ROT} as
a danger sign: the stack is too crowded. Without having to work out the
alternates, we recognize the problem: once we make two copies of ``blk,''
we have four elements on the stack.

\medbreak
At this point, the first resort is usually the return stack:

\begin{Code}
blk @  dup >r  + 1+  swap r> +
\end{Code}
(See ``The Stylish Return Stack,'' coming up next.) Here we've \forthb{DUP}ed
``blk,'' saving one copy on the return stack and adding the other copy to
``hi.''

Admittedly an improvement. But readable?

Next we think, ``Maybe we need a named variable.'' Of course, we
have one already: \forthb{BLK}. So we try:

\begin{Code}
blk @  + 1+  swap blk @ +
\end{Code}
Now it's more readable, but it's still rather long, and redundant too.
\forthb{BLK @ +} appears twice.

``\forthb{BLK @ +}''? That sounds familiar. Finally our neurons connect.

We look back at the source for \forth{+LOAD} just defined:

\begin{Code}
: +load  ( offset -- )  blk @ +  load ;
\end{Code}
This word, \forth{+LOAD}, should be doing the work. All we have to write is:

\begin{Code}
: +thru  ( lo hi )  1+ swap  DO  i +load  LOOP ;
\end{Code}
We haven't created a more efficient version here, because the work of
\forthb{BLK @ +} will be done on every pass of the loop. But we have
created a cleaner, conceptually simpler, and more readable piece of code.
In this case, the inefficiency is unnoticeable because it only occurs as
each block is loaded.

Redesigning, or rethinking the problem, was the path we should
have taken as soon as things got ugly.%
\index{D!Data stacks!depth of|)}

\subsection{Local Variables}%
\index{L!Local variables|(}%
\index{D!Data stacks!local variables and,|(}%
\index{D!Data stacks!data@vs. data structures|(}%
\index{D!Data structures:!data@vs. data stacks|(}
\index{V!Variables:!local|(}%

Most of the time problems can be arranged so that only a few arguments
are needed on the stack at any one time. Occasionally, however, there's
nothing you can do.

Here's an example of a worst case. Assume you have a word called
\forth{LINE} which draws a line between any two points, specified as
coordinates in this order:

\begin{Code}
( x1 y1 x2 y2 -- )
\end{Code}
where $x_1,y_1$ represent the $x,y$ coordinates for the one end-point, and
$x_2,y_2$ represent the opposite end-point.

Now you have to write a box-drawing word called \forth{[BOX]} which
takes four arguments in this order:

\begin{Code}
( x1 y1 x2 y2 -- )
\end{Code}
where x1 y1 represent the $x,y$ coordinates for the upper left-hand corner
of the box, and x2 y2 represent the lower right-hand corner coordinates.
Not only do you have four elements on the stack, they each have to
be referred to more than once as you draw lines from point to point.

Although we're using the stack to get the four arguments, the algorithm
for drawing a box doesn't lend itself to the nature of the stack. If you're
in a hurry, it would probably be best to take the easy way out:

\begin{Code}
: [box] { x1 y1 x2 y2 -- }
  x1 y1 x2 y1 line
  x2 y1 x2 y2 line
  x2 y2 x1 y2 line
  x1 y2 x1 y1 line ;
\end{Code}
What we've done is create four named variables, one for each coordinate.
The first thing \forth{[BOX]} does is fill these variables with the
arguments from the stack. Then the four lines are drawn, referencing the
variables.  Variables such as these that are used only within a definition
(or in some cases, within a lexicon) are called ``local variables.''

I've been guilty many times of playing hotshot, trying to do as
much as possible on the stack rather than define a local variable. There
are three reasons to avoid this cockiness.

First, it's a pain to code that way. Second, the result is unreadable.
Third, all your work becomes useless when a design change becomes
necessary, and the order of two arguments changes on the stack. The
\forthb{DUP}s, \forthb{OVER}s and \forthb{ROT}s weren't really solving the
problem, just jockeying things into position.

With this third reason in mind, I recommend the following:

\begin{tip}
Especially in the design phase, keep on the stack only the arguments you're
using immediately. Create local variables for any others. (If necessary,
eliminate the variables during the optimization phase.)
\end{tip}
Fourth, if the definition is extremely time-critical, those tricky stack
manipulators, (e.g., \forthb{ROT ROT}) can really eat up clock cycles.
Direct access to variables is faster.

If it's \emph{really} time-critical, you may need to convert to assembler
anyway. In this case, all your stack problems fly out the door, because
all your data will be referenced either in registers or indirectly through
registers. Luckily, the definitions with the messiest stack arguments are
often the ones written in code. Our \forth{[BOX]} primitive is a case in
point.  \forthb{CMOVE>} is another.

The approach we took with \forth{[BOX]} certainly beats spending half an
hour juggling items on the stack, but it is by no means the best solution.
What's nasty about it is the expense of creating four named variables,
headers and all, solely for use within this one routine.

(If you're target compiling an application that will not require headers
in the dictionary, the only loss will be the 8 bytes in RAM for the
variables. In \Forth{} systems of the future, headers may be separated
into other pages of memory anyway; again the loss will be only 8 bytes.)
Let me repeat: This example represents a worst-case situation, and occurs
rarely in most \Forth{} applications. If words are well-factored, then
each word is designed to do very little. Words that do little generally
require few arguments.

In this case, though, we are dealing with two points each represented
by two coordinates.

Can we change the design? First, \forth{LINE} may be \emph{too} primitive a
primitive. It requires four arguments because it can draw lines between
any two points, diagonally, if necessary.

In drawing our box, we may only need perfectly vertical and horizontal
lines. In this case we can write the more powerful, but less specific,
words \forth{VERTICAL} and \forth{HORIZONTAL} to draw these lines. Each
requires only \emph{three} arguments: the starting position's x and y, and
the length. This factoring of function simplifies the definition of
\forth{[BOX].}

Or we might discover that this syntax feels more natural to the
user:

\begin{Code}
10 10 origin! 30 30 box
\end{Code}
where \forth{ORIGIN!} sets a two-element pointer to the ``origin,'' the
place where the box will start (the upper left-hand corner). Then
``\forth{30 30 BOX}'' draws a box 30 units high and 30 units wide,
relative to the origin.

This approach reduces the number of stack arguments to \forth{BOX} as
part of the design.

\begin{interview}
\person{Paysan}:

\begin{tfquot}
I prefer turtle graphics. This is a turtle graphics without cursor
direction, so the direction is explicit (using the same \forth{LINE}
primitive):

\begin{Code}
2variable pos
: setpos ( x y -- )  pos 2! ;
: p+ ( x y w h -- x' y' )  rot + >r + r> ;
: moveto ( dx dy -- )  pos 2@ p+ pos 2! ;
: drawto ( dx dy -- )  pos 2@ 2swap moveto pos 2@ line ;

: right ( dx -- )  0 drawto ;
: down  ( dy -- )  0 swap drawto ;
: left  ( dx -- )  negate right ;
: up    ( dy -- )  negate down ;

: box ( w h -- )  2dup down right up left ;
: [box] ( x y w h -- )  2swap setpos box ;
\end{Code}

Now this seems to be a lot of work for a single box, to get rid of the
long definition and the stack juggling. But usually, it doesn't end
with a single box. And then the small initial work pays off big.

I think this is a good illustration how \Forth{} code should look
like. None of the definitions has more than 7 words. Only one has more
than one stack juggling word. The global variable now is no disguised
``local,'' but the state (position) of the turtle.
\end{tfquot}
\end{interview}

\begin{tip}
When determining which arguments to handle via data structures rather
than via the stack, choose the arguments that are the more permanent or
that represent a current state.
\end{tip}%
\index{L!Local variables|)}%
\index{V!Variables:!local|)}%
\index{D!Data stacks!local variables and,|)}%
\index{D!Data stacks!data@vs. data structures|)}%
\index{D!Data structures:!data@vs. data stacks|)}

\subsection{On PICK and ROLL}%
\index{D!Data stacks!PICK and ROLL|(}%
\index{P!PICK|(}%
\index{R!ROLL|(}%

Some folks like the words \forthb{PICK} and \forthb{ROLL}. They use these
words to access elements from any level on the stack. We don't recommend
them.  For one thing, \forthb{PICK} and \forthb{ROLL} encourage the
programmer to think of the stack as an array, which it is not. If you have
so many elements on the stack that you need \forthb{PICK} and
\forthb{ROLL}, those elements should be in an array instead.

Second, they encourage the programmer to refer to arguments that
have been left on the stack by higher-level, calling definitions without
being explicitly \emph{passed} as arguments. This makes the definition
dependent on other definitions. That's unstructured---and dangerous.

Finally, the position of an element on the stack depends on what's
above it, and the number of things above it can change constantly. For
instance, if you have an address at the fourth stack position down, you can
write

\begin{Code}
4 pick @
\end{Code}
to fetch its contents. But you must write

\begin{Code}
( n) 5 pick !
\end{Code}
because with ``$n$'' on the stack, the address is now in the fifth position.
Code like this is hard to read and harder to modify.%
\index{D!Data stacks!PICK and ROLL|)}%
\index{P!PICK|)}%
\index{R!ROLL|)}%

\subsection{Make Stack Drawings}%
\index{D!Data stacks!drawings|(}

When you do have a cumbersome stack situation to solve, it's best to work
it out with paper and pencil. Some people even make up forms, such as the
one in \Fig{fig7-1}. Done formally like this (instead of on the back of your
phone bill), stack commentaries serve as nice auxiliary documentation.

\subsection{Stack Tips}

\begin{tip}
Make sure that stack effects balance out under all possible control flows.
\end{tip}
In the stack commentary for \forthb{CMOVE>} in \Fig{fig7-1}, the inner
brace represents the contents of the \forthb{DO }\forthb{LOOP}. The stack
depth upon exiting the loop is the same as upon entering it: one element.
Within the outer braces, the stack result of the \forthb{IF} clause is the
same as that of the \forthb{ELSE} clause: one element left over. (What
that leftover element represents doesn't matter, as symbolized by the
``x'' next to \forthb{THEN}.)

\wepsfiga{fig7-1}{Example of a stack commentary.}

%!! include \Fig{fig7-1} here

\begin{tip}
When doing two things with the same number, perform the function that
will go underneath first.
\end{tip}
For example:

\begin{Code}
: count  ( a -- a+1 # )  dup c@  swap 1+  swap ;
\end{Code}
(where you first get the count) is more efficiently written:

\begin{Code}
: count  ( a -- a+1 # )  dup 1+  swap c@ ;
\end{Code}
(where you first compute the address).
\goodbreak

\begin{tip}
Where possible, keep the number of return arguments the same in all
possible cases.
\end{tip}%
\index{E!Error-code|(}
You'll often find a definition which does some job and, if something goes
wrong, returns an error-code identifying the problem. Here's one way
the stack interface might be designed:

\begin{Code}
( -- error-code f | -- t )
\end{Code}
If the flag is true, the operation was successful. If the flag is false,
it was unsuccessful and there's another value on the stack to indicate the
nature of the error.

You'll find stack manipulation easier, though, if you redesign the interface
to look like this:

\begin{Code}
( -- error-code | 0=no-error )
\end{Code}
One value serves both as a flag and (in case of an error) the error code.
Note that reverse-logic is used; non-zero indicates an error. You can use
any values for the error codes except zero.%
\index{E!Error-code|)}%
\index{D!Data stacks!drawings|)}

\section{The Stylish Return Stack}%
\index{D!Data stacks!return|(}
\index{R!Return stack|(}

What about this use of the return stack to hold temporary arguments? Is
it good style or what?

Some people take great offense to its use. But the return stack
offers the simplest solution to certain gnarly stack jams. Witness the
definition of \forthb{CMOVE>} in the previous section.

If you decide to use the return stack for this purpose, remember
that you are using a component of \Forth{} for a purpose other than that
intended. (See the section called ``Sharing Components,'' later in this
chapter.)

Here's some suggestions to keep you from shooting yourself in the
foot:

\begin{tip}
%!! there's certainly some better way to do ordered lists in TeX
\begin{enumerate}
\item Keep return stack operators symmetrical.
\item Keep return stack operators symmetrical under all control flow
conditions.
\item In factoring definitions, watch out that one part doesn't contain
one return stack operator, and the other its counterpart.
\item If used inside a \forthb{DO }\forthb{LOOP}, return stack operators
must be symmetrical within the loop, and \forthb{I} is no longer valid in
code bounded by \forthb{>R} and \forthb{R>}.
\end{enumerate}
\end{tip}
For every \forthb{>R} there must be a \forthb{R>} in the same definition.
Sometimes the operators will appear to be symmetrical, but due to the
control structure they aren't. For instance:

\begin{Code}
... BEGIN ... >r ... WHILE ... r> ... REPEAT
\end{Code}
If this construction is used in the outer loop of your application,
everything will run fine until you exit (perhaps hours later) when you'll
suddenly blow up. The problem? The last time through the loop, the
resolving \forthb{R>} has been skipped.%
\index{D!Data stacks!return|)}
\index{R!Return stack|)}

\section{The Problem With Variables}%
\index{V!Variables:!problem with|(}

Although we handle data of immediate interest on the stack, we depend
on much information tucked away in variables, ready for recurring access.
A piece of code can change the contents of a variable without
necessarily having to know anything about how that data will be used,
who will use it, or when and if it will be used. Another piece of code can
fetch the contents of a variable and use it without knowing where that
value came from.

For every word that pushes a value onto the stack, another word
must consume that value. The stack gives us point-to-point communication,
like the post office.

Variables, on the other hand, can be set by any command and accessed
any number of times---or not at all---by any command. Variables
are available for anyone who cares to look---like graffiti.

Thus variables can be used to reflect the current state of affairs.

Using currentness can simplify problems. In the Roman numeral example
of \Chap{4}, we used the variable \forth{COLUMN\#} to represent the
current decimal-place; the words \forth{ONER}, \forth{FIVER}, and
\forth{TENER} depended on this information to determine which type of
symbol to display. We didn't have to specify both descriptions every
time, as in \forth{TENS ONER}, \forth{TENS FIVER}, etc.

On the other hand, currentness adds a new level of complexity. To make
something current we must first define a variable or some type of data
structure. We also must remember to initialize it, if there's any chance
that part of our code will refer to it before another part has had a
chance to set it.

A more serious problem with variables is that they are not ``reentrant.''
On a multi-tasked \Forth{} system, each task which requires local
variables must have its own copies. \Forth{}'s \forthb{USER} variables
serve this purpose. (See \emph{Starting \Forth{}}, Chapter Nine,
``\Forth{} Geography.'')

Even within a single task, a definition that refers to a variable is
harder to test, verify, and reuse in a different situation than one in
which arguments are passed via the stack.

Suppose we are implementing a word-processor editor. We need a routine
that calculates the number of characters between the current cursor
position and the previous carriage-return/line-feed sequence. So we write
a word that employs a \forthb{DO }\forthb{LOOP} starting at the current
position (\forth{CURSOR @}) and ending at the zeroth position, searching
for the line feed character.

Once the loop has found the character sequence, we subtract its
relative address from our current cursor position

\begin{Code}
its-position cursor @  swap -
\end{Code}
to determine the distance between them.

Our word's stack effect is:

\begin{Code}
( -- distance-to-previous-cr/lf)
\end{Code}
But in later coding we find we need a similar word to compute the distance
from an arbitrary character---\emph{not} the current cursor position---to
the first previous line-feed character. We end up factoring out the
``\forth{CURSOR @}'' and allowing the starting address to be passed as an
argument on the stack, resulting in:

\begin{Code}
( starting-position -- distance-to-previous-cr/lf)
\end{Code}
By factoring-out the reference to the variable, we made the definition
more useful.

\begin{tip}
Unless it involves cluttering up the stack to the point of unreadability,
try to pass arguments via the stack rather than pulling them out of
variables.
\end{tip}

\begin{interview}
\index{K!Kogge, Peter|(}
\person{Kogge}:
\begin{tfquot}
Most of the modularity of \Forth{} comes from designing and treating
\Forth{} words as ``functions'' in the mathematical sense. In my
experience a \Forth{} programmer usually tries quite hard to avoid
defining any but the most essential global variables (I have a friend who
has the sign ``Help stamp out variables'' above his desk), and tries to
write words with what is called ``referential transparency,'' i.e., given
the same stack inputs a word will always give the same stack outputs
regardless of the more global context in which it is executed.

In fact this property is exactly what we use when we test words in
isolation.  Words that do not have this property are significantly harder
to test. In a sense a ``named variable'' whose value changes frequently is
the next worst thing to the now ``forbidden'' GOTO.
\end{tfquot}
\index{K!Kogge, Peter|)}
\end{interview}

\wepsfigp{img7-211}{``Shot from a cannon on a fast-moving train,
hurtling between the blades of a windmill, and expecting to grab a
trapeze dangling from a hot-air balloon\dots{} I~told you Ace, there were
too many variables!''}

\noindent Earlier we suggested the use of local variables especially
during the design phase, to eliminate stack traffic. It's important to
note that in doing so, the variables were referred to only within the one
definition.  In our example, \forth{[BOX]} receives four arguments from
the stack and immediately loads them into local variables for its own use.
The four variables are not referred to outside of this definition, and the
word behaves safely as a function.

Programmers unaccustomed to a language in which data can be passed
implicitly don't always utilize the stack as fully as they should.
\person{Michael Ham}\index{H!Ham, Michael}
suggests the reason may be that beginning \Forth{} users
don't trust the stack \cite{ham83}. He admits to initially feeling
safer about storing values into variables than leaving them on the
stack. ``No telling \emph{what} might happen with all that thrashing
about on the stack,'' he felt.

It took some time for him to appreciate that ``if words keep properly
to themselves, using the stack only for their expected input and output
and cleaning up after themselves, they can be looked upon as sealed
systems \dots{} I could put the count on the stack at the beginning of the
loop, go through the complete routine for each group, and at the end the
count would emerge, back on top of the stack, not a hair out of place.''%
\index{V!Variables:!problem with|)}

\section{Local and Global Variables/Initialization}%
\index{V!Variables:!local|(}%
\index{V!Variables:!global|(}%
\index{G!Global variables|(}%
\index{L!Local variables|(}%

As we saw earlier, a variable that is used exclusively within a single
definition (or single lexicon), hidden from other code, is called a local
variable. A variable used by more than one lexicon is called a global
variable. As we've seen in an earlier chapter, a set of global variables that
collectively describe a common interface between several lexicons is
called an ``interface lexicon.''
\index{I!Interface lexicon}

\Forth{} makes no distinction between local and global variables.
But \Forth{} programmers do.

\begin{interview}%
\index{M!Moore, Charles|(}
\person{Moore}:

\begin{tfquot}
We should be writing for the reader. If something is referred to only
locally, a temporary variable just for accumulating a sum in, we should
define it locally. It's handier to define it in the block where it's used,
where you can see its comment.

If it's used globally, we should collect things according to their logical
function, and define them together on a separate screen. One per line with
a comment.

The question is, where do you initialize them? Some say on the same line,
immediately following its definition. But that messes up the comments, and
there isn't room for any decent comment. And it scatters the
initialization all over the application.

I tend to do all my initialization in the load screen. After I've loaded
all my blocks, I initialize the things that have to be initialized. It
might also set up color lookup tables or execute some initialization code.

If your program is destined to be target compiled, then it's easy to write
a word at the point that encompasses all the initialization.

It can get much more elaborate. I've defined variables in ROM where the
variables were all off in an array in high memory, and the initial values are
in ROM, and I copy up the initial values at initialization time. But usually
you're only initializing a few variables to anything other than zero.
\end{tfquot}%
\index{M!Moore, Charles|)}
\end{interview}%
\index{V!Variables:!local|)}%
\index{V!Variables:!global|)}%
\index{G!Global variables|)}%
\index{L!Local variables|)}%

\section{Saving and Restoring a State}%
\index{V!Variables:!saving and restoring states|(}%
\index{D!Data stacks!saving and restoring states|(}

Variables have the characteristic that when you change their contents,
you clobber the value that was there before. Let's look at some of the
problems this can create, and some of the things we can do about them.

\index{B!BASE|(}%
\forthb{BASE} is a variable that indicates the current
number radix for all numeric input and output. The following words are
commonly found in \Forth{} systems:

\begin{Code}
: decimal ( -- )  10 base ! ;
: hex     ( -- )  16 base ! ;
\end{Code}
Suppose we've written a word that displays a ``dump'' of memory.
Ordinarily, we work in decimal mode, but we want the dump in hexadecimal.
So we write:

\begin{Code}
: dump  ( a # -- )
   hex   ...   ( code for the dump) ... decimal ;
\end{Code}
This works---most of the time. But there's a presumption that we want to
come back to decimal mode. What if it had been working in hexadecimal, and
wants to come back to hexadecimal? Before we change the base to
\forthb{HEX}, we have to save its current value. When we're done dumping,
we restore it.

\index{R!Return stack|(}
This means we have to tuck away the saved value temporarily,
while we format the dump. The return stack is one place to do this:

\begin{Code}
: dump  ( a # -- )
   base @ >r  hex   ( code for dump)  r> base ! ;
\end{Code}
If things get too messy, we may have to define a temporary variable:
\index{R!Return stack|)}

\begin{Code}
Variable old-base
: dump  ( a # -- )
   base @  old-base !  hex ( code for dump )
   old-base @  base ! ;
\end{Code}
How quickly things get complicated.%
\index{B!BASE|)}

In this situation, if both the current and the old version of a variable
belong only to your application (and not part of your system), and if this
same situation comes up more than once, apply a technique of factoring:

\begin{Code}
: bury  ( a -- )  dup cell+  1 cells  move ;
: exhume  ( a -- )  dup cell+  swap 1 cells  move ;
\end{Code}
Then instead of defining two variables, such as \forth{CONDITION} and
\forth{OLD-CONDITION}, define one double-length variable:

\begin{Code}
2Variable condition
\end{Code}
Use \forth{BURY} and \forth{EXHUME} to save and restore the original value:

\begin{Code}
: diddle    condition bury  17 condition !  ( diddle )
   condition exhume ;
\end{Code}
\forth{BURY} saves the ``old'' version of condition at \forth{CONDITION CELL+}.

You still have to be careful. Going back to our \forthb{DUMP} example,
suppose you decided to add the friendly feature of letting the user exit
the dump at any time by pressing the ``escape'' key. So inside the loop
you build the test for a key being pressed, and if so execute
\forthb{QUIT}. But what happens?

The user starts in decimal, then types \forthb{DUMP}. He exits
\forthb{DUMP} midway through and finds himself, strangely, in hexadecimal.

In the simple case at hand, the best solution is to not use
\forthb{QUIT}, but rather a controlled exit from the loop (via
\forthb{LEAVE}, etc.) to the end of the definition where
\forthb{BASE} is reset.

In very complex applications a controlled exit is often impractical,
yet many variables must somehow be restored to a natural condition.

\begin{interview}%
\index{M!Moore, Charles|(}
\person{Moore} responds to this example:

\begin{tfquot}
You really get tied up in a knot. You're creating problems for
yourself. If I want a hex dump I say \forthb{HEX }\forthb{DUMP}. If I
want a decimal dump I say \forthb{DECIMAL }\forthb{DUMP}. I don't give
\forthb{DUMP} the privilege of messing around with my environment.

There's a philosophical choice between restoring a situation when you
finish and establishing the situation when you start. For a long time I felt
you should restore the situation when you're finished. And I would try to
do that consistently everywhere. But it's hard to define ``everywhere.'' So
now I tend to establish the state before I start.

If I have a word which cares where things are, it had better set them. If
somebody else changes them, they don't have to worry about resetting
them.

There are more exits than there are entrances.
\end{tfquot}\index{M!Moore, Charles|)}
\end{interview}

In cases in which I need to do the resetting before I'm done, I've found it
useful to have a single word (which I call \forth{PRISTINE}) to perform this
resetting. I invoke \forth{PRISTINE}:

%!! '*'s should be bullets
\begin{itemize}
\item at the normal exit point of the application
\item at the point where the user may deliberately exit (just before
\forthb{QUIT})
\item at any point where a fatal error may occur, causing an abort.
\end{itemize}

Finally, when you encounter this situation of having to save/restore a
value, make sure it's not just a case of bad factoring. For example,
suppose we have written:

\begin{Code}
: long   ( -- )  18 #holes ! ;
: short  ( -- )   9 #holes ! ;
: game   ( -- )  #holes @  0 DO  i hole play  LOOP ;
\end{Code}
The current \forth{GAME} is either \forth{LONG} or \forth{SHORT}.

Later we decide we need a word to play \emph{any} number of holes. So
we invoke \forth{GAME} making sure not to clobber the current value of
\forth{\#HOLES}:

\begin{Code}
: holes  ( n -- )  #holes @  swap #holes !  game  #holes ! ;
\end{Code}
Because we needed \forth{HOLES} after we'd defined \forth{GAME}, it
seemed to be of greater complexity; we built \forth{HOLES} around
\forth{GAME}. But in fact---perhaps you see it already---rethinking is
in order:

\begin{Code}
: holes ( n -- )  0 DO  i hole play  LOOP ;
: game  ( -- )    #holes @ holes ;
\end{Code}
We can build \forth{GAME} around \forth{HOLES} and avoid all this
saving/restoring nonsense.%
\index{V!Variables:!saving and restoring states|)}%
\index{D!Data stacks!saving and restoring states|)}

\section{Application Stacks}

In the last section we examined some ways to save and restore a single
previous value. Some applications require \emph{several} values to be
saved and restored. You may often find the best solution to this problem
in defining your own stack.

Here is the code for a user stack including very simple error checking
(an error clears the stack):

\begin{Code}
Create stack  6 cells allot
              \ { tos-pointer | stack [5 cells] }
here Constant stack>
: init-stack  ( -- )  stack stack ! ;   init-stack
: ?bad ( ? -- )
    IF ." stack error "  init-stack  abort  THEN ;
: push ( n -- )
    cell stack +!  stack @  dup  stack> = ?bad ! ;
: pop  ( -- n )
    stack @ @  cell negate stack +!  stack @ stack < ?bad ;
\end{Code}
The word \forth{PUSH} takes a value from off of your data stack and
``pushes'' it onto this new stack. \forth{POP} is the opposite,
``popping'' a value from off the new stack, and onto \Forth{}'s data
stack.

In a real application you might want to change the names \forth{PUSH}
and \forth{POP} to better match their conceptual purposes.

\section{Sharing Components}%
\index{C!Components:!sharing|(}%
\index{S!Sharing components|(}
\begin{tip}
It's legal to use a component for an additional purpose besides its
intended one, provided:
\medskip
\begin{enumerate}
\item All uses of the component are mutually exclusive
\item Each interrupting use of the component restores the component to
   its previous state when finished.
\end{enumerate}
\medskip\noindent
Otherwise you need an additional component or level of complexity.
\end{tip}%
\index{D!Data stacks!return|(}
We've seen a simple example of this principle with the return stack. The
return stack is a component of the \Forth{} system designed to hold return
addresses, and thereby serve as an indication of where you've been and
where you're going. To use the return stack as a holder for temporary
values is possible, and in many cases desirable. Problems occur when one
of the above restrictions is ignored.%
\index{D!Data stacks!return|)}

In my text formatter the output can go invisible. This feature has
two purposes: 
\begin{enumerate}
\item for looking ahead to see whether something will fit, and
\item for formatting the table of contents (the entire document is
formatted and page numbers are calculated without anything actually being
displayed).
\end{enumerate}

It was tempting to think that once having added the ability to make
the output invisible, I could use this feature to serve both purposes.
Unfortunately, the two purposes are not mutually exclusive.

Let's see what would happen if I tried to violate this rule. Imagine
that the word \forth{DISPLAY} does the output, and it's smart enough
to know whether to be visible or invisible. The words \forth{VISIBLE}
and \forth{INVISIBLE} set the state respectively.

My code for looking ahead will first execute \forth{INVISIBLE,} then
test-format the upcoming text to determine its length, and finally
execute \forth{VISIBLE} to restore things to the normal state.

This works fine.

Later I add the table-of-contents feature. First the code executes
\forth{IN\-VI\-SI\-BLE}, then runs through the document determining page
numbers etc.; then finally executes \forth{VISIBLE} to restore things
to normal.

The catch? Suppose I'm running a table of contents and I hit one of
those places where I look ahead. When I finish looking ahead, I
execute \forth{VISIBLE}. Suddenly I start printing the document when I
was supposed to be running the table of contents.

The solution? There are several.

One solution views the problem as being that the lookahead code is
clobbering the visible/invisible flag, which may have been preset by
table-of-contents. Therefore, the lookahead code should be responsible for
saving, and later restoring, the flag.

Another solution involves keeping two separate variables---one to
indicate we're looking ahead, the other to indicate we're printing the
table of contents. The word \forth{DISPLAY} requires that both flags
be false in order to actually display anything.

There are two ways to accomplish the latter approach, depending on
how you want to decompose the problem. First, we could nest one condition
within the other:

\begin{Code}
: [display]  ...
    ( the original definition, always does the output) ... ;
Variable 'lookahead?  ( t=looking-ahead)
: <display> ( -- )  'lookahead? @ 0=  IF  [display]  THEN ;
Variable 'toc?  ( t=setting-table-of-contents)
: display ( -- )  'toc? @ 0=  IF  <display>  THEN ;
\end{Code}
{\sloppy
\forth{DISPLAY} checks that we're not setting the table of contents
and invokes \forth{<DISPLAY>}, which in turn checks that we're not
looking ahead and invokes \forth{[DISPLAY]}.

}

In the development cycle, the word \forth{[DISPLAY]} that always does
the output was originally called \forth{DISPLAY}. Then a new
\forth{DISPLAY} was defined to include the lookahead check, and the
original definition was renamed \forth{[DISPLAY]}, thus adding a level
of complexity backward without changing any of the code that used
\forth{DISPLAY}.

Finally, when the table-of-contents feature was added, a new
\forth{DISPLAY} was defined to include the table-of-contents check,
and the previous \forth{DISPLAY} was renamed \forth{<DISPLAY>}.

That's one approach to the use of two variables. Another is to include
both tests within a single word:

\begin{Code}
: display ( -- )
    'lookahead? @  'toc @ or  0= IF [display] THEN ;
\end{Code}
But in this particular case, yet another approach can simplify the whole
mess. We can use a single variable not as a flag, but as a counter.

We define:

\begin{Code}
variable 'invisible?  ( t=invisible)
: display ( -- )  'invisible? @  0= IF [display] THEN ;
: invisible   1 'invisible? +! ;
: visible    -1 'invisible? +! ;
\end{Code}
The lookahead code begins by invoking \forth{INVISIBLE} which bumps
the counter up one. Non-zero is ``true,'' so \forth{DISPLAY} will not
do the output.  After the lookahead, the code invokes \forth{VISIBLE}
which decrements the counter back to zero (``false'').

The table-of-contents code also begins with \forth{VISIBLE} and ends
with \forth{IN\-VI\-SI\-BLE}. If we're running the table of contents while
we come upon a lookahead, the second invocation of \forth{VISIBLE}
raises the counter to two.

The subsequent invocation of \forth{INVISIBLE} decrements the counter
to one, so we're still invisible, and will remain invisible until the
table of contents has been run.

%(Note that we must substitute \forthb{0=} for \forthb{NOT}. The '83
%Standard has changed \forthb{NOT} to mean one's complement, so that
%\forthb{1 NOT} yields true. By the way, I think this was a mistake.)

This use of a counter may be dangerous, however. It requires parity of
command usage: two \forth{VISIBLE}s yields invisible. That is, unless
\forth{VISIBLE} clips the counter:

\begin{Code}
: visible ( -- )  'invisible? @  1-  0 max  'invisible? ! ;
\end{Code}
\index{C!Components:!sharing|)}%
\index{S!Sharing components|)}

\section{The State Table}%
\index{S!State table|(}
\index{V!Variables:!state table|(}

A single variable can express a single condition, either a flag, a value, or
the address of a function.

A collection of conditions together represent the \emph{state} of the
application or of a particular component \cite{slater83}. Some applications require the
ability to save a current state, then later restore it, or perhaps to have a
number of alternating states.

\begin{tip}
When the application requires handling a group of conditions
simultaneously, use a state table, not separate variables.
\end{tip}

\noindent The simple case requires saving and restoring a state. Suppose
we initially have six variables representing the state of a particular
component, as shown in \Fig{fig7-2}.
\begin{figure*}[hhhh]
\caption{A collection of related variables.}
\labelfig{fig7-2}
\begin{center}
\begin{BVerbatim}
Variable top
Variable bottom
Variable left
Variable right
Variable inside
Variable out
\end{BVerbatim}
\end{center}
\end{figure*}

\noindent Now suppose that we need to save all of them, so that further
processing can take place, and later restore all of them. We could define:

\begin{Code}
: @state ( -- top bottom left right inside out )
   top @  bottom @  left @  right @  inside @  out @ ;
: !state ( top bottom left right inside out -- )
   out !  inside !  right !  left !  bottom !  top ! ;
\end{Code}
thereby saving all the values on the stack until it's time to restore them.
Or, we might define alternate variables for each of the variables above, in
which to save each value separately.

But a preferred technique involves creating a table, with each
element of the table referred to by name. Then creating a second table of
the same length. As you can see in \Fig{fig7-3}, we can save the state by
copying the table, called \forth{POINTERS,} into the second table, called
\forth{SAVED}.

\wepsfiga{fig7-3}{Conceptual model for saving a state table.}

%!! include \Fig{fig7-3} here

We've implemented this approach with the code in \Fig{fig7-4}.

\begin{figure*}[tttt]
\caption{Implementation of save/restorable state table.}
\labelfig{fig7-4}
\begin{center}
\begin{BVerbatim}
0 Value pointers  \ address of state table patched later
: Position   ( o -- o+cell ) Create dup ,  cell+
   DOES>  ( -- a )  @  pointers + ;
0  \ initial offset
Position top
Position bottom
Position left
Position right
Position inside
Position out
Constant /pointers   \ final computed offset

here to pointers  /pointers allot  \ real table
Create saved  /pointers allot  \ saving place
: save     ( -- )  pointers  saved  /pointers cmove ;
: restore  ( -- )  saved  pointers  /pointers cmove ;
\end{BVerbatim}
\end{center}
\end{figure*}

Notice in this implementation that the names of the pointers,
\forth{TOP}, \forth{BOTTOM}, etc., always return the same address.
There is only one location used to represent the current value of any
state at any time.

Also notice that we define \forth{POINTERS} (the name of the table)
with \forth{CON\-STANT}, not with \forth{CREATE}, using a dummy value of
zero. This is because we refer to \forth{POINTERS} in the defining
word \forth{POSITION}, but it's not until after we've defined all the
field names that we know how big the table must be and can actually
\forth{ALLOT} it.

As soon as we create the field names, we define the size of the table
as a constant \forth{/POINTERS}. At last we reserve room for the table
itself, patching its beginning address (\forth{HERE}) into the
constant \forth{POINTERS}.  (The word \forthb{>BODY} converts the
address returned by tick into the address of the constant's value.)
Thus \forth{POINTERS} returns the address of the table allotted later,
just as a name defined by \forth{CREATE} returns the address of a
table allotted directly below the name's header.

Although it's valid to patch the value of a \forth{CONSTANT} at compile
time, as we do here, there is a restriction of style:

\begin{tip}
A \forth{CONSTANT}'s value should never be changed once the application is
compiled.
\end{tip}
The case of alternating states is slightly more involved. In this situation
we need to alternate back and forth between two (or more) states, never
clobbering the conditions in each state when we jump to the other state.
\Fig{fig7-5} shows the conceptual model for this kind of state table.

\wepsfiga{fig7-5}{Conceptual model for alternating-states tables.}

\noindent In this model, the names \forth{TOP}, \forth{BOTTOM}, etc., can
be made to point into either of two tables, \forth{REAL} or
\forth{PSEUDO}. By making the \forth{REAL} table the current one, all
the pointer names reference addresses in the \forth{REAL} table; by
making the \forth{PSEUDO} table current, they address the
\forth{PSEUDO} table.

The code in \Fig{fig7-6} implements this alternating states mechanism.
The words \forth{WORKING} and \forth{PRETENDING} change the pointer
appropriately. For instance:

\begin{figure*}[bbbt]
\caption{Implementation of alternating-states mechanism.}
\labelfig{fig7-6}
\begin{center}
\begin{BVerbatim}
Variable 'pointers  \ pointer to state table
: pointers ( -- adr-of-current-table )   'pointers @ ;
: Position   ( o -- o+cell ) Create dup ,  cell+
   DOES>  ( -- a )  @ pointers + ;
0  \ initial offset
Position top
Position bottom
Position left
Position right
Position inside
Position out
Constant /pointers  \ final computed offset
Create real    /pointers allot  \ real state table
Create pseudo  /pointers allot  \ temporary state table
: working      real 'pointers ! ;     working
: pretending   pseudo 'pointers ! ;
\end{BVerbatim}
\end{center}
\end{figure*}

\begin{Code}[commandchars=&\{\}]
working
10 top !
top &underline{? 10}
pretending
20 top !
top &underline{? 20}
working
top &underline{? 10}
pretending
top &underline{? 20}
\end{Code}
The major difference with this latter approach is that names go through
an extra level of indirection (\forth{POINTERS} has been changed from a
constant to a colon definition). The field names can be made to point to
either of two state tables. Thus each name has slightly more work to do.
Also, in the former approach the names refer to fixed locations; a
\forthb{CMOVE} is required each time we save or restore the values. In this
approach, we have only to change a single pointer to change the current
table.%
\index{S!State table|)}
\index{V!Variables:!state table|)}

\section{Vectored Execution}%
\index{V!Vectored Execution|(}
\index{F!Functions:!vectored execution|(}

Vectored execution extends the ideas of currentness and indirection
beyond data, to functions. Just as we can save values and flags in
variables, we can also save functions, because functions can be referred to
by address.

The traditional techniques for implementing vectored execution are
described in \emph{Starting \Forth{}}, Chapter Nine. In this section we'll
discuss a new syntax which I invented and which I think can be used in many
circumstances more elegantly than the traditional methods.

\index{D!DOER/MAKE|(}%
The syntax is called \forth{DOER}/\forth{MAKE}. (If your system doesn't
include these words, refer to \App{B} for code and implementation
details.) It works like this: You define the word whose behavior will be
vectorable with the defining word \forthb{DOER}, as in

\begin{Code}
Doer platform
\end{Code}
Initially, the new word \forth{PLATFORM} does nothing. Then you can write
words that change what \forth{PLATFORM} does by using the word \forthb{MAKE}:

\begin{Code}
: leftwing   make platform  ." proponent " ;
: rightwing  make platform  ." opponent " ;
\end{Code}
When you invoke \forth{LEFTWING}, the phrase \forth{MAKE PLATFORM} changes
what \forth{PLATFORM} will do. Now if you type \forth{PLATFORM}, you'll see:

\begin{Code}[commandchars=\&\{\}]
leftwing &underline{ ok}
platform &underline{proponent ok}
\end{Code}
\forth{RIGHTWING} will make \forth{PLATFORM} display ``opponent.'' You can
use \forth{PLATFORM} within another definition:

\begin{Code}
: slogan   ." Our candidate is a longstanding " platform
   ." of heavy taxation for business. " ;
\end{Code}
The statement

\begin{Code}
leftwing slogan
\end{Code}
will display one campaign statement, while

\begin{Code}
rightwing slogan
\end{Code}
will display another.

The ``\forth{MAKE}'' code can be any \Forth{} code, as much or as long as
you want; just remember to conclude it with semicolon. The semicolon at
the end of \forth{LEFTWING} serves for both \forth{LEFTWING} and for the
bit of code after \forth{MAKE}. When \forth{MAKE} redirects execution of
the \forthb{DOER} word, it also \emph{stops} execution of the word in
which it appears.

When you invoke \forth{LEFTWING}, for example, \forth{MAKE} redirects
\forth{PLATFORM} and exits. Invoking \forth{LEFTWING} does not cause
``proponent'' to be printed. \Fig{fig7-7} demonstrates this point, using a
conceptualized illustration of the dictionary.

\wtexfigt{fig7-7}{\forth{DOER} and \forth{MAKE}.}

If you want to \emph{continue} execution, you can use the word
\forthb{;AND} in place of semicolon. \forthb{;AND} terminates the code
that the \forthb{DOER} word points to, and resumes execution of the
definition in which it appears, as you can see in \Fig{fig7-8}.

\wtexfigt{fig7-8}{Multiple \forth{MAKE}s in parallel using \forth{;AND}.}

Finally, you can chain the ``making'' of \forthb{DOER} words in series by
not using \forthb{;AND}. \Fig{fig7-9} explains this better than I could
write about it.%
\index{V!Vectored Execution|)}%
\index{F!Functions:!vectored execution|)}

\wtexfigt{fig7-9}{Multiple \forth{MAKE}s in series.}

\section{Using DOER/MAKE}

There are many occasions when the \forth{DOER}/\forth{MAKE} construct proves
beneficial. They are:

%!! This list has seven items and spans several pages;
%!! I have marked its end using ---End-Of-List---

\begin{enumerate}
\item To change the state of a function (when external testing of the
state is not necessary). The words \forth{LEFTWING} and \forth{RIGHTWING}
change the state of the word \forth{PLATFORM}.

\item To factor out internal phrases from similar definitions, but within
control structures such as loops.

Consider the definition of a word called \forth{DUMP}, designed to reveal the
contents of a specified region of memory.

\begin{Code}[commandchars=\&\{\}]
: dump  ( a # )
   0 DO  i 16 mod 0= IF  cr  dup i +  5 u.r  2 spaces  THEN
   dup i +  &poorbf{@ 6 u.r  2 +LOOP}  drop ;
\end{Code}
The problem arises when you write a definition called \forth{CDUMP},
designed to format the output according to bytes, not cells:

\begin{Code}[commandchars=\&\{\}]
: CDUMP  ( a # )
   0 DO  i 16 mod 0= IF  cr  dup i +  5 u.r  2 spaces  THEN
   dup i +  &poorbf{C@  4 u.r  LOOP} drop ;
\end{Code}

The code within these two definitions is identical except for the
fragments in boldface. But factoring is difficult because the fragments
occur inside the \forthb{DO }\forthb{LOOP}.

Here's a solution to this problem, using \forthb{DOER}/\forthb{MAKE}. The
code that changes has been replaced with the word \forth{.UNIT}, whose
behavior is vectored by the code in \forth{DUMP} and \forth{CDUMP}.
(Recognize that ``\forthb{1 }\forthb{+LOOP}'' has the same effect as
``\forthb{LOOP}''.)

\begin{Code}[commandchars=\&\{\}]
Doer .unit ( a -- increment)  \ display byte or cell
: <dump>  ( a # -- )
   0 DO  i 16 mod 0= IF  cr  dup i +  5 u.r  2 spaces  THEN
   dup i + &poorbf{.unit}  +LOOP  drop ;
: dump   ( a # -- )
   make .unit  @  3 cells u.r  1 cells ;and <dump> ;
: cdump ( a # -- )
   make .unit c@  4       u.r  1 chars ;and <dump> ;
\end{Code}
Notice how \forth{DUMP} and \forth{CDUMP} \emph{set-up} the vector,
then go on to \emph{execute} the shell (the word \forth{<DUMP>}).

\item To change the state of related functions by invoking a single
command. For instance:

\begin{Code}
Doer type'
Doer emit'
Doer spaces'
Doer cr'
: visible     make type'  type ;and
              make emit'  emit ;and
              make spaces'  spaces ;and
              make cr'  cr ;
: invisible   make type'  2drop ;and
              make emit'  drop ;and
              make spaces'  drop ;and
              make cr'  ;
\end{Code}
Here we've defined a vectorable set of output words, each name having
a ``prime'' mark at the end. \forth{VISIBLE} sets them to their
expected functions.  \forth{INVISIBLE} makes them no-ops, eating up
the arguments that would normally be passed to them. Say
\forth{INVISIBLE} and any words defined in terms of these four output
operators will \emph{not} produce any output.

\item To change the state for the next occurrence only, then change
the state (or reset it) again.

Suppose we're writing an adventure game. When the player first arrives
at a particular room, the game will display a detailed description. If
the player returns to the same room later, the game will show a
shorter message.

\goodbreak
We write:
\begin{Code}
Doer announce
: long make announce
   cr ." You're in a large hall with a huge throne"
   cr ." covered with a red velvet canopy."
         make announce
   cr ." You're in the throne room." ;
\end{Code}
The word \forth{ANNOUNCE} will display either message. First we say
\forth{LONG}, to initialize \forth{ANNOUNCE} to the long message. Now we
can test \forth{ANNOUNCE}, and find that it prints the long message.
Having done that, however, it continues to ``make'' \forth{ANNOUNCE}
display the short message.

If we test \forth{ANNOUNCE} a second time, it prints the short message.
And it will for ever more, until we say \forth{LONG} again.

In effect we're queuing behaviors. We can queue any number of behaviors,
letting each one set the next. The following example (though not terribly
practical) illustrates the point.

\begin{Code}
Doer where
Variable shirt
Variable pants
Variable dresser
Variable car

: order  \  specify search order
   make where  shirt   make where  pants
   make where  dresser   make where car
   make where  0 ;

: hunt  ( -- a|0 )  \  find location containing 17
   order  5 0 DO  where  dup 0=  over @  17 =  or  IF
      LEAVE  ELSE  drop  THEN  LOOP ;
\end{Code}
In this code we've created a list of variables, then defined an
\forth{ORDER} in which they are to be searched. The word \forth{HUNT}
looks through each of them, looking for the first one that contains a 17.
\forth{HUNT} returns either the address of the correct variable, or a zero
if none have the value.

It does this by simply executing \forth{WHERE} five times. Each time,
\forth{WHERE} returns a different address, as defined in \forth{ORDER},
then finally zero.

We can even define a \forthb{DOER} word that toggles its own behavior
endlessly:

\begin{Code}
Doer speech
: alternate
   BEGIN  make speech ." Hello "
   make speech ." Goodbye "
   AGAIN ;
\end{Code}
\item To implement a forward reference. A forward reference is usually
needed as a ``hook,'' that is, a word invoked in a low-level definition
but reserved for use by a component defined later in the listing.

To implement a forward reference, build the header of the word with
\forthb{DOER}, before invoking its name.

\begin{Code}
Doer still-undefined
\end{Code}
Later in the listing, use \forth{MAKE};

\begin{Code}
Make still-undefined  all that jazz ;
\end{Code}
(Remember, \forth{MAKE} can be used outside a colon definition.)

\item Recursion, direct or indirect.

Direct recursion occurs when a word invokes itself. A good example is the
recursive definition of greatest-common-denominator:

\begin{Code}
GCD of a, b =  a                     IF b = 0
               GCD of b, a mod b     IF b > 0
\end{Code}
This translates nicely into:

\begin{Code}
Doer gcd ( a b -- gcd)
make gcd  ?dup  IF  dup rot rot  mod  gcd  THEN ;
\end{Code}
Indirect recursion occurs when one word invokes a second word, while the
second word invokes the first. This can be done using the form:

\begin{Code}
Doer B
: A  ... B ... ;
make B  ... A ... ;
\end{Code}
\item Debugging. I often define:

\begin{Code}
Doer snap
\end{Code}
(short for \forth{SNAPSHOT}), then edit \forth{SNAP} into my
application at a point where I want to see what's going on. For
instance, with \forth{SNAP} invoked inside the main loop of a
keystroke interpreter, I can set it up to let me watch what's
happening to a data structure as I enter keys. And I can change what
\forth{SNAP} does without having to recompile the loop.
\end{enumerate}

%%! ---End-Of-List---

The situations in which it's preferable to use the tick-and-execute
approach are those in which you need control over the address of the
vector, such as when vectoring through an element in a decision table, or
attempting to save/restore the contents of the vector.

\section{DEFER/IS instead of DOER/MAKE}

Despite \person{Leo Brodie} has proposed \forth{DOER/MAKE} 20 years
ago, it didn't become widely used. Instead, a somewhat different
vectored execution word pair, \forthb{DEFER/IS} are popular now.

Why is this? First of all, \forth{DEFER/IS} are trivial to implement,
even if you don't know much about the underlying Forth system. They
don't rely on the return stack, but use execution tokens (what comes
out of \forth{'}) instead. Look at the portable definition:

\begin{Code}
: Defer  Create ['] noop ,  DOES>  @ execute ;
: IS ( xt "name" -- )  state @ IF
    ' >body postpone Literal postpone !
  ELSE
    ' >body !
  THEN ; immediate
\end{Code}

Being portable is only one reason --- if \forth{DOER/MAKE} were
important enough to implement, each \Forth{} would have one. The
second reason is named vectors. Let's take a look at the \forth{DUMP}
example written with \forth{DEFER/IS} instead:

\begin{Code}[commandchars=\&\{\}]
Defer .unit ( a -- increment )  \ display byte or cell
: <dump>  ( a # -- )
   0 DO  i 16 mod 0= IF  cr  dup i +  5 u.r  2 spaces  THEN
   dup i + &poorbf{.unit}  +LOOP  drop ;
: ?+ ( a -- inc ) @  3 cells u.r  1 cells ;
: c?+ ( a -- inc ) c@  4 u.r  1 chars ;
: dump   ( a # -- ) ['] ?+  IS .unit <dump> ;
: cdump ( a # -- )  ['] c?+ IS .unit <dump> ;
\end{Code}

This looks more complicated, with the explicit components --- but
remember: You have to test your program as well. So here, you can use
your simpe component (\forth{?+} or \forth{c?+}) in isolation, without
the more complicated logic of the complete application. You can do
that, because they have a name. And words that have a name can be used
as factors for other words.

\section{Summary}
In this chapter we've examined the tradeoffs between using the stack and
using variables and other data structures. Using the stack is preferable
for testing and reusability, but too many values manipulated on the stack
by a single definition hurts readability and writeability.

We also explored techniques for saving and restoring data structures,
and concluded with a study of vectored execution using
\forth{DOER}/\forth{MAKE}.%
\index{D!DOER/MAKE|)}

\begin{references}{9}
\bibitem{ham83} \person{Michael Ham}, ``Why Novices Use So Many Variables,''
   \emph{\Forth{} Dimensions}, vol. 5, no. 4, November/December 1983.
\bibitem{slater83} \person{Daniel Slater}, ``A State Space Approach to
   Robotics,'' \emph{The Journal of \Forth{} Application and Research},
   1, 1 (September 1983), 17.
\end{references}