An Introduction to Pattern Matching in Ruby
Published: 2021-08-04 13:46:31

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](https://elixir-lang.org/getting-started/pattern-matching.html) 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:

```elixir
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:

```ruby
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):

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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":

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
[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:

```ruby
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](https://blog.appsignal.com/#ruby-magic)!**

*Our guest author Pulkit is a senior full-stack engineer and consultant. In his free time, he writes about his experiences on [his blog](https://pulkitgoyal.in/).*