Added comments

CHANGELOG.md

@@ -1,6 +1,18 @@
 Arduino JSON: change log
 ========================
 
+v3.3
+----
+
+* Added indented output for the JSON generator, see example bellow.
+* Added `IndentedPrint`, a decorator for `Print` to allow indented output
+
+Example:
+
+    JsonOject<2> json;
+    json["key"] = "value";
+    json.prettyPrintTo(Serial);
+
 v3.2
 ----
 

JsonGenerator.cpp

@@ -6,7 +6,10 @@
 // This file is here to help the Arduino IDE find the .cpp files
 
 #include "JsonGenerator/EscapedString.cpp"
+#include "JsonGenerator/IndentedPrint.cpp"
 #include "JsonGenerator/JsonArrayBase.cpp"
 #include "JsonGenerator/JsonObjectBase.cpp"
 #include "JsonGenerator/JsonValue.cpp"
+#include "JsonGenerator/JsonPrettyPrint.cpp"
+#include "JsonGenerator/JsonPrintable.cpp"
 #include "JsonGenerator/StringBuilder.cpp"

JsonGenerator/IndentedPrint.cpp

@@ -0,0 +1,45 @@
+#include "IndentedPrint.h"
+
+using namespace ArduinoJson::Generator;
+
+void IndentedPrint::indent()
+{
+    if (level < MAX_LEVEL)
+        level++;
+}
+
+void IndentedPrint::unindent()
+{
+    if (level > 0)
+        level--;
+}
+
+void IndentedPrint::setTabSize(uint8_t n)
+{
+    if (n < MAX_TAB_SIZE)
+        tabSize = n;
+}
+
+size_t IndentedPrint::write(uint8_t c)
+{
+    size_t n = 0;
+
+    if (isNewLine)
+        n += writeTabs();
+
+    n += sink.write(c);
+
+    isNewLine = c == '\n';
+
+    return n;
+}
+
+inline size_t IndentedPrint::writeTabs()
+{
+    size_t n = 0;
+
+    for (int i = 0; i < level*tabSize; i++)
+        n += sink.write(' ');
+
+    return n;
+}

JsonGenerator/IndentedPrint.h

@@ -0,0 +1,53 @@
+/*
+* Arduino JSON library
+* Benoit Blanchon 2014 - MIT License
+*/
+
+#pragma once
+
+#include "Print.h"
+
+namespace ArduinoJson
+{
+    namespace Generator
+    {
+        // Decorator on top of Print to allow indented output.
+        // This class is used by JsonPrintable::prettyPrintTo() but can also be used
+        // for your own purpose, like logging.
+        class IndentedPrint : public Print
+        {
+        public:
+
+            IndentedPrint(Print& p)
+                : sink(p)
+            {
+                level = 0;
+                tabSize = 2;
+                isNewLine = true;
+            }
+
+            virtual size_t write(uint8_t);
+
+            // Adds one level of indentation
+            void indent();
+
+            // Removes one level of indentation
+            void unindent();
+
+            // Set the number of space printed for each level of indentation
+            void setTabSize(uint8_t n);
+
+        private:
+            Print& sink;
+            uint8_t level : 4;
+            uint8_t tabSize : 3;
+            bool isNewLine : 1;
+            
+            size_t writeTabs();
+
+            static const int MAX_LEVEL = 15; // because it's only 4 bits
+            static const int MAX_TAB_SIZE = 7; // because it's only 3 bits
+        };
+    }
+}
+

JsonGenerator/JsonArrayBase.h

@@ -6,6 +6,7 @@
 #pragma once
 
 #include "JsonPrintable.h"
