4 The COMMON-LISP Package

step

Macro

Summary

Steps through the evaluation of a form.

Package

common-lisp

Signature

step form => result

Arguments

form: A form to be stepped and evaluated.

Values

result: The values returned by form.

Description

step evaluates a form and allows you to single-step through it. You can include a call to step inside a tricky definition to invoke the stepper every time the definition is used.step can also optionally step through macros.

The commands shown below are available. When certain stepper variables (as described below) are set, some of these commands are not relevant and are therefore not available. Use:help to get a list of the commands.

:s n: Step this form and all of its subforms (optional positive integer argument).
:st: Step this form without stepping its subforms.
:su: Step up out of this form without stepping its subforms.
:sr: Return a value to use for this form.
:sq: Quit from the current stepper level.
:redo: Redo one of the previous commands.
:get: Get an item from the history list and put it in a variable.
:help: List available commands.
:use: Replace one form with another form in previous command and redo it.
:his: List the commands history.

The optional integer argument n for:s means do:s n times.

Examples

The following examples illustrate some of these commands.

USER 12 > (step (+ 1 (* 2 3) 4))
(+ 1 (* 2 3) 4) -> :s
   1 -> :s
   1
   (* 2 3) -> :su
   6
   4 -> :s
   4
11
11

USER 13 > (defun foo (x y) (+ x y))
FOO

USER 14 > step (foo (+ 1 1) 2)
(FOO (+ 1 1) 2) -> :st
   (+ 1 1) -> :s
     1 -> :s 
     1
      1 -> :s 
     1
   2
   2 -> :s
   2
4
4

USER 15 > :redo (STEP (FOO # 2))
 (FOO (+ 1 1) 2) -> :s
    (+ 1 1) -> :s
       1 -> :s
       1
    2
    2 -> :s
    2
    (+ X Y) -> :s
       X -> :s
       2
       Y -> :s
       2
    4
 4
 4

Interaction
: You can interact when an evaluated form returns, by setting the variable*no-step-out* tonil. The prompt changes as shown below:

USER 36 > step (cons 1 2)
(CONS 1 2) -> :s
   1 -> :s
   1 = 1  <- :sr 3
   2 -> :s
   2 = 2  <- :sr 4
(CONS 1 2) = (3 . 4)  <- :s
(3 . 4)

Macro expansion
: To allow expansion of macros, set the variable*step-macros* tot.
Stepping compiled code
: To step through the function calls in compiled code, set the variablehcl:*step-compiled* tot.
Showing the stepper level
: If required, the stepper can print out the step level: set the variable*print-step-level* tot.

USER 21 > (setq *print-step-level* t) 
T
USER 22 > step (cons 1 2) 
[1](cons 1 2) -> :s 
[2]   1 -> :s       1 
[2]   2 -> :s 
      2 
   (1 . 2) 
(1 . 2)

Non-steppable functions
: It is not advisable to try and step certain compiled functions, such ascar andformat. The variablehcl:*step-filter* contains a list of functions which should not be stepped. If you get deep stack overflows inside the stepper, you may need to add a function name tohcl:*step-filter*.
Printing
: By default, the stepper uses the same printing environment as the rest of LispWorks (the same settings of the*print-...* variables). To control the stepper printing environment independently, set the variablehcl:*step-print-env* tot.
: The values of the variableshcl:*step-print-...* are then used instead of the variables*print-...*.