DUST

DUST uses RON string syntax: bare strings, double-quoted strings, and fences of two or more double quotes. All produce strings, not quotation forms. The examples below show the RON data produced by parsing DUST source.

In value position, a bare token matching a number, null, true, or false denotes that value. Quote it to make a string. Other bare tokens denote strings, except where DUST reserves a prefix for expression syntax.

A leading # introduces a tagged element. In value position, a leading . introduces a local reference, a leading : a constant reference, and a leading / a JSON Pointer. Leading `, ~, ,, and ,@ introduce quotation forms. A leading \ mutes the next complete form. Quote these characters when they are meant to begin a string. Apostrophes and printable Unicode characters, including emoji, are ordinary string characters:

[hello ".-#1" don't true false null
 42 -1.5 "true" "false" "null" "42"
 "-1.5" nil "#name" "^name" .name
 🙂 "" {true false}]

hello
".-#1"
don't
true
false
null
42
-1.5
"true"
"false"
"null"
"42"
"-1.5"
nil
"#name"
^name
.name
🙂
""
<!true>

[hello .-#1 don't true false
 null 42 -1.5 "true" "false"
 "null" "42" "-1.5" nil "#name"
 ^name #local name 🙂 "" <!true>]

A square bracket alone on its opening line starts a line-oriented list. A bare string item occupies one line and may contain spaces; numeric and other scalar literals keep their types. If the first item follows [ on the opening line, whitespace separates items on every line; quote strings containing spaces in that packed form:

[
  Ada Lovelace
  Grace Hopper
]

"Ada Lovelace"
"Grace Hopper"

[
  Ada Lovelace
  Grace Hopper]

Ordinary double-quoted strings use JSON escapes. Fenced strings allow double quotes inside without escaping them, but backslashes and control characters still use escapes. Unicode escapes decode to their characters:

["say \"hello\"" ""C:\\tmp\\notes.txt"" "\u03b5" "\u0000"]

""say "hello"""
C:\tmp\notes.txt
ε
"\u0000"

[
  say "hello"
  C:\tmp\notes.txt
  ε
  "\u0000"]

A fence of three or more quotes followed only by whitespace and a newline starts a multiline string. The newline after the opening fence and the newline before the closing fence are not part of the string. An extra blank line before the closing fence preserves a trailing newline. A single-line fence and a multiline fence can therefore contain the same string:

[
  ""hello world""
  """
    hello world
  """
  """
    first line
    second line
  """
]

"hello world"
"hello world"
"""
  first line
  second line
"""

[
  hello world
  hello world
  """
    first line
    second line
  """
]

A quoted ., :, or / is a string; an unquoted one starts a reference or pointer. A caret has no special meaning:

["^name" "^x" .name :name "^" .name]

^name
^x
.name
:name
^
.name

[^name ^x #local name #const name ^ #local name]

Outside map-key position, a token beginning with . or : denotes a reference. Outside map-key and direct-callee positions, a token that starts with / is a pointer. Put quotes around the token to make it a string. Binding forms introduce names as strings, conventionally written bare. A direct callee is a name encoded as a string in the first element of #invoke, without a #local or #const wrapper. In this position, surrounding quote characters belong to the name. A computed callee is an expression in the first element of #invoke, including a reference such as (.f 1) or (:strings/case upper hi). Elsewhere, bare names and quoted strings denote text.

Whitespace and layout follow RON, except for DUST's form separation rules.

A DUST file holds one or more forms. A file containing exactly one form is that form. Two or more forms, separated by whitespace including newlines, make an implied root list; its outer square brackets may be written or omitted. A root string containing spaces must be quoted. Unlike RON, whose default document is an implied outer object, DUST has no implied root map: a root map is written with braces.

Canonical DUST omits the root list's brackets when the list has two or more forms and its first non-comment form is not a literal list:

(+ 1 2)
(* 3 4)

Root forms are separated by whitespace, not lines, so a root string containing spaces is quoted, as in "two words".

Explicit outer brackets around these forms are also accepted and produce the same list, but are not canonical.

(+ 1 2)
(* 3 4)

[#invoke [+ 1 2] #invoke [* 3 4]]

3
12

Otherwise the brackets are kept, so a one-element list [x] stays distinct from the form x, and [[1 2]] stays distinct from [1 2]. Once an earlier form establishes an implied root list, later literal lists need only their own brackets.

[[1 2]]

[[1 2]]

[[1 2]]

1
[2 3]

[1 [2 3]]

1
[2 3]

A file is evaluated one top-level form at a time, from first to last, so a form can use the top-level locals that earlier forms define. Its value is the list of the forms' values: (+ 1 2) (* 3 4) evaluates to [3 12], and a file with one form evaluates to that form's value. An empty file is an empty list. Read for evaluation, as by the Epsilon REPL, a written list is always one form, so [1 2] followed by [3] is two forms, and each form can have a depth of 256.

DUST comments start with ; at the start of a line or after whitespace and continue to the end of that line. A semicolon inside a quoted string or inside an unbroken token is text. RON uses the same comment syntax. A document must not mix ; comments with an explicit $comment member.

A comment belongs to the value occurrence it describes. A comment immediately before an item belongs to that item. A blank line between the comment and item attaches the comment to the enclosing collection. A comment after a value on the same line belongs to the end of that occurrence.

For example, this file evaluates to 3:

; Root documentation
(+ 1 2)

In explicit comment round-trip mode, its JSON representation is:

[
  {"$comment": "{\"root\":\"scalar\",\"start\":{\"\":[\"Root documentation\"]}}"},
  {"#invoke": ["+", 1, 2]}
]

The marker preserves the comment and is not an element of the value. Collection opening and closing comments are distinct from comments on the collection occurrence. epsilon convert --comment-roundtrip preserves these placements when converting through JSON.

In expression positions, unquoted (), [], and {} delimit forms and end bare strings, reference names, and direct-callee names. In packed lists and invocations, these delimiters separate forms without whitespace.

[[foo(bar)]
 (foo(bar))
 [foo[bar]{}(bar)baz]
 [[.foo(bar)][(bar):foo]]]

[[foo (bar)] (foo (bar)) [foo [bar] {} (bar) baz] [[.foo (bar)] [(bar) :foo]]]

[[foo #invoke [bar]]
 #invoke [foo #invoke [bar]]
 [foo
  [bar]
  {}
  #invoke [bar]
  baz]
 [[#local foo #invoke [bar]] [#invoke [bar] #const foo]]]

Each line-oriented list item or map member value contains one form. Bare line strings can contain spaces, but end at expression delimiters. foo(bar) contains two forms. It may supply consecutive root forms, but is invalid as one line-oriented list item or map member value. "foo(bar)" is one string.

Map keys use RON's token rules, including embedded brackets and parentheses, and require whitespace before their values. Angle brackets delimit tag groups only in map-member position.

[{items[0] 1 foo(bar) 2 .name 3}]

[{.name 3 foo(bar) 2 items[0] 1}]

[{.name 3
  foo(bar) 2
  items[0] 1}]

A key that begins with ) is quoted, since a line that begins with ) closes a form:

{"(a" b ")" 1 ")x" 2 "x)" 3 "(" 4 k ["a <b" "c" "a<b"]}

{( 4
 (a b
 ")" 1
 ")x" 2
 k [
   "a <b"
   c
   a<b]
 x) 3}

( 4
(a b
) 1
)x 2
k [
  "a <b"
  c
  a<b]
x) 3

Forms can nest to a maximum depth of 256. The parser and the evaluator count depth with the same rules:

• Each list, map, invocation, tag, quotation prefix, and mute prefix adds one level. A scalar adds no level, so [[1]] has a depth of 2.
• An invocation is one level, because its list is a part of the invocation.
• A list that is the payload of a tag or of a prefix is a part of it and adds no level. Thus (f x), #invoke [f x], {#invoke [f x]}, and `[x] each have a depth of 1.
• A form in a string template or in a JSON pointer is below the template or the pointer.
• A root list adds one level, written or implied. Thus each form of a file with two or more forms can have a depth of 255. A file with one form has no root list, and that form can have a depth of 256.

The parser rejects a form that is deeper than 256 levels. This is a resource limit, not a syntax error. The result is #err <limit resource>, with a message that gives the depth limit:

#err {<limit resource>
      column 257
      line 1
      message "DUST parse: nesting exceeds the depth limit of 256"}

Other parser errors produce #err <invalid value>. RON documents have the same depth limit and count levels with the same rules.

An implementation can have internal limits that are lower than the limits of the language. These limits are high-water marks of the implementation, not of the language. A valid program can be outside an internal limit. For example, a valid program can have expressions that nest too deeply for the implementation, or a function that has too many names. An implementation can find a limit before evaluation starts or during evaluation. For example, calls that nest too deeply during evaluation are outside the recursion limit. The result of such a program is #err <limit internal KIND>, where KIND names the limit. The message starts with "program exceeds an internal limit:" and names the limit.

A different implementation, or a later version, can accept the same program. Thus a result outside an internal limit is not a part of the language contract.

[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[1]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]

[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[
                                                                                                                                                                                                                                                                 1]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]

#err {<internal limit nesting>
      message "program exceeds an internal limit: expressions nest too deeply"}

(let [count-up (fn count-up [n] (+ 1 (count-up (+ .n 1))))] (count-up 0))

#err {<internal limit recursion>
      message "program exceeds an internal limit: calls nest too deeply"}

Outside map-key position, . followed by a nonempty name produces a #local tagged element, and : followed by a nonempty name produces a #const tagged element. The two are the same in the first position of an invocation, where they make a computed callee. Names follow RON's packed bare-token rules and DUST's form separation rules above. Numeric, boolean, and null spellings are names after the prefix, so .5 is #local "5", not a number. An empty name, or a name that begins with a quote, ., or :, is invalid: ., :, ..., ::x, and ."x" are syntax errors. Quote such text to write a string. A . or : after the first character of a bare string is text, as in a.b or a:b.

{var .name
 const :name
 punctuation (fn? :+)
 qualified-var .user/name
 qualified-const :math/pi
 colon .a:b
 dot :a.b
 literal-names [.42 .-1 .1.5 .true .false .null]
 caret-name .^+
 nested [.x {value :y}]}

{caret-name .^+
 colon .a:b
 const :name
 dot :a.b
 literal-names [.42 .-1 .1.5 .true .false .null]
 nested [.x {value :y}]
 punctuation (fn? :+)
 qualified-const :math/pi
 qualified-var .user/name
 var .name}

caret-name #local ^+
colon #local a:b
const #const name
dot #const a.b
literal-names [#local "42" #local "-1" #local "1.5" #local "true" #local "false" #local "null"]
nested [#local x
        {value #const y}]
punctuation #invoke [fn? #const +]
qualified-const #const math/pi
qualified-var #local user/name
var #local name

#err <name unbound>

(let [name Ada] .name)

#invoke [let [name Ada] #local name]

Ada

:name

#const name

#cases [{bindings {name Ada} output Ada}]

(let [add :+]
  [(add 0 0)
   (add 1 2)
   (add -4 10)])

(let [add :+] [(add 0 0) (add 1 2) (add -4 10)])

#invoke [let [add #const +] [#invoke [add 0 0] #invoke [add 1 2] #invoke [add -4 10]]]

0
3
6

:42

#const "42"

#cases [{bindings {42 42} output 42}]

:true

#const "true"

#cases [{bindings {true enabled} output enabled}]

:null

#const "null"

#cases [{bindings {null missing} output missing}]

Parsing constructs the reference without looking up its name. Binding and parameter names in DUST are ordinary strings, conventionally written bare, rather than references. Parsing does not interpret binding positions.

A string template is a quoted or fenced string prefixed with ~, the quasiquote prefix. Inside it, , followed by a form embeds that form, as unquote does in a quasiquoted list. A string without ~ is always literal, so ",.name" and "{{x}}" are plain text.

(let [name Ada] ~"Hello ,.name")                    ; => "Hello Ada"
(let [subtotal 10 tax 2] ~"Total: ,(+ .subtotal .tax)") ; => "Total: 12"
~"Pi is ,:math/pi"                                  ; => "Pi is 3.141592653589793"
(let [name Ada]
  ~"""
    Hello ,.name
    Sum ,(+ 1 2)
    """)                                            ; => "Hello Ada\nSum 3"

An embedded form in parentheses, brackets, braces, or quotes ends at its closing delimiter. Any other form, such as a reference, reads a full name and ends at whitespace, a comma, a quote, or a bracket. A comma that ends it is consumed, so a reference can be followed directly by text:

(let [name Ada] ~"Hi ,.name there")     ; => "Hi Ada there"
(let [name Ada] ~"Hi ,.name,!")         ; => "Hi Ada!"
(let [foo! bang] ~"Hi ,.foo!")          ; => "Hi bang"
(let [name Ada] ~"Hi ,.name,, there")   ; => "Hi Ada, there"

A comma followed by whitespace or the closing quote is text, and ,, writes a literal comma anywhere:

~"a, b"      ; => "a, b"
~"x,,y"      ; => "x,y"

Embedded forms may contain quotes, as in ~"a ,(str "x") b". A quoted string cannot be embedded directly in a one-line template, because ," before the closing quote is literal text and a quote otherwise ends the template; write ,(str "x") or use a fenced ~""" template. Only a string written directly after ~ is a template; a string nested inside a quasiquoted list stays literal, so ~[a ,.x "b ,.x"] keeps "b ,.x".

The resulting template value keeps the literal pieces and evaluated values separate, so template functions can inspect them or escape each value. A printed or exported template value is its rendered string, the same text str produces. Printing loses the parts: reading the printed result back gives an ordinary string, not a template. A quoted template is a form rather than an evaluated value, so it prints as a template literal.

In RON, the #template tagged representation contains a list of literal strings and a list of forms. The first list has one more item than the second. For example, this DUST template:

~"hello-,.name"

has this RON representation:

#template [[hello- ""] [#local name]]

DUST formatting writes the template literal when the tagged representation can be expressed without changing its data. It always writes a one-line ~"…" literal, escaping line breaks as \n, so a multiline ~""" template is reformatted on one line. A template that embeds a string value that is not a bare token keeps the explicit #template notation.

See string templates for construction, inspection, and rendering.

RFC 6901 defines JSON Pointer as a string syntax for identifying a value within a JSON document. Its reference tokens are separated by /; within a token, ~1 represents / and ~0 represents ~. The empty string refers to the root, while / refers to a member with an empty name.

DUST uses that syntax for pointer text and adds pointer values and embedded forms. A pointer value can be used with DUST maps and lists. DUST distinguishes integer index segments from string key segments; numeric strings with valid index spelling become indices. Embedded forms and DUST's backslash escapes below are DUST extensions, not RFC 6901 pointer text.

(get {a/b 1} /a~1b) ; 1
(get {items [zero one]} /items/1) ; one
(get {"" 7} /) ; 7

A slash-prefixed value constructs a pointer. Pass it to a collection path function to read or update data. In callee position, / is division; a map literal key beginning with / is a string.

(get {a 1} /a) ; 1
(/ 10 2)       ; 5.0
(get {/a 1} "/a") ; 1

A pointer has slash-separated segments:

(get {"" 7} /)                 ; 7
(get {"" {a 1}} //a)           ; 1
(get {a {"" 2}} /a/)           ; 2
(get {a 1} (jsonptr ""))       ; {a 1}

/ selects an empty key; it does not select the root. Use (jsonptr "") for the root pointer.

Segments can contain embedded forms. As in a string template, , followed by a form embeds it, and a comma that ends a token form is consumed. A pointer needs no ~: a bare pointer cannot otherwise contain a comma.

(let [key a] (get {a 1} /,.key))                   ; 1
(let [id 2] (get {user-3 ok} /user-,(+ 1 .id)))    ; ok
(let [id 7] /users/,.id,/name)                     ; /users/7/name

Names can contain /, so /users/,.id/name reads the reference .id/name; the closing comma in /users/,.id,/name ends .id before the next segment. An embedded segment value must be a string or a nonnegative integer.

The RFC escapes ~1 and ~0 select keys containing / and ~:

(get {a/b 1} /a~1b) ; 1
(get {m~n 2} /m~0n) ; 2

DUST also accepts \{, \}, and \\ for literal braces and backslashes, and ,, for a literal comma. Other tilde or backslash escapes are syntax errors. Parentheses, caret, opening braces, and double quote are literal pointer text; an unmatched closing parenthesis ends the pointer token. Whitespace, square brackets, a closing brace, or a comma followed by whitespace or a closer also ends the token.

RON represents a literal pointer as #jsonptr with a string payload. A pointer containing embeds has a list payload. For example, these DUST pointers:

/a/0
/3/,"3"
/foo/user-,(+ 1 .id)/,.k,/0

have these RON representations:

[#jsonptr /a/0 #jsonptr /3/3 #jsonptr [foo [user- #invoke [+ 1 #local id]] #local k 0]]

Formatting the third pointer as DUST writes its embedded forms in the pointer literal rather than the #jsonptr representation.

In the second example, both segments are indices. Map lookup converts an index to its decimal string key. Quotation, mute, and unevaluated parts of quasiquotation preserve tagged data; unquote follows the usual quasiquote rules.

(jsonptr? /)
(str /)
(str //a)
(str /a/)
(str /a~1b/x~0y)
(str /f(x))
(let [k name] (str /users/,.k))
(let [n 10] (str /user-,(+ .n 1)))
(let [k "a/b"] (str /,.k))
(let [k "x~y"] (str /,.k))
(let [p /3/,"3"] (get [null null null {3 found}] .p))
(let [p /3/,(int "3")] (get [null null null [a b c found]] .p))
/,null
/,true
(count /a/b/0)
(first /a/b/0)
(str (rest /a/b/0))
(= /a/0 (jsonptr "/a/0"))
(let [x 3] (str /foo/,.x))
(get [a b c d] /,"3")
(get [a b c d] /,"\u0033")
(let [n "3"] (get [a b c d] /,.n))
(let [n "3"] (get {3 yes} /,.n))
(let [n "03"] (get {03 yes} /,.n))
(let [n "3"] (= /,.n /3))

(jsonptr? /)
(str /)
(str //a)
(str /a/)
(str /a~1b/x~0y)
(str /f(x))
(let [k name] (str /users/,.k))
(let [n 10] (str /user-,(+ .n 1)))
(let [k a/b] (str /,.k))
(let [k x~y] (str /,.k))
(let [p /3/3] (get [null null null {3 found}] .p))
(let [p /3/,(int "3")] (get [null null null [a b c found]] .p))
/,null
/,true
(count /a/b/0)
(first /a/b/0)
(str (rest /a/b/0))
(= /a/0 (jsonptr "/a/0"))
(let [x 3] (str /foo/,.x))
(get [a b c d] /3)
(get [a b c d] /3)
(let [n "3"] (get [a b c d] /,.n))
(let [n "3"] (get {3 yes} /,.n))
(let [n 03] (get {03 yes} /,.n))
(let [n "3"] (= /,.n /3))

true
"/"
"//a"
"/a/"
"/a~1b/x~0y"
"/f(x)"
"/users/name"
"/user-11"
"/a~1b"
"/x~0y"
found
found
#err {<mismatch type>
      message "pointer segments must be strings or integers"}
#err {<mismatch type>
      message "pointer segments must be strings or integers"}
3
a
"/b/0"
true
"/foo/3"
d
d
d
yes
yes
true

(let [p /3/,"3"]
 [.p (get [null null null {3 yes}] .p) (str .p)])
(let [name Ada] (str /,~"hello-,.name"))
(str /,~"inner ,(str "x")")

(let [p /3/3] [.p (get [null null null {3 yes}] .p) (str .p)])
(let [name Ada] (str /,~"hello-,.name"))
(str /,~"inner ,(str x)")

[
  [/3/3 yes "/3/3"]
  "/hello-Ada"
  "/inner x"]

Parentheses produce a #invoke tagged element whose payload is a list. The first element is the callee, and the remaining elements are argument forms. A direct callee is a name encoded as a string, without a #local or #const wrapper. In this position, surrounding quote characters belong to the name. This differs from string parsing in argument position. A callee that begins with . or : is a reference, and therefore a computed callee.

(upper hello)

#invoke [upper hello]

#cases [{bindings {upper (fn [x] .x)} output hello}]

("upper" hello)

#invoke ["""
           "upper"
         """
         hello]

#cases [{bindings {""\"upper""" (fn [x] .x)} output hello}]

(+ 1 2)

#invoke [+ 1 2]

3

("+" 1 2)

#invoke ["""
           "+"
         """
         1
         2]

#cases [{bindings {""\"+""" (fn [a b] (+ .a .b))} output 3}]