+#include "JsonValue.h"
 
 namespace ArduinoJson
 {

JsonGenerator/JsonGenerator.vcxproj

@@ -12,6 +12,8 @@
   </ItemGroup>
   <ItemGroup>
     <ClInclude Include="EscapedString.h" />
+    <ClInclude Include="IndentedPrint.h" />
+    <ClInclude Include="JsonPrettyPrint.h" />
     <ClInclude Include="JsonArray.h" />
     <ClInclude Include="JsonArrayBase.h" />
     <ClInclude Include="JsonObject.h" />
@@ -24,8 +26,11 @@
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="EscapedString.cpp" />
+    <ClCompile Include="IndentedPrint.cpp" />
+    <ClCompile Include="JsonPrettyPrint.cpp" />
     <ClCompile Include="JsonArrayBase.cpp" />
     <ClCompile Include="JsonObjectBase.cpp" />
+    <ClCompile Include="JsonPrintable.cpp" />
     <ClCompile Include="JsonValue.cpp" />
     <ClCompile Include="Print.cpp" />
     <ClCompile Include="StringBuilder.cpp" />

JsonGenerator/JsonGenerator.vcxproj.filters

@@ -45,6 +45,12 @@
     <ClInclude Include="JsonObject.h">
       <Filter>Header Files</Filter>
     </ClInclude>
+    <ClInclude Include="IndentedPrint.h">
+      <Filter>Header Files</Filter>
+    </ClInclude>
+    <ClInclude Include="JsonPrettyPrint.h">
+      <Filter>Header Files</Filter>
+    </ClInclude>
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="EscapedString.cpp">
@@ -65,5 +71,14 @@
     <ClCompile Include="JsonObjectBase.cpp">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="IndentedPrint.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
+    <ClCompile Include="JsonPrettyPrint.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
+    <ClCompile Include="JsonPrintable.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
   </ItemGroup>
 </Project>

JsonGenerator/JsonObjectBase.h

@@ -6,6 +6,7 @@
 #pragma once
 
 #include "JsonPrintable.h"
+#include "JsonValue.h"
 #include "EscapedString.h"
 
 namespace ArduinoJson

JsonGenerator/JsonPrettyPrint.cpp

@@ -0,0 +1,97 @@
+/*
+* Arduino JSON library
+* Benoit Blanchon 2014 - MIT License
+*/
+
+#include "JsonPrettyPrint.h"
+
+using namespace ArduinoJson::Generator;
+
+size_t JsonPrettyPrint::write(uint8_t c)
+{
+    size_t n = inString ? handleStringChar(c) : handleMarkupChar(c);    
+    previousChar = c;
+    return n;
+}
+
+inline size_t JsonPrettyPrint::handleStringChar(uint8_t c)
+{
+    bool isQuote = c == '"' && previousChar != '\\';
+
+    if (isQuote) inString = false;
+
+    return sink.write(c);
+}
+
+inline size_t JsonPrettyPrint::handleMarkupChar(uint8_t c)
+{
+    switch (c)
+    {
+    case '{':
+    case '[':
+        return handleBlockOpen(c);
+
+    case '}':
+    case ']':
+        return handleBlockClose(c);
+
+    case ':':
+        return handleColumn();
+
+    case ',':
+        return handleComma();
+
+    case '"':
+        return handleQuoteOpen();
+
+    default:
+        return handleNormalChar(c);
+    }
+}
+
+inline size_t JsonPrettyPrint::handleBlockOpen(uint8_t c)
+{
+    return indentIfNeeded() + sink.write(c);
+}
+
+inline size_t JsonPrettyPrint::handleBlockClose(uint8_t c)
+{  
+    return unindentIfNeeded() + sink.write(c);
+}
+
+inline size_t JsonPrettyPrint::handleColumn()
+{
+    return sink.write(':') + sink.write(' ');
+}
+
+inline size_t JsonPrettyPrint::handleComma() 
+{
+    return sink.write(',') + sink.println();
+}
+
+inline size_t JsonPrettyPrint::handleQuoteOpen()
+{
+    inString = true;
+    return indentIfNeeded() + sink.write('"');
+}
+
+inline size_t JsonPrettyPrint::handleNormalChar(uint8_t c)
+{
+    return indentIfNeeded() + sink.write(c);
+}
+
+size_t JsonPrettyPrint::indentIfNeeded()
+{
+    if (!inEmptyBlock()) return 0;
+
+    sink.indent();
+    return sink.println();
+}
+
+size_t JsonPrettyPrint::unindentIfNeeded()
+{
+    if (inEmptyBlock()) return 0;
+
+    sink.unindent();
+    return sink.println();
+}

JsonGenerator/JsonPrettyPrint.h

@@ -0,0 +1,52 @@
+/*
+* Arduino JSON library
+* Benoit Blanchon 2014 - MIT License
+*/
+
+#pragma once
+
+#include "Print.h"
+#include "IndentedPrint.h"
+
+namespace ArduinoJson
+{
+    namespace Generator
+    {
+        // Converts a compact JSON string into an indented one.
+        class JsonPrettyPrint : public Print
+        {
+        public:
+
+            JsonPrettyPrint(IndentedPrint& p)
+                : sink(p)
+            {
+                previousChar = 0;
+                inString = false;
+            }
+
+            virtual size_t write(uint8_t);
+
+        private:            
+            uint8_t previousChar;
+            IndentedPrint& sink;
+            bool inString;
+
+            bool inEmptyBlock()
+            {
+                return previousChar == '{' || previousChar == '[';
+            }
+
+            size_t handleStringChar(uint8_t);
+            size_t handleMarkupChar(uint8_t);
+
+            size_t handleBlockClose(uint8_t);
+            size_t handleBlockOpen(uint8_t);
+            size_t handleColumn();
+            size_t handleComma();
+            size_t handleQuoteOpen();
+            size_t handleNormalChar(uint8_t);
+            size_t indentIfNeeded();
+            size_t unindentIfNeeded();
+        };
+    }
+}

JsonGenerator/JsonPrintable.cpp

@@ -0,0 +1,35 @@
+/*
+* Arduino JSON library
+* Benoit Blanchon 2014 - MIT License
+*/
+
+#include "JsonPrintable.h"
+#include "JsonPrettyPrint.h"
+#include "StringBuilder.h"
+
+using namespace ArduinoJson::Generator;
+using namespace ArduinoJson::Internals;
+
+size_t JsonPrintable::printTo(char* buffer, size_t bufferSize) const
+{
+    StringBuilder sb(buffer, bufferSize);
+    return printTo(sb);
+}
+
+size_t JsonPrintable::prettyPrintTo(char* buffer, size_t bufferSize) const
+{
+    StringBuilder sb(buffer, bufferSize);
+    return prettyPrintTo(sb);
+}
+
+size_t JsonPrintable::prettyPrintTo(IndentedPrint& p) const
+{
+    JsonPrettyPrint prettyPrint(p);
+    return printTo(prettyPrint);
+}
+
+size_t JsonPrintable::prettyPrintTo(Print& p) const
+{
+    IndentedPrint indentedPrint(p);
+    return prettyPrintTo(indentedPrint);
+}

JsonGenerator/JsonPrintable.h

@@ -5,27 +5,36 @@
 
 #pragma once
 
-#include "JsonValue.h"
 #include "Print.h"
 #include "Printable.h"
+#include "IndentedPrint.h"
 
 namespace ArduinoJson
 {
     namespace Generator
     {
+        // Contains methods to generate a JSON string.
+        // Implemented by both JsonObject and JsonArray
         class JsonPrintable : public Printable
         {
         public:
 
-            size_t printTo(char* buffer, size_t bufferSize)
-            {
-                using namespace Internals;
-
-                StringBuilder sb(buffer, bufferSize);
-                return printTo(sb);
-            }
-
+            // Generates the compact JSON string and sends it to a Print stream 
             virtual size_t printTo(Print& p) const = 0;
+
+            // Generates the compact JSON string and writes it in a buffer
+            size_t printTo(char* buffer, size_t bufferSize) const;
+
+            // Generates the indented JSON string and sends it to a Print stream
+            size_t prettyPrintTo(Print& p) const;
+
+            // Generates the indented JSON string and sends it to a IndentedPrint stream
+            // This overload allows a finer control of the output because you can customize
+            // the IndentedPrint.
+            size_t prettyPrintTo(IndentedPrint& p) const;
+
+            // Generates the indented JSON string and writes it in a buffer
+            size_t prettyPrintTo(char* buffer, size_t bufferSize) const;
         };
     }
 }

JsonGenerator/Print.cpp

@@ -32,4 +32,9 @@ size_t Print::print(long value)
     return print(tmp);
 }
 
