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.

Note: step is a Listener-based form stepper. LispWorks also offers a graphical source-code Stepper tool. See the LispWorks IDE User Guide for details of that.

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

You can interact when an evaluated form returns, by setting the variable *no-step-out* to nil. 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)

To allow expansion of macros, set the variable *step-macros* to t.

To step through the function calls in compiled code, set the variable hcl:*step-compiled* to t.

If required, the stepper can print out the step level: set the variable *print-step-level* to t, as shown in this session:

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)

It is not advisable to try to step certain compiled functions, such as car and format. The variable hcl:*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 to hcl:*step-filter*.

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 variable hcl:*step-print-env* to t.

The values of the variables hcl:*step-print-...* are then used instead of the variables *print-...*.