Skip to the content
Diaspar

Decision D009 · accepted

Core vocabulary follows Clojure

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)

Decision

Diaspar's core names come from Clojure. Names for concepts Clojure does not have (effects, structured concurrency) are Diaspar's own, chosen from the languages that have those concepts.

Purpose Name
Define a value def
Define a function defn
Anonymous function fn
Define a macro defmacro
Local bindings let
Loop loop, recur (since 2026-11-17: loop with break, continue, done:; no recur, D034)
Threading -> (2026-11-17: the value goes in as the first argument of each form, a pipeline of calls; ->>, which put it last, is removed: sequences are handled by for and std.iter)
Conditionals if, when, cond
Sequences first, rest, conj
Maps get, assoc
Pattern matching match (D015)
Declare an effect defeffect
Perform an effect perform
Handle effects handle, with resume
Errors error, catch, context, attempt (D005)
Cleanup defer, with
Tests and benchmarks deftest, is, defbench (D016)
Structured concurrency scope, spawn, join (D006)
New types deftype

Naming conventions

  • Names are kebab-case.
  • ? ends a predicate: empty?, string?.
  • ! ends an operation that mutates: set!, swap!. Values are immutable (D004), so ! appears only on cells and in the runtime, and stands out.

def defines values, defn defines functions

def always has one shape: (def name expr). Functions are defined with defn. Every defining form follows the same pattern, def<kind> <name> …, so the second element is always the name: def, defn, defmacro, and later deftype, defeffect.

The core has two special forms for this, def and fn. defn is a standard-library macro over them:

(defn total [item] body)
;; expands to
(def total (fn total [item] body))

(def square (fn [x] (* x x))) stays legal, since it is exactly what defn expands to; a linter may suggest defn.

One print (accepted, 2026-11-16)

Output has one function, as Swift's print(_:separator:terminator:) and Python's print: print writes its values separated by spaces and ends with a newline. Named arguments (D030) change that: end: (default "\n"), sep: (default " "), to: (default :stdout).

(print "total:" 42)                  ; total: 42⏎
(print "Name: " end: "")             ; a prompt, no newline
(print "oops" to: :stderr)

term.print has the same arguments and adds Rich markup in an f-string (D019). There is no println, eprint, or eprintln, in the core or in term; this departs from Clojure's print/println for fewer names and one default.

One for, eager, with labels (accepted, 2026-11-16)

for is a macro that walks collections and collects results, as Clojure's for and Elixir's comprehensions, but eager: it builds a vector (or what into: says) at once, with no lazy sequence. Several bindings nest; each binding is a pattern (D015); modifiers are labels (D030), not keywords, so they are never confused with data.

(for [x #[1 2 3 4] when: (odd? x)
      y #[10 20] let: [z (* x y)]]
  #[x y z])                                   ; → #[#[1 10 10] #[1 20 20] #[3 10 30] #[3 20 60]]

(for [u users] into: #set[] u.email)          ; a set
(for [#[k v] config] into: #{} #[k (str v)])  ; a map from pairs
(for [f files] (print f))                     ; for its effects: the result is not used
  • Modifiers in the bindings: when: (skip unless true), let: (bind names), while: (stop this binding's walk when false).
  • into: takes an empty collection to fill: a vector by default, #set[] for a set, #{} for a map from #[key value] pairs; any collection with conj.
  • There is no doseq: for also serves loops run for their effects, as in Elixir; one name instead of two, like print. The compiler does not build the result when it is not used. Clojure's lazy for has the trap that effects never run if the result is not read; an eager for has no such trap.
  • It expands into a loop that adds to a unique accumulator, which Perceus updates in place (D004), so there are no intermediate collections.

let and loop take flat bindings

Bindings are a flat sequence of name–value pairs, as in Clojure. The convention from D008 puts them in []. The brackets are interchangeable, so (let (a 1 b 2) …) reads the same.

The collection comes first (accepted, 2026-11-18)

Sequence functions take the collection as their first argument: (map xs inc), (filter xs even?), (take xs 3), (reduce xs + 0), (sort-by xs .name), (group-by xs .kind), as Elixir's Enum, Gleam's list, Rust's methods and Diaspar's own iter (D036). So a pipeline is one form, (-> xs (filter even?) (map inc) (take 10)), -> stays the only threading macro, and labels follow the positional arguments as everywhere (D030). This departs from Clojure's order (the collection last, for ->>), which this decision otherwise follows; the sources are migrated by a tool, and the old order is simply an error of types at the call (a function where a collection is expected, with a hint). Found by the review of 2026-11 (S3).

Ordering, contains? and get (accepted, 2026-11-18)

  • compare and sort order every value within its kind: false before true, numbers by value (integers and floats together, NaN raises), strings by code points, keywords and symbols by name, vectors and lists lexicographically, structs of one type by their fields in declaration order. Values of different kinds do not compare: that is an error naming both kinds. Before, compare refused booleans ("does not mix booleans and booleans") while the runtime's own order of map keys sorted everything (review S6).
  • contains? asks for an element of a vector, list, range or set, for a grapheme of a string (a substring is string.includes?), and for a key of a map. Clojure's contains?, which asks a vector for an index, is a known trap; an index is checked with (< i (count v)) (review S4).
  • get on a value that cannot have keys (a number, a boolean, a function) raises BadArgument; (get nil :x) is still nil (D013 §6: nil is empty) (review S8).

Example

(defn total [item]
  (let [p (get item :price)
        q (get item :qty)]
    (* p q)))

(defn sum-to [n]
  (loop [acc 0 i 0]
    (if (> i n)
      acc
      (recur (+ acc i) (inc i)))))

(defn greet
  "Greets someone by name."
  ([] (greet "world"))
  ([name] (str "hello " name)))

Why

  • Agents know Clojure best. It is the most widely used modern Lisp, and much of Diaspar's code will be written with coding agents. Familiar names mean fewer mistakes.
  • The names explain themselves. first instead of car, fn instead of lambda.
  • It is a vocabulary for immutable data. That matches Diaspar's value semantics, unlike Common Lisp's vocabulary for mutable lists.
  • Flat bindings are shorter, and agents write them by habit.
  • One shape per defining form. People, agents, grep, the LSP, and documentation tools all read def<kind> <name> the same way. Function-only features (docstrings, several arities, metadata) have a natural place in defn.
  • A smaller core. Only def and fn are special forms, so the interpreter and the compiler (D003) implement definitions once. The redefinition cell, direct calls in release builds, and the function name in stack traces all come from def with an fn inside, and defn gets them for free. Macros that walk definitions see one form, not two.
  • perform and handle are the words OCaml 5 and Koka use for effects. Effekt's try was avoided because it suggests exceptions.

Rejected alternatives

  • Common Lisp names (defun, car/cdr, setf, the -p suffix): a legacy of the 1960s–80s that does not explain itself.
  • Scheme and Racket names (define, lambda, define-syntax, hash-ref): longer. Diaspar takes its brackets from Racket (D008), not its names.
  • def also defining functions, as Racket's (define (f x) …): saves one word but breaks "the second element is the name". With interchangeable brackets (D008), (def [f x] …) would also define a function and is easy to confuse with bindings. Racket's curried form (define ((f a) b) …) adds more parsing cases.
  • Racket-style paired bindings ((let ([a 1] [b 2]) …)): the structure is more visible, but the form is longer and less familiar to agents.

Open questions

  • Names for the rest of the standard library, decided when each module is designed.