1# SAX Interface 2 3The library uses a SAX-like interface with the following functions: 4 5```plantuml 6interface json::sax_t { 7 + {abstract} bool null() 8 9 + {abstract} bool boolean(bool val) 10 11 + {abstract} bool number_integer(number_integer_t val) 12 + {abstract} bool number_unsigned(number_unsigned_t val) 13 14 + {abstract} bool number_float(number_float_t val, const string_t& s) 15 16 + {abstract} bool string(string_t& val) 17 + {abstract} bool binary(binary_t& val) 18 19 + {abstract} bool start_object(std::size_t elements) 20 + {abstract} bool end_object() 21 + {abstract} bool start_array(std::size_t elements) 22 + {abstract} bool end_array() 23 + {abstract} bool key(string_t& val) 24 25 + {abstract} bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) 26} 27``` 28 29```cpp 30// called when null is parsed 31bool null(); 32 33// called when a boolean is parsed; value is passed 34bool boolean(bool val); 35 36// called when a signed or unsigned integer number is parsed; value is passed 37bool number_integer(number_integer_t val); 38bool number_unsigned(number_unsigned_t val); 39 40// called when a floating-point number is parsed; value and original string is passed 41bool number_float(number_float_t val, const string_t& s); 42 43// called when a string is parsed; value is passed and can be safely moved away 44bool string(string_t& val); 45// called when a binary value is parsed; value is passed and can be safely moved away 46bool binary(binary& val); 47 48// called when an object or array begins or ends, resp. The number of elements is passed (or -1 if not known) 49bool start_object(std::size_t elements); 50bool end_object(); 51bool start_array(std::size_t elements); 52bool end_array(); 53// called when an object key is parsed; value is passed and can be safely moved away 54bool key(string_t& val); 55 56// called when a parse error occurs; byte position, the last token, and an exception is passed 57bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex); 58``` 59 60The return value of each function determines whether parsing should proceed. 61 62To implement your own SAX handler, proceed as follows: 63 641. 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. 652. Create an object of your SAX interface class, e.g. `my_sax`. 663. Call `#!cpp 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. 67 68Note the `sax_parse` function only returns a `#!cpp 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 `json_sax.hpp`. 69