Decision D030 · accepted; details proposed
Named arguments with labels name:
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) for labels as a language mechanism, declared and checked; accepted (2026-11-17) for fields and options of forms written as labels, for keywords keeping the leading colon, and for the warning on a keyword that matches a label; implemented (2026-11-18) with a labelled parameter's slot label: [pattern] default (D034) and variants printed through their enum; proposed for the details
Decision
A call may pass arguments by name with a label, a token ending in a colon. A label is not a value: it is syntax, as Racket's #:end, Swift's terminator: and Python's end=.
(print "Name: " end: "") ; no newline, for a prompt
(print "a" "b" "c" sep: ", ") ; a, b, c
(print "oops" to: :stderr)
(term.pad doc 20 align: (term.Align.Right))
(defn print [& values end: "\n" sep: " " to: :stdout]
…)
- Labels and keywords are different tokens.
:endis a keyword, ordinary data that can be printed and stored;end:is a label and exists only in a call. So(print :end)prints:end, and a function that takes any values can still take options. Clojure's trailing keywords ((f x :end "")) cannot tell an option from data. - Checked at compile time. When the called function is known, an unknown label is a compile error with a suggestion (
print has no argument ennd:, did you mean end:?), and a label given twice is an error; otherwise the same checks happen at run time. - Replaces the ad hoc options of the standard library:
pad's:align,term.capture's:stream,cli.simulate's:envand the others become labels.
Proposed details
-
Labels may stand anywhere in a call (accepted, 2026-11-16): a label is its own kind of token, so it is never confused with a value wherever it stands; positional arguments keep their order among themselves. The order is a matter of style: after the values for functions,
(print "x" end: ""), and before the body for forms with a body:(deftest slow-sync tags: #[:slow] seed: 7 (is …)) (context "loading config" hint: "check the path" (load path)) -
usetakes labels too (accepted):(use geom.Shape as: S),(use geom.impl.bbox [Bbox] export: true),(use geom.Land [(area as: land-area)]), replacing:asand:export; one mechanism for options everywhere. -
Declaration: in the parameter vector after the positional and rest parameters, each label with its default:
[a b & rest name: default …]. A labelled parameter always has a default; a required argument is positional. A default is evaluated at the call, and may refer to the parameters before it. -
Inside the function, a labelled parameter is a local with the label's name (
end). -
Several arities share one set of labels.
-
Forwarding:
(apply f args labels)with a map from keywords to values for the labels, so a wrapper can pass options through; a map key that is not a label offis an error. -
Macros receive labels as syntax and may declare them as functions do.
-
Compilation: for a known function, labels are resolved to positional slots at compile time, with no map allocated (D026); a call through an unknown value passes the labels in a small vector.
-
Reading: a symbol followed directly by
:is a label;a.b:is not a label. Keywords keep their leading colon.
Fields and the options of forms are labels (accepted, 2026-11-17)
A label names something declared: a parameter of a function, a field of a type, an option of a form. A keyword is a value. So the names of fields in construction and in patterns, and the options of the defining forms, are labels; keywords stay for data.
(Point x: 1 y: 2) ; construction; was (Point :x 1 :y 2)
(Account owner: "alice" balance: 100)
(match shape
(Rect w: h:) (* w h) ; a label with no pattern binds the field's name
(Rect w: width h: 0) width ; a pattern after the label: renames, or matches
(Circle r:) (* 3.14 r r))
(Button style: :primary) ; the field style holds the keyword :primary
(deftype Percent [value] where: (<= 0 value 100))
(deftype Point3 [x y (z default: 0)])
(deftype File [handle path] opaque: true)
(deftype User
[(user-id :json.name "userId") ; a deriver's key: data, stays a keyword
(email default: nil doc: "contact address")]
derive: #[json.Codec Show])
- Why. In
(Button :style :size)a reader could not tell whether:sizeis the value ofstyleor the next field. D015 answered with a rule that depends on the type (a keyword that names a field starts the next field) and a workaround,(= :size), to match such a keyword. With labels there is one rule, readable without knowing the type:name:is a field or an option,:nameis a value.(Button style: size:)binds two fields;(Button style: :size)matches the keyword. Construction is a call with named arguments, as Swift'sPoint(x: 1, y: 2)and Python'sPoint(x=1, y=2), so it uses the mechanism calls already have. - Construction:
(T field: value …)in any order; a missing field without a default and an unknown field are the errors of D010 §2, named with the label (Point has no field z:). A type with exactly one field may still be built positionally,(Meters 5). Variants and effects are constructed the same way:(Shape.Circle r: 1),(perform (Log message: "x")). - Patterns:
field:followed by a pattern matches the field against it;field:followed by another label, or at the end of the pattern, binds a local with the field's name (D015's shorthand). A keyword in a pattern is always a value. The rule(= :h)for matching a keyword that is also a field name is gone. - Options of forms:
where:,derive:,opaque:,implementation:,doc:,release:and the other options ofdeftype,defenum,defeffect,defprotocol,extend-type, and a field'sdefault:anddoc:. A flag is a label withtrue. - Data stays keywords: map keys (
#{:name "ann"}), the namespaced metadata keys derivers read (:json.name), which are open data that no form declares, the data of(error "message" :port 8080), and every keyword used as a value. A map literal gets no second spelling with labels: maps are data with keys of any kind. - Since D010 §3c (accepted 2026-11-18, for the next migration wave) a variant without fields is a value written and printed by its name:
Color.Red,align: Align.Right,align: (Align) Align.Left. The(Color.Red)and(Align.Right)of this document are the spelling until that migration. - Printing follows construction: a struct prints as it is written,
(Point x: 1 y: 2), inpr-str, the REPL, test reports and diagnostics; a variant through its enum,(Shape.Circle r: 1),(Color.Red), and its typeShape.Circle(D010 §3b), so what a program prints reads back as the code that builds it, asdatadoes. The prelude's variants, written bare everywhere, print bare:(Ok value: 1),(Err failure: …). Messages name a type by its short name:Circle has no field z:. - Unchanged: access
p.xand.x(D029); map patterns and their shorthand#{port host};std.reflect.to-mapandfrom-map, which convert between fields and a map with keyword keys. - Migration: the sources (std, the compiler, tests, examples, docs) are rewritten by a tool over the lossless reader of the formatter (D031), run once and not kept. After it, the keyword spellings are errors with no hint about the old form, as for any removed syntax.
Rejected: keywords for fields (the ambiguity above, and patterns that need the type to be read); labels in map literals as Ruby's and Elixir's {name: "ann"} (two spellings of one key); keeping keywords for the options of forms while fields use labels (two mechanisms for named things).
A label's own local name (accepted, 2026-11-17)
In a parameter vector, a label may be followed by a local name and then its default, as Swift's func wait(at time: Int = 5) and Smalltalk's at: index. One form after a label is the default, and the local has the label's name; two forms are the local name and the default.
(defn wait [ms time: t (time.now)] ; label time:, local t, default (time.now)
(time.sleep-until (+ t ms))) ; std.time stays reachable as time
(defn print [& values end: "\n" sep: " "] …) ; one form: local end, default "\n"
(wait 100 time: start) ; callers see only the label
This matches patterns, where (Rect w: width) is also a label followed by a name of its own. The name is the simplest of the patterns a slot may hold: label: [pattern] default, align: (Align) (Align.Left), align: (Align) as: a (Align.Left) (D034, "Closed sets are enums"). Rejected: time: [t 5] (brackets read as a list, D008, so it would be a call); a separate option such as as: after the default (it reads as binding the default, not the parameter).
as: binds the whole value in patterns (accepted, 2026-11-17)
Since a keyword in a pattern is always a value, the whole-value binding written :as becomes the label as:, after the pattern it names, in every place patterns stand: let, parameters, clauses, vectors and maps.
(let [#[a b as: pair] (load)] …) ; pair is the whole vector
(match shape
(Circle r:) as: c (draw c r)) ; c is the whole Circle
(defn area [(Rect w: h:) as: r] …)
(let [#{port host as: config} (read-config)] …)
Inside a struct pattern's parentheses as: is not available as a field label: as is reserved there, and a type cannot have a field named as.
Passing labels on (accepted, 2026-11-18)
- A parameter that collects labels, as Python's
**kwargs:[f & args &labels opts]bindsoptsto a map from the labels' keywords to their values, for the labels the function does not declare. A function without it still rejects unknown labels. applypasses labels explicitly:(apply f args labels: opts); a map as the last argument is an argument, never labels, so(apply f xs m)is no longer ambiguous.partialandcomppass labels on:(partial pad align: (Align.Right))fixes a label; labels given to a composed function go to the function applied first.
(defn logged [f & args &labels opts]
(log f"calling {f}")
(apply f args labels: opts))
(logged pad doc 10 align: (Align.Right))
Found by the review of 2026-11 (S5).
Keywords keep the leading colon (accepted, 2026-11-17)
With fields and options written as labels, :new (a value) and new: (a name) stand side by side. The colon stays where it is: this is the pair Ruby (:new and name:) and Elixir (atoms :new, keyword lists name:) have used for years without confusion, since the side of the colon is seen at once; Smalltalk, where name: comes from, pairs it with #new. Every Lisp with keywords writes :new (Clojure, ClojureScript, Common Lisp, Emacs Lisp, Janet, Fennel, Hy, EDN), and D009 keeps Clojure's vocabulary.
Rejected spellings for keywords: #new (# opens literals, #[, #{, #set[, and #set would have to be told from a keyword), .new as Swift's enum cases (.x is an accessor, D029), 'new (a quoted symbol is code, not data; keywords exist to keep them apart, as Racket's data symbols do not), `new, @new, ^new, ~new (taken by quasiquote, deref, metadata, unquote), $new, %new, !new (free, but used by no common language).
- A warning for the one real slip (accepted): a keyword passed in a call to a function that has a label of the same name,
(print :end ""), warns "print has a label end:, did you mean end:?". It needs only the callee's declared labels, which calls already check. - Sets of keywords in inferred types (proposed): as OCaml's polymorphic variants and TypeScript's literal types, the inferred type of a parameter records the keywords a function handles, so
(= mode :fsat)against a function that knows only:fastand:slowwarns "did you mean :fast?" (D007). For a closed set the answer is an enum (D034, which replaced itsone-of); this would extend the check to keywords used as open data, with no annotation.
Why
Python, Swift, Kotlin, OCaml (~label), and Racket (#:kw) give named arguments their own syntax; those built on data (Clojure's trailing keywords and option maps) cannot be checked and cannot tell options from values. Labels make optional parameters readable at the call, checkable before running, and cheap.
Rejected alternatives
- Trailing keywords, as Clojure: ambiguous with keyword data, checked by each function by hand.
- An options map as the last argument: ambiguous with a map value, and allocates on every call.
- Racket's
#:endspelling: the same mechanism;end:reads as Swift and Python's named arguments.