From 2e47d9ed4a4ee0cad6e154285e1e0509749b4b3c Mon Sep 17 00:00:00 2001
From: Kiril Zvezdarov <kzvezdarov@monetate.com>
Date: Sat, 2 May 2015 14:20:33 -0400
Subject: [PATCH] Added doc entry on nested key access

---
 README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/README.md b/README.md
index 885b6d8..4e72e97 100644
--- a/README.md
+++ b/README.md
@@ -237,6 +237,71 @@ Example:
         fmt.Println("verbose enabled")
     }
 
+### Accessing nested keys
+
+The accessor methods also accept formatted paths to deeply nested keys. 
+For example, if the following JSON file is loaded:
+
+```
+{
+    "host": {
+        "address": "localhost",
+        "port": 5799
+    },
+    "datastore": {
+        "metric": {
+            "host": "127.0.0.1",
+            "port": 3099
+        },
+        "warehouse": {
+            "host": "198.0.0.1",
+            "port": 2112
+        }
+    }
+}
+
+```
+
+Viper can access a nested field by passing a `.` delimited path of keys:
+```
+GetString("datastore.metric.host") // (returns "127.0.0.1")
+```
+
+This obeys the precendense rules established above; the search for the root key
+(in this examole, `datastore`) will cascade through the remaining configuration registries
+until found. The search for the subkeys (`metric` and `host`), however, will not.
+
+For example, if the `metric` key was not defined in the configuration loaded
+from file, but was defined in the defaults, Viper would return the zero value.
+
+On the other hand, if the primary key was not defined, Viper would go through the
+remaining registries looking for it.
+
+Lastly, if there exists a key that matches the delimited key path, its value will
+be returned instead. E.g. 
+
+```
+{
+    "datastore.metric.host": "0.0.0.0",
+    "host": {
+        "address": "localhost",
+        "port": 5799
+    },
+    "datastore": {
+        "metric": {
+            "host": "127.0.0.1",
+            "port": 3099
+        },
+        "warehouse": {
+            "host": "198.0.0.1",
+            "port": 2112
+        }
+    }
+}
+
+GetString("datastore.metric.host") //returns "0.0.0.0"
+```
+
 ### Marshaling
 
 You also have the option of Marshaling all or a specific value to a struct, map, etc.