📝 add page on parsing and exceptions

This commit is contained in:
Niels Lohmann 2020-06-04 14:01:57 +02:00
parent 32bda1a7af
commit 2df5f107a9
No known key found for this signature in database
GPG key ID: 7F3CEA63AE251B69
5 changed files with 134 additions and 4 deletions

View file

@ -0,0 +1,13 @@
# Overview
!!! note
This page is under construction.
## Input
## SAX vs. DOM parsing
## Exceptions
See [parsing and exceptions](parse_exceptions.md).

View file

@ -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 <iostream>
#include "json.hpp"
using json = nlohmann::json;
class sax_no_exception : public nlohmann::detail::json_sax_dom_parser<json>
{
public:
sax_no_exception(json& j)
: nlohmann::detail::json_sax_dom_parser<json>(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]
```

View file

@ -21,7 +21,7 @@ interface json::sax_t {
+ {abstract} bool end_array() + {abstract} bool end_array()
+ {abstract} bool key(string_t& val) + {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); bool key(string_t& val);
// called when a parse error occurs; byte position, the last token, and an exception is passed // 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. The return value of each function determines whether parsing should proceed.

View file

@ -49,8 +49,11 @@ nav:
- features/json_patch.md - features/json_patch.md
- features/merge_patch.md - features/merge_patch.md
- features/enum_conversion.md - features/enum_conversion.md
- features/parser_callbacks.md - Parsing:
- features/sax_interface.md - features/parsing/index.md
- features/parsing/parse_exceptions.md
- features/parsing/parser_callbacks.md
- features/parsing/sax_interface.md
- features/types.md - features/types.md
- Integration: - Integration:
- integration/index.md - integration/index.md