x-lang syntax: the preferred forms

The syntax of booted x-lang and the idioms this project prefers — the least-surprise contract. Every ruling here is implemented; the ruling record is issue #45. The bare layer underneath is syntax-bare.md.

Symbols and quoting

Write 'x, always, in any code that loads after boot. (lit x) is the boot-layer mechanism — the operative the quote reader expands to — and its spelling belongs only in files that load before the quote reader (the boot block) and in discussions of the mechanism itself.

(prim-ref 'buf 'tok)        ; preferred
(prim-ref (lit buf) (lit tok)) ; boot-layer files only
'(a . 1)                    ; a quoted assoc
'(a b c)                    ; quoted list

The REPL echoes symbols as 'a and quoted structures with the same shorthand — the echo pastes back. (Implemented: the printer’s ' shorthand is live; (lit a) echoes are history.)

`x, ,x, ,@x are the quasiquote family; the printer already echoes them in shorthand.

Numbers

• -1, +7, 0xff — signed integers and hex are core literals at every stage. Never write (- 0 1) for a literal. (- 0 x) remains the correct spelling for negating a variable (it routes through the operand’s type dispatch).
• Tower literals — dialect-gated (xenon, radon, x-base): floats 3.14, -7.5; rationals 1/3, -2/7; complexes 3+4i, 2-3i, -1+2i; arbitrary-precision decimals 1.5d, -0.001d, 1.5e-8d; big integers as plain digit runs. (Implemented — the compiled analysers carry the sign branches.)
• Floats print with their point: 1.0 echoes 1.0, not 1. (Implemented.)
• Decimals print with their d: 1.5d echoes 1.5d, because a printed 1.5 would read back as a float. (Decimal ->str x) is the suffix-free text. (Implemented.)
• Leading-zero integers are decimal (019 is nineteen); 0x13 is hex. (Implemented.)

Characters and strings

• #\a, #\newline, #\€ — everywhere, including boot files. The string-index idiom ("x" 0) is retired.
• Strings escape with \" \\ \n \t \r \0 \xHH.
• #"text {expr} text" interpolates at read time (expands to (Str8 str …)). A hole is scanned in expression context, so it holds arbitrary code — a string (#"{(join " " xs)}"), a #\ character literal, or another #"…" — and only the } that closes it ends it. {{ and }} are literal braces; \ escapes the next character, so \{ opens no hole (and, as in any string, keeps its backslash). The # is the prefix every reader extension wears (#t, #\a, #(…), #/…/); the literal was spelled $"…" through 0.13.0.

Collections

• Vectors have a literal: #(1 2 3), #() — reads and prints.
• Lists quote as data: '(a b c); a bare (a b c) is a call.
• Associations have named doors, not literal syntax — the name carries the shape: '((a . 1)) is an alist literal via quote; (Dict from-plist '(a 1 b 2)) is the simplest dict literal; from-alist / from-bindings for the other shapes. Dict/Set/Array print as opaque #<obj:…> forms (echoes of containers do not paste back — by design, they are mutable objects).
• #/pattern/ regex literals (dialect-gated with the tower).

Idioms

• Primitives are the preferred inline spelling: (+ x 1), (first (rest x)), (- x 1). The class methods (Num inc, List second) are namespace homes and value-passing handles ((method-ref Num inc)), not required spellings.
• when / unless are the one-armed conditionals; (if c x ()) is retired. (They existed all along — the audit found hundreds of hand-rolled emulations written while they sat unused; 214 migrated.) Primitive if stays deliberately in three places: files that load before syntax.x in boot (when isn’t bound yet), reader-callback code (ops are banned inside x_token_read), and hot per-element cores (when/unless are ops — per-call allocation; primitives are the preferred inline spelling in hot loops).
• Sequencing: def-in-body for stepwise computation, let for bindings-with-scope, nested let in tail position (where def would leak under TCO). let* is retired — removed, its six historical uses migrated. (Implemented.)
• Thunks are (fn () …); a self-only signature (fn (_) …) means the closure uses being self-passed. Don’t mix the two for “no arguments”.
• Errors are raised with (error …) and caught with guard; misses are nil behind presence doors (the absence discipline, spec.md).

The echo (what the REPL prints back)

You type	It echoes
'a	'a
42, -7, "s", #\a, #t	itself
#(1 2 3), 1/2, 3.14, 3+4i	itself (tower forms in tower dialects)
`(a ,x)	quasi shorthand
a list value	('a 'b) — quoted elements, pasteable
fn / op / dict / instance	#<…> opaque — deliberately not pasteable
()	(blank)

Dialect matrix

Syntax	bare x	helium	xenon/radon, x-base
ints (signed, hex), strings, #\ chars, lists, ( . x), ;	✓	✓	✓
#t/#f as booleans, printer	—	✓	✓
' ` , ,@ #"…" #(…)	—	✓	✓
floats, rationals, complexes, bigints, decimals (1.5d), #/…/	—	—	✓

The bare column is normative for every implementation of the reader; see syntax-bare.md.