Ця стаття пояснює заплановану несумісність ключових аргументів у Ruby 3.0

## tl;dr

У Ruby 3.0 позиційні аргументи та ключові аргументи будуть розділені. Ruby 2.7 попереджатиме про поведінку, яка зміниться в Ruby 3.0. Якщо ви бачите такі попередження, вам потрібно оновити свій код:

* `Using the last argument as keyword parameters is deprecated`, або
* `Passing the keyword argument as the last hash parameter is deprecated`, або
* `Splitting the last argument into positional and keyword parameters is deprecated`

У більшості випадків можна уникнути несумісності, додавши оператор _double splat_. Він явно вказує на передачу ключових аргументів замість об'єкта `Hash`. Так само можна додати фігурні дужки `{}`, щоб явно передати об'єкт `Hash` замість ключових аргументів. Докладніше читайте в розділі «Типові випадки» нижче.

У Ruby 3 метод, який делегує всі аргументи, повинен явно делегувати ключові аргументи на додаток до позиційних. Якщо ви хочете зберегти поведінку делегування з Ruby 2.7 і раніших версій, використовуйте `ruby2_keywords`. Докладніше див. у розділі «Обробка делегування аргументів».

## Типові випадки
{: #typical-cases }

Ось найтиповіший випадок. Використовуйте оператор double splat (`**`) для передачі ключових слів замість Hash.

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># Цей метод приймає лише ключовий аргумент</span>
<span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="ss">k: </span><span class="mi">1</span><span class="p">)</span>
  <span class="nb">p</span> <span class="n">k</span>
<span class="k">end</span>

<span class="n">h</span> <span class="o">=</span> <span class="p">{</span> <span class="ss">k: </span><span class="mi">42</span> <span class="p">}</span>

<span class="c1"># Цей виклик методу передає позиційний аргумент Hash</span>
<span class="c1"># У Ruby 2.7: Hash автоматично перетворюється на ключовий аргумент</span>
<span class="c1"># У Ruby 3.0: Цей виклик викликає ArgumentError</span>
<span class="n">foo</span><span class="p">(</span><span class="n">h</span><span class="p">)</span>
  <span class="c1"># =&gt; demo.rb:11: warning: Using the last argument as keyword parameters is deprecated; maybe ** should be added to the call</span>
  <span class="c1">#    demo.rb:2: warning: The called method `foo' is defined here</span>
  <span class="c1">#    42</span>

<span class="c1"># Щоб зберегти поведінку в Ruby 3.0, використовуйте double splat</span>
<span class="n">foo</span><span class="p">(</span><span class="o">**</span><span class="n">h</span><span class="p">)</span> <span class="c1">#=&gt; 42</span></code></pre></figure>

