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:
- Matching against an expected data type
- Matching against an expected hash structure (e.g. presence of specific keys)
- Matching against an expected array length
- 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:
- With a strong type match, e.g.
in [Integer => a]
orin {a: Integer => a}
- Without the type specification, e.g.
in [a, 1, 2]
orin {a: a}
. - Without the variable name, which defaults to using the key name, e.g.
in {a:}
will define a variable nameda
with the value at keya
. - Bind rest, e.g.
in [Integer, *rest]
orin {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!