An Introduction to Pattern Matching in Ruby

Let's start with a brief discussion about pattern matching in Ruby, what it does, and how it can help improve code readability.

If you are anything like me a few years ago, you might confuse it with pattern matching in Regex. Even a quick Google search of 'pattern matching' with no other context brings you content that's pretty close to that definition.

Formally, pattern matching is the process of checking any data (be it a sequence of characters, a series of tokens, a tuple, or anything else) against other data.

In terms of programming, depending on the capabilities of the language, this could mean any of the following:

1. Matching against an expected data type
2. Matching against an expected hash structure (e.g. presence of specific keys)
3. Matching against an expected array length
4. Assigning the matches (or a part of them) to some variables

My first foray into pattern matching was through Elixir. Elixir has first class support for pattern matching, so much so that the = operator is, in fact, the match operator, rather than simple assignment.

This means that in Elixir, the following is actually valid code:

iex> x = 1
iex> 1 = x

With that in mind, let's look at the new pattern matching support for Ruby 2.7+ and how we can use it to make our code more readable, starting from today.

Ruby Pattern Matching with case/in

Ruby supports pattern matching with a special case/in expression. The syntax is:

case <expression>
in <pattern1>
  # ...
in <pattern2>
  # ...
else
  # ...
end

This is not to be confused with the case/when expression. when and in branches cannot be mixed in a single case.

If you do not provide an else expression, any failing match will raise a NoMatchingPatternError.

Pattern Matching Arrays in Ruby

Pattern matching can be used to match arrays to pre-required structures against data types, lengths or values.

For example, all of the following are matches (note that only the first in will be evaluated, as case stops looking after the first match):

case [1, 2, "Three"]
in [Integer, Integer, String]
  "matches"
in [1, 2, "Three"]
  "matches"
in [Integer, *]
  "matches" # because * is a spread operator that matches anything
in [a, *]
  "matches" # and the value of the variable a is now 1
end

This type of pattern matching clause is very useful when you want to produce multiple signals from a method call.

In the Elixir world, this is frequently used when performing operations that could have both an :ok result and an :error result, for example, inserted into a database.

Here is how we can use it for better readability:

def create
  case save(model_params)
  in [:ok, model]
    render :json => model
  in [:error, errors]
    render :json => errors
  end
end

# Somewhere in your code, e.g. inside a global helper or your model base class (with a different name).
def save(attrs)
  model = Model.new(attrs)
  model.save ? [:ok, model] : [:error, model.errors]
end

Pattern Matching Objects in Ruby

You can also match objects in Ruby to enforce a specific structure:

case {a: 1, b: 2}
in {a: Integer}
  "matches" # By default, all object matches are partial
in {a: Integer, **}
  "matches" # and is same as {a: Integer}
in {a: a}
  "matches" # and the value of variable a is now 1
in {a: Integer => a}
  "matches" # and the value of variable a is now 1
in {a: 1, b: b}
  "matches" # and the value of variable b is now 2
in {a: Integer, **nil}
  "does not match" # This will match only if the object has a and no other keys
end

This works great when imposing strong rules for matching against any params.

For example, if you are writing a fancy greeter, it could have the following (strongly opinionated) structure:

def greet(hash = {})
  case hash
  in {greeting: greeting, first_name: first_name, last_name: last_name}
    greet(greeting: greeting, name: "#{first_name} #{last_name}")
  in {greeting: greeting, name: name}
    puts "#{greeting}, #{name}"
  in {name: name}
    greet(greeting: "Hello", name: name)
  in {greeting: greeting}
    greet(greeting: greeting, name: "Anonymous")
  else
    greet(greeting: "Hello", name: "Anonymous")
  end
end

greet # Hello, Anonymous
greet(name: "John") # Hello, John
greet(first_name: "John", last_name: "Doe") # Hello, John Doe
greet(greeting: "Bonjour", first_name: "John", last_name: "Doe") # Bonjour, John Doe
greet(greeting: "Bonjour") # Bonjour, Anonymous

Variable Binding and Pinning in Ruby

As we have seen in some of the above examples, pattern matching is really useful in assigning part of the patterns to arbitrary variables.
This is called variable binding, and there are several ways we can bind to a variable:

