Pattern Matching in Ruby 3

Direct Answer

Ruby pattern matching checks the shape of structured data and can bind matched parts to local variables. A case expression uses in branches, such as in { type: "paid", order_id: }, to both verify the keys and capture order_id. Array patterns can separate a first value from the rest, guards add a condition, and the pin operator ^ compares with an existing variable instead of replacing it. A case/in without a matching branch or else raises NoMatchingPatternError, so use a fallback when unknown input is valid.

Deep Dive & Architecture

A pattern has two jobs: it rejects values with the wrong structure and exposes useful pieces from values that fit. Ruby first takes the expression after case, then tests the in branches from top to bottom. The first successful branch supplies its captured local variables to that branch body. when and in are different branch systems and cannot be mixed inside one case expression.

Value patterns rely on ===, so a class checks type, a range checks membership, and a literal checks its expected value. Variable names behave differently: in code assigns the matched value to code; it does not compare with a previous local variable of that name. Writing in ^expected_code changes the role to comparison. Guards such as if amount.positive? belong after the structural part and may use values just captured by the pattern.

Collection rules prevent subtle assumptions. An array pattern describes all positions unless * or *rest absorbs remaining elements. A hash pattern normally asks only for listed symbol keys and ignores other keys. Adding **nil states that no unknown keys are allowed. JSON parsers commonly produce string-keyed hashes, so code must symbolize keys deliberately or match another representation before using a hash pattern.

Standalone forms express two different intentions. payload => { user: { id: } } is an assertion plus unpacking operation and raises when the contract is broken. payload in { cached: true } produces true or false and is useful in a predicate. A multi-branch case/in is better when several valid shapes lead to different behaviour. Omitting both a successful branch and else makes the case exhaustive by raising NoMatchingPatternError.

User-defined objects can participate without being converted manually. Array-style matching asks an object for deconstruct; hash-style matching asks for deconstruct_keys. That is useful for domain value objects, but the returned structure becomes part of the object's public matching contract. It should expose stable meaning rather than private storage details.

Pattern matching improves code only when the visual shape helps the reader. Deep patterns repeated across handlers can become another form of coupling to external payloads. At an integration boundary, validate and normalize an incoming event once, then let the rest of the application work with a small domain object. This separates unreliable transport shape from dependable business behaviour.

Code Example

event = { type: 'paid', order_id: 42, amount: 1_500 }

message = case event
in { type: 'paid', order_id: Integer => id, amount: 1.. => cents }
  "capture order #{id} for #{cents} cents"
in { type: 'failed', order_id:, reason: }
  "order #{order_id} failed: #{reason}"
else
  'unsupported event'
end

puts message

expected_id = 42
matches_expected = event in { order_id: ^expected_id }
puts matches_expected # true; pin compares

Common Mistakes & Pitfalls

Using when instead of in (case/in, not case/when), or forgetting else (NoMatchingPatternError if no match).