(let [twice (fn [x] (* 2 .x))]
  (.twice 21))

(let [twice (fn [x] (* 2 .x))] (.twice 21))

#invoke [let [twice #invoke [fn [x] #invoke [* 2 #local x]]] #invoke [#local twice 21]]

42

(:upper hello)

#invoke [#const upper hello]

#cases [{bindings {upper (fn [x] .x)} output hello}]

(:+ 1 2)

#invoke [#const + 1 2]

3

(f :x)

#invoke [f #const x]

#cases [{bindings {f (fn [value] .value) x Ada} output Ada}]

[upper hello]

upper
hello

[upper hello]

upper
hello

A computed callee is encoded as the first form in #invoke. For example:

((if true :+ :*) 2 3)

#invoke [#invoke [if true #const + #const *] 2 3]

5

The parser does not resolve invocation names, check whether a callee produces a function, or evaluate arguments. Unknown names and expressions such as (/ 1 0) are valid parser inputs. Their evaluation belongs to DUST.

An empty invocation, (), parses as #invoke []. Parsing does not require a callee; an empty invocation has no function to evaluate. Whitespace separates forms throughout an invocation, including across newlines, even when the callee begins on a later line. A bare argument containing spaces must be quoted. Lists retain RON's packed and line-oriented rules in every position, including binding and parameter lists. The parser does not interpret special-form names or binding positions.

