Pattern Matching

# frozen_string_literal: true

config = { db: { user: "admin", host: "localhost", port: 5432 } }

# 1. case/in picks a branch and binds variables.
case config
in { db: { user:, host: } }
  puts "connect #{user}@#{host}"
in { database: { username: } }
  puts "legacy key, user #{username}"
else
  puts "unrecognised shape"
end

# 2. => unpacks or raises when the shape is wrong.
config => { db: { port: } }
puts "port #{port}"

# 3. in answers true or false.
puts((config in { db: { port: Integer } }))
puts((config in { db: { port: String } }))

connect admin@localhost
port 5432
true
false

# frozen_string_literal: true

def classify(value)
  case value
  in Integer then "integer"
  in String then "string"
  end
end

puts classify(1)
begin
  classify(:sym)
rescue NoMatchingPatternError => e
  puts "#{e.class}: #{e.message}"
end

def classify_total(value)
  case value
  in Integer then "integer"
  else "other"
  end
end

puts classify_total(:sym)

begin
  { title: "Dune" } => { title: String, year: }
  puts year
rescue NoMatchingPatternKeyError => e
  puts "#{e.class}: #{e.message}"
  puts "key=#{e.key.inspect} matchee=#{e.matchee.inspect}"
end
p NoMatchingPatternKeyError.ancestors.take(3)

integer
NoMatchingPatternError: sym
other
NoMatchingPatternKeyError: {title: "Dune"}: key not found: :year
key=:year matchee={title: "Dune"}
[DidYouMean::Correctable, NoMatchingPatternKeyError, NoMatchingPatternError]

# frozen_string_literal: true

ALLOWED = Set[:available, :lent].freeze

[0, 7, 42, -3, 2.5, "", "123", "abc", :overdue, :available, nil, [1], 1 / 3r].each do |value|
  label =
    case value
    in 0 then "zero"
    in 1..9 then "digit"
    in 10.. then "large"
    in ..-1 then "negative"
    in "" then "empty string"
    in /\A\d+\z/ then "numeric string"
    in String then "string"
    in :overdue then "overdue symbol"
    in ALLOWED then "allowed state"
    in nil then "nothing"
    in ->(x) { x.respond_to?(:each) } then "iterable"
    else "something else"
    end
  puts "#{value.inspect} -> #{label}"
end

0 -> zero
7 -> digit
42 -> large
-3 -> negative
2.5 -> digit
"" -> empty string
"123" -> numeric string
"abc" -> string
:overdue -> overdue symbol
:available -> allowed state
nil -> nothing
[1] -> iterable
(1/3) -> something else

# frozen_string_literal: true

def describe(row)
  case row
  in [] then "empty row"
  in [String => title] then "title only: #{title}"
  in [String => title, Integer => year] then "#{title} (#{year})"
  in [String => title, Integer => year, *tags] then "#{title} (#{year}) tagged #{tags.join(', ')}"
  in [_, _, _, *] then "unexpected extra columns"
  else "not a row"
  end
end

puts describe([])
puts describe(["Dune"])
puts describe(["Dune", 1965])
puts describe(["Dune", 1965, "sf", "classic"])
puts describe([1965, "Dune"])
puts describe("Dune")

# Brackets are optional, and a leading element can be split from the rest.
case ["978-0-306-40615-7", "The Dispossessed", 1974]
in String => isbn, String => title, Integer => year
  puts "#{isbn}: #{title}, #{year}"
end

first, *rest = [1, 2, 3]
[1, 2, 3] => head, *tail
p [first, rest, head, tail]

# The splat can sit anywhere, once.
case [1, 2, 3, 4, 5]
in [first_item, *middle, last_item]
  p [first_item, middle, last_item]
end

empty row
title only: Dune
Dune (1965)
Dune (1965) tagged sf, classic
not a row
not a row
978-0-306-40615-7: The Dispossessed, 1974
[1, [2, 3], 1, [2, 3]]
[1, [2, 3, 4], 5]

# frozen_string_literal: true

require "shelf"

author = Shelf::Author.new("Ursula K. Le Guin")
isbn = Shelf::Isbn.new("978-0-306-40615-7")
book = Shelf::Book.new(isbn:, title: "The Dispossessed", author:)

