hakorune/docs/reference/language/match-guards.md

Match Guards — Syntax and Lowering (MVP + Design Notes)

Status: reference + design additions during feature‑pause (no implementation changes)

Scope

• Guarded branches as a readable form of first-match selection.
• Canonical lowering target: if/else chain + PHI merges.

Syntax (MVP)

• Guard chain (first-match wins):

  guard <cond> -> { /* then */ }
  guard <cond> -> { /* then */ }
  else         -> { /* else */ }
  

• Conditions may combine comparisons, is/as type checks, and literals with && / ||.

Lowering

• Always lowers to a linear if/else chain with early exit on first true guard.
• Merge points use normal PHI formation invariants (see reference/mir/phi_invariants.md).

Design additions (frozen; docs only)

• Range Pattern (sugar):
  • guard x in '0'..'9' -> { ... }
  • Lowers to: ('0' <= x && x <= '9').
  • Multiple ranges: in A..B || C..D → OR of each bound check.
• CharClass (predefined sets):
  • Digit ≡ '0'..'9', AZ ≡ 'A'..'Z', az ≡ 'a'..'z', Alnum ≡ Digit || AZ || az, Space ≡ ' '\t\r\n (MVP set; expandable later).
  • guard ch in Digit -> { ... } expands to range checks.

Errors & Rules (MVP)

• Default _ branch does not accept guards.
• Type guard succeeds inside the then-branch; bindings (e.g., StringBox(s)) are introduced at branch head.
• Short-circuit semantics follow standard branch evaluation (right side is evaluated only if needed).

Observability (design)

• NYASH_FLOW_TRACE=1 may trace how guard chains desugar into if/else.

Notes

• This page describes existing guard semantics and adds range/charclass as documentation-only sugar during the feature‑pause.