Сопоставление с образцом

Сопоставление с образцом — это функция, позволяющая глубоко сопоставлять структурированные значения: проверять структуру и привязывать сопоставленные части к локальным переменным.

Сопоставление с образцом в Ruby реализуется с помощью выражения case/in:

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

(Обратите внимание, что ветви in и when НЕ могут быть смешаны в одном выражении case)

Или с оператором => и оператором in, которые могут использоваться в отдельном выражении:

<expression> => <pattern>

<expression> in <pattern>

Выражение case/in является полным: если значение выражения не соответствует ни одной ветви выражения case (и ветвь else отсутствует), поднимается NoMatchingPatternError.

Поэтому выражение case может использоваться для условного сопоставления и распаковки:

config = {db: {user: 'admin', password: 'abc123'}}

case config
in db: {user:} # matches subhash and puts matched value in variable user
  puts "Connect with user '#{user}'"
in connection: {username: }
  puts "Connect with user '#{username}'"
else
  puts "Unrecognized structure of config"
end
# Prints: "Connect with user 'admin'"

в то время как оператор => наиболее полезен, когда ожидаемая структура данных известна заранее, для простого распаковки ее частей:

config = {db: {user: 'admin', password: 'abc123'}}

config => {db: {user:}} # will raise if the config's structure is unexpected

puts "Connect with user '#{user}'"
# Prints: "Connect with user 'admin'"

<expression> in <pattern> эквивалентно case <expression>; in <pattern>; true; else false; end. Вы можете использовать его, когда вам нужно только узнать, был ли шаблон сопоставлен или нет:

users = [{name: "Alice", age: 12}, {name: "Bob", age: 23}]
users.any? {|user| user in {name: /B/, age: 20..} } #=> true

См. ниже для получения дополнительных примеров и объяснений синтаксиса.

Шаблоны

Шаблоны могут быть:

• любой объект Ruby (сопоставляется с оператором ===, как в when); (Шаблон значения)

• шаблон массива: [<subpattern>, <subpattern>, <subpattern>, ...]; (Шаблон массива)

• шаблон поиска: [*variable, <subpattern>, <subpattern>, <subpattern>, ..., *variable]; (Шаблон поиска)

• шаблон хэша: {key: <subpattern>, key: <subpattern>, ...}; (Шаблон хэша)

• комбинация шаблонов с |; (Альтернативный шаблон)

• захват переменной: <pattern> => variable или variable; (Шаблон как, Шаблон переменной)

Любой шаблон может быть вложен в шаблоны массива/поиска/хэша, где <subpattern> указан.

Array шаблоны и шаблоны поиска соответствуют массивам или объектам, которые отвечают на deconstruct (см. ниже об этом последнем). Hash шаблоны соответствуют хэшам или объектам, которые отвечают на deconstruct_keys (см. ниже об этом последнем). Обратите внимание, что для шаблонов хэша поддерживаются только символьные ключи.

Важное различие в поведении шаблонов массивов и хэшей заключается в том, что массивы соответствуют только целому массиву:

case [1, 2, 3]
in [Integer, Integer]
  "matched"
else
  "not matched"
end
#=> "not matched"

в то время как хэш соответствует даже если существуют другие ключи помимо указанной части:

case {a: 1, b: 2, c: 3}
in {a: Integer}
  "matched"
else
  "not matched"
end
#=> "matched"

{} является единственным исключением из этого правила. Он соответствует только если задан пустой хэш:

case {a: 1, b: 2, c: 3}
in {}
  "matched"
else
  "not matched"
end
#=> "not matched"

case {}
in {}
  "matched"
else
  "not matched"
end
#=> "matched"

Также есть способ указать, что в сопоставленном хэше не должно быть других ключей, кроме явно указанных в шаблоне, с помощью **nil:

case {a: 1, b: 2}
in {a: Integer, **nil} # this will not match the pattern having keys other than a:
  "matched a part"
in {a: Integer, b: Integer, **nil}
  "matched a whole"
else
  "not matched"
end
#=> "matched a whole"

И шаблоны массивов, и шаблоны хэшей поддерживают спецификацию «остаток»:

case [1, 2, 3]
in [Integer, *]
  "matched"
else
  "not matched"
end
#=> "matched"

case {a: 1, b: 2, c: 3}
in {a: Integer, **}
  "matched"
else
  "not matched"
end
#=> "matched"

Скобки вокруг обоих типов шаблонов можно опустить:

 case [1, 2]
 in Integer, Integer
   "matched"
 else
   "not matched"
 end
 #=> "matched"

 case {a: 1, b: 2, c: 3}
 in a: Integer
   "matched"
 else
   "not matched"
 end
 #=> "matched"

[1, 2] => a, b
[1, 2] in a, b

{a: 1, b: 2, c: 3} => a:
{a: 1, b: 2, c: 3} in a:

Find шаблон похож на шаблон массива, но он может использоваться для проверки наличия в данном объекте элементов, которые соответствуют шаблону:

