From d00ad33e46fb2fe116467a9ef296cc70c4b6ac79 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Thu, 21 Jan 2021 21:47:19 +0100 Subject: [PATCH] :memo: update documentation --- doc/examples/diagnostics_extended.cpp | 22 +++++++++++++ doc/examples/diagnostics_extended.link | 1 + doc/examples/diagnostics_extended.output | 1 + doc/examples/diagnostics_standard.cpp | 20 ++++++++++++ doc/examples/diagnostics_standard.link | 1 + doc/examples/diagnostics_standard.output | 1 + doc/mkdocs/docs/features/macros.md | 10 ++++++ doc/mkdocs/docs/home/exceptions.md | 39 ++++++++++++++++++++++++ doc/mkdocs/docs/home/license.md | 2 +- 9 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 doc/examples/diagnostics_extended.cpp create mode 100644 doc/examples/diagnostics_extended.link create mode 100644 doc/examples/diagnostics_extended.output create mode 100644 doc/examples/diagnostics_standard.cpp create mode 100644 doc/examples/diagnostics_standard.link create mode 100644 doc/examples/diagnostics_standard.output diff --git a/doc/examples/diagnostics_extended.cpp b/doc/examples/diagnostics_extended.cpp new file mode 100644 index 000000000..f4c43f05e --- /dev/null +++ b/doc/examples/diagnostics_extended.cpp @@ -0,0 +1,22 @@ +#include + +# define JSON_DIAGNOSTICS 1 +#include + +using json = nlohmann::json; + +int main() +{ + json j; + j["address"]["street"] = "Fake Street"; + j["address"]["housenumber"] = "12"; + + try + { + int housenumber = j["address"]["housenumber"]; + } + catch (json::exception& e) + { + std::cout << e.what() << '\n'; + } +} diff --git a/doc/examples/diagnostics_extended.link b/doc/examples/diagnostics_extended.link new file mode 100644 index 000000000..9f10da942 --- /dev/null +++ b/doc/examples/diagnostics_extended.link @@ -0,0 +1 @@ +online \ No newline at end of file diff --git a/doc/examples/diagnostics_extended.output b/doc/examples/diagnostics_extended.output new file mode 100644 index 000000000..f142927a1 --- /dev/null +++ b/doc/examples/diagnostics_extended.output @@ -0,0 +1 @@ +[json.exception.type_error.302] (/address/housenumber) type must be number, but is string diff --git a/doc/examples/diagnostics_standard.cpp b/doc/examples/diagnostics_standard.cpp new file mode 100644 index 000000000..575c409eb --- /dev/null +++ b/doc/examples/diagnostics_standard.cpp @@ -0,0 +1,20 @@ +#include +#include + +using json = nlohmann::json; + +int main() +{ + json j; + j["address"]["street"] = "Fake Street"; + j["address"]["housenumber"] = "12"; + + try + { + int housenumber = j["address"]["housenumber"]; + } + catch (json::exception& e) + { + std::cout << e.what() << '\n'; + } +} diff --git a/doc/examples/diagnostics_standard.link b/doc/examples/diagnostics_standard.link new file mode 100644 index 000000000..cd0453b5e --- /dev/null +++ b/doc/examples/diagnostics_standard.link @@ -0,0 +1 @@ +online \ No newline at end of file diff --git a/doc/examples/diagnostics_standard.output b/doc/examples/diagnostics_standard.output new file mode 100644 index 000000000..79707a0cb --- /dev/null +++ b/doc/examples/diagnostics_standard.output @@ -0,0 +1 @@ +[json.exception.type_error.302] type must be number, but is string diff --git a/doc/mkdocs/docs/features/macros.md b/doc/mkdocs/docs/features/macros.md index 696438d2f..d044bfd26 100644 --- a/doc/mkdocs/docs/features/macros.md +++ b/doc/mkdocs/docs/features/macros.md @@ -12,6 +12,14 @@ This macro overrides `#!cpp catch` calls inside the library. The argument is the See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. +## `JSON_DIAGNOSTICS` + +This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable (default). + +When enabled, exception messages contain a [JSON Pointer](json_pointer.md) to the JSON value that triggered the exception, see [Extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) for an example. + +The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets `JSON_DIAGNOSTICS` accordingly. + ## `JSON_NOEXCEPTION` Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. @@ -56,6 +64,8 @@ When defined to `0`, implicit conversions are switched off. By default, implicit auto s = j.get(); ``` +Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly. + ## `NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)` This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object. diff --git a/doc/mkdocs/docs/home/exceptions.md b/doc/mkdocs/docs/home/exceptions.md index 0475f53e2..a3b1e9c76 100644 --- a/doc/mkdocs/docs/home/exceptions.md +++ b/doc/mkdocs/docs/home/exceptions.md @@ -50,6 +50,45 @@ Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or #include ``` +### Extended diagnostic messages + +Exceptions in the library are thrown in the local context of the JSON value they are detected. This makes detailed +diagnostics messages, and hence debugging, difficult. + +??? example + + ```cpp + --8<-- "examples/diagnostics_standard.cpp" + ``` + + Output: + + ``` + --8<-- "examples/diagnostics_standard.output" + ``` + + This exception can be hard to debug if storing the value `#!c "12"` and accessing it is further apart. + +To create better diagnostics messages, each JSON value needs a pointer to its parent value such that a global context (i.e., a path from the root value to the value that lead to the exception) can be created. That global context is provided as [JSON Pointer](../features/json_pointer.md). + +As this global context comes at the price of storing one additional pointer per JSON value and runtime overhead to maintain the parent relation, extended diagnostics are disabled by default. They can, however, be enabled by defining the preprocessor symbol [`JSON_DIAGNOSTICS`](../features/macros.md#json_diagnostics) to `1` before including `json.hpp`. + +??? example + + ```cpp + --8<-- "examples/diagnostics_extended.cpp" + ``` + + Output: + + ``` + --8<-- "examples/diagnostics_extended.output" + ``` + + Now the exception message contains a JSON Pointer `/address/housenumber` that indicates which value has the wrong type. + + + ## Parse errors This exception is thrown by the library when a parse error occurs. Parse errors diff --git a/doc/mkdocs/docs/home/license.md b/doc/mkdocs/docs/home/license.md index 4cd6ca2cc..d359468e0 100644 --- a/doc/mkdocs/docs/home/license.md +++ b/doc/mkdocs/docs/home/license.md @@ -4,7 +4,7 @@ The class is licensed under the [MIT License](https://opensource.org/licenses/MIT): -Copyright © 2013-2020 [Niels Lohmann](https://nlohmann.me) +Copyright © 2013-2021 [Niels Lohmann](https://nlohmann.me) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: