Decision D017 · accepted
The REPL debugger: an error freezes the computation, the user fixes it and goes on
A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.
Status: accepted (2026-11-15). Built after stage-1 effects (D005).
Decision
In the REPL, an unhandled error does not end the computation. The REPL's top-level handler for Fail is a kind-2 handler (D005): it runs a nested REPL on top of the failed computation's stack, as Common Lisp's debugger does. The failed computation stays frozen below while the user inspects it, redefines functions (D003), and chooses how to go on. Nothing has unwound yet: no defer has run and no work is lost.
A session
user=> (import "data.csv")
error: cannot parse number "x"
--> csv.dias:30:5
= while: parsing line 500 of data.csv
frames:
0: csv.parse-number "x" csv.dias:30:5
1: csv.parse-entry "1,2,x" csv.dias:12:7
2: csv.parse-file #[…1000] csv.dias:18:3
3: csv.import "data.csv" csv.dias:22:3
restarts:
0: abort return to user=>; cleanup runs
1: retry-form run (import "data.csv") again from the start
2: retry-frame call a frame's function again with the same arguments
3: skip-entry replace the line with nil and continue (offered by csv.parse-entry)
[1] user=> (frame 1)
csv.parse-entry line = "1,2,x"
[1] user=> (in-frame 1 (split line ","))
#["1" "2" "x"]
[1] user=> (defn parse-number [s] (or (parse-int s) 0))
csv.parse-number ; redefined
[1] user=> (restart :retry-frame 0)
#[…1000 entries…]
user=>
retry-frame 0 called parse-number again with "x", now through the new definition; it returned 0, and the frozen import went on to the end.
Commands (accepted)
Ordinary functions and macros available at a debugger level [n]:
| Command | Does |
|---|---|
(frames) |
list the frames again |
(frame n) |
show frame n: its function, arguments, locals, position |
(in-frame n expr) |
evaluate expr with frame n's locals in scope |
(restart name args…) |
choose a restart by name (or by number) |
(abort) |
the abort restart: back one level |
Anything else typed at [n] user=> is ordinary REPL input: definitions, calls, tests (D016).
Restarts
Always available:
abortunwinds to the previous level, runningdefers on the way (D005).retry-formunwinds, then evaluates the whole top-level form again. Side effects before the error happen again.retry-frame nunwinds to framenand calls its function again with the same arguments, through the global cell, so a redefinition is used. Side effects inside that frame before the error happen again. SBCL offers the same.return-from-frame n vunwinds to framenand makes that call returnv, as SBCL'sreturn-from-frame. Unlike continuing aftererror, this is safe for the code: the caller of a function expects a result from it. Inference warns whenvdoes not fit what the caller expects (D007).- A restart that would repeat side effects is marked in the list, using the inferred effects of the frames it reruns (D005):
retry-form run (import "data.csv") again (repeats file and network effects).
Offered by code with restartable (sketch):
(defn parse-entry [line]
(restartable (parse-line line)
(skip-entry [] nil)
(use-value [v] v))) ; a restart may take arguments: (restart :use-value 42)
Inside, restartable handles an internal effect that the debugger performs; choosing a restart unwinds to that restartable and runs its branch (kind 1). Outside the REPL, a program chooses the same restarts with ordinary handlers.
Not offered (accepted): continuing an error call with a value of the user's choice. Code after error does not expect error to return; only code that offers use-value agrees to that.
Other unhandled effects (accepted) are questions, not errors, so the debugger offers to answer them: an unhandled (Log "…") gets an answer restart that resumes perform with a typed value.
Levels (accepted)
An error inside the debugger opens level [2] on top of [1]; abort goes back one level, (top) to user=>. While a level is open, the frozen computation still holds what it acquired: a lock taken before the error stays taken until the user aborts or continues.
Printing results
Status: accepted (2026-11-18), at the author's request.
The REPL prints a result within limits, so a large or deep value does not fill thousands of lines. IEx's inspect has limits (limit: 50 items, printable_limit: 4096 characters), and Clojure has *print-length* and *print-level*:
user=> (for [i (range 100000)] (print "10"))
10
10
… ; the 100,000 lines print does write
#[nil nil nil nil nil … 99,900 more] ; 100 nils, then the marker (shortened here)
user=> (reduce (fn [a _] #[a]) 1 (range 20))
#[#[#[#[#[#[#[#[#[#[#[…]]]]]]]]]]]
user=> (apply str (repeat 13345 "x"))
"xxxxxxxx…"… (12,345 more characters) ; the first 1,000 characters (shortened here)
- A collection (vector, list, set, map) shows its first 100 items, then
… N more. A map counts entries. Records show their fields. - Nesting deeper than 10 levels shows as
#[…]. - A string shows its first 1,000 characters, then
… (N more characters)after the closing quote. A value with its ownShow, or one that prints as#<…>, is cut the same way. - The whole result fits in about twice the terminal's height (the rows when the input was read; 24 rows and 80 columns in a pipe). Past that, every collection still open is closed with its own
… N more, so the text stays well formed. A last line says the result was cut and how to see it all:… cut to about 48 lines: (repl.show *1) prints all of it. - The markers (
… N more,…, the last line) are in the theme'smutedcolour (D019). The words say the same thing without colour. - Why these numbers. Measured on an 80 × 24 terminal: 100
nils take 5 rows, 100 small integers 4 rows, and 100 short keyword–number map entries about 18 rows (7 rows at 200 columns). Typical nested data is less than 10 levels deep. A 1,000-character string takes 13 rows at 80 columns. Twice the height keeps the prompt and the start of the result within one scroll back. - Output and result together. What the evaluation printed (
print) is not limited; it is the program's output. A result that is a large collection ofnils fromprintcalls needs no special case: the limits are enough.
Seeing everything. *1, *2 and *3 are the last three values, as in Clojure (IEx's v(1)). Each form's value moves them along. Definitions and errors do not. (repl.show *1) prints a value in full. Its labels set limits: (repl.show *1 limit: 1000 depth: 3 text: 200). repl is the session's name for std.repl.show: a session starts with (use std.repl.show as: repl).
Only the REPL cuts. pr-str, str and print never truncate: programs and data writing need the whole text. The limits are labels of std.repl.show's functions (parts, format, show): limit:, depth:, text: and total:. Each defaults to unlimited, and with none of them show.format is pr-str.
Outside the REPL
A program that is not run in the REPL must never stop and wait for a person by default: scripts, CI, and servers would hang.
| How it runs | On an unhandled error |
|---|---|
diaspar run, compiled programs |
print the diagnostic (D014) and exit with status 1 |
diaspar run --debug |
open the debugger in the terminal |
diaspar test |
report a failed test and go on with the others |
diaspar test --debug |
open the debugger at the first failure, inside the failing test |
| piped REPL input | print the error and continue, so output stays comparable in tests (D013) |
diaspar run --repl (later) |
the program serves the REPL protocol; a connected editor gets the debugger, so a running server or game is fixed without restarting it (D018) |
For editors and agents
Frames, locals, and restarts are data, sent through the REPL protocol in a machine-readable form (D014), as SLIME's debugger and CIDER's are. An editor shows them as a panel; a coding agent driving the REPL reads them and picks a restart instead of parsing text.
What it costs
Nothing until an error happens: the top-level handler is found only when Fail is performed. Frames show their function and position always; arguments and locals are available for code run by the interpreter (all REPL input, D003) and in debug builds of compiled code.
Later
- Errors in tasks (D006): open the debugger for the failing task before its failure reaches
scope, while other tasks go on. - Post-mortem: save the failure report with frames and locals to a file and open it in a debugger later.
Why
- Fixing a running program without losing its state is the Lisp feature mainstream languages still lack, and it is the point of a live environment.
- It needs no new mechanism: a kind-2 handler, restarts as effects, and global cells, all of which exist in stage 1.