From 2df5f107a98486f599b0f9a982b1a8995d1ba1dc Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Thu, 4 Jun 2020 14:01:57 +0200 Subject: [PATCH] :memo: add page on parsing and exceptions --- doc/mkdocs/docs/features/parsing/index.md | 13 ++ .../docs/features/parsing/parse_exceptions.md | 114 ++++++++++++++++++ .../{ => parsing}/parser_callbacks.md | 0 .../features/{ => parsing}/sax_interface.md | 4 +- doc/mkdocs/mkdocs.yml | 7 +- 5 files changed, 134 insertions(+), 4 deletions(-) create mode 100644 doc/mkdocs/docs/features/parsing/index.md create mode 100644 doc/mkdocs/docs/features/parsing/parse_exceptions.md rename doc/mkdocs/docs/features/{ => parsing}/parser_callbacks.md (100%) rename doc/mkdocs/docs/features/{ => parsing}/sax_interface.md (97%) diff --git a/doc/mkdocs/docs/features/parsing/index.md b/doc/mkdocs/docs/features/parsing/index.md new file mode 100644 index 000000000..5cf59bfe9 --- /dev/null +++ b/doc/mkdocs/docs/features/parsing/index.md @@ -0,0 +1,13 @@ +# Overview + +!!! note + + This page is under construction. + +## Input + +## SAX vs. DOM parsing + +## Exceptions + +See [parsing and exceptions](parse_exceptions.md). diff --git a/doc/mkdocs/docs/features/parsing/parse_exceptions.md b/doc/mkdocs/docs/features/parsing/parse_exceptions.md new file mode 100644 index 000000000..b882e0b5c --- /dev/null +++ b/doc/mkdocs/docs/features/parsing/parse_exceptions.md @@ -0,0 +1,114 @@ +# Parsing and exceptions + +When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown. This exception contains the position in the input where the error occurred, together with a diagnostic message and the last read input token. The exceptions page contains a [list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like + +```cpp +json j; +try +{ + j = json::parse(my_input); +} +catch (json::exception::parse_error& ex) +{ + std::cerr << "parse error at byte " << ex.byte << std::endl; +} +``` + +In case exceptions are undesired or not supported by the environment, there are different ways to proceed: + + +## Switch off exceptions + +The `parse()` function accepts as last parameter a `#!cpp bool` variable `allow_exceptions` which controls whether an exception is thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned (`#!cpp false`). + +```cpp +json j = json::parse(my_input, nullptr, false); +if (j.is_discarded()) +{ + std::cerr << "parse error" << std::endl; +} +``` + +Note there is no diagnostic information available in this scenario. + +## Use accept() function + +Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating whether the input is valid JSON. + +```cpp +if (!json::accept(my_input)) +{ + std::cerr << "parse error" << std::endl; +} +``` + +Again, there is no diagnostic information available. + + +## User-defined SAX interface + +Finally, you can implement the [SAX interface](sax_interface.md) and decide what should happen in case of a parse error. + +This function has the following interface: + +```cpp +bool parse_error(std::size_t position, + const std::string& last_token, + const json::exception& ex); +``` + +The return value indicates whether the parsing should continue, so the function should usually return `#!cpp false`. + +??? example + + ```cpp + #include + #include "json.hpp" + + using json = nlohmann::json; + + class sax_no_exception : public nlohmann::detail::json_sax_dom_parser + { + public: + sax_no_exception(json& j) + : nlohmann::detail::json_sax_dom_parser(j, false) + {} + + bool parse_error(std::size_t position, + const std::string& last_token, + const json::exception& ex) + { + std::cerr << "parse error at input byte " << position << "\n" + << ex.what() << "\n" + << "last read: \"" << last_token << "\"" + << std::endl; + return false; + } + }; + + int main() + { + std::string myinput = "[1,2,3,]"; + + json result; + sax_no_exception sax(result); + + bool parse_result = json::sax_parse(myinput, &sax); + if (!parse_result) + { + std::cerr << "parsing unsuccessful!" << std::endl; + } + + std::cout << "parsed value: " << result << std::endl; + } + ``` + + Output: + + ``` + parse error at input byte 8 + [json.exception.parse_error.101] parse error at line 1, column 8: syntax error while parsing value - unexpected ']'; expected '[', '{', or a literal + last read: "3,]" + parsing unsuccessful! + parsed value: [1,2,3] + ``` diff --git a/doc/mkdocs/docs/features/parser_callbacks.md b/doc/mkdocs/docs/features/parsing/parser_callbacks.md similarity index 100% rename from doc/mkdocs/docs/features/parser_callbacks.md rename to doc/mkdocs/docs/features/parsing/parser_callbacks.md diff --git a/doc/mkdocs/docs/features/sax_interface.md b/doc/mkdocs/docs/features/parsing/sax_interface.md similarity index 97% rename from doc/mkdocs/docs/features/sax_interface.md rename to doc/mkdocs/docs/features/parsing/sax_interface.md index b25a59cc4..ef83a532e 100644 --- a/doc/mkdocs/docs/features/sax_interface.md +++ b/doc/mkdocs/docs/features/parsing/sax_interface.md @@ -21,7 +21,7 @@ interface json::sax_t { + {abstract} bool end_array() + {abstract} bool key(string_t& val) - + {abstract} bool parse_error(std::size_t position, const std::string& last_token, const detail::exception& ex) + + {abstract} bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) } ``` @@ -51,7 +51,7 @@ bool end_array(); bool key(string_t& val); // called when a parse error occurs; byte position, the last token, and an exception is passed -bool parse_error(std::size_t position, const std::string& last_token, const detail::exception& ex); +bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex); ``` The return value of each function determines whether parsing should proceed. diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index a53dca2f3..5d6e3b4e3 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -49,8 +49,11 @@ nav: - features/json_patch.md - features/merge_patch.md - features/enum_conversion.md - - features/parser_callbacks.md - - features/sax_interface.md + - Parsing: + - features/parsing/index.md + - features/parsing/parse_exceptions.md + - features/parsing/parser_callbacks.md + - features/parsing/sax_interface.md - features/types.md - Integration: - integration/index.md