The library uses a SAX-like interface with the following functions:
// called when null is parsed bool null(); // called when a boolean is parsed; value is passed bool boolean(bool val); // called when a signed or unsigned integer number is parsed; value is passed bool number_integer(number_integer_t val); bool number_unsigned(number_unsigned_t val); // called when a floating-point number is parsed; value and original string is passed bool number_float(number_float_t val, const string_t& s); // called when a string is parsed; value is passed and can be safely moved away bool string(string_t& val); // called when a binary value is parsed; value is passed and can be safely moved away bool binary(binary& val); // called when an object or array begins or ends, resp. The number of elements is passed (or -1 if not known) bool start_object(std::size_t elements); bool end_object(); bool start_array(std::size_t elements); bool end_array(); // called when an object key is parsed; value is passed and can be safely moved away 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 json::exception& ex);
The return value of each function determines whether parsing should proceed.
To implement your own SAX handler, proceed as follows:
- Implement the SAX interface in a class. You can use class
nlohmann::json_sax<json>as base class, but you can also use any class where the functions described above are implemented and public.
- Create an object of your SAX interface class, e.g.
bool json::sax_parse(input, &my_sax);where the first parameter can be any input like a string or an input stream and the second parameter is a pointer to your SAX interface.
sax_parse function only returns a
bool indicating the result of the last executed SAX event. It does not return
json value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error - it is up to you what to do with the exception object passed to your
parse_error implementation. Internally, the SAX interface is used for the DOM parser (class
json_sax_dom_parser) as well as the acceptor (
json_sax_acceptor), see file