Adding doc/dig_methods.rdoc and links to it (#3416)

Adds a full discussion of #dig, along with links from Array, Hash, Struct, and OpenStruct.

CSV::Table and CSV::Row are over in ruby/csv. I'll get to them soon.

The art to the thing is to figure out how much (or how little) to say at each #dig.

array.c

@@ -8639,19 +8639,20 @@ rb_ary_one_p(int argc, VALUE *argv, VALUE ary)
 }
 
 /*
- * call-seq:
+ *  call-seq:
- *   ary.dig(idx, ...)                 -> object
+ *    array.dig(index, *identifiers) -> object
  *
- * Extracts the nested value specified by the sequence of <i>idx</i>
+ *  Finds and returns the object in nested objects
- * objects by calling +dig+ at each step, returning +nil+ if any
+ *  that is specified by +index+ and +identifiers+.
- * intermediate step is +nil+.
+ *  The nested objects may be instances of various classes.
+ *  See {Dig Methods}[doc/dig_methods_rdoc.html].
  *
- *   a = [[1, [2, 3]]]
+ *  Examples:
- *
+ *    a = [:foo, [:bar, :baz, [:bat, :bam]]]
- *   a.dig(0, 1, 1)                    #=> 3
+ *    a.dig(1) # => [:bar, :baz, [:bat, :bam]]
- *   a.dig(1, 2, 3)                    #=> nil
+ *    a.dig(1, 2) # => [:bat, :bam]
- *   a.dig(0, 0, 0)                    #=> TypeError: Integer does not have #dig method
+ *    a.dig(1, 2, 0) # => :bat
- *   [42, {foo: :bar}].dig(1, :foo)    #=> :bar
+ *    a.dig(1, 2, 3) # => nil
  */
 
 static VALUE

doc/dig_methods.rdoc