1. With a strong type match, e.g. in [Integer => a] or in {a: Integer => a}
2. Without the type specification, e.g. in [a, 1, 2] or in {a: a}.
3. Without the variable name, which defaults to using the key name, e.g. in {a:} will define a variable named a with the value at key a.
4. Bind rest, e.g. in [Integer, *rest] or in {a: Integer, **rest}.

How, then, can we match when we want to use an existing variable as a sub-pattern? This is when we can use variable pinning with the ^ (pin) operator:

a = 1
case {a: 1, b: 2}
in {a: ^a}
  "matches"
end

You can even use this when a variable is defined in a pattern itself, allowing you to write powerful patterns like this:

case order
in {billing_address: {city:}, shipping_address: {city: ^city}}
  puts "both billing and shipping are to the same city"
else
  raise "both billing and shipping must be to the same city"
end

One important quirk to mention with variable binding is that even if the pattern doesn't fully match, the variable will still have been bound.
This can sometimes be useful.

But, in most cases, this could also be a cause of subtle bugs — so make sure that you don't rely on shadowed variable values that have been used inside a match.
For example, in the following, you would expect the city to be "Amsterdam", but it would instead be "Berlin":

city = "Amsterdam"
order = {billing_address: {city: "Berlin"}, shipping_address: {city: "Zurich"}}
case order
in {billing_address: {city:}, shipping_address: {city: ^city}}
  puts "both billing and shipping are to the same city"
else
  puts "both billing and shipping must be to the same city"
end
puts city # Berlin instead of Amsterdam

Matching Ruby's Custom Classes

You can implement some special methods to make custom classes pattern matching aware in Ruby.

For example, to pattern match a user against his first_name and last_name, we can define deconstruct_keys on the class:

class User
  def deconstruct_keys(keys)
    {first_name: first_name, last_name: last_name}
  end
end

case user
in {first_name: "John"}
  puts "Hey, John"
end

The keys argument to deconstruct_keys contains the keys that have been requested in the pattern.
This is a way for the receiver to provide only the required keys if computing all of them is expensive.

In the same way as deconstruct_keys, we could provide an implementation of deconstruct to allow objects to be pattern matched as an array.
For example, let's say we have a Location class that has latitude and longitude. In addition to using deconstruct_keys to provide latitude and longitude keys, we could expose an array in the form of [latitude, longitude] as well:

class Location
  def deconstruct
    [latitude, longitude]
  end
end

case location
in [Float => latitude, Float => longitude]
  puts "#{latitude}, #{longitude}"
end

Using Guards for Complex Patterns

If we have complex patterns that cannot be represented with regular pattern match operators, we can also use an if (or unless) statement to provide a guard for the match:

case [1, 2]
in [a, b] if b == a * 2
  "matches"
else
  "no match"
end

Pattern Matching with =>/in Without case

If you are on Ruby 3+, you have access to even more pattern matching magic. Starting from Ruby 3, pattern matching can be done in a single line without a case statement:

[1, 2, "Three"] => [Integer => one, two, String => three]
puts one # 1
puts two # 2
puts three # Three

# Same as above
[1, 2, "Three"] in [Integer => one, two, String => three]

Given that the above syntax does not have an else clause, it is most useful when the data structure is known beforehand.

As an example, this pattern could fit well inside a base controller that allows only admin users:

class AdminController < AuthenticatedController
  before_action :verify_admin

  private

  def verify_admin
    Current.user => {role: :admin}
  rescue NoMatchingPatternError
    raise NotAllowedError
  end
end

Pattern Matching in Ruby: Watch This Space

At first, pattern matching can feel a bit strange to grasp.
To some, it might feel like glorified object/array deconstruction.

But if the popularity of Elixir is any indication, pattern matching is a great tool to have in your arsenal.
Having first-hand experience using it on Elixir, I can confirm that it is hard to live without once you get used to it.

If you are on Ruby 2.7, pattern matching (with case/in) is still experimental. With Ruby 3, case/in has moved to stable while the newly introduced single-line pattern matching expressions are experimental.
Warnings can be turned off with Warning[:experimental] = false in code or -W:no-experimental command-line key.

Even though pattern matching in Ruby is still in its early stages, I hope you've found this introduction useful and that you're as excited as I am about future developments to come!

P.S. If you’d like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Our guest author Pulkit is a senior full-stack engineer and consultant. In his free time, he writes about his experiences on his blog.