Syntax Design

Status: active design (2026-09-04)

• Normative description of the target syntax: Syntax
• Implementation plan: syntax-rewrite

This note is the record of the research behind blr's surface syntax: what
other designers wrote, the principles distilled from it, surveys of specific
constructs (quote, sum labels), and every decision point with its rationale.
The design is the "whatever is easiest to implement" era re-examined against
those principles.

1. Research: what other designers wrote

Cross-cutting observation: every surviving language (C, Go, Rust, OCaml,
Haskell, Python) made the same trade-off — decode cost beats writing cost.
Syntax is optimized for a reader who may never have seen the language, not
for the fastest keystrokes. Blr makes the same trade.

2. Principles

P1 — Familiar

Blr code should be decodable by someone who has never read blr docs, using
only the conventions of C, JS, Rust, OCaml, and Python. New spellings are
allowed only for constructs with no mainstream precedent, modeled on the
closest precedent. POLA test: show the snippet to a programmer from another
language; if they guess the meaning wrong, the syntax is wrong.

P2 — Consistent (isomorphic)

The type of a value and the value of that type should be written the same
way; the same mechanism in the same position everywhere; one spelling per
concept. Target:

P3 — One meaning per token

Every token means exactly one thing, everywhere; meaning must not depend on
position or the type checker. A token may be reused only if (a) the two uses
are in positions that cannot occur together, or (b) mainstream languages
already reuse it that way (e.g. ( for grouping and call).

P4 — Minimal symbols

The punctuation budget is the C-family set:
{ } ( ) [ ] , ; . : " / + - * = > ! | ' #. A new punctuation character
requires a decision-log entry proving no allowed alternative works. Prefer
multi-character familiar sequences (->, ::, ==) over exotic singles.
No Unicode punctuation, no confusable glyphs.

P5 — Minimal keywords

A keyword is an identifier the user may not name. Use a keyword only when
it informs the parser or the type checker. Decisions: true/false
demoted to built-in identifiers; match kept as keyword for P1 reasons
(overriding P5, recorded). No keyword is needed for sum types: [ A unit, B P ] is unambiguous by position (type position, comma-separated case
pairs) — the rejected sum keyword is recorded in the decision log.

P6 — Open/close pairs for every block

Every syntactic group is enclosed in a matched pair. A pair's role is fixed
by the form that introduces it: bare { ... } is a block or record;
match { ... } pins arms, # { ... } pins a quote block. In type
position [ ... ] is a sum type (comma-separated case pairs) while the
prefix []T is a list type — decided by the token after [. No construct may end implicitly.

P7 — No hidden syntax

Nothing about meaning may depend on whitespace, line breaks, file position,
or a previous declaration. No context-sensitive tokens; no grammar "mode"
that changes mid-file.

P8 — Orthogonal composition

The same small set of expression forms works at every position and depth.
Prefer rewriting a special form into the general one.

P9 — Frequency-based explicitness

Frequent constructs get the shortest form; rare constructs the most
explicit. Quote is extremely common → one-character prefix. Sum types
are rare → their spelling may be less compact than a common one (they
share [ ... ] with list literals and rely on position), but common
forms never get longer to pay for it.

P10 — Uniform punctuation placement

One convention per punctuation role, documented in the grammar: , between
siblings (trailing allowed everywhere, required nowhere); ; statement
separator; : only for name : type and record fields; -> only for
function results.

P11 — Naming conventions (lint-enforced, not grammar)

One lexical class of identifiers; case carries meaning only by documented
convention + lint. PascalCase for types and sum case labels; snake_case
for values/functions/modules/fields; 'a for type variables.

Considered and rejected: Haskell-style case-as-lexemes (Varid/Conid
split at the lexer). Haskell is essentially the only mainstream language
that does it, it is a persistent source of confusion, and blr has a cleaner
mechanism — labels are distinguished from variables by path qualification,
not case (§5). Recorded in the decision log.

P12 — Toolable and documented

Full EBNF grammar in-repo as the single source of truth; highlighting,
formatting, and match-jump work on incomplete type-less code; every syntax
error names the construct and the expected form; every feature passes the
checklist (§8) and gets a decision-log entry.

3. Current surface inventory (pre-rewrite)

Keywords (9): pub fn type let import match extern
true false

Punctuation (15 distinct): { } ( ) [ ] , ; . : -> >
>> = + - * / ! .. | ` # (comments only) @
(comments only)

Forms (as found in lang/tests/ and stdlib/):

4. Survey: quote syntax

Constraint: blr's quote must be a syntactic form, not a function call —
a quoted expression is captured as data (compile-time rewrite to node
lists), so the type checker must not resolve a callee named quote and
type-check the argument in normal mode. The type system cannot distinguish
quote-the-function from quote-the-operation, so the parser must. Every
language with this feature made it syntactic:

Observations: (1) the cheap forms are all short prefixes (:, ', #)
— never a bare word, because a bare word would collide with the caller's
namespace (a function could be named quote); (2) short-form languages make
the prefix unambiguous by position — it only ever starts an expression;
(3) the paired-block form keeps true open/close pairs intact.

Decision (2026-09-04): # prefix quote, #{ ... } paired block form.

• #expr — quotes the next complete expression (Scheme-' boundary model).
• #{ ... } — paired form for a group: multiple statements, or nested
  structure where a single prefix expression is hard to bound.
• Rationale: cheapest possible spelling for a very common form (P9); #
  was free once comments moved to //; prefix-reader precedent (Racket
  #/#', F# #); no P3 collision.
• Superseded candidates, kept on the record: '{ expr } (Scala 3; true
  pair, unified ' family with 'a, but 3+2 keystrokes) and :( expr )
  (Julia; shortest familiar form for the data community, but not a true pair
  and a third meaning of :).

5. Survey: naming sum case labels

With backticks off the table, how is a case label like A told apart from a
user variable named A? Options considered:

Decision (2026-09-04): C — owner-qualified paths, with a bare top-level
form.

• T::A(unit) — case A of sum T, qualified by its owner.
• ::A(unit) — leading-:: top-level form, superseded by the
  anonymous 'A(unit) (§5.1).
• Match arms take the same path form: match t { T::A(_) => 1, T::B(b) => b.x }.
• Inside the definition, cases are written bare — declaration context binds
  them: type T = [ A unit, B P ] defines the labels T::A, T::B.
• Why over A: a value can never begin with ::, so labels cannot collide
  with user variables in any position — no resolution rule needed; the
  "PascalCase variable" concern is void by construction. Rides the existing
  :: path syntax (std::df, df::filter) — no new token. Self-documenting
  arms; same-named cases across sums coexist (T1::A, T2::A).
• Accepted cost (recorded against P9): match arms are longer (T::A(_) vs
  A(_)); long owners can alias through the module path.

5.1 The construction ambiguity (2026-09-07)

The §5 decision made an injection a path application — T::A(x) is
syntactically identical to calling a function A in module T. The first
implementation (commit 2026-09-07, decision-log entry of the same date) broke
the tie in the crust lowering: an application whose final path segment is a
case of an in-scope sum lowers to an injection. That is wrong in three ways:

1. P3 — the same tokens mean two things; the meaning depends on
   declarations, not syntax.
2. P7 (spirit) — T::A(x) changes meaning if a sum named T appears
   (or disappears) elsewhere in the file. When a local sum T and an
   imported module T both exist, the local sum silently wins.
3. P12 — an editor cannot classify T::A as constructor or callee
   without full resolution.

Rust, Scala, Swift, and Zig all ship bare Owner::Variant(x) construction
without a marker. They can, because their namespaces forbid T from being
both a module and an enum in one scope — T::A is never both a function
and a case. blr has one item namespace, so the collision is legal; the Rust
model is unavailable here. The mode must be switched by syntax.

Constraint (agreed): the T::A path stays — it names the case explicitly and
reads well — but the path is used only to check that the final segment is
a case of the named sum (and the payload type matches), never to choose
between syntactic modes. The mode switch must be a lexical marker the parser
can see.

Decision (2026-09-07): option 1 — tick prefix, with an anonymous label.

• Qualified: 'T::A(x) — case A of sum T.
• Anonymous: 'A(x) — the same, without naming the owner. Both spell
  the same node: a value labeled A. There is no name-level resolution of
  the owner at all — if two sums have a case A, the expected type of the
  position picks which one the value is (a case that is not in the declared
  sum is a row-mismatch type error, like a bad match arm). This replaces the
  leading-:: top-level form, which is gone (from expressions and
  patterns); imported sums stay qualified ('sums::Shape::Circle(2.0)).
• Grammar: one new term alternative — ' InjectPath ( Expr ), where
  InjectPath is one or more ::-separated identifiers. The tick is the
  mode switch; everything after it is an ordinary path. No type info
  anywhere in the parse. Unit payloads keep the (unit) spelling for now —
  one form — revisit under P9.
• The path is not consulted by the compiler at all: the label is the
  final segment and nothing more; the owner (T::, import::T::) exists
  for the reader. The lowering emits a labeled value with no lookup — no
  sum-declaration map, no diagnostics from the lowering. Whether the value
  has the right type is the inference phase's job: the injected row is
  unified against the declared type of the position
  ('T::C(unit) where the position expects T = [ A unit, B unit ] is a
  row-mismatch type error). With no declared type in scope (a generic
  'a result, an inferred let), the value simply gets an anonymous sum
  type — the same treatment as any other unconstrained expression.
• P3 entry for ': type variable (type position) vs injection prefix
  (expression position). The two positions are disjoint nonterminals
  (types occur only after : in parameters, in type declarations, and in
  extern signatures); the grammar must keep it that way. Rule (a) applies —
  recorded, not bent.
• Patterns: qualified arms stay bare — match t { T::A(_) => 1 } — and gain
  the anonymous form A(_) mirroring 'A(x). Pattern position has no
  application, so no tick: the marker means "literal value spelling", and a
  pattern does not spell a value.
• Injection is an ordinary term: it composes in arguments, records, lists,
  pipes, and quotes. As the function of an application it parses and fails
  type-check, like (1)(x) — no special ban (unlike #, which must not be
  applied because it captures syntax).

6. Audit: decision points

The pre-rewrite surface, row by row. Status: keep / change / decide.

7. Decision log

Append-only. Every decision, and every deliberate "keep the wart", lives
here.

8. Review checklist

Before any syntax is added or changed, answer (and show the answers in the
PR):

1. Familiar? Would a Rust/OCaml/JS reader decode it unprompted? (P1)
2. Isomorphic? Does the type look like its values, the definition like
   its type? (P2)
3. One meaning? Does this token mean only one thing in this code? (P3)
4. In the budget? Every symbol from the allowed set? (P4)
5. Keyword justified? Does it change parsing, or could it be an
   identifier? (P5)
6. Balanced? Which open/close pair wraps it, and is that pair's role
   pinned? (P6)
7. No hidden state? Would the same tokens on any other line parse the
   same? (P7)
8. Composable? Works in every expression position? (P8)
9. Right weight? Short-and-common or long-and-rare, matching frequency?
   (P9)
10. Uniform placement? Sibling separators, trailing commas, : usage
    match the one convention? (P10)
11. Named right? Case conventions followed? (P11)
12. Toolable? Highlightable/formattable without types; in the EBNF; with
    a good error message? (P12)

A "no" requires either a fix or a new entry in the decision log (§7).