Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 38 ยท Getting Started

REPL Workflow and the Debugger

Work the Lisp way: redefine functions live, inspect values, read documentation with describe and apropos, and use the debugger with its restarts to recover from errors.

The biggest difference between Common Lisp and most languages is how you work. You do not edit, save, compile, run and restart. You keep one running Lisp, send small pieces of code into it, look at the results, and fix things in place. This lesson teaches that workflow and the tools around it: documentation lookup, inspection, and the debugger with its restarts.

The interactive loop

A typical cycle looks like this:

  1. Write a function in your editor.
  2. Send that one function to the running Lisp (in SLIME or SLY: C-c C-c).
  3. Call it in the REPL with test values.
  4. Spot a bug, edit the function, send it again. The new definition replaces the old one at once.
LISP
(defun discount (price)
  (* price 0.9))         ; first draft

(discount 100)           ; => 90.0

(defun discount (price)  ; redefine: callers use the new version immediately
  (* price 0.85))

(discount 100)           ; => 85.0

Since function calls go through the symbol, any code that calls discount picks up the new definition without being recompiled. This is why Lisp feels so fast to develop in. Your data (open files, loaded datasets, objects) stays alive while the code changes.

Test small units as you write them. Because redefinition is instant, you can write a function, try three inputs, and move on in under a minute.

Asking Lisp about itself

Common Lisp has built-in help functions that answer questions directly in the REPL.

LISP
(describe 'car)                   ; description of the symbol CAR
(documentation 'mapcar 'function) ; its documentation string
(apropos "STRING-UP")             ; every symbol whose name contains STRING-UP
(apropos-list "HASH-TABLE")       ; same, as a list
(type-of 42)                      ; => (INTEGER 0 4611686018427387903) in SBCL, or just INTEGER
(describe 42)                     ; facts about the number

describe prints what Lisp knows about an object: for a function, its lambda list and documentation; for a variable, its value; for an object, its class and slots. apropos is the answer to "what is the function that upper-cases a string?" You type (apropos "UPCASE") and find STRING-UPCASE.

Others you will use often: (inspect obj) opens an interactive inspector for any object, (trace fn) prints each call to fn with its arguments and result, and (time form) reports run time and memory.

LISP
(defun fact (n) (if (<= n 1) 1 (* n (fact (- n 1)))))

(trace fact)
(fact 3)
;; prints (roughly):
;;   0: (FACT 3)
;;     1: (FACT 2)
;;       2: (FACT 1)
;;       2: FACT returned 1
;;     1: FACT returned 2
;;   0: FACT returned 6
(untrace fact)

The exact trace layout depends on the implementation, but the idea is the same everywhere.

Meeting the debugger

When Lisp cannot continue, it does not just crash. It signals a condition and, if nothing handles it, enters the debugger with your program paused, not destroyed.

LISP
* (/ 1 0)

debugger invoked on a DIVISION-BY-ZERO ...:
  arithmetic error DIVISION-BY-ZERO signalled
Operation was (/ 1 0).

Type HELP for debugger help, or (SB-EXT:EXIT) to exit from SBCL.

restarts (invokable by number or by possibly-abbreviated name):
  0: [ABORT] Exit debugger, returning to top level.

(SB-KERNEL::INTEGER-/-INTEGER 1 0)
0] 

(This is the shape of real SBCL output; exact internal names vary by version.) Note the prompt 0]: you are one debugger level deep. The important section is restarts. A restart is a ready-made way to continue. You can type its number:

LISP
0] 0
; returning to the top level, prompt * again

Debugger commands

In SBCL's debugger you can type:

Command Meaning
0, 1, ... Invoke the numbered restart
:backtrace or backtrace Show the call stack
(sb-debug:arg 0) Inspect an argument of the current frame
:up, :down Move between frames
:abort Take the ABORT restart: back to the top level

(Command spelling varies by implementation. In SLIME the debugger is a buffer: press the digit for a restart, v to see source, t to toggle detail.)

Restarts: the big idea

Many languages unwind the stack when an error occurs (exceptions). Lisp can stay at the point of the error and offer choices. For a typo like (squar 3) SBCL offers restarts such as "retry the call", "return a value instead" and "use a different function". You can pick one, fix the definition in the REPL, and continue the very same computation. We study this fully in the Condition System chapter of the course; for now remember that the debugger is a tool, not a crash screen.

LISP
* (defun scale (x) (* x factor))   ; FACTOR is not defined yet
* (scale 3)
;; debugger: "The variable FACTOR is unbound."
;; restarts include:
;;   [CONTINUE] Retry using FACTOR.
;;   [USE-VALUE] Specify a value to use this time.
;;   [STORE-VALUE] Specify a value to set FACTOR to.

Choose STORE-VALUE, type 10, and the call finishes with factor set to 10. No restart of the program needed.

A stand-in for restarts

This is a JavaScript stand-in (not Lisp) showing the idea: the code that fails asks a handler for a recovery choice instead of unwinding. The failing code and the policy are separate.

JS Stand-in: restarts

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The computation scale(3, env) never stopped: the handler supplied the missing value and the code continued from where it was.

Reading a backtrace

A backtrace lists the stack of active calls, newest first:

TEXT
0: (SCALE 3)
1: (SB-INT:SIMPLE-EVAL-IN-LEXENV (SCALE 3) #<NULL-LEXENV>)
2: (EVAL (SCALE 3))

Read it from top to bottom: frame 0 is where the error happened, frame 1 called it, and so on. Frames starting with SB- are SBCL internals; ignore them and look for your own function names.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens when you send a new defun for an existing function to a running Lisp?

    Redefinition is normal in Lisp; callers see the new definition at once (inlined calls are the exception).
  2. 2. Which function lists every symbol whose name contains a given string?

    (apropos "UPCASE") shows STRING-UPCASE and its relatives.
  3. 3. What is a restart?

    Restarts are named recovery options, such as retry, use a value, or abort to the top level.
  4. 4. In SBCL, what does the prompt 0] tell you?

    After an error the prompt shows the debugger level; invoke the ABORT restart to return to *.

Summary

  • Develop interactively: define, call, redefine, call again in one living session.
  • describe, apropos, documentation, inspect, trace and time explain and measure code.
  • Errors enter the debugger instead of destroying the program; the prompt becomes 0].
  • The debugger lists restarts you can choose to continue or abort.
  • Read backtraces top-down, skipping implementation frames.

Next: S-Expressions and Evaluation