Add a new function "try_get_value"

* Extracts a value from a deeply-nested data structure
* Returns default if a value could not be extracted

1 files changed, 34 insertions, 0 deletions

diff --git a/README.markdown b/README.markdown
index 8ed3d9b..22bece8 100644
--- a/README.markdown
+++ b/README.markdown
@@ -669,6 +669,40 @@ Returns the current Unix epoch time as an integer. For example, `time()` returns
 
 Converts the argument into bytes, for example "4 kB" becomes "4096". Takes a single string value as an argument. *Type*: rvalue.
 
+#### `try_get_value`
+
+*Type*: rvalue.
+
+Looks up into a complex structure of arrays and hashes and returns a value
+or the default value if nothing was found.
+
+Key can contain slashes to describe path components. The function will go down
+the structure and try to extract the required value.
+
+$data = {
+  'a' => {
+    'b' => [
+      'b1',
+      'b2',
+      'b3',
+    ]
+  }
+}
+
+$value = try_get_value($data, 'a/b/2', 'not_found', '/')
+=> $value = 'b3'
+
+a -> first hash key
+b -> second hash key
+2 -> array index starting with 0
+
+not_found -> (optional) will be returned if there is no value or the path did not match. Defaults to nil.
+/ -> (optional) path delimiter. Defaults to '/'.
+
+In addition to the required "key" argument, "try_get_value" accepts default
+argument. It will be returned if no value was found or a path component is
+missing. And the fourth argument can set a variable path separator.
+
 #### `type3x`
 
 Returns a string description of the type when passed a value. Type can be a string, array, hash, float, integer, or boolean. This function will be removed when Puppet 3 support is dropped and the new type system can be used. *Type*: rvalue.