plum

# Guard-Clause Match Arms — Design Spec

## Goal

Add a second form of `match` expression: one with no subject expression, where
each arm is a boolean guard condition instead of a value pattern, e.g.:

```
compare(x: Int, y: Int) -> Ordering =
  match
    | x > y => GT
    | x == y => EQ
    | _ => LT
```

This lets a function express a cascade of independent boolean conditions
without threading a placeholder subject through `match` or writing an
`if`/`else if`/`else` chain by hand. It is purely additive: the existing
subject-ful `match` form (`match expr \n  pattern => body`) is completely
unchanged.

## Non-goals

- No new stdlib types (no `Ordering` enum) — `GT`/`EQ`/`LT` in the example
  above are illustrative; a caller brings their own type.
- No exhaustiveness *proof* for guard matches — guard conditions are
  arbitrary runtime booleans, not statically enumerable like an enum's
  variants, so there is no compile-time exhaustiveness check for this form
  (mirrors how today's pattern-match exhaustiveness check is itself only a
  codegen-time affordance for enums with no wildcard, not a hard error).
- No change to the `fn` keyword, parameter syntax, or case-body arrow
  (`=>`) — this spec is scoped to guard-clause arms only, reusing every
  other piece of existing syntax as-is.

## Current state

- `match`'s grammar (`tooling/tree-sitter-plum/grammar.js`, `match` rule) requires
  one or more subject expressions (`commaSep1(field("subject", $.expression))`,
  no `optional()`); there is no subject-less form today.
- `case`'s patterns (`case_pattern` rule) are literals, constructor patterns,
  dotted names, bare names, or `_` — never a full boolean expression like `x > y`.
- `plum-core/src/ast.rs`'s `CasePattern` enum has no variant for an arbitrary
  expression.
- `plum-checker`'s `check_match` type-checks each case's patterns against the
  subject types 1:1, erroring if the counts don't match; there is no code path
  for zero subjects today.
- `plum-wasm-codegen`'s `compile_match` always evaluates and scratch-stores
  every subject, then dispatches per-pattern-kind (int/string/float/class/name/
  wildcard) with constructor-fallthrough logic — considerably more machinery
  than a guard match needs.

## Design

### Grammar

`match` gains a second alternative via `choice`, disambiguated by whether the
line has a subject expression before the indent:

```js
match: ($) =>
  prec.left(
    choice(
      seq(
        "match",
        commaSep1(field("subject", $.expression)),
        $._indent,
        repeat(field("case", $.case)),
        $._dedent,
      ),
      seq(
        "match",
        $._indent,
        repeat(field("case", $.guard_case)),
        $._dedent,
      ),
    ),
  ),

guard_case: ($) =>
  seq(
    "|",
    field("guard", choice($.expression, "_")),
    "=>",
    field("body", choice($.expression, $.body)),
  ),
```

The existing `case`/`case_pattern`/`class_pattern` rules are untouched. Guard
arms are a structurally distinct rule (`guard_case`), not a new
`case_pattern` alternative — a guard is a full expression (`x > y`, `x == y`),
never a literal/constructor/name pattern, so keeping the two arm kinds as
separate grammar rules avoids any ambiguity between "is this a pattern or an
expression" at parse time.

### AST

One new variant on the existing `CasePattern` enum
(`plum-core/src/ast.rs`):

```rust
pub enum CasePattern {
    Class { name: String, fields: Vec<CasePattern> },
    String(String),
    Int(i64),
    Float(f64),
    Name(String),
    Wildcard,
    Guard(Expr),
}
```

No new top-level struct. A subject-less `match` parses to the existing
`Match { subjects: vec![], cases }` shape, where each `Case` has exactly one
pattern: either `CasePattern::Guard(expr)` for a boolean condition, or
`CasePattern::Wildcard` for a bare `_` guard arm (the parser recognizes the
literal `_` token in guard position and emits the existing `Wildcard`
variant — not a `Guard` wrapping a trivial "true" expression — so every other
part of the pipeline that already knows how to handle `Wildcard` needs no new
knowledge of "guard-flavored wildcards").

`plum-core/src/parser.rs` gains a `guard_case`-parsing branch (parallel to
today's `case` parsing) that builds a `Case` with one `CasePattern::Guard` or
`CasePattern::Wildcard` pattern from each `guard_case` node, and `parse_match`
is extended so an empty subject list is valid (today's subject-collection
logic already just slices "named children before the first case node," so an
empty slice naturally falls out — no structural change needed there, only the
grammar's `optional`-equivalent `choice` unlocks it).

### Checker

`check_match` (`plum-checker/src/lib.rs`) branches on `m.subjects.is_empty()`:

- **Subject-ful (today's path, unchanged):** infer each subject's type, zip
  patterns against subject types 1:1, `check_pattern` as today.
- **Guard (new path):** for each case (exactly one pattern per case, enforced
  by the grammar), if the pattern is `CasePattern::Guard(expr)`, infer `expr`'s
  type via `infer_expr` and unify it against `PlumType::TBool`, producing a
  type error if a guard isn't boolean (e.g. `| x + 1 => ...`). If the pattern
  is `CasePattern::Wildcard`, no type-check is needed (matches everything, same
  as today's wildcard-pattern meaning). Every arm's body is still
  `check_block`-ed against `declared_ret` exactly as today — this already
  enforces that all arms return a consistent type, no new "unify across arms"
  step is needed.

### Codegen

`plum-wasm-codegen` compiles a guard match as an if/else-if chain, reusing
whatever codegen the `if`/`else if`/`else` statement already uses (not routed
through `compile_match_arms_multi`'s subject-scratch-slot machinery, which
this form has no use for — no subject to evaluate/store, no destructuring, no
per-pattern-kind branching). Each `CasePattern::Guard(expr)` arm compiles its
guard as the `if`/`else if` condition and its body as that branch's body; a
`CasePattern::Wildcard` arm (if present) becomes the chain's trailing `else`.
If no `Wildcard` arm is present and every guard evaluates false at runtime,
the chain falls through to `Unreachable` (a trap) — consistent with today's
non-exhaustive pattern-match behavior, just determined at runtime instead of
compile time, since guard conditions aren't statically enumerable.

### Testing strategy

- Tree-sitter corpus (`tooling/tree-sitter-plum/test/corpus/match.txt`): add
  cases for a subject-less guard match (with and without a trailing `_`
  arm), verifying the new `guard_case` node shape.
- `plum-core` parser tests: add coverage for the new `guard_case` parsing
  path (note: the survey found no dedicated existing `match` test in
  `parser_test.rs` today — this is a good opportunity to add the first one,
  scoped to this feature).
- `plum-checker` tests: a guard match with all-boolean guards type-checks;
  a non-boolean guard (e.g. `| x + 1 => ...`) produces a type error; a guard
  match with inconsistent arm-body return types produces the same kind of
  error today's subject-ful match already produces for that case.
- `plum-wasm-codegen` tests: a guard match with a `_` fallback runs and
  returns the expected arm's value for several inputs; a guard match with NO
  `_` fallback traps at runtime when no guard is true (mirrors the existing
  non-exhaustive-match trap test pattern already used for enum matches,
  per the survey's note on `codegen_tests.rs`'s existing non-exhaustive-match
  coverage).