Ось інший випадок. Використовуйте фігурні дужки (`{}`) для явної передачі Hash замість ключових слів.

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># Цей метод приймає один позиційний аргумент і решту ключових аргументів</span>
<span class="k">def</span> <span class="nf">bar</span><span class="p">(</span><span class="n">h</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
  <span class="nb">p</span> <span class="n">h</span>
<span class="k">end</span>

<span class="c1"># Цей виклик передає тільки ключовий аргумент і жодних позиційних</span>
<span class="c1"># У Ruby 2.7: Ключове слово перетворюється на позиційний аргумент Hash</span>
<span class="c1"># У Ruby 3.0: Цей виклик викликає ArgumentError</span>
<span class="n">bar</span><span class="p">(</span><span class="ss">k: </span><span class="mi">42</span><span class="p">)</span>
  <span class="c1"># =&gt; demo2.rb:9: warning: Passing the keyword argument as the last hash parameter is deprecated</span>
  <span class="c1">#    demo2.rb:2: warning: The called method `bar' is defined here</span>
  <span class="c1">#    {:k=&gt;42}</span>

<span class="c1"># Щоб зберегти поведінку в Ruby 3.0, використовуйте фігурні дужки</span>
<span class="n">bar</span><span class="p">({</span> <span class="ss">k: </span><span class="mi">42</span> <span class="p">})</span> <span class="c1"># =&gt; {:k=&gt;42}</span></code></pre></figure>

## Що застаріло?
{: #what-is-deprecated }

У Ruby 2 ключові аргументи можуть оброблятися як останній позиційний аргумент Hash, і навпаки — останній позиційний Hash може оброблятися як ключові аргументи.

Оскільки автоматичне перетворення іноді занадто складне й проблемне (як описано в останньому розділі), воно застаріло в Ruby 2.7 і буде видалено в Ruby 3. Іншими словами, в Ruby 3 ключові аргументи будуть повністю відокремлені від позиційних. Отже, коли ви хочете передати ключові аргументи, завжди використовуйте `foo(k: expr)` або `foo(**expr)`. Якщо хочете приймати ключові аргументи, в принципі завжди використовуйте `def foo(k: default)` або `def foo(k:)` або `def foo(**kwargs)`.

Зверніть увагу, що Ruby 3.0 поводиться так само при виклику методу, який не приймає ключові аргументи, з ключовими аргументами. Наприклад, наступний випадок не буде застарілим і працюватиме в Ruby 3.0. Ключові аргументи все ще обробляються як позиційний аргумент Hash.

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">kwargs</span> <span class="o">=</span> <span class="p">{})</span>
  <span class="n">kwargs</span>
<span class="k">end</span>

<span class="n">foo</span><span class="p">(</span><span class="ss">k: </span><span class="mi">1</span><span class="p">)</span> <span class="c1">#=&gt; {:k=&gt;1}</span></code></pre></figure>

Це тому, що цей стиль використовується дуже часто, і немає неоднозначності в тому, як слід обробляти аргумент.

Однак цей стиль не рекомендується в новому коді, якщо ви не часто передаєте Hash як позиційний аргумент і також використовуєте ключові аргументи. В іншому випадку використовуйте double splat:

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
  <span class="n">kwargs</span>
<span class="k">end</span>

<span class="n">foo</span><span class="p">(</span><span class="ss">k: </span><span class="mi">1</span><span class="p">)</span> <span class="c1">#=&gt; {:k=&gt;1}</span></code></pre></figure>

## Чи зламається мій код на Ruby 2.7?
{: #break-on-ruby-2-7 }

Коротка відповідь: «можливо, ні».

Зміни в Ruby 2.7 розроблено як шлях міграції до 3.0. Хоча в принципі Ruby 2.7 лише попереджає про поведінку, яка зміниться в Ruby 3, він включає деякі несумісні зміни, які ми вважаємо незначними. Докладніше див. розділ «Інші незначні зміни».

За винятком попереджень і незначних змін, Ruby 2.7 намагається зберегти сумісність з Ruby 2.6. Отже, ваш код, ймовірно, працюватиме на Ruby 2.7, хоча може видавати попередження. І запустивши його на Ruby 2.7, ви можете перевірити, чи готовий ваш код до Ruby 3.0.

Якщо хочете вимкнути попередження про застаріння, використовуйте аргумент командного рядка `-W:no-deprecated` або додайте `Warning[:deprecated] = false` у свій код.

## Обробка делегування аргументів
{: #delegation }

### Ruby 2.6 або раніше
{: #delegation-ruby-2-6-or-prior }

У Ruby 2 можна написати метод делегування, приймаючи аргумент `*rest` і аргумент `&block`, і передаючи обидва до цільового методу. У цій поведінці ключові аргументи також неявно обробляються автоматичним перетворенням між позиційними та ключовими аргументами.

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
  <span class="n">target</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
<span class="k">end</span></code></pre></figure>

### Ruby 3
{: #delegation-ruby-3 }

Потрібно явно делегувати ключові аргументи.

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
  <span class="n">target</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
<span class="k">end</span></code></pre></figure>

Альтернативно, якщо вам не потрібна сумісність з Ruby 2.6 або раніше і ви не змінюєте жодних аргументів, можете використовувати новий синтаксис делегування (`...`), введений у Ruby 2.7.

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
  <span class="n">target</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
<span class="k">end</span></code></pre></figure>

### Ruby 2.7
{: #delegation-ruby-2-7 }

Коротко: використовуйте `Module#ruby2_keywords` і делегуйте `*args, &block`.

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="n">ruby2_keywords</span> <span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
  <span class="n">target</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
<span class="k">end</span></code></pre></figure>

`ruby2_keywords` приймає ключові аргументи як останній аргумент Hash і передає їх як ключові аргументи при виклику іншого методу.

### Сумісне делегування для Ruby 2.6, 2.7 і Ruby 3
{: #a-compatible-delegation }

Коротко: знову використовуйте `Module#ruby2_keywords`.

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="n">ruby2_keywords</span> <span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
  <span class="n">target</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
<span class="k">end</span></code></pre></figure>

На жаль, нам потрібно використовувати старий стиль делегування (тобто без `**kwargs`), оскільки Ruby 2.6 або раніше не обробляє новий стиль делегування правильно. Це одна з причин розділення ключових аргументів. І `ruby2_keywords` дозволяє запускати старий стиль навіть у Ruby 2.7 і 3.0. Оскільки `ruby2_keywords` не визначено в 2.6 або раніше, використовуйте [гем ruby2_keywords](https://rubygems.org/gems/ruby2_keywords) або визначте його самостійно:

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">ruby2_keywords</span><span class="p">(</span><span class="o">*</span><span class="p">)</span>
<span class="k">end</span> <span class="k">if</span> <span class="no">RUBY_VERSION</span> <span class="o">&lt;</span> <span class="s2">"2.7"</span></code></pre></figure>

---

Якщо вашому коду не потрібно працювати на Ruby 2.6 або старішому, можете спробувати новий стиль у Ruby 2.7. У майже всіх випадках він працює. Однак зверніть увагу на кутові випадки:

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">target</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">)</span>
  <span class="nb">p</span> <span class="n">args</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
  <span class="n">target</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
<span class="k">end</span>

<span class="n">foo</span><span class="p">({})</span>       <span class="c1">#=&gt; Ruby 2.7: []   ({} відкидається)</span>
<span class="n">foo</span><span class="p">({},</span> <span class="o">**</span><span class="p">{})</span> <span class="c1">#=&gt; Ruby 2.7: [{}] (Можете передати {} явно вказавши «без» ключових слів)</span></code></pre></figure>

Порожній аргумент Hash автоматично перетворюється і поглинається в `**kwargs`, і виклик делегування видаляє порожній keyword hash, тому жодного аргументу не передається в `target`.

Якщо ви справді турбуєтесь про переносимість, використовуйте `ruby2_keywords`. `ruby2_keywords` може бути видалено в майбутньому після того, як Ruby 2.6 досягне кінця життєвого циклу. На той момент ми рекомендуємо явно делегувати ключові аргументи.

## Інші незначні зміни
{: #other-minor-changes }

У Ruby 2.7 є три незначні зміни щодо ключових аргументів.

### 1. Не-Symbol ключі дозволені в ключових аргументах
{: #other-minor-changes-non-symbol-keys }

У Ruby 2.6 або раніше в ключових аргументах дозволялися лише Symbol-ключі. У Ruby 2.7 ключові аргументи можуть використовувати не-Symbol ключі.

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
  <span class="n">kwargs</span>
<span class="k">end</span>
<span class="n">foo</span><span class="p">(</span><span class="s2">"key"</span> <span class="o">=&gt;</span> <span class="mi">42</span><span class="p">)</span>
  <span class="c1">#=&gt; Ruby 2.6 або раніше: ArgumentError: wrong number of arguments</span>
  <span class="c1">#=&gt; Ruby 2.7 або пізніше: {"key"=&gt;42}</span></code></pre></figure>

### 2. Double splat з порожнім hash (`**{}`) не передає аргументів
{: #other-minor-changes-empty-hash }

У Ruby 2.6 або раніше передача `**empty_hash` передавала порожній Hash як позиційний аргумент. У Ruby 2.7 або пізніше він не передає жодних аргументів.

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">)</span>
  <span class="n">args</span>
<span class="k">end</span>

<span class="n">empty_hash</span> <span class="o">=</span> <span class="p">{}</span>
<span class="n">foo</span><span class="p">(</span><span class="o">**</span><span class="n">empty_hash</span><span class="p">)</span>
  <span class="c1">#=&gt; Ruby 2.6 або раніше: [{}]</span>
  <span class="c1">#=&gt; Ruby 2.7 або пізніше: []</span></code></pre></figure>

### 3. Введено синтаксис без ключових аргументів (`**nil`)
{: #other-minor-changes-double-splat-nil }

Можна використовувати `**nil` у визначенні методу, щоб явно позначити, що метод не приймає ключових аргументів. Виклик таких методів з ключовими аргументами призведе до `ArgumentError`.

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="kp">nil</span><span class="p">)</span>
<span class="k">end</span>

<span class="n">foo</span><span class="p">(</span><span class="ss">k: </span><span class="mi">1</span><span class="p">)</span>
  <span class="c1">#=&gt; Ruby 2.7 або пізніше: no keywords accepted (ArgumentError)</span></code></pre></figure>

## Чому ми застаріли автоматичне перетворення
{: #why-deprecated }

Автоматичне перетворення спочатку здавалося гарною ідеєю і добре працювало в багатьох випадках. Однак у нього було занадто багато кутових випадків, і ми отримали багато звітів про помилки щодо цієї поведінки.

Автоматичне перетворення не працює добре, коли метод приймає опціональні позиційні аргументи та ключові аргументи. Деякі люди очікують, що останній об'єкт Hash буде оброблено як позиційний аргумент, а інші очікують, що він буде перетворено на ключові аргументи.

Ось один з найбільш заплутаних випадків:

<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
  <span class="nb">p</span> <span class="p">[</span><span class="n">x</span><span class="p">,</span> <span class="n">kwargs</span><span class="p">]</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">bar</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
  <span class="nb">p</span> <span class="p">[</span><span class="n">x</span><span class="p">,</span> <span class="n">kwargs</span><span class="p">]</span>
<span class="k">end</span>

<span class="n">foo</span><span class="p">({})</span> <span class="c1">#=&gt; [{}, {}]</span>
<span class="n">bar</span><span class="p">({})</span> <span class="c1">#=&gt; [1, {}]</span>

<span class="n">bar</span><span class="p">({},</span> <span class="o">**</span><span class="p">{})</span> <span class="c1">#=&gt; очікувано: [{}, {}], фактично: [1, {}]</span></code></pre></figure>

У Ruby 2, `foo({})` передає порожній hash як звичайний аргумент (тобто `{}` присвоюється `x`), тоді як `bar({})` передає ключовий аргумент (тобто `{}` присвоюється `kwargs`). Отже, `any_method({})` дуже неоднозначний.

## Подяки

Цю статтю люб'язно переглянули (або навіть співавторчо написали) Jeremy Evans і Benoit Daloze.

## Історія

* Оновлено 2019-12-25: У 2.7.0-rc2 повідомлення попередження було трохи змінено, і додано API для придушення попереджень.