()

#invoke []

(
  .f
  hello world
)

(.f hello world)

#invoke [#local f hello world]

(let [
  first name
  second name
] [first name])

(let
  [
    first name
    second name]
  [first name])

#invoke [let
         [
           first name
           second name]
         [first name]]

The four prefixes apply to the immediately following form and parse to a tagged element. The prefix and its form are adjacent; quote or fence a string beginning with one of these characters when it is meant as text.

`.name

#quote #local name

.name

~[a .b]

#quasiquote [a #local b]

a
.b

,.name

#unquote #local name

#err <outside quasiquote unquote>

,@.items

#unquote-splicing #local items

#err <outside quasiquote splicing unquote>

`~(f ,.x ,@.xs)

#quote #quasiquote #invoke [f #unquote #local x #unquote-splicing #local xs]

~(f ,.x ,@.xs)

Quoting a string does not turn it into a DUST quotation form.

#quote .name

`.name

#quote #local name

.name

#quasiquote [a b]

~[a b]

#quasiquote [a b]

a
b

#unquote .name

,.name

#unquote #local name

#err <outside quasiquote unquote>

Quotation names have no special meaning inside parentheses: (quote 1) parses as #invoke [quote 1] and formats as (quote 1). The explicit quotation notation is #quote 1, whose canonical DUST spelling is `1. The same rules apply to the other three quotation tags.

Quote returns its enclosed form as data without evaluating references, invocations, or collection contents within it. Quasiquote constructs data in the same way, except that unquote evaluates one enclosed form and substitutes its resulting value. Unquote-splicing evaluates an enclosed list and inserts its elements into the surrounding list, in order.

With x bound to 2 and xs bound to [3 4]:

`[a .x]           ; returns [a .x]
~[a ,.x ,@.xs]    ; returns [a 2 3 4]

Nested quasiquotes match unquotes by nesting depth: entering a quasiquote increases the depth, and an unquote or splice belongs to its matching quasiquote. An inner quasiquote's substitutions are not executed by an outer one. Unquote outside quasiquote produces #err <outside quasiquote unquote>, and unquote-splicing outside quasiquote produces #err <outside quasiquote splicing unquote>. Unquote-splicing outside a list-element position, or splicing a value that is not a list, produces #err <invalid quotation>.

The DUST parser constructs the tagged elements. DUST decides how to resolve a reference, invoke a function, or process a quotation form. Those evaluation rules belong to DUST rather than the data format.

The meanings of #link, #dur, #utc, and #hash belong to DUST. They use RON’s generic #prefix value notation; RON accepts these prefixes without interpreting them. Payload validation and evaluation semantics belong to DUST. Parsing preserves the tagged representation without evaluating it, except that a valid #utc or #dur payload is rewritten to its canonical spelling: #utc 1970-01-01T00:00Z reads and formats as #utc 1970-01-01T00:00:00Z, and #dur PT90M as #dur PT1H30M. Payloads that do not parse are kept for evaluation to reject.

Epsilon imports #utc as a typed UTC value. Evaluating it returns that same value; it does not execute or reinterpret its timestamp payload. Formatting exports the normal tagged representation through the selected notation codec.

#utc and #dur are distinct signed 64-bit counts of 100 ns ticks. UTC counts from the Unix epoch; durations count elapsed ticks. Canonical text has at most seven fractional second digits. Input accepts up to nine digits, rounded to the nearest tick, with halfway cases rounded away from zero. A nonzero timestamp or duration that would round to zero is represented by one tick in magnitude. See the Time library for ranges, constructors, units, calendar operations, and explicit tick/nanosecond conversion.

#link constructs a distinct link value with an integer, string, or tagged payload. Integer payloads use the full signed 64-bit range. String payloads stay strings, including numeric-looking names such as #link "42". Tagged payloads retain their tag and value, as in #link #url https://arst.com/arst.

Bare strings are valid: #link foo carries the name foo. Epsilon preserves names without resolving them; a query or transaction engine can interpret a name as a temporary ID. Epsilon does not fetch or interpret tagged link targets.

A reference or invocation in the payload is evaluated before constructing the link. For example, (let [foo 42] #link .foo) produces #link 42. Quotation preserves constructor syntax: `#link .foo does not look up foo. Booleans, floats, plain maps, and lists are invalid evaluated link payloads. A payload that evaluates to an error is the result instead of a link: #link .missing returns the unbound-name error, so error? and falsiness see it.

