From 411978db322cefda4e156537491b15dddbf2698f Mon Sep 17 00:00:00 2001
From: Dmitry Ilyin <dilyin@mirantis.com>
Date: Fri, 4 Sep 2015 19:12:21 +0300
Subject: [MAINT] Improve 'try_get_value' readme

---
 README.markdown | 51 +++++++++++++++++++++++++++++++++------------------
 1 file changed, 33 insertions(+), 18 deletions(-)

diff --git a/README.markdown b/README.markdown
index a880222..d345947 100644
--- a/README.markdown
+++ b/README.markdown
@@ -706,12 +706,18 @@ Converts the argument into bytes, for example "4 kB" becomes "4096". Takes a sin
 
 *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.
-
+Looks up into a complex structure of arrays and hashes to extract a value by
+its path in the structure. The path is a string of hash keys or array indexes
+starting with zero, separated by the path separator character (default "/").
+The function will go down the structure by each path component and will try to
+return the value at the end of the path.
+
+In addition to the required "path" argument the function accepts the default
+argument. It will be returned if the path is not correct, no value was found or
+a any other error have occurred. And the last argument can set the path
+separator character.
+
+```ruby
 $data = {
   'a' => {
     'b' => [
@@ -722,19 +728,28 @@ $data = {
   }
 }
 
-$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 '/'.
+$value = try_get_value($data, 'a/b/2')
+# $value = 'b3'
 
-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.
+# with all possible options
+$value = try_get_value($data, 'a/b/2', 'not_found', '/')
+# $value = 'b3'
+
+# using the default value
+$value = try_get_value($data, 'a/b/c/d', 'not_found')
+# $value = 'not_found'
+
+# using custom separator
+$value = try_get_value($data, 'a|b', [], '|')
+# $value = ['b1','b2','b3']
+```
+
+1. **$data** The data structure we are working with.
+2. **'a/b/2'** The path string.
+3. **'not_found'** The default value. It will be returned if nothing is found.
+   (optional, defaults to *undef*)
+4. **'/'** The path separator character.
+   (optional, defaults to *'/'*)
 
 #### `type3x`
 
-- 
cgit v1.2.3