Misc #15109: Improve safe navigation operator's docs

• Status: Closed
• Assignee: -

[zverok (Victor Shepelev)]

Reason: current docs look this way (in "Receiver" section, one paragraph before last):

You may use &. to designate a receiver, then my_method is not invoked and the result is nil when the receiver is nil. In that case, the arguments of my_method are not evaluated.

There are several problems:

• "safe navigation operator" is never spelled explicitly (so nobody can google these docs);
• it is rendered as "unimportant secondary" feature (just before note about legacy :: call syntax).

While mentoring newcomers, I noticed it is hard for them just to be aware of the feature. So, the proposed rendering is subsection of "Receiver" spelled this way:

=== Safe navigation operator

<code>&.</code>, called "safe navigation operator", allows to skip method call
when receiver is +nil+. It returns +nil+ and doesn't evaluate method's arguments
if the call is skipped.

  REGEX = /(ruby) is (\w+)/i
  "Ruby is awesome!".match(REGEX).values_at(1, 2)
  # => ["Ruby", "awesome"]
  "Python is fascinating!".match(REGEX).values_at(1, 2)
  # NoMethodError: undefined method `values_at' for nil:NilClass
  "Python is fascinating!".match(REGEX)&.values_at(1, 2)
  # => nil

This allows to easily chain methods which could return empty value. Note that
<code>&.</code> skips only one next call, so for a longer chain it is necessary
to add operator on each level:

  "Python is fascinating!".match(REGEX)&.values_at(1, 2).join(' - ')
  # NoMethodError: undefined method `join' for nil:NilClass
  "Python is fascinating!".match(REGEX)&.values_at(1, 2)&.join(' - ')
  # => nil

[shevegen (Robert A. Heiler)]

I think it is good to have more documentation. I would however
had perhaps replace the word Python with Ruby (or Duck or
something else), if possible.

[aycabta (aycabta .)]

• Status changed from Open to Closed

Applied in changeset trunk|r65228.

---

Improve safe navigation operator's docs [Misc #15109]

• doc/syntax/calling_methods.rdoc: Add Safe navigation operator section.