#link .missing
#link (/ 1 0)
(error? #link .missing)

#err <name unbound>
#err <division integer zero>
true

The canonical form #link 42 has this JSON representation:

{"#link": 42}

A link is distinct from an integer even when their payloads match. Both (int? #link 42) and (number? #link 42) return false, and numeric operations reject link operands. Integer link payloads sort before string payloads, then tagged payloads. Payloads use their native ordering; tagged ordering requires scalar tag payloads. Comparing #link 42 with the integer 42 produces a type-mismatch error.

(do [#link 0 #link -1 #link -9223372036854775808 #link 9223372036854775807])

#link 0
#link -1
#link -9223372036854775808
#link 9223372036854775807

#link "42"

#link "42"

(int? #link 42)

false

(number? #link 42)

false

(+ 1 #link 42)

#err <mismatch type>

(do [(= #link 42 #link 42) (= #link 42 #link 43) (comparison/identical? #link 42 #link 42)])

true
false
true

(= #link 42 42)

#err <mismatch type>

{#utc 2026-10-24T12:34:56Z}

#utc 2026-10-24T12:34:56Z

#utc 2026-10-24T12:34:56Z

{#utc 2026-10-24T12:34:56Z}

#utc 2026-10-24T12:34:56Z

#utc 2026-10-24T12:34:56Z

#utc 2026-10-24T12:34:56Z

{
  dependsOn {#link 42}
  when {#utc 2026-09-09T00:00:00Z}
}

{dependsOn #link 42
 when #utc 2026-09-09T00:00:00Z}

dependsOn #link 42
when #utc 2026-09-09T00:00:00Z

{dependsOn #link 42
 when #utc 2026-09-09T00:00:00Z}

#dur PT30S

#dur PT30S

#utc 2026-10-24T12:34:56Z

#utc 2026-10-24T12:34:56Z

#hash holds a digest tagged with its algorithm; the hash library defines its payload and equality.

#hash #sha256 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

#hash #sha256 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

#hash #sha256 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

A backslash prefix, \form, mutes the immediately following complete form. The prefix and its form are adjacent. It applies to invocations, references, scalar values, lists, maps, and tagged elements. The parser still reads the muted form's notation and balances its delimiters; malformed strings or unmatched delimiters remain syntax errors.

A muted form is represented as a #mute tagged element whose payload is the preserved form. For example, (+ 1 \(* 20 30) 2) has the form representation #invoke [+ 1 #mute #invoke [* 20 30] 2]. The explicit #mute form spelling is accepted, and canonical DUST writes the backslash shorthand. RON and JSON keep the tagged element.

(+ 1 #mute (* 20 30) 2)

(+ 1 \(* 20 30) 2)

#invoke [+ 1 #mute #invoke [* 20 30] 2]

#mute #invoke [+ 1 2 3]

\(+ 1 2 3)

#mute #invoke [+ 1 2 3]

When reading files or interpreting source lists and invocation argument sequences, DUST excludes muted elements before evaluation, macro expansion, and arity or binding checks. Their payloads are not evaluated or checked for semantic validity. Muted elements contribute no element or argument, not a null placeholder. The active forms must satisfy the usual rules. Known tags inside a muted payload are still validated on import, so \#local 42 is invalid just as #local 42 is.

(+ 1 \(* 2 3) 4)        ; evaluates to 5

(+ 1 #mute (/ 1 0) 2)

(+ 1 \(/ 1 0) 2)

3

[1 #mute .missing 2]

1
\.missing
2

1
2

[\.missing \[1 2] \{a 1}]

\.missing
\[1 2]
\{a 1}

[#mute #local missing
 #mute [1 2]
 #mute {a 1}]

A file containing only muted forms produces no evaluation results. A muted value cannot be compiled directly as a root expression or supply a map value or invocation callee. These uses are evaluation errors, not parse errors: #err <mute root value>, #err <map mute value>, and #err <callee mute>. Runtime data is not filtered for mute elements.

#invoke [#mute + 1 2]

(\+ 1 2)

#err <callee mute>

To begin a literal string with a backslash, quote the string.

["\\path" "\\(+ 1 2)"]

"\\path"
"\\(+ 1 2)"

[
  \path
  \(+ 1 2)]

"\\path"
"\\(+ 1 2)"

Canonical DUST formatting preserves the parsed form. Consecutive forms in an invocation or packed list are separated by a space when they share a line. Consecutive closing delimiters can be adjacent. An invocation stays on one line when it fits RON's 100-column target. Otherwise, it wraps between complete arguments, with continuation lines indented two spaces from the invocation's starting column. This rule applies to all callees without recognizing function or special-form names. Valid references use .name and :name, invocations use parentheses (including ()), quotation forms use their short prefixes, and muted forms use \. Explicit tagged data that has no faithful shorthand, such as #local "two words", #const "", or #local ".x", retains explicit notation. A direct callee whose name begins with . or : also keeps the explicit #invoke notation. Formatting and parsing the result preserves the JSON representation. Comments on invocation elements remain attached to those elements.

[ (quote 1) (quasiquote [a b]) (unquote .x) (unquote-splicing .xs) ]

(quote 1)
(quasiquote [a b])
(unquote .x)
(unquote-splicing .xs)

[#invoke [quote 1] #invoke [quasiquote [a b]]
 #invoke [unquote #local x] #invoke [unquote-splicing #local xs]]

{empty #local ""
 spaces #local "two words"
 non-string #local 42
 quoted-name #local ".x"
 colon-name #const ":x"
 non-list #invoke 42
 numeric-callee #invoke [1 2]
 spaced-callee #invoke ["two words" 1]
 var-callee #invoke [#local f 1]
 const-callee #invoke [#const f 1]
 dotted-callee #invoke [".f" 1]
 quoted-callee #invoke [#quote .f 1]
 empty-call #invoke []}

{colon-name #const ":x"
 const-callee (:f 1)
 dotted-callee #invoke [".f" 1]
 empty #local ""
 empty-call ()
 non-list #invoke 42
 non-string #local 42
 numeric-callee #invoke [1 2]
 quoted-callee (`.f 1)
 quoted-name #local ".x"
 spaced-callee #invoke [
   two words
   1]
 spaces #local "two words"
 var-callee (.f 1)}

colon-name #const :x
const-callee #invoke [#const f 1]
dotted-callee #invoke [.f 1]
empty #local ""
empty-call #invoke []
non-list #invoke 42
non-string #local 42
numeric-callee #invoke [1 2]
quoted-callee #invoke [#quote #local f 1]
quoted-name #local .x
spaced-callee #invoke [
  two words
  1]
spaces #local "two words"
var-callee #invoke [#local f 1]

(f
  ; before the first argument
  1 ; first argument
  2)

"#invoke" [f
           ; before the first argument
           1 ; first argument
           2]

(function-name "a string argument with several words" "a string argument with several words" "a string argument with several words" "a string argument with several words" )

(function-name
  "a string argument with several words"
  "a string argument with several words"
  "a string argument with several words"
  "a string argument with several words")

#invoke [
  function-name
  a string argument with several words
  a string argument with several words
  a string argument with several words
  a string argument with several words]

["foo(bar)" "(bar)" "abc)" ".name" ":name"]

"foo(bar)"
"(bar)"
"abc)"
".name"
":name"

[foo(bar) (bar) abc) .name :name]

These rules apply to DUST source, not str, which formats collections through the canonical RON formatter.

However DUST does need references. A reference is a name that refers to something else; in other languages you might know it as an identifier. DUST has two kinds, and the prefix says where the name is looked up:

References follow the source notation rules. A quoted string whose contents begin with . or : is not a reference. Map keys are always strings, including names beginning with . or :. Parsing constructs a reference without resolving its name. Binding forms use string names rather than references.

A local reference resolves to the nearest enclosing local binding, whether its value is a function or ordinary data. With no enclosing binding, it is the top-level local of that name, read each time the reference runs. It never reaches a constant: .math/pi is unbound unless a local binding has that name. An unbound local is an error when evaluation reaches it, so (if true 1 .missing) returns 1.

A constant reference never reaches a local binding: (let [x 1] :x) is unbound. Library entries are fixed: a host binding with the same name as a library entry is rejected, and every evaluation with that binding produces #err <conflict name>, whether or not the program refers to the name. A host that needs its own value supplies it under another namespace. Every constant in a program is resolved once, before evaluation starts. If any of them is unbound, the program evaluates to that #err <name unbound>, even when the reference is in a branch that would not run. Constants inside quoted or muted forms are not evaluated, so they are not resolved.

(let [name Ada] .name)

Ada

.math/pi

#err <name unbound>

(if true 1 .missing)

1

:name

#cases [{bindings {name Ada} output Ada}]

(let [x 1] :x)

#err <name unbound>

(if false :missing 1)

#err <name unbound>

`[:missing .missing]

:missing
.missing

(+ 1 \:missing 2)

3

:math/pi

#cases [{bindings {math/pi 3} output #err <conflict name>}]

(+ 1 2)

#cases [{bindings {+ 0} output #err <conflict name>}]

A pointer has the type name pointer and holds a sequence of Key string segments and nonnegative Index integer segments. RFC 6901 text is used when constructing, encoding, or printing it. Decoding splits at /, replaces ~1 with / and ~0 with ~, and treats decimal digits with no leading zeroes as an index, saturating at the largest signed 64-bit integer. Encoding writes indices in decimal and escapes ~ before / in keys. After printing and reading again, Key "0" becomes Index 0. The two select the same map key, but only the index can select a list element.

Pointer equality compares segment kinds and values. list? is false for a pointer, and jsonptr? is true. str returns the RFC 6901 text, while format and the REPL print the canonical DUST form. Functions that accept arbitrary values also accept pointers, including equality, distinctness, and map values.

A direct invocation resolves the exact name stored in the first element of #invoke. It looks first in the local bindings and then in the constants, so both (increment 4) with a let-bound increment and (+ 1 2) work. ("+" 1 2) looks up a name containing the quote characters as well as the plus sign. (.f 1) and (:+ 1 2) are computed callees whose references follow the rules above. A missing binding produces an unbound-name error.

Evaluation turns a form into a value. RON and JSON representations of the same source form have identical evaluation semantics. Runtime inputs and returned values are values, not source to evaluate again.

Known tagged elements are validated before evaluation. This includes known tags inside quotations, muted forms, and branches that would not be selected at runtime. Unknown tags remain generic tagged data. Evaluating one returns its tag and payload as data, without evaluating the payload or any nested invocation. For example, #custom (/ 1 0) preserves the invocation as data and does not divide by zero. Formatting and notation round trips preserve the normal tagged representation.

This opaque evaluation rule does not bypass import validation. Known tags nested inside an unknown payload are still validated eagerly; for example, #custom #local 42 has an invalid known reference payload. Today that is the error #err <invalid tag> when the form is evaluated; once readers use the cell decoders, such a source does not parse.

{#tag value}

#tag value

#tag value

#application {
  symbol .missing
  invocation (unknown-function .missing)
  unquote ,.missing
  splice ,@.missing
  nested #another (unknown-function (/ 1 0))
}

#application {invocation (unknown-function .missing)
              nested #another (unknown-function (/ 1 0))
              splice ,@.missing
              symbol .missing
              unquote ,.missing}

#application {invocation (unknown-function .missing)
              nested #another (unknown-function (/ 1 0))
              splice ,@.missing
              symbol .missing
              unquote ,.missing}

#application {known #local 42}

#err <invalid tag>

The self-evaluating forms already represent their value, so evaluating them results in themselves. Other forms describe how to obtain a value, for example by looking up a name to grab what it represents or invoking a function.

An invocation is encoded as a #invoke tagged element containing the callee followed by its argument forms.

For an ordinary function call, a string in the first element of #invoke names the function to resolve. Any other form in that position is evaluated once to obtain the function. Direct invocation names resolve to the nearest local binding, then to a constant. References resolve as described in References. The result must be a function.

A computed callee that returns a string is an error, even if that string names a function. There is no second name lookup.

DUST excludes muted argument forms, then evaluates the active argument forms from left to right and passes their resulting values to the function. The function's return value becomes the value of the invocation.

Examples show DUST source beside its expected result.

(+ 1 2)

3

(:+ 1 2)

3

("+" 1 2)

#cases [{bindings {""\"+""" (fn [a b] (+ .a .b))} output 3}]

((if true :+ :*) 2 3)

5

((if true "+" "*") 2 3)

((if true + *) 2 3)

#err <callee string>

(let [op (if true :+ :*)]
  (op 2 3))

(let [op (if true :+ :*)] (op 2 3))

5

(let [a-fn :+]
  (a-fn 1 2))

(let [a-fn :+] (a-fn 1 2))

3

(+ 1 (* 2 2)) can be thought of as being evaluated in two steps:

1. Evaluate (* 2 2) to obtain 4.
2. Substitute 4 for the multiplication, giving (+ 1 4), which evaluates to 5.

Hence:

(+ 1 (* 2 2))

5

Square brackets construct lists and braces construct maps. List construction excludes muted elements and evaluates the active elements from left to right. Map construction evaluates each member value²; the order in which member values are evaluated is not defined. Canonical key order is a formatting rule, not an evaluation order. A muted form cannot supply a map member value.

[+ 1 2]

+
1
2

+
1
2

[(+ 1 2) 4]

(+ 1 2)
4

3
4

{total (+ 1 2)}

{total 3}

Tags parse into ordinary boolean map members before evaluation. Their names are string keys, not references, and their boolean values evaluate to themselves. Tags introduce no new evaluation behavior.

An evaluation error is a value. It can be passed to a function, bound by let, or stored in a list or map. Evaluation of other arguments and elements can continue. A program can inspect an error with error?.

An error is a #err tagged element. Its payload may be a string or a detailed map. A map can contain a RON tag group that classifies the error and members that describe the failure:

#err {<division integer zero>
      column 1
      line 1
      message "division by zero"}

Conformance expectations write only the tags, as #err <division integer zero>; messages and positions are diagnostics, not part of the contract. An error value retains its tags when passed through a program. Resource and allocation failures remain runtime failures that can stop evaluation.

Special forms control evaluation rather than following the ordinary function-call rule. For example, if evaluates only the selected branch.

Macros transform forms before evaluation, while quotation allows a form to be used as data without evaluating it.

Collection paths select values in maps and lists. A string is always one literal map key, including a string that starts with /. A nonnegative integer is one index. A list contains only string keys and nonnegative integer indices; an empty list selects the root. A pointer from /..., #jsonptr, or jsonptr supplies its segments directly.

An out-of-range list index is missing. A missing read returns the default or null, and contains? returns false. A write creates intermediate maps; an index in a new map uses its decimal key. A list write at its length appends. Other container types give #err <mismatch type>. A negative index gives #err <invalid value>. A pointer inside a list path is a type error.

A whole embedded segment becomes one segment based on its value:

A mixed segment always becomes a key, even if its resulting text is digits. Its literal parts and embedded strings are concatenated directly; null becomes null, and other values use their canonical DUST text.

DUST provides one primitive special form for branching, if. The macros when, when-not, and cond build on it to express common branching patterns.

Use for to iterate over collections.