Skip to content

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.

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.

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.

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
}
}

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
}
}
  • 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 receive intentionally handles only selected mailbox messages; the others stay queued (processes).