use diagnostic positions in exceptions (#4585)

* add a ci step for Json_Diagnostic_Positions

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* Update ci.cmake to address review comments

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* address review comment

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* fix typo in the comment

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* fix typos in ci.cmake

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* invoke the new ci step from ubuntu.yml

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* issue4561 - use diagnostic positions for exceptions

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* fix ci_test_documentation check

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* address review comments

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* fix ci check failures for unit-diagnostic-postions.cpp

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* improvements based on review comments

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* fix const correctness string

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* further refinements based on reviews

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* add one more test case for full coverage

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* ci check fix - add const

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* add unit tests for json_diagnostic_postions only

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* fix ci_test_diagnostics

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

* fix ci_test_build_documentation check

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

---------

Signed-off-by: Harinath Nampally <harinath922@gmail.com>

docs/mkdocs/docs/api/macros/json_diagnostic_positions.md

@@ -81,6 +81,33 @@ When the macro is not defined, the library will define it to its default value.
 
     The output shows the start/end positions of all the objects and fields in the JSON string.
 
+??? example "Example 2: using only diagnostic positions in exceptions"
+
+    ```cpp
+    --8<-- "examples/diagnostic_positions_exception.cpp"
+    ```
+    
+    Output:
+
+    ```
+    --8<-- "examples/diagnostic_positions_exception.output"
+    ```
+
+        The output shows the exception with start/end positions only.
+
+??? example "Example 3: using extended diagnostics with positions enabled in exceptions"
+
+    ```cpp
+    --8<-- "examples/diagnostics_extended_positions.cpp"
+    ```
+    
+    Output:
+
+    ```
+    --8<-- "examples/diagnostics_extended_positions.output"
+    ```
+    
+        The output shows the exception with diagnostic path info and start/end positions.
 ## Version history
 
 - Added in version 3.12.0.

docs/mkdocs/docs/api/macros/json_diagnostics.md

@@ -70,6 +70,19 @@ When the macro is not defined, the library will define it to its default value.
 
     Now the exception message contains a JSON Pointer `/address/housenumber` that indicates which value has the wrong type.
 
+??? example "Example 3: using only diagnostic positions in exceptions"
+
+    ```cpp
+    --8<-- "examples/diagnostic_positions_exception.cpp"
+    ```
+    
+    Output:
+
+    ```
+    --8<-- "examples/diagnostic_positions_exception.output"
+    ```    
+        The output shows the exception with start/end positions only.
+        
 ## Version history
 
 - Added in version 3.10.0.

docs/mkdocs/docs/examples/diagnostic_positions_exception.cpp

@@ -0,0 +1,30 @@
+#include <iostream>
+
+#define JSON_DIAGNOSTIC_POSITIONS 1
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+/* Demonstration of type error exception with diagnostic postions support enabled */
+int main()
+{
+    //Invalid json string - housenumber type must be int instead of string
+    const std::string json_invalid_string = R"(
+    {
+        "address": {
+            "street": "Fake Street",
+            "housenumber": "1"
+        }
+    }
+    )";
+    json j = json::parse(json_invalid_string);
+    try
+    {
+        int housenumber = j["address"]["housenumber"];
+        std::cout << housenumber;
+    }
+    catch (const json::exception& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+}

docs/mkdocs/docs/examples/diagnostic_positions_exception.output

@@ -0,0 +1 @@
+[json.exception.type_error.302] (bytes 92-95) type must be number, but is string

docs/mkdocs/docs/examples/diagnostics_extended_positions.cpp

@@ -0,0 +1,31 @@
+#include <iostream>
+
+#define JSON_DIAGNOSTICS 1
+#define JSON_DIAGNOSTIC_POSITIONS 1
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+/* Demonstration of type error exception with diagnostic postions support enabled */
+int main()
+{
+    //Invalid json string - housenumber type must be int instead of string
+    const std::string json_invalid_string = R"(
+    {
+        "address": {
+            "street": "Fake Street",
+            "housenumber": "1"
+        }
+    }
+    )";
+    json j = json::parse(json_invalid_string);
+    try
+    {
+        int housenumber = j["address"]["housenumber"];
+        std::cout << housenumber;
+    }
+    catch (const json::exception& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+}

docs/mkdocs/docs/examples/diagnostics_extended_positions.output

@@ -0,0 +1 @@
+[json.exception.type_error.302] (/address/housenumber) (bytes 92-95) type must be number, but is string