events = [:created, :lent, "note: damaged cover", :returned, "note: repaired"]

case events
in [*before, String => note, *after]
  puts "first note: #{note}"
  puts "before: #{before.inspect}"
  puts "after: #{after.inspect}"
end

case events
in [*, :lent, String => remark, *]
  puts "#{book.title} was lent, then noted: #{remark}"
end

puts((events in [*, :overdue, *]))

case [1, 42, "x", 7, "y"]
in [*, Integer => n, String => s, *]
  puts "first Integer followed by a String: #{n}, #{s}"
end

first note: note: damaged cover
before: [:created, :lent]
after: [:returned, "note: repaired"]
The Dispossessed was lent, then noted: note: damaged cover
false
first Integer followed by a String: 42, x

# frozen_string_literal: true

entry = { title: "Dune", year: 1965, tags: %w[sf classic] }

case entry
in { title: String => title }
  puts "extra keys are fine: #{title}"
end

case entry
in { title:, **nil }
  puts "never reached"
in { title:, year:, tags:, **nil }
  puts "closed pattern matched: #{title}, #{year}, #{tags}"
end

case entry
in { title:, **others }
  puts "title #{title}, others #{others}"
end

puts((entry in {}))
puts(({} in {}))

# Only symbol keys are matched; a string key never matches.
puts(({ "title" => "Dune" } in { title: "Dune" }))
puts(({ "content-type": "text/plain" } in { "content-type": String }))

# Nested hashes and arrays compose.
case { name: "Ada", loans: [{ title: "Dune" }, { title: "Emma" }] }
in { name:, loans: [{ title: first_title }, *] }
  puts "#{name} first borrowed #{first_title}"
end

extra keys are fine: Dune
closed pattern matched: Dune, 1965, ["sf", "classic"]
title Dune, others {year: 1965, tags: ["sf", "classic"]}
false
true
false
true
Ada first borrowed Dune

# frozen_string_literal: true

[1, 2.5, "3", :four, nil].each do |value|
  case value
  in Integer | Float => number
    puts "number #{number}"
  in String | Symbol => text
    puts "text #{text}"
  else
    puts "neither: #{value.inspect}"
  end
end

# A variable inside an alternative is a syntax error.
begin
  RubyVM::InstructionSequence.compile("case 1\nin a | 2 then a\nend", "alternative.rb")
rescue SyntaxError => e
  puts e.message
end

# Variables starting with an underscore are allowed there.
case [1, 2]
in [_first, _second] | [_, _, _]
  puts "two or three items"
end

# Bare names bind; they never compare.
expected = 18
case [1, 2]
in [expected, *]
  puts "matched, expected is now #{expected}"
end

number 1
number 2.5
text 3
text four
neither: nil
alternative.rb:2: syntax error found
  1 | case 1
> 2 | in a | 2 then a
    |    ^ variable capture in alternative pattern
  3 | end
two or three items
matched, expected is now 1

# frozen_string_literal: true

expected = 18
pair = [1, 2]
case pair
in [^expected, *]
  puts "matched"
else
  puts "not matched, expected is still #{expected}"
end

# rubocop:disable Style/GlobalVars, Style/ClassVars
$limit = 2
class Window
  @size = 3
  @@depth = 4

  def self.check(values)
    case values
    in [^$limit, ^@size, ^@@depth]
      "globals, ivars and class variables can be pinned"
    else
      "no match"
    end
  end
end
puts Window.check([2, 3, 4])
# rubocop:enable Style/GlobalVars, Style/ClassVars

a = 1
b = 2
total = 3
case total
in ^(a + b)
  puts "an expression can be pinned"
end

# Pin makes two positions agree.
pairs = [%i[lent lent], %i[lent returned]]
pairs.each do |pair|
  case pair
  in [state, ^state] then puts "#{pair.inspect}: same state twice"
  else puts "#{pair.inspect}: different states"
  end
end

begin
  RubyVM::InstructionSequence.compile("case 1\nin ^missing then 2\nend", "pin.rb")
rescue SyntaxError => e
  puts e.message
end

