Documentation change (#3672)

Co-authored-by: Florian Albrechtskirchinger <falbrechtskirchinger@gmail.com>
This commit is contained in:
Niels Lohmann
2022-08-05 19:51:39 +02:00
committed by GitHub
co-authored by Florian Albrechtskirchinger
parent 9e1a7c85e3
commit 7b6cf5918b
65 changed files with 582 additions and 302 deletions
@@ -1,6 +1,10 @@
# Parsing and Exceptions
When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown. This exception contains the position in the input where the error occurred, together with a diagnostic message and the last read input token. The exceptions page contains a [list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like
When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown.
This exception contains the position in the input where the error occurred, together with a diagnostic message and the
last read input token. The exceptions page contains a
[list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted
input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like
```cpp
json j;
@@ -19,7 +23,9 @@ In case exceptions are undesired or not supported by the environment, there are
## Switch off exceptions
The `parse()` function accepts as last parameter a `#!cpp bool` variable `allow_exceptions` which controls whether an exception is thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned (`#!cpp false`).
The `parse()` function accepts a `#!cpp bool` parameter `allow_exceptions` which controls whether an exception is
thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned
(`#!cpp false`).
```cpp
json j = json::parse(my_input, nullptr, false);
@@ -33,7 +39,8 @@ Note there is no diagnostic information available in this scenario.
## Use accept() function
Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating whether the input is valid JSON.
Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating
whether the input is valid JSON.
```cpp
if (!json::accept(my_input))
@@ -2,9 +2,10 @@
## Overview
With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is called on certain events
(passed as `parse_event_t` via parameter `event`) with a set recursion depth `depth` and context JSON value `parsed`. The return value of the
callback function is a boolean indicating whether the element that emitted the callback shall be kept or not.
With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is
called on certain events (passed as `parse_event_t` via parameter `event`) with a set recursion depth `depth` and
context JSON value `parsed`. The return value of the callback function is a boolean indicating whether the element that
emitted the callback shall be kept or not.
The type of the callback function is:
@@ -17,8 +18,8 @@ using parser_callback_t =
## Callback event types
We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values
of the parameters `depth`, `event`, and `parsed`.
We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following
table describes the values of the parameters `depth`, `event`, and `parsed`.
| parameter `event` | description | parameter `depth` | parameter `parsed` |
|-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------|
@@ -59,10 +60,13 @@ of the parameters `depth`, `event`, and `parsed`.
## Return value
Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which function was called:
Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which the function
was called:
- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never read.
- In case a value outside a structured type is skipped, it is replaced with `#!json null`. This case happens if the top-level element is skipped.
- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never
read.
- In case a value outside a structured type is skipped, it is replaced with `#!json null`. This case happens if the
top-level element is skipped.
??? example