From c6a482b16c2b78baab5fa9fa58184de1d146488d Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sat, 18 Aug 2018 15:42:18 +0200 Subject: [PATCH] :memo: added example for sax_parse --- doc/examples/sax_parse.cpp | 124 +++++++++++++++++++++++++++++++ doc/examples/sax_parse.link | 1 + doc/examples/sax_parse.output | 2 + doc/index.md | 3 +- include/nlohmann/json.hpp | 4 + single_include/nlohmann/json.hpp | 5 +- 6 files changed, 137 insertions(+), 2 deletions(-) create mode 100644 doc/examples/sax_parse.cpp create mode 100644 doc/examples/sax_parse.link create mode 100644 doc/examples/sax_parse.output diff --git a/doc/examples/sax_parse.cpp b/doc/examples/sax_parse.cpp new file mode 100644 index 00000000..69e8962c --- /dev/null +++ b/doc/examples/sax_parse.cpp @@ -0,0 +1,124 @@ +#include +#include +#include +#include + +using json = nlohmann::json; + +// a simple event consumer that collects string representations of the passed +// values; not inheriting from json::json_sax_t is not required, but can +// help not to forget a required function +class sax_event_consumer : public json::json_sax_t +{ + public: + std::vector events; + + bool null() override + { + events.push_back("value: null"); + return true; + } + + bool boolean(bool val) override + { + events.push_back("value: " + std::string(val ? "true" : "false")); + return true; + } + + bool number_integer(number_integer_t val) override + { + events.push_back("value: " + std::to_string(val)); + return true; + } + + bool number_unsigned(number_unsigned_t val) override + { + events.push_back("value: " + std::to_string(val)); + return true; + } + + bool number_float(number_float_t val, const string_t& s) override + { + events.push_back("value: " + s); + return true; + } + + bool string(string_t& val) override + { + events.push_back("value: " + val); + return true; + } + + bool start_object(std::size_t elements) override + { + events.push_back("start: object"); + return true; + } + + bool end_object() override + { + events.push_back("end: object"); + return true; + } + + bool start_array(std::size_t elements) override + { + events.push_back("start: array"); + return true; + } + + bool end_array() override + { + events.push_back("end: array"); + return true; + } + + bool key(string_t& val) override + { + events.push_back("key: " + val); + return true; + } + + bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) override + { + events.push_back("error: " + std::string(ex.what())); + return false; + } +}; + +int main() +{ + // a JSON text + auto text = R"( + { + "Image": { + "Width": 800, + "Height": 600, + "Title": "View from 15th Floor", + "Thumbnail": { + "Url": "http://www.example.com/image/481989943", + "Height": 125, + "Width": 100 + }, + "Animated" : false, + "IDs": [116, 943, 234, 38793], + "Distance": 12.723374634 + } + } + )"; + + // create a SAX event consumer object + sax_event_consumer sec; + + // parse and serialize JSON + bool result = json::sax_parse(text, &sec); + + // output the recorded events + for (auto& event : sec.events) + { + std::cout << "(" << event << ") "; + } + + // output the result of sax_parse + std::cout << "\nresult: " << std::boolalpha << result << std::endl; +} diff --git a/doc/examples/sax_parse.link b/doc/examples/sax_parse.link new file mode 100644 index 00000000..14aa5e38 --- /dev/null +++ b/doc/examples/sax_parse.link @@ -0,0 +1 @@ +online \ No newline at end of file diff --git a/doc/examples/sax_parse.output b/doc/examples/sax_parse.output new file mode 100644 index 00000000..e16c2c4d --- /dev/null +++ b/doc/examples/sax_parse.output @@ -0,0 +1,2 @@ +(start: object) (key: Image) (start: object) (key: Width) (value: 800) (key: Height) (value: 600) (key: Title) (value: View from 15th Floor) (key: Thumbnail) (start: object) (key: Url) (value: http://www.example.com/image/481989943) (key: Height) (value: 125) (key: Width) (value: 100) (end: object) (key: Animated) (value: false) (key: IDs) (start: array) (value: 116) (value: 943) (value: 234) (value: 38793) (end: array) (key: Distance) (value: 12.723374634) (end: object) (end: object) +result: true diff --git a/doc/index.md b/doc/index.md index 830c4463..88054c59 100644 --- a/doc/index.md +++ b/doc/index.md @@ -39,7 +39,8 @@ These pages contain the API documentation of JSON for Modern C++, a C++11 header - @link nlohmann::basic_json::dump dump @endlink serialize to string - @link nlohmann::basic_json::operator<<(std::ostream&, const basic_json &) operator<< @endlink serialize to stream - deserialization / parsing - - @link nlohmann::basic_json::parse parse @endlink parse from string + - @link nlohmann::basic_json::parse parse @endlink parse from input (string, file, etc.) and return JSON value + - @link nlohmann::basic_json::sax_parse sax_parse @endlink parse from input (string, file, etc.) and generate SAX events - @link nlohmann::basic_json::operator>>(std::istream&, basic_json&) operator>> @endlink parse from stream - @link nlohmann::basic_json::accept accept @endlink check for syntax errors without parsing - @link nlohmann::json_sax SAX interface @endlink define a user-defined SAX event consumer diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index 9546520e..aed3a737 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -6064,6 +6064,10 @@ class basic_json @note A UTF-8 byte order mark is silently ignored. + @liveexample{The example below demonstrates the `sax_parse()` function + reading from string and processing the events with a user-defined SAX + event consumer.,sax_parse} + @since version 3.2.0 */ template diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index f7ff131d..fd91930c 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -17157,7 +17157,7 @@ class basic_json @param[in] format the format to parse (JSON, CBOR, MessagePack, or UBJSON) @param[in] strict whether the input has to be consumed completely - @return result of the deserialization + @return return value of the last processed SAX event @throw parse_error.101 if a parse error occurs; example: `""unexpected end of input; expected string literal""` @@ -17170,6 +17170,9 @@ class basic_json @note A UTF-8 byte order mark is silently ignored. + @liveexample{The example below demonstrates the `sax_parse()` function + reading from string.,sax_parse} + @since version 3.2.0 */ template