Decision D034 · accepted
Refinements from the audit of the standard library
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-16); on 2026-11-17 the rule of loop was replaced by break, continue and done:, and one-of by enums (sections below); on 2026-11-18 a variant without fields became a value written by its name (D010 §3c, decided by the review agent on the author's delegation, to be implemented in the next migration wave); enums for closed sets implemented on 2026-11-18 in the interpreter, the compiler and the evaluator, with std's closed sets moved to enums
The audit of std (design/std-audit.md) listed what the library wants to say and the language could not say well. These are the answers.
def in a body is a local name
Inside a body (of fn, let, when, a match clause, and so on), (def name expr) binds a local name from that line to the end of the body, as define in Racket and let statements in Rust, Swift and Go. It replaces D015's "def inside a function body is an error", which existed because def there used to define a global.
(defn load-config [path]
(def text (fs.read-text path))
(when (empty? text)
(error "config is empty"))
(def data (json.parse text))
(def config (json.decode Config data))
config)
-
The name is immutable, and it never reaches the module. A second
defof the same name in the same body shadows the first from its line on (accepted, 2026-11-17, replacing "a seconddef… is an error"), as Rust'sletdoes; the expression on its right still sees the old value, so a value can be refined step by step without inventing names:(defn parse-port [text] (def text (string.trim text)) ; the trimmed text from here on (def port (string.parse-int text)) (def port (if (zero? port) 80 port)) ; refined port)Nothing changes for code that already has the earlier value: a closure made before the second
defkeeps the value it captured. Rejected: the error (it forces names liketext2,port*, which Rust's experience shows to be noise); a warning on shadowing (it would fire on the intended use). -
It is sugar: the compiler turns the rest of the body into a nested
let. The left side is a pattern, as inlet. -
letstays, for expressions. The_ (check)idiom between bindings is no longer needed.
loop: break, continue and done: (accepted, 2026-11-17)
This replaces the rule of the next section, under which any value other than recur left the loop and the result of an exhausted loop was a vector when there were several accumulators: the exits could only be found by reading every branch, and the shape of the result depended on how the loop ended.
(loop [width 0 n 0] over: [g graphemes]
done: n ; the result when graphemes run out
(when (> (+ width (w g)) limit)
(break n)) ; leaves with n; allowed anywhere in the body
(continue (+ width (w g)) (inc n))) ; the next element, with this state
(loop [line (read-line)] ; no over: repeats until break
(when (nil? line) (break))
(process line)
(continue (read-line)))
(loop rows [y 0] ; a named loop
(loop [x 0]
(when (hit? x y) (break #[x y] from: rows)) ; leaves the outer loop
(when (< x w) (continue (inc x))))
(if (< y h) (continue (inc y)) (break nil)))
(continue v …)starts the next iteration with these values of the loop's bindings, one for each, in order; a wrong count is an error at compile time. Withover:it also takes the next element.(break v)leaves the loop withv;(break)leaves withnil.breakandcontinuemay stand anywhere in the body, not only in tail position: insidewhen,let,do,match,if, at any depth. They run thedefers andwithreleases between them and the loop, as any exit does (D005). They do not cross afn: inside a nested function they are an error, "break inside a fn does not reach the loop".- A body that ends without
breakorcontinuegoes on: withover:, to the next element with the same state, which skips an element; withoutover:, to the next iteration with the same state, as Rust'sloop. done:gives the result of anover:loop whose elements ran out, evaluated with the final state in scope. Withoutdone:the result is the single binding, ornilwhen there is none; with several bindings and nodone:the loop is an error at compile time: "several bindings: say what the loop gives with done:".- A loop may have a name, a symbol before its bindings;
breakandcontinuetakefrom: nameto reach an outer loop. Withoutfrom:they reach the innermost loop. recuris removed (accepted, 2026-11-17):continuetakes its place in loops, and a function calls itself by its name. Like any removed name it is simply unknown.- A function's call to itself in tail position runs in constant stack (accepted, 2026-11-17), replacing
recurin functions:(defn count-down [n] (if (zero? n) :done (count-down (dec n))))compiles to a jump to the function's head, guarded as every call is (D026 [11]): the jump is taken only while the function's cell still holds this version, else the call goes through the cell, so a redefinition is seen at the next call as before. An anonymous function that calls itself has a name,(fn walk [node] … (walk child)). Mutual recursion keepstrampoline. The interpreter and the evaluator give the same guarantee. What is lost isrecur's check that the call really is in tail position; a self-call that is not in tail position is an ordinary call on the 64 MB stack (D026), and the compiler's warning about a self-call in tail position withoutrecurgoes away. - Tests and fuzzing are part of the change (accepted, 2026-11-17), because
breakandcontinueleave scopes that holddefers andwithresources:- one-file cases for every exit (
break,continue,break … from:an outer loop, the end ofover:, an error raised in the body, an effect handled outside the loop that does not resume) crossed with what the exit leaves (defer,withandRelease, nestedlet,match,when, a nested loop, ahandle), checking the order of cleanup and of releases, and errors inside cleanup (D005); - the differential fuzzer (self-hosting.md 7.7) generates nested and named loops with
breakandcontinueat random depths,defers and resources whose releases print, errors and effects in the body; the interpreter, the compiler and the evaluator must print the same cleanup order, and compiled runs go through ASan and the leak check; - properties: a loop over a collection gives what the same fold with
reducegives; every resource opened in an iteration is released exactly once whatever the exit.
- one-file cases for every exit (
- Compilation:
continueis a jump to the loop's head andbreaka jump to its end, through the cleanup labels of D026 [10]; constant stack, asrecurwas.
This is Rust's loop with break value, continue and labelled loops, Kotlin's and Swift's labels, and Racket's for/fold with #:result, over immutable state. Rejected: keeping loop/recur with only done: added (the exits stay implicit); Scheme's named let (the jump looks like a call, and a loop without a name has none); Common Lisp's LOOP language.
loop walks a collection with over: (replaced on 2026-11-17 by the section above)
(loop [sum 0] over: [x xs]
(recur (+ sum x)))
(loop [i 0] over: [x xs] ; leaves early with a result
(if (big? x) i (recur (inc i))))
(loop [evens #[] odds #[]] over: [x xs]
(if (even? x) (recur (conj evens x) odds) (recur evens (conj odds x))))
recur means "the next element, with these accumulators"; any other value leaves the loop with that value; when the elements run out, the result is the accumulator, or a vector of them when there are several. This is Racket's for/fold and Elixir's reduce: in the terms of loop/recur, without Common Lisp's LOOP language. for (D009) gets no further labels: an index is (for [#[i x] (enumerate xs)] …), several results per step are mapcat, the first match is find.
Structs
- The term is "struct", not "record", in documentation, diagnostics and names (
struct?), as Rust, Swift, Go and Elixir say; the form staysdeftype. - No shared fields in enums. What every variant has goes into a struct that holds the enum as its kind, as Rust's
io::Error:(deftype FsError [path kind])with(defenum FsErrorKind …). - Reflection lives in its own module,
std.reflect, not in the prelude:(reflect.variants Color),(reflect.fields Point)(with their metadata),(reflect.from-map Point m), which reports missing and unknown fields, and(reflect.to-map p). Since D010 §3c (2026-11-18, for the next migration wave)reflect.variantsgives each variant as its name denotes it, the value of a variant without fields and the type of one with fields, so(reflect.variants Color)is the vector ofColor's values.fieldsandvariantsare common local names; reflection is rare and should show at the import, as atoms do (D027); and it respects opaque types: outside its module an opaque type shows no fields (D010).typeand the predicates stay in the prelude. It is apart fromstd.meta, which is for compile time. Go'sreflectand Python'sinspectare separate modules too.
Patterns for built-in types
(Int), (Float), (String), (Keyword), (Symbol), (Bool), (Vector), (List), (Map), (Set), (Fn) are patterns, written like struct patterns; the prelude gains int?, float?, boolean?, struct?.
Literals
Integers may be written 0x200D, 0o644, 0b1010, and with _ between digits (1_000_000), as in Ferron. There are no character literals: a character is a string of one grapheme (D013), and comparing with a one-grapheme literal is made fast by the compiler.
Typed runtime errors
The runtime's own errors are variants of std.core.RuntimeError (no such field, wrong arity, not a function, no implementation of a protocol, overflow, no clause matched, and the rest), catchable by type; std has one BadArgument for argument checks. No code compares an error's text.
Closed sets are enums (accepted, 2026-11-17)
This replaces one-of (next section). A closed set of values is an enum (D010 §3), for a label's value as for a field or any other value; keywords stay for open data.
(defenum Align Left Right Center)
(defn pad [doc width align: (Align) (Align.Left)] …) ; a type pattern before the default
(pad d 10 align: (Align.Right))
(pad d 10 align: :right) ; error: pad: align: takes an Align, not :right
(deftype Caps [(depth of: Depth)]) ; a field holding a Depth
(Caps depth: (Depth.Rgb))
(Caps depth: :rgb) ; error: Caps: depth: takes a Depth, not :rgb
Changed (2026-11-18) by D010 §3c, accepted and to be implemented in the next migration wave: a variant without fields is a value written by its name, so this section's examples become
(defn pad [doc width align: (Align) Align.Left] …) ; the type pattern (Align), the default Align.Left (pad d 10 align: Align.Right) (Caps depth: Depth.Rgb)The slot
label: [pattern] default, the type pattern(Align)andof:are unchanged;of:names a struct type, an enum, a variant with fields or a kind, not a variant without fields. The cost at the call is nowalign: Align.Rightagainstalign: :right. Until the migration the tools take(Align.Right).
-
A labelled parameter's slot is
label: [pattern] default: the pattern before the default is any parameter pattern. A symbol is the local name (D030); a type pattern such as(Align)checks the value at the call, at compile time when the callee is known, else at run time; a pattern that binds no name binds the label's name, as a field label with no pattern does (D015);(Align) as: achecks and names ita. -
A field's
of: Typechecks the value at every construction, aswhere:does (D010). -
The cost is at the call:
align: (Align.Right)instead ofalign: :right. In exchange a misspelling is caught everywhere the value goes, not only at one call, and variants are written through their enum as everywhere else (D010 §3b). -
How the tools do it (2026-11-18):
- The value given or the default is checked when the function runs, and its error is a
BadArgumentat the label in the definition: "pad: align: takes an Align, not :right" for a type pattern, "f: range: #[1] does not match its pattern" for another. At compile time, a constant a call gives (a keyword, string, number,nil) to a label whose pattern is a type of the program (a record type, an enum or a variant, not a kind such asInt) is that error at the call, when the callee is known; any other value is checked when the function runs. - The patterns are checked in order once every label is bound, so the names a pattern binds are the body's, not the later defaults'; a label whose pattern binds no name is a local from the start, as one with no pattern, and a later default may use it.
label: p as: n defaultreads as a pattern with its name only whenas:stands between one form and a name followed by the default; otherwiseas:is the labelas, as before.of:is for the fields of struct types, aswhere:is for structs; a variant's field withof:is an error. It is checked before the type'swhere:, at every construction,associncluded, with the type's short name in the message.- The runtime's words stay keywords where the standard library talks to the runtime (
fs-open's mode, aGenerator's algorithm,highlight-lines' mode) and where the value comes as data from outside:term.with-color's choice andstd.repl.read's mode, whichcliand the bootstrap's REPL give as keywords.
- The value given or the default is checked when the function runs, and its error is a
-
std's closed sets (2026-11-18):
fs.OpenMode(Read Write Append Create),json.Unknown(Ignore Error),stats.QuantileMethod(Exclusive Inclusive) andstats.CorrelationMethod(Linear Ranked),random.Algorithm(Chacha8 Xoshiro),term.Align(Left Right Center, alsoterm.Column'salign,of: Align),term.Side(End Start),term.ColorChoice(Auto Always Never),term.CaptureStream(Stdout Stderr Both),line-editor.Highlight(Color Attrs Plain).
Rejected: keywords with one-of for labels and enums for fields (two mechanisms for one idea); a bare variant resolved by the label's type, as Swift's .right (.right is an accessor here, and the rule needs the callee known).
Labels with a closed set of values (replaced on 2026-11-17 by the section above, removed from the tools on 2026-11-18)
A labelled parameter may declare its values, checked at compile time when the call is visible, else at run time:
(defn pad [doc width align: (one-of :left :right :center) :left] …)
(pad d 10 align: :rihgt) ; error: did you mean :right?
Prelude vocabulary
enumerate, subvec, peek, pop, take-last, sum, min-by, max-by; sets: union, intersection, difference; bits: bit-and, bit-or, bit-xor, bit-not, shift-left, shift-right.