mirror of
https://github.com/nlohmann/json.git
synced 2026-07-11 21:15:10 +00:00
nlohmann
115 lines
5.1 KiB
Markdown
115 lines
5.1 KiB
Markdown
# Parser Callbacks
|
|
|
|
## 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.
|
|
|
|
The type of the callback function is:
|
|
|
|
```cpp
|
|
template<typename BasicJsonType>
|
|
using parser_callback_t =
|
|
std::function<bool(int depth, parse_event_t event, BasicJsonType& parsed)>;
|
|
```
|
|
|
|
|
|
## 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`.
|
|
|
|
| parameter `event` | description | parameter `depth` | parameter `parsed` |
|
|
|-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------|
|
|
| `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 |
|
|
| `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 |
|
|
| `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 |
|
|
| `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 |
|
|
| `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 |
|
|
| `parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value |
|
|
|
|
??? example
|
|
|
|
When parsing the following JSON text,
|
|
|
|
```json
|
|
{
|
|
"name": "Berlin",
|
|
"location": [
|
|
52.519444,
|
|
13.406667
|
|
]
|
|
}
|
|
```
|
|
|
|
these calls are made to the callback function:
|
|
|
|
| event | depth | parsed |
|
|
| -------------- | ----- | ------ |
|
|
| `object_start` | 0 | *discarded* |
|
|
| `key` | 1 | `#!json "name"` |
|
|
| `value` | 1 | `#!json "Berlin"` |
|
|
| `key` | 1 | `#!json "location"` |
|
|
| `array_start` | 1 | *discarded* |
|
|
| `value` | 2 | `#!json 52.519444` |
|
|
| `value` | 2 | `#!json 13.406667` |
|
|
| `array_end` | 1 | `#!json [52.519444,13.406667]` |
|
|
| `object_end` | 0 | `#!json {"location":[52.519444,13.406667],"name":"Berlin"}` |
|
|
|
|
## Return value
|
|
|
|
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.
|
|
|
|
??? example
|
|
|
|
The example below demonstrates the `parse()` function with and without callback function.
|
|
|
|
```cpp
|
|
--8<-- "examples/parse__string__parser_callback_t.cpp"
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
--8<-- "examples/parse__string__parser_callback_t.output"
|
|
```
|
|
|
|
## Recipe: rejecting duplicate object keys
|
|
|
|
The JSON specification leaves the handling of objects with repeated keys up to the implementation. As described in
|
|
[`object_t`](../../api/basic_json/object_t.md#behavior), it is unspecified which value for a repeated key ends up in
|
|
the resulting `#!c json` value -- once parsing has produced that value, the duplicate is already gone, because object
|
|
storage maps each key to a single value. If duplicate keys should instead be treated as an error, a parser callback
|
|
can detect them while the object is still being read, before that ambiguity ever applies.
|
|
|
|
??? example
|
|
|
|
```cpp
|
|
--8<-- "examples/reject_duplicate_keys.cpp"
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
--8<-- "examples/reject_duplicate_keys.output"
|
|
```
|
|
|
|
This approach has two limitations:
|
|
|
|
- The depth-indexed bookkeeping must account for the fact that `object_start` reports the depth of the *parent* of
|
|
the object, while the `key` events inside that object are reported one depth deeper (see the event table above);
|
|
it is easy to get this off by one for nested objects.
|
|
- The thrown exception cannot carry a `parse_error`-style byte offset, because position tracking only exists inside
|
|
the parser and lexer, not at the callback layer.
|
|
|
|
For strict validation with precise error positions, implementing a [SAX interface](sax_interface.md) instead gives
|
|
access to the parser's position information directly.
|