@@ -0,0 +1,82 @@
+= Dig Methods
+
+Ruby's +dig+ methods are useful for accessing nested data structures.
+
+Consider this data:
+    item = {
+      id: "0001",
+      type: "donut",
+      name: "Cake",
+      ppu: 0.55,
+      batters: {
+        batter: [
+          {id: "1001", type: "Regular"},
+          {id: "1002", type: "Chocolate"},
+          {id: "1003", type: "Blueberry"},
+          {id: "1004", type: "Devil's Food"}
+        ]
+      },
+      topping: [
+        {id: "5001", type: "None"},
+        {id: "5002", type: "Glazed"},
+        {id: "5005", type: "Sugar"},
+        {id: "5007", type: "Powdered Sugar"},
+        {id: "5006", type: "Chocolate with Sprinkles"},
+        {id: "5003", type: "Chocolate"},
+        {id: "5004", type: "Maple"}
+      ]
+    }
+
+Without a +dig+ method, you can write:
+    item[:batters][:batter][1][:type] # => "Chocolate"
+
+With a +dig+ method, you can write:
+    item.dig(:batters, :batter, 1, :type) # => "Chocolate"
+
+Without a +dig+ method, you can write, erroneously
+(raises <tt>NoMethodError (undefined method `[]' for nil:NilClass)</tt>):
+    item[:batters][:BATTER][1][:type]
+
+With a +dig+ method, you can write (still erroneously, but avoiding the exception):
+    item.dig(:batters, :BATTER, 1, :type) # => nil
+
+== Why Is +dig+ Better?
+
+- It has fewer syntactical elements (to get wrong).
+- It reads better.
+- It does not raise an exception if an item is not found.
+
+== How Does +dig+ Work?
+
+The call sequence is:
+  obj.dig(*identifiers)
+
+The +identifiers+ define a "path" into the nested data structures:
+- For each identifier in +identifiers+, calls method \#dig on a receiver
+  with that identifier.
+- The first receiver is +self+.
+- Each successive receiver is the value returned by the previous call to +dig+.
+- The value finally returned is the value returned by the last call to +dig+.
+
+A +dig+ method raises an exception if any receiver does not respond to \#dig:
+  h = { foo: 1 }
+  # Raises TypeError (Integer does not have #dig method):
+  h.dig(:foo, :bar)
+
+== What Else?
+
+The structure above has \Hash objects and \Array objects,
+both of which have instance method +dig+.
+
+Altogether there are six built-in Ruby classes that have method +dig+,
+three in the core classes and three in the standard library.
+
+In the core:
+- Array#dig: the first argument is an \Integer index.
+- Hash#dig: the first argument is a key.
+- Struct#dig: the first argument is a key.
+
+In the standard library:
+- OpenStruct#dig: the first argument is a \String name.
+- CSV::Table#dig: the first argument is an \Integer index or a \String header.
+- CSV::Row#dig: the first argument is an \Integer index or a \String header.

hash.c

@@ -5080,53 +5080,19 @@ rb_hash_any_p(int argc, VALUE *argv, VALUE hash)
 
 /*
  *  call-seq:
- *    hash.dig(*keys) -> value
+ *    hash.dig(key, *identifiers) -> object
  *
- *  Returns the value for a specified object in nested objects.
+ *  Finds and returns the object in nested objects
- *
+ *  that is specified by +key+ and +identifiers+.
- *  For nested objects:
+ *  The nested objects may be instances of various classes.
- *  - For each key in +keys+, calls method \#dig on a receiver.
+ *  See {Dig Methods}[doc/dig_methods_rdoc.html].
- *  - The first receiver is +self+.
- *  - Each successive receiver is the value returned by the previous call to \#dig.
- *  - The value finally returned is the value returned by the last call to \#dig.
  *
  *  Examples:
- *    h = {foo: 0}
- *    h.dig(:foo) # => 0
- *
- *    h = {foo: {bar: 1}}
- *    h.dig(:foo, :bar) # => 1
- *
  *    h = {foo: {bar: {baz: 2}}}
+ *    h.dig(:foo) # => {:bar=>{:baz=>2}}
+ *    h.dig(:foo, :bar) # => {:bar=>{:baz=>2}}
  *    h.dig(:foo, :bar, :baz) # => 2
- *
+ *    h.dig(:foo, :bar, :BAZ) # => nil
- *  Returns +nil+ if any key is not found:
- *    h = { foo: {bar: {baz: 2}}}
- *    h.dig(:foo, :nosuch) # => nil
- *
- *  The nested objects may include any that respond to \#dig.  See:
- *  - Hash#dig
- *  - Array#dig
- *  - Struct#dig
- *  - OpenStruct#dig
- *  - CSV::Table#dig
- *  - CSV::Row#dig
- *
- *  Example:
- *    h = {foo: {bar: [:a, :b, :c]}}
- *    h.dig(:foo, :bar, 2) # => :c
- *
- *  ---
- *
- *  Raises an exception if any given key is invalid
- *  (see {Invalid Hash Keys}[#class-Hash-label-Invalid+Hash+Keys]):
- *    # Raises NoMethodError (undefined method `hash' for #<BasicObject>)
- *    h.dig(BasicObject.new)
- *
- *  Raises an exception if any receiver does not respond to \#dig:
- *    h = { foo: 1 }
- *    # Raises TypeError: Integer does not have #dig method
- *    h.dig(:foo, 1)
  */
 
 static VALUE

lib/ostruct.rb

@@ -255,26 +255,20 @@ class OpenStruct
     modifiable?[new_ostruct_member!(name)] = value
   end
 
-  #
   # :call-seq:
-  #   ostruct.dig(name, ...)  -> object
+  #   ostruct.dig(name, *identifiers) -> object
   #
-  # Extracts the nested value specified by the sequence of +name+
+  # Finds and returns the object in nested objects
-  # objects by calling +dig+ at each step, returning +nil+ if any
+  # that is specified by +name+ and +identifiers+.
-  # intermediate step is +nil+.
+  # The nested objects may be instances of various classes.
+  # See {Dig Methods}[doc/dig_methods_rdoc.html].
   #
+  # Examples:
   #   require "ostruct"
   #   address = OpenStruct.new("city" => "Anytown NC", "zip" => 12345)
   #   person  = OpenStruct.new("name" => "John Smith", "address" => address)
-  #
+  #   person.dig(:address, "zip") # => 12345
-  #   person.dig(:address, "zip")            # => 12345
+  #   person.dig(:business_address, "zip") # => nil
-  #   person.dig(:business_address, "zip")   # => nil
-  #
-  #   data = OpenStruct.new(:array => [1, [2, 3]])
-  #
-  #   data.dig(:array, 1, 0)   # => 2
-  #   data.dig(:array, 0, 0)   # TypeError: Integer does not have #dig method
-  #
   def dig(name, *names)
     begin
       name = name.to_sym

struct.c

@@ -1328,18 +1328,21 @@ rb_struct_size(VALUE s)
 
 /*
  * call-seq:
- *   struct.dig(key, ...)              -> object
+ *   struct.dig(key, *identifiers) -> object
  *
- * Extracts the nested value specified by the sequence of +key+
+ * Finds and returns the object in nested objects
- * objects by calling +dig+ at each step, returning +nil+ if any
+ * that is specified by +key+ and +identifiers+.
- * intermediate step is +nil+.
+ * The nested objects may be instances of various classes.
+ * See {Dig Methods}[doc/dig_methods_rdoc.html].
  *
+ * Examples:
  *   Foo = Struct.new(:a)
  *   f = Foo.new(Foo.new({b: [1, 2, 3]}))
- *
+ *   f.dig(:a) # => #<struct Foo a={:b=>[1, 2, 3]}>
- *   f.dig(:a, :a, :b, 0)    # => 1
+ *   f.dig(:a, :a) # => {:b=>[1, 2, 3]}
- *   f.dig(:b, 0)            # => nil
+ *   f.dig(:a, :a, :b) # => [1, 2, 3]
- *   f.dig(:a, :a, :b, :c)   # TypeError: no implicit conversion of Symbol into Integer
+ *   f.dig(:a, :a, :b, 0) # => 1
+ *   f.dig(:b, 0) # => nil
  */
 
 static VALUE