_{Official ZPE/YASS documentation}Matcher expressions

ZPE 1.14.9 (Spurriergate, September 2026) added support for the matcher expression. A matcher is a reusable, first-class callable value built from a set of compiled match branches.

Unlike an ordinary match expression, a matcher does not select a value when it is declared. Instead, it can be stored in a variable and called repeatedly with different input values.

$status = matcher(
  200 => "OK";
  404 => "Not found";
  500 => "Server error";
  else => "Unknown";
)

print($status(404))
print($status(200))
    

The example outputs "Not found" and "OK". The value passed to the matcher is its single implicit input parameter.

Reusable compiled branches

A matcher stores its result expressions in compiled form. Once a value has been resolved, the selected branch is cached so subsequent calls with the same value do not need to scan every branch again. Inputs which do not match a branch are also cached.

Only the selected result expression is evaluated. The expressions belonging to all other branches are skipped.

$formatter = matcher(
  "short" => make_short_label();
  "long" => make_long_label();
  else => "Unknown format";
)

print($formatter("short"))
    

In this example, make_long_label is not called.

Capturing surrounding values

Matchers are callable values and may capture values from their surrounding scope in the same way as other YASS closures.

$suffix = "!"
$response = matcher(
  200 => "OK" & $suffix;
  404 => "Not found" & $suffix;
)

print($response(200))
    

The else branch

An else branch may be placed after the keyed branches. It is evaluated lazily only when no key matches.

$number_name = matcher(
  1 => "one";
  2 => "two";
  else => "another number";
)

print($number_name(5))
    

The else branch is optional. If it is omitted and no key matches, the matcher returns null.

Matcher keys

Matcher keys must be literals. Strings, integers, real numbers, booleans, null, and negative numeric literals are supported. Function calls, variables, and other dynamic expressions cannot be used as matcher keys.

Each key must be unique. Duplicate keys are reported as compilation errors rather than being silently ignored.

$valid = matcher(
  1 => "one";
  "ready" => true;
  null => "no value";
)
    

Match and matcher

Use match when a value needs to be selected immediately and its candidate expressions may be dynamic:

$result = match($value :
  1 => "one";
  else => "other";
)
    

Use matcher when the same fixed set of literal keys will be used repeatedly:

$lookup = matcher(
  1 => "one";
  else => "other";
)

$first = $lookup(1)
$second = $lookup(2)
    

Passing matchers around

Since a matcher is a first-class callable value, it can be assigned to another variable, passed as an argument, returned from a function, or stored as an object property.

function use_matcher($lookup, $value)
  return $lookup($value)
end function

$lookup = matcher(
  "yes" => true;
  "no" => false;
)

print(use_matcher($lookup, "yes"))