mirror of
https://github.com/nlohmann/json.git
synced 2026-10-12 10:13:13 +00:00
240 lines
9.1 KiB
Markdown
240 lines
9.1 KiB
Markdown
# <small>nlohmann::basic_json::</small>parser_callback_t
|
|
|
|
```cpp
|
|
template<typename BasicJsonType>
|
|
using parser_callback_t =
|
|
std::function<bool(int depth, parse_event_t event, BasicJsonType& parsed)>;
|
|
```
|
|
|
|
With a parser callback function, the result of parsing a JSON text can be influenced. When passed to
|
|
[`parse`](parse.md), it is called on certain events (passed as [`parse_event_t`](parse_event_t.md) 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.
|
|
|
|
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 |
|
|
|
|
|
|
|
|
Discarding a value (i.e., returning `#!cpp false`) has different effects depending on the context in which function was
|
|
called:
|
|
|
|
- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never
|
|
read. This holds for every value type and for both kinds of parent: a discarded element is removed from the
|
|
surrounding array, and a discarded member is removed from the surrounding object together with its key.
|
|
- Arrays and objects can be discarded either at their `parse_event_t::array_start`/`parse_event_t::object_start` event
|
|
or at their `parse_event_t::array_end`/`parse_event_t::object_end` event, and both remove the whole value. Discarding
|
|
it at the start event also means the callback is called neither for the content of the value nor for its matching end
|
|
event.
|
|
- Discarding a `parse_event_t::key` event discards the whole object member. The callback is still called for the
|
|
associated value, but its return value has no further effect.
|
|
- In case a value outside a structured type is skipped, it is replaced with `null`. This case happens if the top-level
|
|
element is skipped.
|
|
|
|
## Parameters
|
|
|
|
`depth` (in)
|
|
: the depth of the recursion during parsing
|
|
|
|
`event` (in)
|
|
: an event of type [`parse_event_t`](parse_event_t.md) indicating the context in
|
|
the callback function has been called
|
|
|
|
`parsed` (in, out)
|
|
: the current intermediate parse result; note that
|
|
writing to this value has no effect for `parse_event_t::key` events
|
|
|
|
## Return value
|
|
|
|
Whether the JSON value which called the function during parsing should be kept (`#!cpp true`) or not (`#!cpp false`). In
|
|
the latter case, it is skipped completely, or replaced by `null` if it is the top-level value.
|
|
|
|
## Examples
|
|
|
|
??? example "Example: skip an object key while parsing"
|
|
|
|
The example below demonstrates the `parse()` function with
|
|
and without callback function.
|
|
|
|
```cpp
|
|
#include <iostream>
|
|
#include <iomanip>
|
|
#include <nlohmann/json.hpp>
|
|
|
|
using json = nlohmann::json;
|
|
|
|
int main()
|
|
{
|
|
// a JSON text
|
|
auto text = R"(
|
|
{
|
|
"Image": {
|
|
"Width": 800,
|
|
"Height": 600,
|
|
"Title": "View from 15th Floor",
|
|
"Thumbnail": {
|
|
"Url": "http://www.example.com/image/481989943",
|
|
"Height": 125,
|
|
"Width": 100
|
|
},
|
|
"Animated" : false,
|
|
"IDs": [116, 943, 234, 38793]
|
|
}
|
|
}
|
|
)";
|
|
|
|
// parse and serialize JSON
|
|
json j_complete = json::parse(text);
|
|
std::cout << std::setw(4) << j_complete << "\n\n";
|
|
|
|
// define parser callback
|
|
json::parser_callback_t cb = [](int depth, json::parse_event_t event, json & parsed)
|
|
{
|
|
// skip object elements with key "Thumbnail"
|
|
if (event == json::parse_event_t::key and parsed == json("Thumbnail"))
|
|
{
|
|
return false;
|
|
}
|
|
else
|
|
{
|
|
return true;
|
|
}
|
|
};
|
|
|
|
// parse (with callback) and serialize JSON
|
|
json j_filtered = json::parse(text, cb);
|
|
std::cout << std::setw(4) << j_filtered << '\n';
|
|
}
|
|
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{
|
|
"Image": {
|
|
"Animated": false,
|
|
"Height": 600,
|
|
"IDs": [
|
|
116,
|
|
943,
|
|
234,
|
|
38793
|
|
],
|
|
"Thumbnail": {
|
|
"Height": 125,
|
|
"Url": "http://www.example.com/image/481989943",
|
|
"Width": 100
|
|
},
|
|
"Title": "View from 15th Floor",
|
|
"Width": 800
|
|
}
|
|
}
|
|
|
|
{
|
|
"Image": {
|
|
"Animated": false,
|
|
"Height": 600,
|
|
"IDs": [
|
|
116,
|
|
943,
|
|
234,
|
|
38793
|
|
],
|
|
"Title": "View from 15th Floor",
|
|
"Width": 800
|
|
}
|
|
}
|
|
|
|
```
|
|
|
|
??? example "Example: how discarded values are removed"
|
|
|
|
The example below shows where discarded values are removed. The array and the number are discarded in different
|
|
ways, but in each case the parse result contains neither the value nor its key.
|
|
|
|
```cpp
|
|
#include <iostream>
|
|
#include <nlohmann/json.hpp>
|
|
|
|
using json = nlohmann::json;
|
|
|
|
int main()
|
|
{
|
|
// a JSON text with an array and a number inside an object
|
|
auto text = R"({"IDs": [116, 943], "Width": 800})";
|
|
|
|
// discard the array when the parser reads its opening bracket
|
|
json j_array_start = json::parse(text, [](int /*depth*/, json::parse_event_t event, json& /*parsed*/)
|
|
{
|
|
return event != json::parse_event_t::array_start;
|
|
});
|
|
|
|
// discard the same array when the parser reads its closing bracket
|
|
json j_array_end = json::parse(text, [](int /*depth*/, json::parse_event_t event, json& /*parsed*/)
|
|
{
|
|
return event != json::parse_event_t::array_end;
|
|
});
|
|
|
|
// discard the number, but keep its key
|
|
json j_value = json::parse(text, [](int /*depth*/, json::parse_event_t event, json & parsed)
|
|
{
|
|
return !(event == json::parse_event_t::value && parsed == json(800));
|
|
});
|
|
|
|
// discard the key of the number
|
|
json j_key = json::parse(text, [](int /*depth*/, json::parse_event_t event, json & parsed)
|
|
{
|
|
return !(event == json::parse_event_t::key && parsed == json("Width"));
|
|
});
|
|
|
|
// discard the top-level object
|
|
json j_root = json::parse(text, [](int /*depth*/, json::parse_event_t event, json& /*parsed*/)
|
|
{
|
|
return event != json::parse_event_t::object_end;
|
|
});
|
|
|
|
// in every case, the discarded value is removed together with its key
|
|
std::cout << j_array_start << '\n'
|
|
<< j_array_end << '\n'
|
|
<< j_value << '\n'
|
|
<< j_key << '\n'
|
|
<< j_root << '\n';
|
|
}
|
|
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{"Width":800}
|
|
{"Width":800}
|
|
{"IDs":[116,943]}
|
|
{"IDs":[116,943]}
|
|
null
|
|
|
|
```
|
|
|
|
## See also
|
|
|
|
- [parse](parse.md) deserialize from a compatible input
|
|
- [parse_event_t](parse_event_t.md) enumeration of parser events
|
|
|
|
## Version history
|
|
|
|
- Added in version 1.0.0.
|
|
- Fixed in version 3.13.0 to also remove discarded values from a parent object; before, discarding an array or a value
|
|
stored under an object key left a discarded member behind, which made the parse result serialize to invalid JSON.
|
|
- Fixed in version 3.13.0 so that discarding an array or object at its start event also hides its content from the
|
|
callback, as documented above; before, the callback was still called for the content, and the key of every member of
|
|
a discarded object was kept in memory until the parse ended.
|