Add ignore_trailing_commas option (#4609)

Added examples and modified the corresponding documents and unit tests.

Signed-off-by: chirsz-ever <chirsz-ever@outlook.com>
Co-authored-by: Niels Lohmann <niels.lohmann@gmail.com>

docs/mkdocs/docs/api/basic_json/accept.md

@@ -4,12 +4,14 @@
 // (1)
 template<typename InputType>
 static bool accept(InputType&& i,
-                   const bool ignore_comments = false);
+                   const bool ignore_comments = false,
+                   const bool ignore_trailing_commas = false);
 
 // (2)
 template<typename IteratorType>
 static bool accept(IteratorType first, IteratorType last,
-                   const bool ignore_comments = false);
+                   const bool ignore_comments = false,
+                   const bool ignore_trailing_commas = false);
 ```
 
 Checks whether the input is valid JSON.
@@ -50,6 +52,10 @@ Unlike the [`parse()`](parse.md) function, this function neither throws an excep
 :   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
     (`#!cpp false`); (optional, `#!cpp false` by default)
 
+`ignore_trailing_commas` (in)
+:   whether trailing commas in arrays or objects should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
+    (`#!cpp false`); (optional, `#!cpp false` by default)
+
 `first` (in)
 :   iterator to the start of the character range
 
@@ -102,6 +108,7 @@ A UTF-8 byte order mark is silently ignored.
 - Added in version 3.0.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
 - Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
+- Added `ignore_trailing_commas` in version 3.12.1.
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/api/basic_json/parse.md

@@ -6,14 +6,16 @@ template<typename InputType>
 static basic_json parse(InputType&& i,
                         const parser_callback_t cb = nullptr,
                         const bool allow_exceptions = true,
-                        const bool ignore_comments = false);
+                        const bool ignore_comments = false,
+                        const bool ignore_trailing_commas = false);
 
 // (2)
 template<typename IteratorType>
 static basic_json parse(IteratorType first, IteratorType last,
                         const parser_callback_t cb = nullptr,
                         const bool allow_exceptions = true,
-                        const bool ignore_comments = false);
+                        const bool ignore_comments = false,
+                        const bool ignore_trailing_commas = false);
 ```
 
 1. Deserialize from a compatible input.
@@ -56,6 +58,10 @@ static basic_json parse(IteratorType first, IteratorType last,
 :   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
     (`#!cpp false`); (optional, `#!cpp false` by default)
 
+`ignore_trailing_commas` (in)
+:   whether trailing commas in arrays or objects should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
+    (`#!cpp false`); (optional, `#!cpp false` by default)
+
 `first` (in)
 :   iterator to the start of a character range
 
@@ -189,6 +195,34 @@ A UTF-8 byte order mark is silently ignored.
     --8<-- "examples/parse__allow_exceptions.output"
     ```
 
+??? example "Effect of `ignore_comments` parameter"
+
+    The example below demonstrates the effect of the `ignore_comments` parameter in the `parse()` function.
+
+    ```cpp
+    --8<-- "examples/comments.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/comments.output"
+    ```
+
+??? example "Effect of `ignore_trailing_commas` parameter"
+
+    The example below demonstrates the effect of the `ignore_trailing_commas` parameter in the `parse()` function.
+
+    ```cpp
+    --8<-- "examples/trailing_commas.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/trailing_commas.output"
+    ```
+
 ## See also
 
 - [accept](accept.md) - check if the input is valid JSON
@@ -200,6 +234,7 @@ A UTF-8 byte order mark is silently ignored.
 - Overload for contiguous containers (1) added in version 2.0.3.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
 - Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
+- Added `ignore_trailing_commas` in version 3.12.1.
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/api/basic_json/sax_parse.md

@@ -7,7 +7,8 @@ static bool sax_parse(InputType&& i,
                       SAX* sax,
                       input_format_t format = input_format_t::json,
                       const bool strict = true,
-                      const bool ignore_comments = false);
+                      const bool ignore_comments = false,
+                      const bool ignore_trailing_commas = false);
 
 // (2)
 template<class IteratorType, class SAX>
@@ -15,7 +16,8 @@ static bool sax_parse(IteratorType first, IteratorType last,
                       SAX* sax,
                       input_format_t format = input_format_t::json,
                       const bool strict = true,
-                      const bool ignore_comments = false);
+                      const bool ignore_comments = false,
+                      const bool ignore_trailing_commas = false);
 ```
 
 Read from input and generate SAX events
