Diff: Json.h

Revision:

7:8aa4d0e98eb0

Parent:

6:c1d2153da4ed

Child:

8:43e1e35bb7ec

--- a/Json.h	Mon Aug 15 22:52:37 2016 +0000
+++ b/Json.h	Tue Aug 16 22:26:36 2016 +0000
@@ -43,6 +43,106 @@
  * tokens, parsed by the Json constructor, unless and until explicitly mentioned
  * otherwise.
  */
+ 
+ /*
+    Example:
+    
+    Let's say we have to parse the samle JSON:
+    
+    {
+        "team": "Night Crue",
+        "company": "TechShop",
+        "city": "San Jose",
+        "state": "California",
+        "country": "USA",
+        "zip": 95113,
+        "active": true,
+        "members":
+        [
+            {
+                "firstName": "John",
+                "lastName": "Smith",
+                "active": false,
+                "hours": 18.5,
+                "age": 21
+            },
+            {
+                "firstName": "Foo",
+                "lastName": "Bar",
+                "active": true,
+                "hours": 25,
+                "age": 21
+            },
+            {
+                "firstName": "Peter",
+                "lastName": "Jones",
+                "active": false
+            }
+        ]
+    }
+    
+    which without the "white spaces" will look like: {"team":"Night Crue","company":"TechShop","city":"San Jose","state":"California","country":"USA","zip":95113,"active":true,"members":[{"firstName":"John","lastName":"Smith","active":false,"hours":18.5,"age":21},{"firstName":"Foo","lastName":"Bar","active":true,"hours":25,"age":21},{"firstName":"Peter","lastName":"Jones","active":false}]}
+    
+    Anyways, this class doesn't care about the formatting of JSON, however, it
+    DOES care about the validity of JSON.  So here's a sample code to parse and
+    extract values from this JSON structure.
+    
+    @code
+    
+    void main ()
+    {
+        // Note that the JSON object is 'escaped'.  One doesn't get escaped JSON
+        // directly from the webservice, if the response type is APPLICATION/JSON
+        // Just a little thing to keep in mind.
+        const char * jsonSource = "{\"team\":\"Night Crue\",\"company\":\"TechShop\",\"city\":\"San Jose\",\"state\":\"California\",\"country\":\"USA\",\"zip\":95113,\"active\":true,\"members\":[{\"firstName\":\"John\",\"lastName\":\"Smith\",\"active\":false,\"hours\":18.5,\"age\":21},{\"firstName\":\"Foo\",\"lastName\":\"Bar\",\"active\":true,\"hours\":25,\"age\":21},{\"firstName\":\"Peter\",\"lastName\":\"Jones\",\"active\":false}]}";
+        
+        Json json ( jsonSource, strlen ( jsonSource ) );
+        
+        if ( !json.isValidJson () )
+        {
+            logError ( "Invalid JSON: %s", jsonSource );
+            return;
+        }
+
+        if ( json.type (0) != JSMN_OBJECT )
+        {
+            logError ( "Invalid JSON.  ROOT element is not Object: %s", jsonSource );
+            return;
+        }
+        
+        // Let's get the value of key "city" in ROOT object, and copy into 
+        // cityValue
+        char cityValue [ 32 ];
+        
+        logInfo ( "Finding \"city\" Key ... " );
+        // ROOT object should have '0' tokenIndex, and -1 parentIndex
+        int cityKeyIndex = json.findKeyIndexIn ( "city", 0 );
+        if ( cityKeyIndex == -1 )
+        {
+            // Error handling part ...
+            logError ( "\"city\" does not exist ... do something!!" );
+        }
+        else
+        {
+            // Find the first child index of key-node "city"
+            int cityValueIndex = json.findChildIndexOf ( cityKeyIndex, -1 );
+            if ( cityValueIndex > 0 )
+            {
+                const char * valueStart  = json.tokenAddress ( cityValueIndex );
+                int          valueLength = json.tokenLength ( cityValueIndex );
+                strncpy ( cityValue, valueStart, valueLength );
+                cityValue [ valueLength ] = 0; // NULL-terminate the string
+                
+                //let's print the value.  It should be "San Jose"
+                logInfo ( "city: %s", cityValue );
+            }
+        }
+        
+        // More on this example to come, later.
+    }
+    
+    @endcode
+ */
 
 class Json
 {