not matched, expected is still 18
globals, ivars and class variables can be pinned
an expression can be pinned
[:lent, :lent]: same state twice
[:lent, :returned]: different states
pin.rb:2: syntax error found
  1 | case 1
> 2 | in ^missing then 2
    |     ^~~~~~~ missing: no such local variable
  3 | end

# frozen_string_literal: true

[[:lent, 3], [:lent, 20], [:returned, 0], [:overdue, 40]].each do |pair|
  label =
    case pair
    in [:lent, days] if days > 14 then "lent too long (#{days} days)"
    in [:lent, days] then "lent for #{days} days"
    in [state, days] unless days.zero? then "#{state}, #{days} days"
    in [state, _] then state.to_s
    end
  puts label
end

# Guards belong to case/in only. After => or in, "if" is a plain modifier,
# evaluated first, so the pattern variables are still nil.
begin
  pair = [1, 1]
  result = (pair in [first, second]) if second == first * 2
  p result
rescue NoMethodError => e
  puts e.message
end

lent for 3 days
lent too long (20 days)
returned
overdue, 40 days
undefined method '*' for nil

# frozen_string_literal: true

Loan = Struct.new(:title, :state, :days)
loans = [
  Loan.new("Dune", :lent, 3),
  Loan.new("Emma", :overdue, 40),
  Loan.new("Kim", :lent, 20),
  Loan.new("Ulysses", :returned, 0)
]

# in answers a yes/no question, so it works as a block predicate.
p(loans.count { it in { state: :lent } })
p loans.select { it in { state: :overdue | :lent, days: 15.. } }.map(&:title)
late, fine = loans.partition { it in { days: 15.. } }
p [late.map(&:title), fine.map(&:title)]
p(loans.filter_map { |loan| loan.title if loan in { state: :returned } })

# => unpacks, and doubles as an assertion about the shape.
loans.first => { title:, days: }
puts "#{title}: #{days} days"

# Parentheses around the pattern are optional.
[0, 1] => _, last
p last
{ y: 2 } => y:
p y

# in has low precedence: wrap it in parentheses before combining it with
# && or ||, or when its result is used as a value.
value = 7
big_integer = (value in Integer) && value > 5
p big_integer
captured = value in Integer # assignment binds first: captured is value itself
p captured
if (value in Integer => n) && n.odd?
  puts "odd integer #{n}"
end

2
["Emma", "Kim"]
[["Emma", "Kim"], ["Dune", "Ulysses"]]
["Ulysses"]
Dune: 3 days
1
2
true
7
odd integer 7

# frozen_string_literal: true

# A loan receipt that can be matched as a list or as a hash.
class Receipt
  attr_reader :title, :state, :days

  def initialize(title, state, days)
    @title = title
    @state = state
    @days = days
  end

  def deconstruct
    puts "  deconstruct"
    [title, state, days]
  end

  def deconstruct_keys(keys)
    puts "  deconstruct_keys(#{keys.inspect})"
    { title:, state:, days: }
  end
end

LateReceipt = Class.new(Receipt) { def late? = true }

receipt = Receipt.new("Dune", :lent, 3)

case receipt
in [String => title, :lent, days]
  puts "array pattern: #{title}, #{days}"
end

case receipt
in { state: :lent, days: }
  puts "hash pattern: #{days}"
end

case receipt
in { state: :lent, **rest }
  puts "with **rest the keys argument is nil; rest = #{rest}"
end

# The constant in front is checked with ===, then the contents are matched.
case receipt
in Receipt(title:)
  puts "Receipt(...) form: #{title}"
end
case receipt
in LateReceipt[title:]
  puts "never reached"
else
  puts "a plain Receipt is not a LateReceipt"
end

# The methods must return the right type.
broken = Object.new
def broken.deconstruct = "not an array"
def broken.deconstruct_keys(_keys) = []

[-> { broken in [_] }, -> { broken in { a: _ } }].each do |attempt|
  attempt.call
rescue TypeError => e
  puts "#{e.class}: #{e.message}"
end

  deconstruct
array pattern: Dune, 3
  deconstruct_keys([:state, :days])
hash pattern: 3
  deconstruct_keys(nil)
with **rest the keys argument is nil; rest = {title: "Dune", days: 3}
  deconstruct_keys([:title])