@@ -65,6 +67,10 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
 :   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
     (`#!cpp false`); (optional, `#!cpp false` by default)
 
+`ignore_trailing_commas` (in)
+:   whether trailing commas in arrays or objects should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
+    (`#!cpp false`); (optional, `#!cpp false` by default)
+
 `first` (in)
 :   iterator to the start of a character range
 
@@ -107,6 +113,7 @@ A UTF-8 byte order mark is silently ignored.
 
 - Added in version 3.2.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
+- Added `ignore_trailing_commas` in version 3.12.1.
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/examples/comments.cpp

@@ -0,0 +1,31 @@
+
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::string s = R"(
+    {
+        // update in 2006: removed Pluto
+        "planets": ["Mercury", "Venus", "Earth", "Mars",
+                    "Jupiter", "Uranus", "Neptune" /*, "Pluto" */]
+    }
+    )";
+
+    try
+    {
+        json j = json::parse(s);
+    }
+    catch (json::exception& e)
+    {
+        std::cout << e.what() << std::endl;
+    }
+
+    json j = json::parse(s,
+                         /* callback */ nullptr,
+                         /* allow exceptions */ true,
+                         /* ignore_comments */ true);
+    std::cout << j.dump(2) << '\n';
+}

docs/mkdocs/docs/examples/comments.output

@@ -0,0 +1,12 @@
+[json.exception.parse_error.101] parse error at line 3, column 9: syntax error while parsing object key - invalid literal; last read: '<U+000A>    {<U+000A>        /'; expected string literal
+{
+  "planets": [
+    "Mercury",
+    "Venus",
+    "Earth",
+    "Mars",
+    "Jupiter",
+    "Uranus",
+    "Neptune"
+  ]
+}

docs/mkdocs/docs/examples/trailing_commas.cpp

@@ -0,0 +1,37 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::string s = R"(
+    {
+        "planets": [
+            "Mercury",
+            "Venus",
+            "Earth",
+            "Mars",
+            "Jupiter",
+            "Uranus",
+            "Neptune",
+        ]
+    }
+    )";
+
+    try
+    {
+        json j = json::parse(s);
+    }
+    catch (json::exception& e)
+    {
+        std::cout << e.what() << std::endl;
+    }
+
+    json j = json::parse(s,
+                         /* callback */ nullptr,
+                         /* allow exceptions */ true,
+                         /* ignore_comments */ false,
+                         /* ignore_trailing_commas */ true);
+    std::cout << j.dump(2) << '\n';
+}

docs/mkdocs/docs/examples/trailing_commas.output

@@ -0,0 +1,12 @@
+[json.exception.parse_error.101] parse error at line 11, column 9: syntax error while parsing value - unexpected ']'; expected '[', '{', or a literal
+{
+  "planets": [
+    "Mercury",
+    "Venus",
+    "Earth",
+    "Mars",
+    "Jupiter",
+    "Uranus",
+    "Neptune"
+  ]
+}

docs/mkdocs/docs/features/comments.md