+size_t Print::println()
+{
+    return write('\r') + write('\n');
+}
+
 #endif

JsonGenerator/Print.h

@@ -19,6 +19,7 @@ public:
     size_t print(const char[]);
     size_t print(double, int = 2);
     size_t print(long);
+    size_t println();
 };
 
 #else

JsonGenerator/README.md

@@ -15,6 +15,7 @@ Features
 * Fixed memory allocation (no malloc)
 * Small footprint
 * Supports nested objects
+* Supports indented output
 * Implements Arduino's `Printable interface
 * MIT License
 
@@ -177,6 +178,13 @@ Whether you have a `JsonArray` or a `JsonObject`, simply call `printTo()` with t
 	char buffer[256];
     array.printTo(buffer, sizeof(buffer));
 
+> ##### Want an indented output?
+> By default the generated JSON is as small as possible. It contains no extra space, nor line break.
+> But if you want an indented, more readable output, you can.
+> Simply call `prettyPrintTo` instead of `printTo()`:
+> 
+>     array.prettyPrintTo(buffer, sizeof(buffer));
+
 #### Send to a stream
 
 It's very likely that the generated JSON will end up in a stream like `Serial` or `EthernetClient `, so you can save some time and memory by doing this:
@@ -190,7 +198,7 @@ or
 > ##### About the Printable interface
 > `JsonArray` and `JsonObject` implement Arduino's `Printable` interface.
 > This is why you can call `Serial.print()` like in the example above.
