summaryrefslogtreecommitdiff
path: root/README.markdown
diff options
context:
space:
mode:
authorNate Potter <ntpttr@gmail.com>2016-07-07 21:10:22 -0700
committerNate Potter <ntpttr@gmail.com>2016-07-08 08:53:24 -0700
commita2f980d44d6703561769c5e0ef25a7f531417643 (patch)
treefd5118256340a58ed674911cf741169264af0589 /README.markdown
parent098e82e694704222200d42f2dd4b50ca6d9999fa (diff)
(MODULES-3568) Move dig to dig44 and deprecate dig
A new version of dig was introduced in Puppet 4.5.0 that isn't compatible with the stdlib version of dig. To maintain backwards compatibility and ensure that tests for stdlib aren't broken, this patch renames dig to dig44 and adds a deprecation warning to the stdlib dig function.
Diffstat (limited to 'README.markdown')
-rw-r--r--README.markdown38
1 files changed, 38 insertions, 0 deletions
diff --git a/README.markdown b/README.markdown
index 373b08c..1368b2f 100644
--- a/README.markdown
+++ b/README.markdown
@@ -295,6 +295,8 @@ Returns the difference between two arrays. The returned array is a copy of the o
#### `dig`
+DEPRECATED: This function has been replaced in Puppet 4.5.0, use dig44() for backwards compatibility or use the new version.
+
*Type*: rvalue.
Retrieves a value within multiple layers of hashes and arrays via an array of keys containing a path. The function goes through the structure by each path component and tries to return the value at the end of the path.
@@ -329,6 +331,42 @@ $value = dig($data, ['a', 'b', 'c', 'd'], 'not_found')
3. **'not_found'** The default value. It will be returned if nothing is found.
(optional, defaults to *undef*)
+#### `dig44`
+
+*Type*: rvalue.
+
+Retrieves a value within multiple layers of hashes and arrays via an array of keys containing a path. 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 = dig44($data, ['a', 'b', 2])
+# $value = 'b3'
+
+# with all possible options
+$value = dig44($data, ['a', 'b', 2], 'not_found')
+# $value = 'b3'
+
+# using the default value
+$value = dig44($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 will be returned if nothing is found.
+ (optional, defaults to *undef*)
+
#### `dirname`
Returns the `dirname` of a path. For example, `dirname('/path/to/a/file.ext')` returns '/path/to/a'. *Type*: rvalue.