• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# <small>nlohmann::basic_json::</small>parser_callback_t
2
3```cpp
4template<typename BasicJsonType>
5using parser_callback_t =
6    std::function<bool(int depth, parse_event_t event, BasicJsonType& parsed)>;
7```
8
9With a parser callback function, the result of parsing a JSON text can be influenced. When passed to
10[`parse`](parse.md), it is called on certain events (passed as [`parse_event_t`](parse_event_t.md) via parameter
11`event`) with a set recursion depth `depth` and context JSON value `parsed`. The return value of the callback function
12is a boolean indicating whether the element that emitted the callback shall be kept or not.
13
14We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following
15table describes the values of the parameters `depth`, `event`, and `parsed`.
16
17| parameter `event`             | description                                               | parameter `depth`                         | parameter `parsed`               |
18|-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------|
19| `parse_event_t::object_start` | the parser read `{` and started to process a JSON object  | depth of the parent of the JSON object    | a JSON value with type discarded |
20| `parse_event_t::key`          | the parser read a key of a value in an object             | depth of the currently parsed JSON object | a JSON string containing the key |
21| `parse_event_t::object_end`   | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object    | the parsed JSON object           |
22| `parse_event_t::array_start`  | the parser read `[` and started to process a JSON array   | depth of the parent of the JSON array     | a JSON value with type discarded |
23| `parse_event_t::array_end`    | the parser read `]` and finished processing a JSON array  | depth of the parent of the JSON array     | the parsed JSON array            |
24| `parse_event_t::value`        | the parser finished reading a JSON value                  | depth of the value                        | the parsed JSON value            |
25
26![Example when certain parse events are triggered](../../images/callback_events.png)
27
28Discarding a value (i.e., returning `#!cpp false`) has different effects depending on the context in which function was
29called:
30
31- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never
32  read.
33- In case a value outside a structured type is skipped, it is replaced with `null`. This case happens if the top-level
34  element is skipped.
35
36## Parameters
37
38`depth` (in)
39:   the depth of the recursion during parsing
40
41`event` (in)
42:   an event of type [`parse_event_t`](parse_event_t.md) indicating the context in
43    the callback function has been called
44
45`parsed` (in, out)
46:    the current intermediate parse result; note that
47     writing to this value has no effect for `parse_event_t::key` events
48
49## Return value
50
51Whether the JSON value which called the function during parsing should be kept (`#!cpp true`) or not (`#!cpp false`). In
52the latter case, it is either skipped completely or replaced by an empty discarded object.
53
54## Examples
55
56??? example
57
58    The example below demonstrates the `parse()` function with
59    and without callback function.
60
61    ```cpp
62    --8<-- "examples/parse__string__parser_callback_t.cpp"
63    ```
64
65    Output:
66
67    ```json
68    --8<-- "examples/parse__string__parser_callback_t.output"
69    ```
70
71## Version history
72
73- Added in version 1.0.0.
74