-> You can do the same with any other implementation of `Print`:  `HardwareSerial`,  `SoftwareSerial`, `LiquidCrystal`, `EthernetClient`, `WiFiClient`...
+> You can do the same with any other implementation of `Print`:  `HardwareSerial`,  `SoftwareSerial`, `LiquidCrystal`, `EthernetClient`, `WiFiClient`, `Wire`...
    
 
 Memory usage

JsonGeneratorTests/JsonGeneratorTests.vcxproj

@@ -85,6 +85,9 @@
   </ItemDefinitionGroup>
   <ItemGroup>
     <ClCompile Include="EscapedStringTests.cpp" />
+    <ClCompile Include="PrettyPrint_Array_Tests.cpp" />
+    <ClCompile Include="PrettyPrint_Object_Tests.cpp" />
+    <ClCompile Include="PrettyPrint_String_Tests.cpp" />
     <ClCompile Include="Issue10.cpp" />
     <ClCompile Include="JsonArrayTests.cpp" />
     <ClCompile Include="JsonObject_Indexer_Tests.cpp" />

JsonGeneratorTests/JsonGeneratorTests.vcxproj.filters

@@ -39,5 +39,14 @@
     <ClCompile Include="Issue10.cpp">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="PrettyPrint_Array_Tests.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
+    <ClCompile Include="PrettyPrint_Object_Tests.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
+    <ClCompile Include="PrettyPrint_String_Tests.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
   </ItemGroup>
 </Project>

JsonGeneratorTests/PrettyPrint_Array_Tests.cpp

