📝 add documentation of parser callbacks

doc/mkdocs/docs/features/parser_callbacks.md

@@ -0,0 +1,79 @@
+# 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 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"
+    ```

doc/mkdocs/mkdocs.yml

@@ -49,6 +49,7 @@ nav:
     - features/json_patch.md
     - features/merge_patch.md
     - features/enum_conversion.md
+    - features/parser_callbacks.md
     - features/sax_interface.md
     - features/types.md
   - Integration: