From d740622f961a07d73fa2f6e1f61841812c998b1f Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Thu, 9 Jul 2020 13:23:33 +0200 Subject: [PATCH] :pencil: add documentation for macros --- doc/mkdocs/docs/features/arbitrary_types.md | 37 ++++++++++++++ doc/mkdocs/docs/features/macros.md | 55 +++++++++++++++++++++ doc/mkdocs/docs/home/exceptions.md | 18 +++++++ doc/mkdocs/mkdocs.yml | 1 + 4 files changed, 111 insertions(+) create mode 100644 doc/mkdocs/docs/features/macros.md diff --git a/doc/mkdocs/docs/features/arbitrary_types.md b/doc/mkdocs/docs/features/arbitrary_types.md index 3d238317..7bd7adf7 100644 --- a/doc/mkdocs/docs/features/arbitrary_types.md +++ b/doc/mkdocs/docs/features/arbitrary_types.md @@ -81,6 +81,43 @@ Some important things: * You do not need to add serializers or deserializers for STL types like `std::vector`: the library already implements these. +## Simplify your life with macros + +If you just want to serialize/deserialize some structs, the `to_json`/`from_json` functions can be a lot of boilerplate. + +There are two macros to make your life easier as long as you (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object: + +- `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(name, member1, member2, ...)` is to be defined inside of the namespace of the class/struct to create code for. +- `NLOHMANN_DEFINE_TYPE_INTRUSIVE(name, member1, member2, ...)` is to be defined inside of the class/struct to create code for. This macro can also access private members. + +In both macros, the first parameter is the name of the class/struct, and all remaining parameters name the members. + +??? example + + The `to_json`/`from_json` functions for the `person` struct above can be created with: + + ```cpp + namespace ns { + NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(person, name, address, age) + } + ``` + + Here is an example with private members, where `NLOHMANN_DEFINE_TYPE_INTRUSIVE` is needed: + + ```cpp + namespace ns { + class address { + private: + std::string street; + int housenumber; + int postcode; + + public: + NLOHMANN_DEFINE_TYPE_INTRUSIVE(address, street, housenumber, postcode) + }; + } + ``` + ## How do I convert third-party types? This requires a bit more advanced technique. But first, let's see how this conversion mechanism works: diff --git a/doc/mkdocs/docs/features/macros.md b/doc/mkdocs/docs/features/macros.md new file mode 100644 index 00000000..7147be7e --- /dev/null +++ b/doc/mkdocs/docs/features/macros.md @@ -0,0 +1,55 @@ +# Supported Macros + +Some aspects of the library can be configured by defining preprocessor macros before including the `json.hpp` header. + +## `JSON_CATCH_USER(exception)` + +This macro overrides `#!cpp catch` calls inside the library. The argument is the type of the exception to catch. As of version 3.8.0, the library only catches `std::out_of_range` exceptions internally to rethrow them as [`json::out_of_range`](../home/exceptions.md#out-of-range) exceptions. The macro is always followed by a scope. + +See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. + +## `JSON_NOEXCEPTION` + +Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. +When defining `JSON_NOEXCEPTION`, `#!cpp try` is replaced by `#!cpp if (true)`, +`#!cpp catch` is replaced by `#!cpp if (false)`, and `#!cpp throw` is replaced by `#!cpp std::abort()`. + +The same effect is achieved by setting the compiler flag `-fno-exceptions`. + +## `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK` + +When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows to use the library with compilers that do not fully support C++11 and may only work if unsupported features are not used. + +## `JSON_THROW_USER(exception)` + +This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior. + +See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. + +## `JSON_TRY_USER` + +This macro overrides `#!cpp try` calls inside the library. It has no arguments and is always followed by a scope. + +See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. + +## `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. + +The macro is to be defined inside of the class/struct to create code for. Unlike [`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](#nlohmann_define_type_non_intrusivetype-member), it can access private members. +The first parameter is the name of the class/struct, and all remaining parameters name the members. + +See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example. + +## `NLOHMANN_DEFINE_TYPE_NON_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. + +The macro is to be defined inside of the namespace of the class/struct to create code for. Private members cannot be accessed. Use [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](#nlohmann_define_type_intrusivetype-member) in these scenarios. +The first parameter is the name of the class/struct, and all remaining parameters name the members. + +See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example. + +## `NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)` + +This macro simplifies the serialization/deserialization of enum types. See [Specializing enum conversion](enum_conversion.md) for more information. diff --git a/doc/mkdocs/docs/home/exceptions.md b/doc/mkdocs/docs/home/exceptions.md index 92dfb43b..d7430ccc 100644 --- a/doc/mkdocs/docs/home/exceptions.md +++ b/doc/mkdocs/docs/home/exceptions.md @@ -32,6 +32,24 @@ Exceptions are used widely within the library. They can, however, be switched of Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior. +??? example + + The code below switches off exceptions and creates a log entry with a detailed error message in case of errors. + + ```cpp + #include + + #define JSON_TRY_USER if(true) + #define JSON_CATCH_USER(exception) if(false) + #define JSON_THROW_USER(exception) \ + {std::clog << "Error in " << __FILE__ << ":" << __LINE__ \ + << " (function " << __FUNCTION__ << ") - " \ + << (exception).what() << std::endl; \ + std::abort();} + + #include + ``` + ## Parse errors This exception is thrown by the library when a parse error occurs. Parse errors diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index 5d6e3b4e..9169e4f1 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -49,6 +49,7 @@ nav: - features/json_patch.md - features/merge_patch.md - features/enum_conversion.md + - features/macros.md - Parsing: - features/parsing/index.md - features/parsing/parse_exceptions.md