The debugger may be invoked through the functions
INVOKE-DEBUGGER
, BREAK
, SIGNAL
, ERROR
, CERROR
, WARN
.
The stepper is invoked through the macro STEP
.
Debugger and stepper execute subordinate read-eval-print loop (called "break loops")
which are similar to the main read-eval-print loop except for the
prompt and the set of available commands.
Commands must be typed literally, in any case,
without surrounding quotes or whitespace.
Each command has a keyword abbreviation,
indicated in the second column.
Table 25.1. Commands common to the main loop, the debugger and the stepper
command | abbreviation | operation |
---|---|---|
Help | :h | prints a list of available commands |
Table 25.2. Commands common to the debugger and the stepper
command | abbreviation | operation |
---|---|---|
Abort | :a | abort to the next most recent read-eval-print loop |
Unwind | :uw | abort to the next most recent read-eval-print loop |
Quit | :q | quit to the top read-eval-print loop |
The stack is organized into frames and other stack elements.
Usually every invocation of an interpreted function and every
evaluation of an interpreted form corresponds to one stack frame.
Special forms such as LET
, LET*
, UNWIND-PROTECT
and CATCH
produce special kinds of stack frames.
In a break loop there is a current stack frame, which is initially the most recent stack frame but can be moved using the debugger commands Up and Down.
Evaluation of forms in a break loop occurs in the lexical environment of the current stack frame and at the same time in the dynamic environment of the debugger's caller. This means that to inspect or modify a lexical variable all you have to do is to move the current stack frame to be just below the frame that corresponds to the form or the function call that binds that variable.
There is a current stack mode which defines in how much detail the stack is shown by the stack-related debugger commands.
Table 25.3. Commands common to the debugger and the stepper
command | abbreviation | operation |
---|---|---|
Error | :e | print the last error object. |
Inspect | :i | INSPECT the last error object. |
Mode-1 | :m1 | sets the current mode to 1: all the stack elements are considered. This mode works fine for debugging compiled functions. |
Mode-2 | :m2 | sets the current mode to 2: all the frames are considered. |
Mode-3 | :m3 | sets the current mode to 3: only lexical frames (frames that correspond to special forms that modify the lexical environment) are considered. |
Mode-4 | :m4 | sets the current mode to 4 (the default): only EVAL and
APPLY frames are considered. Every evaluation of a form in the
interpreter corresponds to an EVAL frame. |
Mode-5 | :m5 | sets the current mode to 5: only APPLY frames are
considered. Every invocation of an interpreted function
corresponds to one APPLY frame. |
Where | :w | shows the current stack frame. |
Up | :u | goes up one frame, i.e., to the caller if in mode-5 |
Down | :d | does down one frame, i.e., to the callee if in mode-5 |
Top | :t | goes to top frame, i.e., to the top-level form if in mode-4 |
Bottom | :b | goes to bottom (most recent) frame, i.e., most probably to the form or function that caused the debugger to be entered. |
Backtrace | :bt | lists the stack in current mode, bottom frame first, top frame last. |
Backtrace-1 | :bt1 | lists the stack in mode 1. |
Backtrace-2 | :bt2 | lists the stack in mode 2. |
Backtrace-3 | :bt3 | lists the stack in mode 3. |
Backtrace-4 | :bt4 | lists the stack in mode 4. |
Backtrace-5 | :bt5 | lists the stack in mode 5. |
Frame-limit | :fl | set the frame-limit: this many frames will be printed in a backtrace at most. |
Backtrace-l | :bl | limit of frames to print will be prompted for. |
If the current stack frame is an EVAL
or APPLY
frame, the
following commands are available as well:
Table 25.4. Commands specific to EVAL
/APPLY
command | abbreviation | operation |
---|---|---|
Break+ | :br+ | sets a breakpoint in the current frame. When the corresponding
form or function will be left, the debugger will be entered again, with
the variable EXT:*TRACE-VALUES* containing a list of its values. |
Break- | :br- | removes a breakpoint from the current frame. |
Redo | :rd | re-evaluates the corresponding form or function call. This command can be used to restart parts of a computation without aborting it entirely. |
Return | :rt | leaves the current frame. You will be prompted for the return values. |
Table 25.5. Commands specific to the debugger
command | abbreviation | operation |
---|---|---|
Continue | :c | continues evaluation of the program. |
Table 25.6. Commands specific to the stepper
command | abbreviation | operation |
---|---|---|
Step | :s | step into a form: evaluate this form in single step mode |
Next | :n | step over a form: evaluate this form at once |
Over | :o | step over this level: evaluate at once up to the next return |
Continue | :c | switch off single step mode, continue evaluation |
The stepper is usually used like this: If some form returns a
strange value or results in an error, call (
and navigate using the
commands Step and Next until you
reach the form you regard as responsible. If you are too fast (execute
Next once and get the error), there is no way back;
you have to restart the entire stepper session. If you are too slow
(stepped into a function or a form which certainly is OK), a couple of
Next commands or one Over command
will help.STEP
form
)
You can set CUSTOM:*USER-COMMANDS*
to a list of
FUNCTION
s, each returning a LIST
of bindings, i.e., either a
E.g.,
(setq CUSTOM:*USER-COMMANDS*
(list (lambda () (list (format nil "~2%User-defined commands:")))
(lambda ()
(flet ((panic () (format t "don't panic, ~D~%" (random 42))))
(list (format nil "~%panic :p hit the panic button!")
(cons "panic" #'panic)
(cons ":p" #'panic))))
(lambda ()
(let ((curses #("ouch" "yuk" "bletch")))
(flet ((swear ()
(format t "~A!~%"
(aref curses (random (length curses))))))
(list (format nil "~%swear :e curse")
(cons "swear" #'swear)
(cons ":e" #'swear)))))))
These notes document CLISP version 2.41 | Last modified: 2006-10-13 |