Receipt(...) form: Dune
a plain Receipt is not a LateReceipt
TypeError: deconstruct must return Array
TypeError: deconstruct_keys must return Hash

# frozen_string_literal: true

require "shelf"

le_guin = Shelf::Author.new("Ursula K. Le Guin")
herbert = Shelf::Author.new("Frank Herbert")
books = [
  Shelf::Book.new(isbn: Shelf::Isbn.new("978-0-306-40615-7"), title: "The Dispossessed", author: le_guin),
  Shelf::Book.new(isbn: Shelf::Isbn.new("9780441172719"), title: "Dune", author: herbert)
]

# Data supports hash patterns, and positional patterns follow member order.
books.each do |book|
  case book
  in Shelf::Book[title:, author: Shelf::Author[name: /\AUrsula/]]
    puts "#{title}: by Ursula"
  in Shelf::Book[title:, isbn: { digits: /\A9780/ }]
    puts "#{title}: ISBN starts with 9780"
  end
end

# Unpack nested values with => and a single line.
books.first => { author: { name: }, isbn: { digits: } }
puts "#{name} / #{digits}"

# in as a filter; hash patterns on Data ignore the other members.
herbert_books = books.select { it in { author: { name: "Frank Herbert" } } }
puts herbert_books.map(&:title).inspect

# The domain object from the gem uses the same idea internally.
loan = Shelf::Loan.new(books.first, state: :overdue)
puts loan.describe

The Dispossessed: by Ursula
Dune: ISBN starts with 9780
Ursula K. Le Guin / 9780306406157
["Dune"]
The Dispossessed is overdue

# frozen_string_literal: true

# Pure transition function: (state, event) -> next state.
def transition(state, event)
  case [state, event]
  in [:available, :lend] then :lent
  in [:lent | :overdue, :expire] then :overdue
  in [:lent | :overdue, :return] then :returned
  in [:returned, :shelve] then :available
  in [_, :tick] then state
  else raise ArgumentError, "cannot #{event} while #{state}"
  end
end

state = :available
%i[lend tick expire return shelve].each do |event|
  following = transition(state, event)
  puts "#{state.to_s.ljust(9)} --#{event}--> #{following}"
  state = following
end

begin
  transition(:available, :return)
rescue ArgumentError => e
  puts "#{e.class}: #{e.message}"
end

available --lend--> lent
lent      --tick--> lent
lent      --expire--> overdue
overdue   --return--> returned
returned  --shelve--> available
ArgumentError: cannot return while available

# frozen_string_literal: true

require "json"

def describe_loan(type, data)
  case [type, data]
  in ["loan.created", { isbn:, member: { id: Integer => member_id } }]
    "lend #{isbn} to member #{member_id}"
  in ["loan.returned", { isbn:, late_days: Integer => late }] if late.positive?
    "return #{isbn}, #{late} days late"
  in ["loan.returned", { isbn: }]
    "return #{isbn} on time"
  end
end

def describe(event)
  case event
  in { type: "loan.created" | "loan.returned" => type, data: } then describe_loan(type, data)
  in { type: String => type } then "ignore unknown event #{type}"
  else "reject payload without a type"
  end
end

def handle(raw)
  describe(JSON.parse(raw, symbolize_names: true))
rescue JSON::ParserError
  "reject invalid JSON"
end

[
  '{"type":"loan.created","data":{"isbn":"9780441172719","member":{"id":7}}}',
  '{"type":"loan.returned","data":{"isbn":"9780441172719","late_days":3}}',
  '{"type":"loan.returned","data":{"isbn":"9780441172719","late_days":0}}',
  '{"type":"member.updated","data":{}}',
  '{"data":{}}',
  "[1, 2]",
  "not json"
].each { |raw| puts handle(raw) }

lend 9780441172719 to member 7
return 9780441172719, 3 days late
return 9780441172719 on time
ignore unknown event member.updated
reject payload without a type
reject payload without a type
reject invalid JSON

# frozen_string_literal: true

# The broken snippets also trigger unrelated void-context warnings; silence them.
$VERBOSE = nil