@@ -0,0 +1,91 @@
+/*
+* Arduino JSON library
+* Benoit Blanchon 2014 - MIT License
+*/
+
+#include "CppUnitTest.h"
+#include "JsonPrettyPrint.h"
+#include "StringBuilder.h"
+
+using namespace ArduinoJson::Internals;
+using namespace ArduinoJson::Generator;
+using namespace Microsoft::VisualStudio::CppUnitTestFramework;
+
+namespace JsonGeneratorTests
+{
+    TEST_CLASS(PrettyPrint_Array_Tests)
+    {
+        char buffer[1024];
+        size_t returnValue;
+
+    public:
+        
+        TEST_METHOD(EmptyArray)
+        {
+            whenInputIs("[]");
+            outputMustBe("[]");
+        }
+
+        TEST_METHOD(OneElement)
+        {
+            whenInputIs("[1]");
+            outputMustBe(
+                "[\r\n"
+                "  1\r\n"
+                "]");
+        }
+
+        TEST_METHOD(TwoElements)
+        {
+            whenInputIs("[1,2]");
+            outputMustBe(
+                "[\r\n"
+                "  1,\r\n"
+                "  2\r\n"
+                "]");
+        }
+
+        TEST_METHOD(EmptyNestedArrays)
+        {
+            whenInputIs("[[],[]]");
+            outputMustBe(
+                "[\r\n"
+                "  [],\r\n"
+                "  []\r\n"
+                "]");
+        }
+
+        TEST_METHOD(NestedArrays)
+        {
+            whenInputIs("[[1,2],[3,4]]");
+            outputMustBe(
+                "[\r\n"
+                "  [\r\n"
+                "    1,\r\n"
+                "    2\r\n"
+                "  ],\r\n"
+                "  [\r\n"
+                "    3,\r\n"
+                "    4\r\n"
+                "  ]\r\n"
+                "]");
+        }
+
+    private:
+
+        void whenInputIs(const char input[])
+        {
+            StringBuilder sb(buffer, sizeof(buffer));
+            IndentedPrint indentedPrint(sb);
+            JsonPrettyPrint decorator(indentedPrint);
+
+            returnValue = decorator.print(input);
+        }
+
+        void outputMustBe(const char* expected)
+        {
+            Assert::AreEqual(expected, buffer);
+            Assert::AreEqual(strlen(expected), returnValue);
+        }
+    };
+}

JsonGeneratorTests/PrettyPrint_Object_Tests.cpp

@@ -0,0 +1,89 @@
+/*
+* Arduino JSON library
+* Benoit Blanchon 2014 - MIT License
+*/
+
+#include "CppUnitTest.h"
+#include "JsonPrettyPrint.h"
+#include "StringBuilder.h"
+
+using namespace ArduinoJson::Internals;
+using namespace ArduinoJson::Generator;
+using namespace Microsoft::VisualStudio::CppUnitTestFramework;
+
+namespace JsonGeneratorTests
+{
+    TEST_CLASS(PrettyPrint_Object_Tests)
+    {
+        char buffer[1024];
+        size_t returnValue;
+
+    public:
+
+        TEST_METHOD(EmptyObject)
+        {
+            whenInputIs("{}");
+            outputMustBe("{}");
+        }
+
+        TEST_METHOD(OneMember)
+        {
+            whenInputIs("{\"key\":\"value\"}");
+            outputMustBe(
+                "{\r\n"
+                "  \"key\": \"value\"\r\n"
+                "}");
+        }
+
+        TEST_METHOD(TwoMembers)
+        {
+            whenInputIs("{\"key1\":\"value1\",\"key2\":\"value2\"}");
+            outputMustBe(
+                "{\r\n"
+                "  \"key1\": \"value1\",\r\n"
+                "  \"key2\": \"value2\"\r\n"
+                "}");
+        }
+
+        TEST_METHOD(EmptyNestedObjects)
+        {
+            whenInputIs("{\"key1\":{},\"key2\":{}}");
+            outputMustBe(
+                "{\r\n"
+                "  \"key1\": {},\r\n"
+                "  \"key2\": {}\r\n"
+                "}");
+        }
+
+        TEST_METHOD(NestedObjects)
+        {
+            whenInputIs("{\"key1\":{\"a\":1},\"key2\":{\"b\":2}}");
+            outputMustBe(
+                "{\r\n"
+                "  \"key1\": {\r\n"
+                "    \"a\": 1\r\n"
+                "  },\r\n"
+                "  \"key2\": {\r\n"
+                "    \"b\": 2\r\n"
+                "  }\r\n"
+                "}");
+        }
+
+    private:
+
+        void whenInputIs(const char input[])
+        {
+            StringBuilder sb(buffer, sizeof(buffer));
+            IndentedPrint indentedPrint(sb);
+            JsonPrettyPrint decorator(indentedPrint);
+
+            returnValue = decorator.print(input);
+        }
+
+        void outputMustBe(const char* expected)
+        {
+            Assert::AreEqual(expected, buffer);
+            Assert::AreEqual(strlen(expected), returnValue);
+        }
+    };
+}

