Merge pull request nlohmann#17 from nlohmann/develop

Sync Fork from Upstream Repo

CMakeLists.txt

@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.1)
 ## PROJECT
 ## name and version
 ##
-project(nlohmann_json VERSION 3.8.0 LANGUAGES CXX)
+project(nlohmann_json VERSION 3.8.0 DESCRIPTION "JSON for Modern C++" LANGUAGES CXX)
 
 ##
 ## INCLUDE
@@ -79,6 +79,12 @@ if (MSVC)
     )
 endif()
 
+# Install a pkg-config file, so other tools can find this.
+CONFIGURE_FILE(
+  "${CMAKE_CURRENT_SOURCE_DIR}/cmake/pkg-config.pc.in"
+  "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.pc"
+)
+
 ##
 ## TESTS
 ## create and configure the unit test target
@@ -139,4 +145,8 @@ endif()
         NAMESPACE ${PROJECT_NAME}::
         DESTINATION ${NLOHMANN_JSON_CONFIG_INSTALL_DIR}
     )
+    install(
+        FILES "${CMAKE_BINARY_DIR}/${PROJECT_NAME}.pc"
+        DESTINATION lib/pkgconfig
+    )
 endif()

Makefile

@@ -97,6 +97,7 @@ doctest:
 # -Wno-exit-time-destructors: warning in json code triggered by NLOHMANN_JSON_SERIALIZE_ENUM
 # -Wno-float-equal: not all comparisons in the tests can be replaced by Approx
 # -Wno-keyword-macro: unit-tests use "#define private public"
+# -Wno-missing-prototypes: for NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE
 # -Wno-padded: padding is nothing to warn about
 # -Wno-range-loop-analysis: items tests "for(const auto i...)"
 # -Wno-switch-enum -Wno-covered-switch-default: pedantic/contradicting warnings about switches
@@ -113,6 +114,7 @@ pedantic_clang:
 		-Wno-exit-time-destructors \
 		-Wno-float-equal \
 		-Wno-keyword-macro \
+		-Wno-missing-prototypes \
 		-Wno-padded \
 		-Wno-range-loop-analysis \
 		-Wno-switch-enum -Wno-covered-switch-default \

README.md

@@ -27,6 +27,7 @@
 - [Integration](#integration)
   - [CMake](#cmake)
   - [Package Managers](#package-managers)
+  - [Pkg-config](#pkg-config)
 - [Examples](#examples)
   - [JSON as first-class data type](#json-as-first-class-data-type)
   - [Serialization / Deserialization](#serialization--deserialization)
@@ -230,6 +231,20 @@ Please file issues [here](https://github.com/build2-packaging/nlohmann-json) if
 
 If you are using [`wsjcpp`](https://wsjcpp.org), you can use the command `wsjcpp install "https://github.com/nlohmann/json:develop"` to get the latest version. Note you can change the branch ":develop" to an existing tag or another branch.
 
+### Pkg-config
+
+If you are using bare Makefiles, you can use `pkg-config` to generate the include flags that point to where the library is installed:
+
+```sh
+pkg-config nlohmann_json --cflags
+```
+
+Users of the Meson build system will also be able to use a system wide library, which will be found by `pkg-config`:
+
+```meson
+json = dependency('nlohmann_json', required: true)
+```
+
 ## Examples
 
 Beside the examples below, you may want to check the [documentation](https://nlohmann.github.io/json/) where each function contains a separate code example (e.g., check out [`emplace()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a5338e282d1d02bed389d852dd670d98d.html#a5338e282d1d02bed389d852dd670d98d)). All [example files](https://github.com/nlohmann/json/tree/develop/doc/examples) can be compiled and executed on their own (e.g., file [emplace.cpp](https://github.com/nlohmann/json/blob/develop/doc/examples/emplace.cpp)).
@@ -1572,7 +1587,7 @@ Here is a related issue [#1924](https://github.com/nlohmann/json/issues/1924).
 
 ### Further notes
 
-- The code contains numerous debug **assertions** which can be switched off by defining the preprocessor macro `NDEBUG`, see the [documentation of `assert`](https://en.cppreference.com/w/cpp/error/assert). In particular, note [`operator[]`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a233b02b0839ef798942dd46157cc0fe6.html#a233b02b0839ef798942dd46157cc0fe6) implements **unchecked access** for const objects: If the given key is not present, the behavior is undefined (think of a dereferenced null pointer) and yields an [assertion failure](https://github.com/nlohmann/json/issues/289) if assertions are switched on. If you are not sure whether an element in an object exists, use checked access with the [`at()` function](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a73ae333487310e3302135189ce8ff5d8.html#a73ae333487310e3302135189ce8ff5d8).
+- The code contains numerous debug **assertions** which can be switched off by defining the preprocessor macro `NDEBUG`, see the [documentation of `assert`](https://en.cppreference.com/w/cpp/error/assert). In particular, note [`operator[]`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a233b02b0839ef798942dd46157cc0fe6.html#a233b02b0839ef798942dd46157cc0fe6) implements **unchecked access** for const objects: If the given key is not present, the behavior is undefined (think of a dereferenced null pointer) and yields an [assertion failure](https://github.com/nlohmann/json/issues/289) if assertions are switched on. If you are not sure whether an element in an object exists, use checked access with the [`at()` function](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a73ae333487310e3302135189ce8ff5d8.html#a73ae333487310e3302135189ce8ff5d8). Furthermore, you can define `JSON_ASSERT(x)` to replace calls to `assert(x)`.
 - As the exact type of a number is not defined in the [JSON specification](https://tools.ietf.org/html/rfc8259.html), this library tries to choose the best fitting C++ number type automatically. As a result, the type `double` may be used to store numbers which may yield [**floating-point exceptions**](https://github.com/nlohmann/json/issues/181) in certain rare situations if floating-point exceptions have been unmasked in the calling code. These exceptions are not caused by the library and need to be fixed in the calling code, such as by re-masking the exceptions prior to calling library functions.
 - The code can be compiled without C++ **runtime type identification** features; that is, you can use the `-fno-rtti` compiler flag.
 - **Exceptions** are used widely within the library. They can, however, be switched off with either using the compiler flag `-fno-exceptions` or by defining the symbol `JSON_NOEXCEPTION`. In this case, exceptions are replaced by `abort()` calls. You can further control this behavior by defining `JSON_THROW_USER´` (overriding `throw`), `JSON_TRY_USER` (overriding `try`), and `JSON_CATCH_USER` (overriding `catch`). Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.

cmake/pkg-config.pc.in

@@ -0,0 +1,4 @@
+Name: ${PROJECT_NAME}
+Description: ${PROJECT_DESCRIPTION}
+Version: ${PROJECT_VERSION}
+Cflags: -I${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}

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:

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.

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 <iostream>
+
+    #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 <nlohmann/json.hpp>
+    ```
+
 ## Parse errors
 
 This exception is thrown by the library when a parse error occurs. Parse errors

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