jolt/docs/spec/02-reader.md

§2 The Reader (Lexical Syntax)

Status: token grammar drafted; reader-macro catalog complete with normative entries; syntax-quote section carries two open divergences. Conformance: jolt reader-forms-spec + reader-syntax-spec (granularity model: jank's per-construct corpus, 62 files under test/jank/{reader-macro,syntax-quote} — adapted rows cited per entry).

The reader maps a stream of characters to forms (data). Reading is independent of evaluation: every form the reader produces is a value of the language (§4), and read-string exposes the reader as a function. Evaluation of forms is §1's concern; only quote-family reader macros reference it here.

2.1 Tokens

Whitespace is space, tab, newline, return, and comma (, is whitespace — S1). A ; begins a comment to end of line (S2). Tokens:

form        := literal | symbol | keyword | list | vector | map | set
             | reader-macro-form
list        := '(' form* ')'
vector      := '[' form* ']'
map         := '{' (form form)* '}'
literal     := nil | boolean | number | string | character
nil         := 'nil'        boolean := 'true' | 'false'

• S3. A map literal MUST contain an even number of forms; duplicate keys MUST be an error at read time.
• S4. A set literal (#{…}, §2.3) with duplicate elements MUST be an error at read time.

Numbers

integer  := ['+'|'-'] (digits | '0' [xX] hexdigits | '0' octdigits | radixR digits)
float    := ['+'|'-'] digits '.' digits? exponent? | ['+'|'-'] digits exponent
ratio    := ['+'|'-'] digits '/' digits            ; host-numeric-tower (§4 note)
exponent := [eE] ['+'|'-'] digits

• S5. Trailing N (BigInt) and M (BigDecimal) suffixes are part of the grammar; their value semantics are the §4 numeric-tower question. Implementations without those towers SHOULD read them as the nearest numeric type and MUST document the choice.

Symbols and keywords

symbol   := name | ns '/' name        ; '/' alone names the division fn
keyword  := ':' name | ':' ns '/' name | '::' name | '::' alias '/' name

• S6. Symbol constituent characters: alphanumerics and * + ! - _ ' ? < > = . $ & % (with % and & further constrained inside #()); a symbol MUST NOT begin with a digit; . and / have positional restrictions.
• S7. ::kw MUST resolve to the current namespace at read time (::k in ns user reads as :user/k); ::alias/k resolves the alias or MUST be a read error if the alias does not exist.

Strings and characters

• S8. Strings are "…" with escapes \" \\ \n \t \r \b \f \uNNNN \oNNN.
• S9. Character literals: \c, the named set \newline \space \tab \return \backspace \formfeed, unicode \uNNNN, octal \oNNN.

Conformance (2.1): jolt reader-syntax-spec "dispatch & sugar"; clojure-test-suite reader files; jank form/* literal dirs. S3/S4 duplicate checks → UNVERIFIED (rows to add).

2.2 Quote-family reader macros

Sugar	Reads as
'form	(quote form)	S10
@form	(deref form)	S11
^meta form	form with metadata attached (see below)	S12
#'sym	(var sym)	S13
`form	syntax-quote (§2.4)
~form, ~@form	unquote / unquote-splicing — only within syntax-quote (S14: MUST error outside)

• S12a. ^:kw form ≡ ^{:kw true} form; ^Sym form ≡ ^{:tag Sym} form; ^"str" ≡ ^{:tag "str"} form. Multiple ^ stack, rightmost innermost, merged left-over-right.
• S13a. #'ns/sym MUST denote the same var as (var ns/sym): (= (var clojure.core/str) #'clojure.core/str) is true.

Conformance: jolt reader-forms-spec "var-quote #'", "metadata ^", "syntax-quote"; jank var-quote/pass-qualified.jank, metadata/*.

2.3 Dispatch (#) reader macros

Form	Meaning	Entry
#{…}	set literal	S4 above
#"…"	regex literal — reads to a regex value; escaping is regex-level, not string-level (single \d)	S15
#(…)	anonymous fn	S16 below
#_form	discard	S17 below
#?(…) / #?@(…)	reader conditional (+splicing)	S18 below
##Inf ##-Inf ##NaN	symbolic floats	S19
#tag form	tagged literal	S20 below
#! …	shebang comment line (implementations SHOULD accept)

S16 — anonymous function #(…)

• #(body) reads as (fn [args…] (body)) with parameters derived from the %-symbols appearing in body: %≡%1, %n positional, %& the rest parameter. Arity = highest %n mentioned (plus rest if %&).
• #() literals MUST NOT nest.

(#(+ %1 %2) 1 2)            ;=> 3
(apply #(apply + %&) [1 2 3]) ;=> 6
(map #(* % %) [1 2])        ;=> (1 4)

S17 — discard #_

• #_form reads and discards the next form entirely (it is never evaluated).
• Discards compose: #_ #_ a b discards two following forms.
• #_ inside collection literals removes the element: [1 #_2 3] ⇒ [1 3].

S18 — reader conditionals

• #?(:feat₁ f₁ :feat₂ f₂ …) reads as the form of the first feature key the platform satisfies, else nothing. :default matches any platform. #?@(…) splices a sequential form into the surrounding context.
• Feature keys are implementation-defined; each implementation MUST document its feature set. ⚠ jolt currently satisfies :clj (inheriting JVM branches in .cljc files) — under review; the portable convention is own-key + :default.
• Reader conditionals MUST be an error outside .cljc-style reading unless the implementation documents otherwise.

S19 — symbolic values

##Inf, ##-Inf, ##NaN read as the IEEE-754 values. (= ##NaN ##NaN) is false; (NaN? ##NaN) is true.

S20 — tagged literals

• #tag form: the reader resolves tag in the data-reader table and MUST apply the reader function to the read form, yielding its result as the read value. An unknown tag MUST be a read error (jank fail-unsupported-tag).
• Built-in tags every implementation MUST provide: #uuid "…" → a UUID value (§9 parse-uuid semantics — round-trips through printing), #inst "…" → an instant (representation host-classified; ⚠ jolt currently reads #inst as its bare string — divergence, filed).

Conformance (2.3): jolt reader-forms-spec "#() (% %N %&)" + new rows (symbolic values, stacked discard, conditionals); uuid-spec reader-literal group; jank reader-macro/{function,regex,uuid,symbolic-value}/*, fail-unsupported-tag.jank.

2.4 Syntax-quote

Syntax-quote (`) is read-level template construction with namespace resolution:

• S21. Inside syntax-quote, an unqualified symbol that resolves in clojure.core MUST be qualified to clojure.core/sym; a symbol resolving through a namespace alias MUST be qualified to the aliased namespace; an unresolved symbol MUST be qualified to the current namespace. Special-form names stay bare.
• S22. sym# generates a fresh symbol, stable within one syntax-quote template (all sym# in the same template denote the same generated symbol; distinct templates generate distinct symbols).
• S23. ~form inserts the value of form; ~@form splices a sequential value; ~'sym is the idiom for an intentionally-unqualified symbol.
• S24. Syntax-quote distributes through collection literals (vectors, maps, sets) — qualification and unquoting apply inside them.
• S25. Nested syntax-quotes expand recursively (quasiquote semantics); a syntax-quoted self-evaluating literal is the literal: (= "meow" ```"meow") is true. ⚠ jolt currently fails S25 (filed) — UNVERIFIED pending the fix.

Conformance: jolt reader-forms-spec "syntax-quote" (gensym, unquote, splice) + conformance "syntax-quote fully-qualifies"; jank syntax-quote/{pass-gensym,pass-namespace-resolution,pass-resolve-alias, unquote,unquote-splice}/*. S25 → UNVERIFIED.

2.5 What the reader is not

The reader performs no macroexpansion and no evaluation (tagged-literal reader functions are the deliberate exception, S20). Forms read identically whether or not they will be evaluated; read-string of any printable value v followed by evaluation yields a value equal to v for the self-evaluating types (§4 print/read round-trip contract).