@@ -11,7 +11,9 @@ This library does not support comments *by default*. It does so for three reason
 
 3. It is dangerous for interoperability if some libraries add comment support while others do not. Please check [The Harmful Consequences of the Robustness Principle](https://tools.ietf.org/html/draft-iab-protocol-maintenance-01) on this.
 
-However, you can pass set parameter `ignore_comments` to `#!c true` in the parse function to ignore `//` or `/* */` comments. Comments will then be treated as whitespace.
+However, you can set parameter `ignore_comments` to `#!cpp true` in the [`parse`](../api/basic_json/parse.md) function to ignore `//` or `/* */` comments. Comments will then be treated as whitespace.
+
+For more information, see [JSON With Commas and Comments (JWCC)](https://nigeltao.github.io/blog/2021/json-with-commas-comments.html).
 
 !!! example
 
@@ -28,56 +30,11 @@ However, you can pass set parameter `ignore_comments` to `#!c true` in the parse
     When calling `parse` without additional argument, a parse error exception is thrown. If `ignore_comments` is set to `#! true`, the comments are ignored during parsing:
 
     ```cpp
-    #include <iostream>
-    #include "json.hpp"
-    
-    using json = nlohmann::json;
-    
-    int main()
-    {
-        std::string s = R"(
-        {
-            // update in 2006: removed Pluto
-            "planets": ["Mercury", "Venus", "Earth", "Mars",
-                        "Jupiter", "Uranus", "Neptune" /*, "Pluto" */]
-        }
-        )";
-        
-        try
-        {
-            json j = json::parse(s);
-        }
-        catch (json::exception &e)
-        {
-            std::cout << e.what() << std::endl;
-        }
-        
-        json j = json::parse(s,
-                             /* callback */ nullptr,
-                             /* allow exceptions */ true,
-                             /* ignore_comments */ true);
-        std::cout << j.dump(2) << '\n';
-    }
+    --8<-- "examples/comments.cpp"
     ```
 
     Output:
     
     ```
-    [json.exception.parse_error.101] parse error at line 3, column 9:
-    syntax error while parsing object key - invalid literal;
-    last read: '<U+000A>    {<U+000A>        /'; expected string literal
-    ```
-    
-    ```json
-    {
-      "planets": [
-        "Mercury",
-        "Venus",
-        "Earth",
-        "Mars",
-        "Jupiter",
-        "Uranus",
-        "Neptune"
-      ]
-    }
+    --8<-- "examples/comments.output"
     ```

docs/mkdocs/docs/features/trailing_commas.md

@@ -0,0 +1,39 @@
+# Trailing Commas
+
+Like [comments](comments.md), this library does not support trailing commas in arrays and objects *by default*.
+
+You can set parameter `ignore_trailing_commas` to `#!cpp true` in the [`parse`](../api/basic_json/parse.md) function to allow trailing commas in arrays and objects. Note that a single comma as the only content of the array or object (`[,]` or `{,}`) is not allowed, and multiple trailing commas (`[1,,]`) are not allowed either.
+
+This library does not add trailing commas when serializing JSON data.
+
+For more information, see [JSON With Commas and Comments (JWCC)](https://nigeltao.github.io/blog/2021/json-with-commas-comments.html).
+
+!!! example
+
+    Consider the following JSON with trailing commas.
+
+    ```json
+    {
+        "planets": [
+            "Mercury",
+            "Venus",
+            "Earth",
+            "Mars",
+            "Jupiter",
+            "Uranus",
+            "Neptune",
+        ]
+    }
+    ```
+    
+    When calling `parse` without additional argument, a parse error exception is thrown. If `ignore_trailing_commas` is set to `#! true`, the trailing commas are ignored during parsing:
+
+    ```cpp
+    --8<-- "examples/trailing_commas.cpp"
+    ```
+
+    Output:
+    
+    ```
+    --8<-- "examples/trailing_commas.output"
+    ```

docs/mkdocs/mkdocs.yml

@@ -67,6 +67,7 @@ nav:
           - features/binary_formats/ubjson.md
       - features/binary_values.md
       - features/comments.md
+      - features/trailing_commas.md
       - Element Access:
           - features/element_access/index.md
           - features/element_access/unchecked_access.md