From baef8ad137623687cdfd45c0c6e72cbea442cbff Mon Sep 17 00:00:00 2001 From: Raphael Grimm Date: Mon, 19 Dec 2022 18:16:18 +0100 Subject: [PATCH] Add documentation for extend sax parser --- docs/mkdocs/docs/api/json_sax/index.md | 3 + .../docs/api/json_sax/next_token_end.md | 73 +++++++++++++++++++ .../docs/api/json_sax/next_token_start.md | 73 +++++++++++++++++++ 3 files changed, 149 insertions(+) create mode 100644 docs/mkdocs/docs/api/json_sax/next_token_end.md create mode 100644 docs/mkdocs/docs/api/json_sax/next_token_start.md diff --git a/docs/mkdocs/docs/api/json_sax/index.md b/docs/mkdocs/docs/api/json_sax/index.md index f63e85c9a..719c037f8 100644 --- a/docs/mkdocs/docs/api/json_sax/index.md +++ b/docs/mkdocs/docs/api/json_sax/index.md @@ -37,8 +37,11 @@ processing the input. - [**start_array**](start_array.md) (_virtual_) - the beginning of an array was read - [**start_object**](start_object.md) (_virtual_) - the beginning of an object was read - [**string**](string.md) (_virtual_) - a string value was read +- [**next_token_start**](next_token_start.md) - called to provide the start of the next element in the parsed input. +- [**next_token_end**](next_token_end.md) - called to provide the end (one past convention) of the next element in the parsed input. ## Version history - Added in version 3.2.0. - Support for binary values (`binary_t`, `binary`) added in version 3.8.0. +- Support for parser location information (`next_token_start`, `next_token_end`) added in version ???.???.???. diff --git a/docs/mkdocs/docs/api/json_sax/next_token_end.md b/docs/mkdocs/docs/api/json_sax/next_token_end.md new file mode 100644 index 000000000..25f9fd4bd --- /dev/null +++ b/docs/mkdocs/docs/api/json_sax/next_token_end.md @@ -0,0 +1,73 @@ +# nlohmann::json_sax::next_token_end + +Informs the sax parser about the end of the next element. +There are two possible signatures for this method: + +1. +```cpp +void next_token_end(std::size_t pos); +``` +This version is called with the byte position after the next element ends. This version also works when parsing binary formats such as [msgpack](../basic_json/input_format_t.md). + +2. +```cpp +template +void next_token_end(const nlohmann::detail::lexer& lex) +``` +This version is called with the lexer after the last character of the next element was parsed. The lexer can provide additional information about the current parse context. This version only available when calling `nlohmann::json::sax_parse` with `nlohmann::json::input_format_t::json` and takes precedence. + +## Template parameters +1. +(none) +2. +`BasicJsonType` +: a specialization of `basic_json` used by the lexer. (Leave this as a template parameter) +`InputAdapterType` +: The input adapter used by the lexer. (Leave this as a template parameter) + +## Parameters +1. +`pos` (in) +: Byte position one after the next elements last byte. +2. +`lex` (in) +: Lexer after the last char of the next element was parsed. + +## Notes + +Implementing either version is optional, and no function is called if neither version of `next_token_end` is available in the sax parser. + +It is recommended, but not required, to also implement [next_token_start](next_token_start.md). + +## Examples + +??? example + + The example below shows a SAX parser using the first version of this method to log the location. + + ```cpp + --8<-- "examples/sax_parse_with_src_location.cpp" + ``` + + Output: + + ```json + --8<-- "examples/sax_parse_with_src_location.output" + ``` + +??? example + + The example below shows a SAX parser using the second version of this method and storing the location information in each json node using a [base class](../basic_json/json_base_class_t.md) for `nlohmann::json` as customization point. + + ```cpp + --8<-- "examples/sax_parse_with_src_location_in_json.cpp" + ``` + + Output: + + ```json + --8<-- "examples/sax_parse_with_src_location_in_json.output" + ``` +## Version history + +- Added in version ???.???.???. diff --git a/docs/mkdocs/docs/api/json_sax/next_token_start.md b/docs/mkdocs/docs/api/json_sax/next_token_start.md new file mode 100644 index 000000000..9543f53ad --- /dev/null +++ b/docs/mkdocs/docs/api/json_sax/next_token_start.md @@ -0,0 +1,73 @@ +# nlohmann::json_sax::next_token_start + +Informs the sax parser about the start of the next element. +There are two possible signatures for this method: + +1. +```cpp +void next_token_start(std::size_t pos); +``` +This version is called with the byte position where the next element starts. This version also works when parsing binary formats such as [msgpack](../basic_json/input_format_t.md). + +2. +```cpp +template +void next_token_start(const nlohmann::detail::lexer& lex) +``` +This version is called with the lexer after the first character of the next element was parsed. The lexer can provide additional information about the current parse context. This version only available when calling `nlohmann::json::sax_parse` with `nlohmann::json::input_format_t::json` and takes precedence. + +## Template parameters +1. +(none) +2. +`BasicJsonType` +: a specialization of `basic_json` used by the lexer. (Leave this as a template parameter) +`InputAdapterType` +: The input adapter used by the lexer. (Leave this as a template parameter) + +## Parameters +1. +`pos` (in) +: Byte position where the next element starts. +2. +`lex` (in) +: Lexer after the first char of the next element was parsed. + +## Notes + +Implementing either version is optional, and no function is called if neither version of `next_token_start` is available in the sax parser. + +It is recommended, but not required, to also implement [next_token_end](next_token_end.md). + +## Examples + +??? example + + The example below shows a SAX parser using the first version of this method to log the location. + + ```cpp + --8<-- "examples/sax_parse_with_src_location.cpp" + ``` + + Output: + + ```json + --8<-- "examples/sax_parse_with_src_location.output" + ``` + +??? example + + The example below shows a SAX parser using the second version of this method and storing the location information in each json node using a [base class](../basic_json/json_base_class_t.md) for `nlohmann::json` as customization point. + + ```cpp + --8<-- "examples/sax_parse_with_src_location_in_json.cpp" + ``` + + Output: + + ```json + --8<-- "examples/sax_parse_with_src_location_in_json.output" + ``` +## Version history + +- Added in version ???.???.???.