JsonGeneratorTests/PrettyPrint_String_Tests.cpp

@@ -0,0 +1,76 @@
+/*
+* Arduino JSON library
+* Benoit Blanchon 2014 - MIT License
+*/
+
+#include "CppUnitTest.h"
+#include "JsonPrettyPrint.h"
+#include "StringBuilder.h"
+
+using namespace ArduinoJson::Internals;
+using namespace ArduinoJson::Generator;
+using namespace Microsoft::VisualStudio::CppUnitTestFramework;
+
+namespace JsonGeneratorTests
+{
+    TEST_CLASS(PrettyPrint_String_Tests)
+    {
+        char buffer[1024];
+        size_t returnValue;
+
+    public:
+        
+        TEST_METHOD(EmptyString)
+        {
+            whenInputIs("");
+            outputMustBe("");
+        }
+
+        TEST_METHOD(TrickyCharacters)
+        {
+            whenInputIs ("\":\\\"',\"");
+            outputMustBe("\":\\\"',\"");
+        }
+
+        TEST_METHOD(OpeningCurlyBrace)
+        {
+            whenInputIs ("\"{\"");
+            outputMustBe("\"{\"");
+        }
+
+        TEST_METHOD(OpeningSquareBrace)
+        {
+            whenInputIs("\"[\"");
+            outputMustBe("\"[\"");
+        }
+
+        TEST_METHOD(ClosingCurlyBrace)
+        {
+            whenInputIs("\"}\"");
+            outputMustBe("\"}\"");
+        }
+
+        TEST_METHOD(ClosingSquareBrace)
+        {
+            whenInputIs("\"]\"");
+            outputMustBe("\"]\"");
+        }
+               
+    private:
+
+        void whenInputIs(const char input[])
+        {
+            StringBuilder sb(buffer, sizeof(buffer));
+            IndentedPrint indentedPrint(sb);
+            JsonPrettyPrint decorator(indentedPrint);
+
+            returnValue = decorator.print(input);
+        }
+
+        void outputMustBe(const char* expected)
+        {
+            Assert::AreEqual(expected, buffer);
+            Assert::AreEqual(strlen(expected), returnValue);
+        }
+    };
+}

examples/IndentedPrintExample/IndentedPrintExample.ino

@@ -0,0 +1,43 @@
+/*
+ * Arduino JSON library - IndentedPrint example
+ * Benoit Blanchon 2014 - MIT License
+ */
+
+#include <JsonGenerator.h>
+
+using namespace ArduinoJson::Generator;
+
+void setup()
+{
+    Serial.begin(9600);
+    
+    JsonObject<1> json;
+    json["key"] = "value";
+    
+    IndentedPrint serial(Serial);    
+    serial.setTabSize(4);
+    
+    serial.println("This is at indentation 0");
+    serial.indent();
+    serial.println("This is at indentation 1");
+    serial.println("This is also at indentation 1");
+    serial.indent();
+    serial.println("This is at indentation 2");
+    
+    serial.println("You can print JSON here, as usual:");
+    serial.println(json);
+    serial.println();
+        
+    serial.println("But you can also prettyPrint JSON here:");
+    json.prettyPrintTo(serial);  
+    serial.println();
+    
+    serial.unindent();
+    serial.unindent();
+    serial.println("This is back at indentation 0");
+}
+
+void loop()
+{
+
+}

examples/JsonGeneratorExample/JsonGeneratorExample.ino

@@ -21,6 +21,9 @@ void setup()
     root["data"] = array;
 
     Serial.print(root); // {"sensor":"gps","time":1351824120,"data":[48.756080,2.302038]}
+
+    Serial.println();
+    root.prettyPrintTo(Serial); // same string indented
 }
 
 void loop()