Misc #15109


Improve safe navigation operator's docs

Added by zverok (Victor Shepelev) over 5 years ago. Updated over 5 years ago.



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


safe_navigation.patch (1.73 KB) safe_navigation.patch zverok (Victor Shepelev), 09/12/2018 06:42 PM

Updated by shevegen (Robert A. Heiler) over 5 years ago

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.

Actions #2

Updated by aycabta (aycabta .) over 5 years ago

  • 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.

Also available in: Atom PDF