• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Parser Callbacks
2
3## Overview
4
5With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is called on certain events
6(passed as `parse_event_t` via parameter `event`) with a set recursion depth `depth` and context JSON value `parsed`. The return value of the
7callback function is a boolean indicating whether the element that emitted the callback shall be kept or not.
8
9The type of the callback function is:
10
11```cpp
12template<typename BasicJsonType>
13using parser_callback_t =
14    std::function<bool(int depth, parse_event_t event, BasicJsonType& parsed)>;
15```
16
17
18## Callback event types
19
20We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values
21of the parameters `depth`, `event`, and `parsed`.
22
23parameter `event` | description | parameter `depth` | parameter `parsed`
24------------------ | ----------- | ------------------ | -------------------
25`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
26`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
27`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
28`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
29`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
30`parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value
31
32??? example
33
34    When parsing the following JSON text,
35
36    ```json
37    {
38        "name": "Berlin",
39        "location": [
40            52.519444,
41            13.406667
42        ]
43    }
44    ```
45
46    these calls are made to the callback function:
47
48    | event          | depth | parsed |
49    | -------------- | ----- | ------ |
50    | `object_start` | 0     | *discarded* |
51    | `key`          | 1     | `#!json "name"` |
52    | `value`        | 1     | `#!json "Berlin"` |
53    | `key`          | 1     | `#!json "location"` |
54    | `array_start`  | 1     | *discarded* |
55    | `value`        | 2     | `#!json 52.519444` |
56    | `value`        | 2     | `#!json 13.406667` |
57    | `array_end`    | 1     | `#!json [52.519444,13.406667]` |
58    | `object_end`   | 0     | `#!json {"location":[52.519444,13.406667],"name":"Berlin"}` |
59
60## Return value
61
62Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which function was called:
63
64- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never read.
65- 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.
66
67??? example
68
69    The example below demonstrates the `parse()` function with and without callback function.
70
71    ```cpp
72    --8<-- "examples/parse__string__parser_callback_t.cpp"
73    ```
74
75    Output:
76
77    ```json
78    --8<-- "examples/parse__string__parser_callback_t.output"
79    ```
80