case ["a", 1, "b", "c", 2]
in [*, String, String, *]
  "matched"
else
  "not matched"
end

Привязка переменных

Помимо глубокой проверки структуры, одной из очень важных функций сопоставления с образцом является привязка сопоставленных частей к локальным переменным. Основной формой привязки является просто указание => variable_name после сопоставленного (под)шаблона (можно найти это похожим на хранение исключений в локальных переменных в rescue ExceptionClass => var блоке):

case [1, 2]
in Integer => a, Integer
  "matched: #{a}"
else
  "not matched"
end
#=> "matched: 1"

case {a: 1, b: 2, c: 3}
in a: Integer => m
  "matched: #{m}"
else
  "not matched"
end
#=> "matched: 1"

Если не требуется дополнительная проверка, для привязки только части данных к переменной можно использовать более простой формат:

case [1, 2]
in a, Integer
  "matched: #{a}"
else
  "not matched"
end
#=> "matched: 1"

case {a: 1, b: 2, c: 3}
in a: m
  "matched: #{m}"
else
  "not matched"
end
#=> "matched: 1"

Для шаблонов хэшей существует еще более простой формат: спецификация только ключа (без каких-либо подшаблонов) привязывает локальную переменную к имени ключа тоже:

case {a: 1, b: 2, c: 3}
in a:
  "matched: #{a}"
else
  "not matched"
end
#=> "matched: 1"

Binding работает и для вложенных шаблонов:

case {name: 'John', friends: [{name: 'Jane'}, {name: 'Rajesh'}]}
in name:, friends: [{name: first_friend}, *]
  "matched: #{first_friend}"
else
  "not matched"
end
#=> "matched: Jane"

Часть «остаток» шаблона также может быть привязана к переменной:

case [1, 2, 3]
in a, *rest
  "matched: #{a}, #{rest}"
else
  "not matched"
end
#=> "matched: 1, [2, 3]"

case {a: 1, b: 2, c: 3}
in a:, **rest
  "matched: #{a}, #{rest}"
else
  "not matched"
end
#=> "matched: 1, {:b=>2, :c=>3}"

Binding к переменным в настоящее время НЕ работает для альтернативных шаблонов, соединенных с |:

case {a: 1, b: 2}
in {a: } | Array
  "matched: #{a}"
else
  "not matched"
end
# SyntaxError (illegal variable in alternative pattern (a))

Переменные, начинающиеся с _ — единственные исключения из этого правила:

case {a: 1, b: 2}
in {a: _, b: _foo} | Array
  "matched: #{_}, #{_foo}"
else
  "not matched"
end
# => "matched: 1, 2"

Однако не рекомендуется повторно использовать связанное значение, так как цель этого шаблона — обозначить отброшенное значение.

Привязка переменных

Из-за функции привязки переменных существующую локальную переменную нельзя напрямую использовать как подшаблон:

expectation = 18

case [1, 2]
in expectation, *rest
  "matched. expectation was: #{expectation}"
else
  "not matched. expectation was: #{expectation}"
end
# expected: "not matched. expectation was: 18"
# real: "matched. expectation was: 1" -- local variable just rewritten

В этом случае можно использовать оператор привязки ^, чтобы сказать Ruby «используйте это значение как часть шаблона»:

expectation = 18
case [1, 2]
in ^expectation, *rest
  "matched. expectation was: #{expectation}"
else
  "not matched. expectation was: #{expectation}"
end
#=> "not matched. expectation was: 18"

Одно важное использование привязки переменных — указание, что одно и то же значение должно встречаться в шаблоне несколько раз:

jane = {school: 'high', schools: [{id: 1, level: 'middle'}, {id: 2, level: 'high'}]}
john = {school: 'high', schools: [{id: 1, level: 'middle'}]}

case jane
in school:, schools: [*, {id:, level: ^school}] # select the last school, level should match
  "matched. school: #{id}"
else
  "not matched"
end
#=> "matched. school: 2"

case john # the specified school level is "high", but last school does not match
in school:, schools: [*, {id:, level: ^school}]
  "matched. school: #{id}"
else
  "not matched"
end
#=> "not matched"

Помимо привязки локальных переменных, вы также можете привязать экземпляры, глобальные и классовые переменные:

$gvar = 1
class A
  @ivar = 2
  @@cvar = 3
  case [1, 2, 3]
  in ^$gvar, ^@ivar, ^@@cvar
    "matched"
  else
    "not matched"
  end
  #=> "matched"
end

Вы также можете привязать результат произвольных выражений, используя скобки:

a = 1
b = 2
case 3
in ^(a + b)
  "matched"
else
  "not matched"
end
#=> "matched"

Сопоставление не примитивных объектов: deconstruct и deconstruct_keys

Как уже упоминалось выше, шаблоны массива, поиска и хэша помимо буквальных массивов и хэшей будут пытаться сопоставить любой объект, реализующий deconstruct (для шаблонов массива/поиска) или deconstruct_keys (для шаблонов хэша).

