[ruby-core:88997] [Ruby trunk Misc#15109] Improve safe navigation operator's docs

Issue #15109 has been updated by 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.

----------------------------------------
Misc #15109: Improve safe navigation operator's docs
https://bugs.ruby-lang.org/issues/15109#change-74025

* Author: zverok (Victor Shepelev)
* Status: Open
* Priority: Normal
* Assignee: 
----------------------------------------
Reason: [current docs](http://ruby-doc.org/core-2.5.1/doc/syntax/calling_methods_rdoc.html) 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

```

---Files--------------------------------
safe_navigation.patch (1.73 KB)


-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:[e-mail]?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>