Update stdlib and concat to 6.1.0 both

[mirror/dsa-puppet.git] / 3rdparty / modules / stdlib / lib / puppet / parser / functions / dig.rb

diff --git a/3rdparty/modules/stdlib/lib/puppet/parser/functions/dig.rb b/3rdparty/modules/stdlib/lib/puppet/parser/functions/dig.rb
index 75e83aa..b6addb4 100644 (file)
--- a/3rdparty/modules/stdlib/lib/puppet/parser/functions/dig.rb
+++ b/3rdparty/modules/stdlib/lib/puppet/parser/functions/dig.rb
@@ -3,7 +3,49 @@
 #
 module Puppet::Parser::Functions
   newfunction(:dig, :type => :rvalue, :doc => <<-DOC
-    DEPRECATED: This function has been replaced in Puppet 4.5.0, please use dig44() for backwards compatibility or use the new version.
+    @summary
+      **DEPRECATED** Retrieves a value within multiple layers of hashes and arrays via an
+      array of keys containing a path.
+
+    @return
+      The function goes through the structure by each path component and tries to return
+      the value at the end of the path.
+
+    In addition to the required path argument, the function accepts the default argument.
+    It is returned if the path is not correct, if no value was found, or if any other error
+    has occurred.
+
+      ```ruby
+      $data = {
+        'a' => {
+          'b' => [
+            'b1',
+            'b2',
+            'b3',
+          ]
+        }
+      }
+
+      $value = dig($data, ['a', 'b', 2])
+      # $value = 'b3'
+
+      # with all possible options
+      $value = dig($data, ['a', 'b', 2], 'not_found')
+      # $value = 'b3'
+
+      # using the default value
+      $value = dig($data, ['a', 'b', 'c', 'd'], 'not_found')
+      # $value = 'not_found'
+      ```
+
+      1. `$data` The data structure we are working with.
+      2. `['a', 'b', 2]` The path array.
+      3. `not_found` The default value. It is returned if nothing is found.
+
+    > **Note:*
+      **Deprecated** This function has been replaced with a built-in
+      [`dig`](https://puppet.com/docs/puppet/latest/function.html#dig) function as of
+      Puppet 4.5.0. Use [`dig44()`](#dig44) for backwards compatibility or use the new version.
     DOC
              ) do |arguments|
     warning('dig() DEPRECATED: This function has been replaced in Puppet 4.5.0, please use dig44() for backwards compatibility or use the new version.')