ceph/src/jaegertracing/opentelemetry-cpp/third_party/nlohmann-json/doc/mkdocs/docs/features/parsing/parser_callbacks.md

   1 # Parser Callbacks
   2
   3 ## Overview
   4
   5 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
   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
   7 callback function is a boolean indicating whether the element that emitted the callback shall be kept or not.
   8
   9 The type of the callback function is:
  10
  11 ```cpp
  12 template<typename BasicJsonType>
  13 using parser_callback_t =
  14     std::function<bool(int depth, parse_event_t event, BasicJsonType& parsed)>;
  15 ```
  16
  17
  18 ## Callback event types
  19
  20 We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values
  21 of the parameters `depth`, `event`, and `parsed`.
  22
  23 | parameter `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
  62 Discarding 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     ```