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 NoMethodError (undefined method `[]' for nil:NilClass)):

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.

Ruby-doc.org is a service of James Britt and Neurogami, an erratic source of art, music, and technology.

Generated with Rubydoc Rdoc Generator 0.42.0.

There is an updated format of the API docs for this version here.