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 operator, rather than simple assignment.

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

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 /

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

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

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

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 will be evaluated, as stops looking after the first match):

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 result and an result, for example, inserted into a database.

Here is how we can use it for better readability:

Pattern Matching Objects in Ruby

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

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:

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. or 2. Without the type specification, e.g. or . 3. Without the variable name, which defaults to using the key name, e.g. will define a variable named with the value at key . 4. Bind rest, e.g. or .

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:

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

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”:

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 and , we can define on the class:

The argument to 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 , we could provide an implementation of to allow objects to be pattern matched as an array. For example, let's say we have a class that has latitude and longitude. In addition to using to provide latitude and longitude keys, we could expose an array in the form of as well:

Using Guards for Complex Patterns

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

Pattern Matching with / Without

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:

Given that the above syntax does not have an 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:

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 / ) is still experimental. With Ruby 3, / has moved to stable while the newly introduced single-line pattern matching expressions are experimental. Warnings can be turned off with in code or 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.

Originally published at on July 28, 2021.

Error tracking and performance insights for Ruby and Elixir without the silly per-host pricing. From Amsterdam with love.

Error tracking and performance insights for Ruby and Elixir without the silly per-host pricing. From Amsterdam with love.