Skip to the content
Diaspar

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:

  • abort unwinds to the previous level, running defers on the way (D005).
  • retry-form unwinds, then evaluates the whole top-level form again. Side effects before the error happen again.
  • retry-frame n unwinds to frame n and 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 v unwinds to frame n and makes that call return v, as SBCL's return-from-frame. Unlike continuing after error, this is safe for the code: the caller of a function expects a result from it. Inference warns when v does 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 own Show, 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's muted colour (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 of nils from print calls 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.