SNIPPETS = {
  "when and in mixed" => "case 1\nwhen 1 then puts(1)\nin 2 then puts(2)\nend",
  "variable in an alternative" => "case 1\nin a | 2 then puts(a)\nend",
  "same name twice" => "case [1, 2]\nin [a, a] then puts(a)\nend",
  "two splats, no anchor" => "case [1, 2]\nin [*a, *b] then puts(a, b)\nend",
  "second find splat" => "case [1, 2]\nin [*, 1, *, 2, *] then puts(1)\nend",
  "rest after **nil" => "case { a: 1 }\nin { a: 1, **nil, **r } then puts(r)\nend",
  "hash rocket in a hash pattern" => "case { a: 1 }\nin { \"a\" => 1 } then puts(1)\nend",
  "interpolated key" => "case { a: 1 }\nin { \"\#{1}a\": 1 } then puts(1)\nend",
  "pin of an unknown name" => "case 1\nin ^missing then puts(2)\nend",
  "subject and in on one line" => "case 1 in Integer then puts(1) end",
  "instance variable as a pattern" => "case 1\nin @size then puts(2)\nend"
}.freeze

SNIPPETS.each do |name, source|
  RubyVM::InstructionSequence.compile(source, "snippet.rb")
  puts "#{name}: compiled"
rescue SyntaxError => e
  puts "#{name}:"
  e.message.lines.grep(/\A\s*\|\s*\^/).first(2).each { |line| puts "  #{line.strip}" }
end

when and in mixed:
  | ^~ unexpected 'in', ignoring it
  |      ^~~~ unexpected 'then', ignoring it
variable in an alternative:
  |    ^ variable capture in alternative pattern
same name twice:
  |        ^ duplicated variable name
two splats, no anchor:
  |     ^~~~~~ find patterns need at least one required inner pattern
second find splat:
  |                 ^ unexpected rest pattern
rest after **nil:
  |                   ^~~ unexpected pattern expression after the `**` expression
hash rocket in a hash pattern:
  |    ^ expected a `}` to close the pattern expression
  |      ^~~ expected a label as the key in the hash pattern
interpolated key:
  |    ^ expected a `}` to close the pattern expression
  |      ^~~~~~~~ symbol literal with interpolation is not allowed
pin of an unknown name:
  |     ^~~~~~~ missing: no such local variable
subject and in on one line:
  | ^~~~ expected an `end` to close the `case` statement
  | ^~~~ expected a `when` or `in` clause after `case`
instance variable as a pattern:
  |   ^ expected a delimiter after the patterns of an `in` clause
  |    ^~~~~ expected a pattern expression after the `in` keyword

# frozen_string_literal: true

def show(label, matched) = puts("#{label}: #{matched}")

# The extra parentheses around "x in y" are needed inside an argument list.
show "hash with an extra key", ({ a: 1, b: 2 } in { a: 1 })
show "array with an extra item", ([1, 2] in [1])
show "nil value, bare key", ({ a: nil } in { a: _ })
show "missing key, bare key", ({} in { a: _ })
show "nil value, nil pattern", ({ a: nil } in { a: nil })
show "missing key, nil pattern", ({} in { a: nil })
show "string key", ({ "a" => 1 } in { a: 1 })
show "Float in an Integer range", (2.5 in 1..9)

STATES = %i[available lent].freeze
show "Array constant", (:lent in STATES)
ALLOWED = Set.new(STATES).freeze
show "Set built from it", (:lent in ALLOWED)

# A bare name is a catch-all: it matches anything, so it must come last.
case 5
in n then puts "the first branch binds #{n} whatever the value is"
end

# A failed branch can still have assigned some of its variables.
case [1, "x"]
in [Integer => number, Integer]
  puts "no"
in [Integer, String]
  puts "second branch; number is #{number.inspect}"
end

hash with an extra key: true
array with an extra item: false
nil value, bare key: true
missing key, bare key: false
nil value, nil pattern: true
missing key, nil pattern: false
string key: false
Float in an Integer range: true
Array constant: false
Set built from it: true
the first branch binds 5 whatever the value is
second branch; number is 1

# frozen_string_literal: true

config = { db: { user: "admin", port: 5432 } }
config => { db: { user:, port: } }
puts port

w.rb:4: warning: assigned but unused variable - user
5432