." $Header: /na/franz/doc/RCS/ch14.n,v 1.1 83/01/31 07:08:43 jkf Exp $
.Lc The\ LISP\ Stepper 14
.sh 2 Simple\ Use\ Of\ Stepping 14
The LISP "stepping" package is intended to give the LISP programmer
a facility analogous to the Instruction Step mode of running a
machine language program.
The user interface is through the function (fexpr) step, which sets
switches to put the LISP interpreter in and out of "stepping" mode.
The most common \fIstep\fP invocations follow. These invocations are
usually typed at the top-level, and will take effect
immediately (i.e. the next S-expression typed in will be evaluated in stepping
\fI(step t)\fP ; Turn on stepping mode.
\fI(step nil)\fP ; Turn off stepping mode.
In stepping mode, the LISP evaluator will print out each S-exp to
be evaluated before evaluation, and the returned value after evaluation,
calling itself recursively to display the stepped evaluation of each
argument, if the S-exp is a function call. In stepping mode, the
evaluator will wait after displaying each S-exp before evaluation
for a command character from the console.
\fISTEP COMMAND SUMMARY\fP
<return> Continue stepping recursively.
c Show returned value from this level
only, and continue stepping upward.
e Only step interpreted code.
g Turn off stepping mode. (but continue
evaluation without stepping).
n <number> Step through <number> evaluations without
p Redisplay current form in full
(i.e. rebind prinlevel and prinlength to nil)
.sh 3 Selectively\ Turning\ On\ Stepping.
\fI(step foo1 foo2 ...)\fP
is typed at top level, stepping will not commence
immediately, but rather when the evaluator first encounters an S-expression
whose car is one of \fIfoo1, foo2\fP, etc. This form will then display
at the console, and the evaluator will be in stepping mode waiting
Normally the stepper intercepts calls to \fIfuncall\fP and \fIeval\fP.
When \fIfuncall\fP is intercepted, the arguments to the function
have already been evaluated but when \fIeval\fP is intercepted, the
arguments have not been evaluated. To differentiate the two cases,
when printing the form in evaluation, the stepper preceded intercepted
Calls to \fIfuncall\fP are normally caused by compiled lisp code calling
other functions, whereas calls to \fIeval\fP
usually occur when lisp code is interpreted.
To step only calls to eval use:
.sh 3 Stepping\ With\ Breakpoints.
For the moment, step is turned off inside of error breaks, but not by
the break function. Upon exiting the error, step is reenabled.
However, executing \fI(step nil)\fP inside a error loop will turn off
stepping globally, i.e. within the error loop, and after return has
.sh 2 Overhead\ of\ Stepping.
If stepping mode has been turned off by \fI(step nil)\fP,
of having the stepping packing in your LISP is identically nil.
If one stops stepping by typing "g", every call to eval
incurs a small overhead--several machine instructions, corresponding
to the compiled code for a simple cond and one function pushdown.
Running with \fI(step foo1 foo2 ...)\fP can be more expensive, since a
member of the car of the current form into the list \fI(foo1 foo2 ...)\fP
is required at each call to eval.
.sh 2 Evalhook\ and\ Funcallhook
interpreter to permit a user written function to gain control of the
These hooks are used by the Step package just described.
There are two hooks and they have been strategically placed in the
two key functions in the interpreter:
(which all interpreted code goes through)
(which all compiled code goes through if \fI(sstatus\ translink\ nil)\fP
is compatible with Maclisp, but there is no
Maclisp equivalent of the hook in
To arm the hooks two forms must be evaluated: \fI(*rset\ t)\fP and
\fI(sstatus\ evalhook\ t)\fP.
do a special check when they enter.
is given a form to evaluate, say \fI(foo\ bar)\fP,
and the symbol `evalhook' is non nil, say its value is `ehook',
will lambda bind the symbols `evalhook' and `funcallhook'
to nil and will call ehook passing \fI(foo\ bar)\fP as the argument.
It is ehook's responsibility to evaluate \fI(foo\ bar)\fP and
Typically ehook will call the function `evalhook'
to evaluate \fI(foo\ bar)\fP.
Note that `evalhook' is a symbol whose function binding is a system function
described in Chapter 4, and whose value binding, if non nil, is the
function (or a lambda expression, or a binary object) which
will gain control whenever eval is called.
`evalhook' is also the name of the
tag which must be set for
is given a function, say foo, and a set of already evaluated
arguments, say barv and bazv, and if the symbol `funcallhook'
has a non nil value, say `fhook', then
will lambda bind `evalhook' and `funcallhook' to nil
and will call fhook with arguments barv, bazv and foo.
Thus fhook must be a lexpr since it may be given any number
The function to call, foo in this case, will be the
of the arguments given to fhook.
It is fhooks responsibility to do the function call and return the
Typically fhook will call the function
This is an example of a funcallhook function which just prints
the arguments on each entry to funcall and the return value.
-> \fI(defun fhook n (let ((form (cons (arg n) (listify (1- n))))
(patom "calling ")(print form)(terpr)
(setq retval (funcallhook form 'fhook))
(patom "returns ")(print retval)(terpr)
-> \fI(*rset t) (sstatus evalhook t) (sstatus translink nil)\fP
-> \fI(setq funcallhook 'fhook)\fP
calling (print fhook) ;; now all compiled code is traced
calling (read nil Q00000)
\fI(array foo t 10)\fP ;; to test it, we see what happens when
returns (array foo t 10) ;; we make an array
calling (eval (array foo t 10))
calling (append (10) nil)
calling (apply times (10))
calling (small-segment value 10)
calling (boole 4 137 127)
... there is plenty more ...