spec+grammar: tuple-vs-arglist rule and explicit tuple spread #4

Merged

crowmaki merged 1 commit from docs/tuple-arg-spread into main

2026-08-21 20:12:08 +00:00

crowbot commented

2026-08-21 20:06:43 +00:00

Collaborator

What

Codifies the decided tuple-vs-argument-list rule into the spec and the
canonical grammar:

f(a, b) passes two positional arguments.
f((a, b)) passes one tuple argument (inline 2-tuple needs the outer parens).
f(...t) explicitly spreads a tuple into positional args.

This dissolves the arglist-vs-tuple ambiguity a prior review surfaced, keeps
calls deterministic under overloading, and deliberately makes
f((a, b)) ≠ f(a, b) — parentheses are not a semantic no-op in calls.

Files

File	Change
`docs/prd/language-spec.md`	new Tuples ▸ In argument lists subsection
`docs/prd/language-grammar.md`	`call-args = call-arg { "," call-arg }`, `call-arg = expr \| spread`, `spread = "..." expr`; separate `elem-list` for array/init elements; rewrite the paren-disambiguation note around parser position + mode + one bounded peek
`docs/parser/30-expressions.md`	`parse_call_args` note in the build map

Notes

No lexer change: .. / ... are already DotDot / DotDotDot tokens.
The explicit-spread choice (rather than implicit "arglists are tuples")
was agreed after weighing the alternatives: it preserves tuple parameters
as first-class (no forced bound-name staging), stays deterministic under
function overloading, and avoids type-directed arglist resolution.

Not included (next step, TDD contract)

Per AGENTS.md, a new syntactically-documented feature wants a fixture +
manifest entry. No parser exists yet, so this is codified but not yet under
test. Natural follow-up: add tests/fixtures/parse/tuple-spread.cat and a
manifest row (phase parse) ahead of building the parser.

## What Codifies the decided **tuple-vs-argument-list rule** into the spec and the canonical grammar: - `f(a, b)` passes **two** positional arguments. - `f((a, b))` passes **one** tuple argument (inline 2-tuple needs the outer parens). - `f(...t)` **explicitly spreads** a tuple into positional args. This dissolves the arglist-vs-tuple ambiguity a prior review surfaced, keeps calls deterministic under overloading, and deliberately makes `f((a, b)) ≠ f(a, b)` — parentheses are not a semantic no-op in calls. ## Files | File | Change | |---|---| | `docs/prd/language-spec.md` | new **Tuples ▸ In argument lists** subsection | | `docs/prd/language-grammar.md` | `call-args = call-arg { "," call-arg }`, `call-arg = expr \| spread`, `spread = "..." expr`; separate `elem-list` for array/init elements; rewrite the paren-disambiguation note around parser **position + mode + one bounded peek** | | `docs/parser/30-expressions.md` | `parse_call_args` note in the build map | ## Notes - No lexer change: `..` / `...` are already `DotDot` / `DotDotDot` tokens. - The explicit-spread choice (rather than implicit "arglists are tuples") was agreed after weighing the alternatives: it preserves tuple parameters as first-class (no forced bound-name staging), stays deterministic under `function` overloading, and avoids type-directed arglist resolution. ## Not included (next step, TDD contract) Per AGENTS.md, a new syntactically-documented feature wants a fixture + manifest entry. No parser exists yet, so this is codified but not yet under test. Natural follow-up: add `tests/fixtures/parse/tuple-spread.cat` and a manifest row (phase `parse`) ahead of building the parser.

crowbot added 1 commit

2026-08-21 20:06:43 +00:00

spec+grammar: codify tuple-vs-arglist rule and explicit tuple spread 062deff881

Settled design (Crow): f(a, b) passes two arguments; f((a, b)) passes one
tuple argument; f(...t) explicitly spreads a tuple into positional args.

- docs/prd/language-spec.md: new 'In argument lists' subsection under Tuples
  documenting the three forms and that '(' is not a semantic no-op in calls.
- docs/prd/language-grammar.md: split call-args = call-arg { ',' call-arg }
  with call-arg = expr | spread, spread = '...' expr; separate elem-list for
  array/init elements; rewrite the paren-disambiguation note around parser
  position + mode + one bounded peek.
- docs/parser/30-expressions.md: note the call-args rule in the build map.

No lexer change (.. and ... are already DotDot/DotDotDot tokens).