Language Features /docs/match

Match

The match Construct

match is a control-flow expression that selects one of several branches by attempting to match a single scrutinee value against a series of patterns in source order. It is the structural-dispatch counterpart to pickup , which dispatches on free-standing boolean guards. Together, match and pickup are the only branching constructs in the language.

The construct is governed by a single mental model:

match walks the clauses and picks up the first one whose pattern matches the scrutinee.

match differs from pickup along two axes:

  • Pattern dispatch. Selection is by structural shape, not by predicate truth. Patterns may bind names from sub-positions of the scrutinee.
  • Decidable exhaustiveness. For algebraic data types and other finite-shape domains, the compiler computes coverage exactly via a Maranget-style algorithm and rejects non-exhaustive blocks at compile time.

Basic form

match value
  Number(n) -> n
  Person(_name) -> 0

Clauses are evaluated top to bottom; the first matching pattern wins. Each clause may carry a when guard:

match x
  n when n > 0 -> Positive()
  0            -> Zero()
  _            -> Negative()

Pattern positions

match is not the only place patterns appear. The same grammar is accepted by:

  • let bindings (including pattern-valued let , which introduces all narrowed bindings sequentially);
  • multi-clause function heads;
  • comprehension generators;
  • try ... catch clauses.

Pattern-position sigils

The following lexical sigils are recognized in pattern position and have no special meaning outside it:

  • _ — wildcard.
  • ^ — pin operator, followed by an identifier.
  • %[ ... ] — tuple pattern.
  • %{ ... } — map pattern.
  • << ... >> — binary pattern.

A _ followed immediately by an identifier (e.g. _unused ) is a silent binding , not a wildcard.

Reserved words

match and when are reserved keywords. They must not be used as identifiers, type names, module names, or labels. when is reserved globally; its only normative position is as the guard separator in a clause, but reservation prevents accidental shadowing elsewhere.

Exhaustiveness

A missing reachable constructor — at the top level of the scrutinee or at a tuple element position — is rejected under E118 (Pattern Coverage). This is a compile-time error: it blocks compilation. There is no separate flat/nested pass; both cases are reported under the same code.

Further reading