Matching
Gale matches values by shape. Each arm pairs a pattern with a result. The first pattern that fits wins. The compiler rejects a case that leaves a shape uncovered.
A name in a pattern binds a new value. Pin it with ^ to compare against a
value already in scope. Use separate arms for separate patterns.
"GET " <> rest binds the rest of a string.
value when value in [:debug, :info] narrows an atom in a guard.
Patterns extract fields and select branches by value or shape. The compiler
checks that case covers every value allowed by the matched type.
Case, and the coverage guarantee
Section titled “Case, and the coverage guarantee”mod matching
pub fn describe(status: :idle | :running | :done) -> String { case status { :idle -> "waiting" :running -> "busy" :done -> "finished" }}case walks its arms top to bottom and picks the first pattern that fits the
value. Cover every shape of the matched type, as the complete match above does.
A literal arm matches one value. A guard (when) attaches a Boolean test to
an arm: the arm wins only when the pattern fits and the test holds. _
fits anything, which makes it the standard closing arm:
mod matching
pub fn stock(count: Integer) -> String { case count { 0 -> "empty" n when n < 10 -> "low" _ -> "many" }}Constructor patterns narrow by payload too. For type Box<A> = Wrap(A),
arms for Wrap(1) and Wrap(2) cover Box<1 | 2>; a Box<Integer> still
needs Wrap(_) for every other integer. (A raw atom inside a Term never
establishes membership in a nominal data type; decode it first.) The same
patterns work in function heads and in infallible bindings.
Bindings bind; pins compare
Section titled “Bindings bind; pins compare”A name written in a pattern is a new binding for whatever value sits at
that position. It never compares against anything you already hold. _
ignores a position:
mod matching
pub type Entry = {Integer, String}
pub fn name_of(entry: Entry) -> String { case entry { {_, name} -> name }}
pub fn first(items: List<Integer>, fallback: Integer) -> Integer { case items { [] -> fallback [head | _] -> head }}{wanted, _} matches every entry and names the first element
wanted. To compare a position against a value you already hold, pin
the name with ^. A pin binds nothing; the arm fits only when the position
equals the pinned value when the case starts:
mod matching
pub type Entry = {Integer, String}
pub fn has_id(entry: Entry, wanted: Integer) -> Boolean { case entry { {^wanted, _} -> true _ -> false }}A pinned arm can fail on a value its shape admits, so it needs a fallback.
The _ above covers the remaining values. The same ^name works anywhere a
pattern does, including receive, where pinning a reply tag lets a process
skip messages it is not waiting for (processes).
Two syntax notes carried over from Elixir: | inside a pattern is the
list-tail marker, not an alternative operator. Write one arm per
alternative. And repeated names in a single pattern compare strictly against
the first binding; rebinding a name later creates a new identity, while
captures and pins refer to the version at their source location.
Text and atom patterns
Section titled “Text and atom patterns”A prefix string pattern matches a non-empty literal and binds the rest.
On a String scrutinee, rest is String. On Binary or Term it is
Binary; matching text at the front does not make the remaining bytes
valid UTF-8. On a finite string type like "GET a" | "GET b", the prefix
covers both alternatives and types rest as "a" | "b":
mod matching
pub fn verb(line: String) -> String { case line { "GET " <> rest -> rest _ -> line }}in [atoms] is a guard; when every literal is an atom, the bound value is
refined to that atom union inside the arm:
mod matching
pub fn shown?(level: Atom) -> Boolean { case level { value when value in [:debug, :info, :warning] -> true _ -> false }}Multiple conditions
Section titled “Multiple conditions”When the decision is about conditions rather than shapes, cond picks the
first true one. Each condition must be Boolean, and the last must be the
literal true:
pub fn sign(value: Integer) -> Integer { cond { value > 0 -> 1 value < 0 -> -1 true -> 0 }}Limits
Section titled “Limits”- A guard that fails rejects its clause; it does not raise. Runtime guard tests observe only representation: byte alignment is not UTF-8 validity, and a function’s arity is not its signature.
- Content restrictions (a pinned value, a specific prefix, bit sizes) normally require a fallback arm, because the compiler conservatively assumes they can fail.
- Selective
receiveintentionally handles only selected mailbox messages; the others stay queued (processes).