3rdparty/modules/stdlib/lib/puppet/parser/functions/dig.rb

   1 #
   2 # dig.rb
   3 #
   4 module Puppet::Parser::Functions
   5   newfunction(:dig, :type => :rvalue, :doc => <<-DOC
   6     @summary
   7       **DEPRECATED** Retrieves a value within multiple layers of hashes and arrays via an
   8       array of keys containing a path.
   9
  10     @return
  11       The function goes through the structure by each path component and tries to return
  12       the value at the end of the path.
  13
  14     In addition to the required path argument, the function accepts the default argument.
  15     It is returned if the path is not correct, if no value was found, or if any other error
  16     has occurred.
  17
  18       ```ruby
  19       $data = {
  20         'a' => {
  21           'b' => [
  22             'b1',
  23             'b2',
  24             'b3',
  25           ]
  26         }
  27       }
  28
  29       $value = dig($data, ['a', 'b', 2])
  30       # $value = 'b3'
  31
  32       # with all possible options
  33       $value = dig($data, ['a', 'b', 2], 'not_found')
  34       # $value = 'b3'
  35
  36       # using the default value
  37       $value = dig($data, ['a', 'b', 'c', 'd'], 'not_found')
  38       # $value = 'not_found'
  39       ```
  40
  41       1. `$data` The data structure we are working with.
  42       2. `['a', 'b', 2]` The path array.
  43       3. `not_found` The default value. It is returned if nothing is found.
  44
  45     > **Note:*
  46       **Deprecated** This function has been replaced with a built-in
  47       [`dig`](https://puppet.com/docs/puppet/latest/function.html#dig) function as of
  48       Puppet 4.5.0. Use [`dig44()`](#dig44) for backwards compatibility or use the new version.
  49     DOC
  50              ) do |arguments|
  51     warning('dig() DEPRECATED: This function has been replaced in Puppet 4.5.0, please use dig44() for backwards compatibility or use the new version.')
  52     unless Puppet::Parser::Functions.autoloader.loaded?(:dig44)
  53       Puppet::Parser::Functions.autoloader.load(:dig44)
  54     end
  55     function_dig44(arguments)
  56   end
  57 end