External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

📝 overwork macro documentation

Browse Source
This commit is contained in:
Niels Lohmann 2022-04-18 16:07:23 +02:00
parent b94e90e66e
commit 90be3582e8
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
7 changed files with 139 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/mkdocs/docs/api/macros/index.md
View File

@ -13,11 +13,9 @@ header.
## Exceptions
- `JSON_CATCH_USER(exception)`
- [**JSON_CATCH_USER(exception)**<br>**JSON_THROW_USER(exception)**<br>**JSON_TRY_USER**](json_throw_user.md) - control exceptions
- [**JSON_DIAGNOSTICS**](json_diagnostics.md) - control extended diagnostics
- `JSON_NOEXCEPTION`
- `JSON_THROW_USER(exception)`
- `JSON_TRY_USER`
- [**JSON_NOEXCEPTION**](json_noexception.md) - switch off exceptions
## Language support

32
doc/mkdocs/docs/api/macros/json_noexception.md Normal file
View File

@ -0,0 +1,32 @@
# JSON_NOEXCEPTION
```cpp
#define 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`.
## Default definition
By default, the macro is not defined.
```cpp
#undef JSON_NOEXCEPTION
```
## Notes
The explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not
available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).
## See also
- [Switch off exceptions](../../home/exceptions.md#switch-off-exceptions) for more information how to switch off exceptions
## Version history
Added in version 2.1.0.

17
doc/mkdocs/docs/api/macros/json_skip_library_version_check.md
View File

@ -15,6 +15,23 @@ By default, the macro is not defined.
#undef JSON_SKIP_LIBRARY_VERSION_CHECK
```
## Notes
!!! warning
Mixing different library versions in the same code can be a problem as the different versions may not be ABI
compatible.
## Examples
!!! example
The following warning will be shown in case a different version of the library was already included:
```
Already included a different version of the library!
```
## Version history
Added in version 3.11.0.

70
doc/mkdocs/docs/api/macros/json_throw_user.md Normal file
View File

@ -0,0 +1,70 @@
# JSON_CATCH_USER(exception), JSON_THROW_USER(exception), JSON_TRY_USER
```cpp
// (1)
#define JSON_CATCH_USER(exception) /* value */
// (2)
#define JSON_THROW_USER(exception) /* value */
// (3)
#define JSON_TRY_USER /* value */
```
Controls how exceptions are handled by the library.
1. This macro overrides [`#!cpp catch`](https://en.cppreference.com/w/cpp/language/try_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.
2. 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.
3. This macro overrides `#!cpp try` calls inside the library. It has no arguments and is always followed by a scope.
## Default definition
By default, the macros map to their respective C++ keywords:
```cpp
#define JSON_CATCH_USER(exception) catch(exception)
#define JSON_THROW_USER(exception) throw exception
#define JSON_TRY_USER try
```
When exceptions are switched off, the `#!cpp try` block is executed unconditionally, and throwing exceptions is
replaced by calling [`std::abort`](https://en.cppreference.com/w/cpp/utility/program/abort) to make reaching the
`cpp throw` branch abort the process.
```cpp
#define JSON_THROW_USER(exception) std::abort()
#define JSON_TRY_USER if (true)
#define JSON_CATCH_USER(exception) if (false)
```
## Examples
??? 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>
```
## See also
- [Switch off exceptions](../../home/exceptions.md#switch-off-exceptions) for more information how to switch off exceptions
- [JSON_NOEXCEPTION](JSON_NOEXCEPTION) - switch off exceptions
## Version history
- Added in version 3.1.0.

89
doc/mkdocs/docs/features/macros.md
View File

@ -11,29 +11,8 @@ See [full documentation of `JSON_ASSERT(x)`](../api/macros/json_assert.md).
## `JSON_CATCH_USER(exception)`
This macro overrides [`#!cpp catch`](https://en.cppreference.com/w/cpp/language/try_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.
!!! info "Default behavior"
When exceptions are enabled, the default value is
[`#!cpp catch(exception)`](https://en.cppreference.com/w/cpp/language/try_catch).
```cpp
#define JSON_CATCH_USER(exception) catch(exception)
```
When exceptions are switched off by the compiler, the default value is `#!cpp if (false)` to make the catch block
unreachable.
```cpp
#define JSON_CATCH_USER(exception) if (false)
```
The macro was introduced in version 3.1.0.
See [full documentation of `JSON_CATCH_USER(exception)`](../api/macros/json_throw_user.md).
## `JSON_DIAGNOSTICS`
@ -70,24 +49,9 @@ See [full documentation of `JSON_HAS_FILESYSTEM` and `JSON_HAS_EXPERIMENTAL_FILE
## `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()`.
Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`.
!!! info "Default behavior"
By default, the macro is not defined.
```cpp
#undef JSON_NOEXCEPTION
```
The same effect is achieved by setting the compiler flag `-fno-exceptions`.
Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not
available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).
The macro was introduced in version 2.1.0.
See [full documentation of `JSON_NOEXCEPTION`](../api/macros/json_noexception.md).
## `JSON_NO_IO`
@ -113,54 +77,15 @@ See [full documentation of `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`](../api/macros
## `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.
This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown.
!!! info "Default behavior"
When exceptions are enabled, the default value is
[`#!cpp throw exception`](https://en.cppreference.com/w/cpp/language/throw).
```cpp
#define JSON_THROW_USER(exception) throw exception
```
When exceptions are switched off by the compiler, the default value is
[`#!cpp std::abort()`](https://en.cppreference.com/w/cpp/utility/program/abort) to make reaching the throw branch
abort the process.
```cpp
#define JSON_THROW_USER(exception) std::abort()
```
See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
The macro was introduced in version 3.1.0.
See [full documentation of `JSON_THROW_USER(exception)`](../api/macros/json_throw_user.md).
## `JSON_TRY_USER`
This macro overrides `#!cpp try` calls inside the library. It has no arguments and is always followed by a scope.
This macro overrides `#!cpp try` calls inside the library.
!!! info "Default behavior"
When exceptions are enabled, the default value is
[`#!cpp try`](https://en.cppreference.com/w/cpp/language/try_catch).
```cpp
#define JSON_TRY_USER try
```
When exceptions are switched off by the compiler, the default value is `#!cpp if (true)` to unconditionally execute
the following code block.
```cpp
#define JSON_TRY_USER if (true)
```
See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
The macro was introduced in version 3.1.0.
See [full documentation of `JSON_TRY_USER`](../api/macros/json_throw_user.md).
## `JSON_USE_IMPLICIT_CONVERSIONS`

7
doc/mkdocs/docs/home/exceptions.md
View File

@ -28,9 +28,9 @@ class json::parse_error {
### Switch off exceptions
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 `#!cpp throw`), `JSON_TRY_USER` (overriding `#!cpp try`), and `JSON_CATCH_USER` (overriding `#!cpp catch`).
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`](../api/macros/json_noexception.md). In this case, exceptions are replaced by `abort()` calls. You can further control this behavior by defining `JSON_THROW_USER` (overriding `#!cpp throw`), `JSON_TRY_USER` (overriding `#!cpp try`), and `JSON_CATCH_USER` (overriding `#!cpp 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.
Note that [`JSON_THROW_USER`](../api/macros/json_throw_user.md) should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.
??? example
@ -52,6 +52,8 @@ Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or
Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).
See [documentation of `JSON_TRY_USER`, `JSON_CATCH_USER` and `JSON_THROW_USER`](../api/macros/json_throw_user.md) for more information.
### 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.
@ -88,6 +90,7 @@ As this global context comes at the price of storing one additional pointer per
Now the exception message contains a JSON Pointer `/address/housenumber` that indicates which value has the wrong type.
See [documentation of `JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) for more information.
## Parse errors

8
doc/mkdocs/mkdocs.yml
View File

@ -234,17 +234,21 @@ nav:
- macros:
- 'Overview': api/macros/index.md
- 'JSON_ASSERT(x)': api/macros/json_assert.md
- 'JSON_CATCH_USER': api/macros/json_throw_user.md
- 'JSON_DIAGNOSTICS': api/macros/json_diagnostics.md
- 'JSON_HAS_EXPERIMENTAL_FILESYSTEM': api/macros/json_has_filesystem.md
- 'JSON_HAS_CPP_11': api/macros/json_has_cpp_11.md
- 'JSON_HAS_CPP_14': api/macros/json_has_cpp_11.md
- 'JSON_HAS_CPP_17': api/macros/json_has_cpp_11.md
- 'JSON_HAS_CPP_20': api/macros/json_has_cpp_11.md
- 'JSON_HAS_EXPERIMENTAL_FILESYSTEM': api/macros/json_has_filesystem.md
- 'JSON_HAS_FILESYSTEM': api/macros/json_has_filesystem.md
- 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md
- 'JSON_NOEXCEPTION': api/macros/json_noexception.md
- 'JSON_NO_IO': api/macros/json_no_io.md
- 'JSON_SKIP_LIBRARY_VERSION_CHECK': api/macros/json_skip_library_version_check.md
- 'JSON_SKIP_UNSUPPORTED_COMPILER_CHECK': api/macros/json_skip_unsupported_compiler_check.md
- 'JSON_THROW_USER': api/macros/json_throw_user.md
- 'JSON_TRY_USER': api/macros/json_throw_user.md
- 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md
- 'NLOHMANN_JSON_VERSION_MAJOR': api/macros/nlohmann_json_version_major.md
- 'NLOHMANN_JSON_VERSION_MINOR': api/macros/nlohmann_json_version_major.md
- 'NLOHMANN_JSON_VERSION_PATCH': api/macros/nlohmann_json_version_major.md