class Point
  def initialize(x, y)
    @x, @y = x, y
  end

  def deconstruct
    puts "deconstruct called"
    [@x, @y]
  end

  def deconstruct_keys(keys)
    puts "deconstruct_keys called with #{keys.inspect}"
    {x: @x, y: @y}
  end
end

case Point.new(1, -2)
in px, Integer  # sub-patterns and variable binding works
  "matched: #{px}"
else
  "not matched"
end
# prints "deconstruct called"
"matched: 1"

case Point.new(1, -2)
in x: 0.. => px
  "matched: #{px}"
else
  "not matched"
end
# prints: deconstruct_keys called with [:x]
#=> "matched: 1"

keys передаются в deconstruct_keys для предоставления возможности оптимизации в сопоставленном классе: если вычисление полного представления хэша дорогостоящее, можно вычислить только необходимый подхэш. При использовании шаблона **rest в качестве значения nil передается в качестве keys:

case Point.new(1, -2)
in x: 0.. => px, **rest
  "matched: #{px}"
else
  "not matched"
end
# prints: deconstruct_keys called with nil
#=> "matched: 1"

Кроме того, при сопоставлении пользовательских классов ожидаемый класс может быть указан как часть шаблона и проверяется с помощью ===

class SuperPoint < Point
end

case Point.new(1, -2)
in SuperPoint(x: 0.. => px)
  "matched: #{px}"
else
  "not matched"
end
#=> "not matched"

case SuperPoint.new(1, -2)
in SuperPoint[x: 0.. => px] # [] or () parentheses are allowed
  "matched: #{px}"
else
  "not matched"
end
#=> "matched: 1"

Блоки условия

if может использоваться для добавления дополнительного условия (блока условия) при сопоставлении с образцом. Это условие может использовать привязанные переменные:

case [1, 2]
in a, b if b == a*2
  "matched"
else
  "not matched"
end
#=> "matched"

case [1, 1]
in a, b if b == a*2
  "matched"
else
  "not matched"
end
#=> "not matched"

unless тоже работает:

case [1, 1]
in a, b unless b == a*2
  "matched"
else
  "not matched"
end
#=> "matched"

Текущий статус функций

Начиная с Ruby 3.1, шаблоны поиска считаются экспериментальными: его синтаксис может измениться в будущем. Каждый раз, когда вы используете эти функции в коде, будет выводиться предупреждение:

[0] => [*, 0, *]
# warning: Find pattern is experimental, and the behavior may change in future versions of Ruby!
# warning: One-line pattern matching is experimental, and the behavior may change in future versions of Ruby!

Чтобы подавить это предупреждение, можно использовать метод Warning::[]=:

Warning[:experimental] = false
eval('[0] => [*, 0, *]')
# ...no warning printed...

Обратите внимание, что предупреждения при сопоставлении с образцом поднимаются во время компиляции, поэтому это не подавит предупреждение:

Warning[:experimental] = false # At the time this line is evaluated, the parsing happened and warning emitted
[0] => [*, 0, *]

Таким образом, только загруженные впоследствии файлы или код, обработанный функцией ‘eval`, затронуты переключением флага.

В качестве альтернативы, можно использовать командную опцию -W:no-experimental для отключения предупреждений об «экспериментальных» функциях.

Приложение A. Синтаксис шаблона

Приблизительный синтаксис:

pattern: value_pattern
       | variable_pattern
       | alternative_pattern
       | as_pattern
       | array_pattern
       | find_pattern
       | hash_pattern

value_pattern: literal
             | Constant
             | ^local_variable
             | ^instance_variable
             | ^class_variable
             | ^global_variable
             | ^(expression)

variable_pattern: variable

alternative_pattern: pattern | pattern | ...

as_pattern: pattern => variable

array_pattern: [pattern, ..., *variable]
             | Constant(pattern, ..., *variable)
             | Constant[pattern, ..., *variable]

find_pattern: [*variable, pattern, ..., *variable]
            | Constant(*variable, pattern, ..., *variable)
            | Constant[*variable, pattern, ..., *variable]

hash_pattern: {key: pattern, key:, ..., **variable}
            | Constant(key: pattern, key:, ..., **variable)
            | Constant[key: pattern, key:, ..., **variable]

Приложение B. Некоторые примеры неопределенного поведения

Для того чтобы в будущем оставалась возможность оптимизации, спецификация содержит некоторое неопределенное поведение.

Использование переменной в несопоставленном шаблоне:

case [0, 1]
in [a, 2]
  "not matched"
in b
  "matched"
in c
  "not matched"
end
a #=> undefined
c #=> undefined

Количество deconstruct, вызовов метода deconstruct_keys:

$i = 0
ary = [0]
def ary.deconstruct
  $i += 1
  self
end
case ary
in [0, 1]
  "not matched"
in [0]
  "matched"
end
$i #=> undefined