diff options
Diffstat (limited to 'sl4n/rapidjson/doc/sax.md')
-rw-r--r-- | sl4n/rapidjson/doc/sax.md | 475 |
1 files changed, 0 insertions, 475 deletions
diff --git a/sl4n/rapidjson/doc/sax.md b/sl4n/rapidjson/doc/sax.md deleted file mode 100644 index 9a6d814..0000000 --- a/sl4n/rapidjson/doc/sax.md +++ /dev/null @@ -1,475 +0,0 @@ -# SAX - -The term "SAX" originated from [Simple API for XML](http://en.wikipedia.org/wiki/Simple_API_for_XML). We borrowed this term for JSON parsing and generation. - -In RapidJSON, `Reader` (typedef of `GenericReader<...>`) is the SAX-style parser for JSON, and `Writer` (typedef of `GenericWriter<...>`) is the SAX-style generator for JSON. - -[TOC] - -# Reader {#Reader} - -`Reader` parses a JSON from a stream. While it reads characters from the stream, it analyze the characters according to the syntax of JSON, and publish events to a handler. - -For example, here is a JSON. - -~~~~~~~~~~js -{ - "hello": "world", - "t": true , - "f": false, - "n": null, - "i": 123, - "pi": 3.1416, - "a": [1, 2, 3, 4] -} -~~~~~~~~~~ - -While a `Reader` parses this JSON, it publishes the following events to the handler sequentially: - -~~~~~~~~~~ -StartObject() -Key("hello", 5, true) -String("world", 5, true) -Key("t", 1, true) -Bool(true) -Key("f", 1, true) -Bool(false) -Key("n", 1, true) -Null() -Key("i") -UInt(123) -Key("pi") -Double(3.1416) -Key("a") -StartArray() -Uint(1) -Uint(2) -Uint(3) -Uint(4) -EndArray(4) -EndObject(7) -~~~~~~~~~~ - -These events can be easily matched with the JSON, except some event parameters need further explanation. Let's see the `simplereader` example which produces exactly the same output as above: - -~~~~~~~~~~cpp -#include "rapidjson/reader.h" -#include <iostream> - -using namespace rapidjson; -using namespace std; - -struct MyHandler { - bool Null() { cout << "Null()" << endl; return true; } - bool Bool(bool b) { cout << "Bool(" << boolalpha << b << ")" << endl; return true; } - bool Int(int i) { cout << "Int(" << i << ")" << endl; return true; } - bool Uint(unsigned u) { cout << "Uint(" << u << ")" << endl; return true; } - bool Int64(int64_t i) { cout << "Int64(" << i << ")" << endl; return true; } - bool Uint64(uint64_t u) { cout << "Uint64(" << u << ")" << endl; return true; } - bool Double(double d) { cout << "Double(" << d << ")" << endl; return true; } - bool String(const char* str, SizeType length, bool copy) { - cout << "String(" << str << ", " << length << ", " << boolalpha << copy << ")" << endl; - return true; - } - bool StartObject() { cout << "StartObject()" << endl; return true; } - bool Key(const char* str, SizeType length, bool copy) { - cout << "Key(" << str << ", " << length << ", " << boolalpha << copy << ")" << endl; - return true; - } - bool EndObject(SizeType memberCount) { cout << "EndObject(" << memberCount << ")" << endl; return true; } - bool StartArray() { cout << "StartArray()" << endl; return true; } - bool EndArray(SizeType elementCount) { cout << "EndArray(" << elementCount << ")" << endl; return true; } -}; - -void main() { - const char json[] = " { \"hello\" : \"world\", \"t\" : true , \"f\" : false, \"n\": null, \"i\":123, \"pi\": 3.1416, \"a\":[1, 2, 3, 4] } "; - - MyHandler handler; - Reader reader; - StringStream ss(json); - reader.Parse(ss, handler); -} -~~~~~~~~~~ - -Note that, RapidJSON uses template to statically bind the `Reader` type and the handler type, instead of using class with virtual functions. This paradigm can improve the performance by inlining functions. - -## Handler {#Handler} - -As the previous example showed, user needs to implement a handler, which consumes the events (function calls) from `Reader`. The handler must contain the following member functions. - -~~~~~~~~~~cpp -class Handler { - bool Null(); - bool Bool(bool b); - bool Int(int i); - bool Uint(unsigned i); - bool Int64(int64_t i); - bool Uint64(uint64_t i); - bool Double(double d); - bool String(const Ch* str, SizeType length, bool copy); - bool StartObject(); - bool Key(const Ch* str, SizeType length, bool copy); - bool EndObject(SizeType memberCount); - bool StartArray(); - bool EndArray(SizeType elementCount); -}; -~~~~~~~~~~ - -`Null()` is called when the `Reader` encounters a JSON null value. - -`Bool(bool)` is called when the `Reader` encounters a JSON true or false value. - -When the `Reader` encounters a JSON number, it chooses a suitable C++ type mapping. And then it calls *one* function out of `Int(int)`, `Uint(unsigned)`, `Int64(int64_t)`, `Uint64(uint64_t)` and `Double(double)`. - -`String(const char* str, SizeType length, bool copy)` is called when the `Reader` encounters a string. The first parameter is pointer to the string. The second parameter is the length of the string (excluding the null terminator). Note that RapidJSON supports null character `'\0'` inside a string. If such situation happens, `strlen(str) < length`. The last `copy` indicates whether the handler needs to make a copy of the string. For normal parsing, `copy = true`. Only when *insitu* parsing is used, `copy = false`. And beware that, the character type depends on the target encoding, which will be explained later. - -When the `Reader` encounters the beginning of an object, it calls `StartObject()`. An object in JSON is a set of name-value pairs. If the object contains members it first calls `Key()` for the name of member, and then calls functions depending on the type of the value. These calls of name-value pairs repeats until calling `EndObject(SizeType memberCount)`. Note that the `memberCount` parameter is just an aid for the handler, user may not need this parameter. - -Array is similar to object but simpler. At the beginning of an array, the `Reader` calls `BeginArary()`. If there is elements, it calls functions according to the types of element. Similarly, in the last call `EndArray(SizeType elementCount)`, the parameter `elementCount` is just an aid for the handler. - -Every handler functions returns a `bool`. Normally it should returns `true`. If the handler encounters an error, it can return `false` to notify event publisher to stop further processing. - -For example, when we parse a JSON with `Reader` and the handler detected that the JSON does not conform to the required schema, then the handler can return `false` and let the `Reader` stop further parsing. And the `Reader` will be in error state with error code `kParseErrorTermination`. - -## GenericReader {#GenericReader} - -As mentioned before, `Reader` is a typedef of a template class `GenericReader`: - -~~~~~~~~~~cpp -namespace rapidjson { - -template <typename SourceEncoding, typename TargetEncoding, typename Allocator = MemoryPoolAllocator<> > -class GenericReader { - // ... -}; - -typedef GenericReader<UTF8<>, UTF8<> > Reader; - -} // namespace rapidjson -~~~~~~~~~~ - -The `Reader` uses UTF-8 as both source and target encoding. The source encoding means the encoding in the JSON stream. The target encoding means the encoding of the `str` parameter in `String()` calls. For example, to parse a UTF-8 stream and outputs UTF-16 string events, you can define a reader by: - -~~~~~~~~~~cpp -GenericReader<UTF8<>, UTF16<> > reader; -~~~~~~~~~~ - -Note that, the default character type of `UTF16` is `wchar_t`. So this `reader`needs to call `String(const wchar_t*, SizeType, bool)` of the handler. - -The third template parameter `Allocator` is the allocator type for internal data structure (actually a stack). - -## Parsing {#Parsing} - -The one and only one function of `Reader` is to parse JSON. - -~~~~~~~~~~cpp -template <unsigned parseFlags, typename InputStream, typename Handler> -bool Parse(InputStream& is, Handler& handler); - -// with parseFlags = kDefaultParseFlags -template <typename InputStream, typename Handler> -bool Parse(InputStream& is, Handler& handler); -~~~~~~~~~~ - -If an error occurs during parsing, it will return `false`. User can also calls `bool HasParseEror()`, `ParseErrorCode GetParseErrorCode()` and `size_t GetErrorOffset()` to obtain the error states. Actually `Document` uses these `Reader` functions to obtain parse errors. Please refer to [DOM](doc/dom.md) for details about parse error. - -# Writer {#Writer} - -`Reader` converts (parses) JSON into events. `Writer` does exactly the opposite. It converts events into JSON. - -`Writer` is very easy to use. If your application only need to converts some data into JSON, it may be a good choice to use `Writer` directly, instead of building a `Document` and then stringifying it with a `Writer`. - -In `simplewriter` example, we do exactly the reverse of `simplereader`. - -~~~~~~~~~~cpp -#include "rapidjson/writer.h" -#include "rapidjson/stringbuffer.h" -#include <iostream> - -using namespace rapidjson; -using namespace std; - -void main() { - StringBuffer s; - Writer<StringBuffer> writer(s); - - writer.StartObject(); - writer.Key("hello"); - writer.String("world"); - writer.Key("t"); - writer.Bool(true); - writer.Key("f"); - writer.Bool(false); - writer.Key("n"); - writer.Null(); - writer.Key("i"); - writer.Uint(123); - writer.Key("pi"); - writer.Double(3.1416); - writer.Key("a"); - writer.StartArray(); - for (unsigned i = 0; i < 4; i++) - writer.Uint(i); - writer.EndArray(); - writer.EndObject(); - - cout << s.GetString() << endl; -} -~~~~~~~~~~ - -~~~~~~~~~~ -{"hello":"world","t":true,"f":false,"n":null,"i":123,"pi":3.1416,"a":[0,1,2,3]} -~~~~~~~~~~ - -There are two `String()` and `Key()` overloads. One is the same as defined in handler concept with 3 parameters. It can handle string with null characters. Another one is the simpler version used in the above example. - -Note that, the example code does not pass any parameters in `EndArray()` and `EndObject()`. An `SizeType` can be passed but it will be simply ignored by `Writer`. - -You may doubt that, why not just using `sprintf()` or `std::stringstream` to build a JSON? - -There are various reasons: -1. `Writer` must output a well-formed JSON. If there is incorrect event sequence (e.g. `Int()` just after `StartObject()`), it generates assertion fail in debug mode. -2. `Writer::String()` can handle string escaping (e.g. converting code point `U+000A` to `\n`) and Unicode transcoding. -3. `Writer` handles number output consistently. -4. `Writer` implements the event handler concept. It can be used to handle events from `Reader`, `Document` or other event publisher. -5. `Writer` can be optimized for different platforms. - -Anyway, using `Writer` API is even simpler than generating a JSON by ad hoc methods. - -## Template {#WriterTemplate} - -`Writer` has a minor design difference to `Reader`. `Writer` is a template class, not a typedef. There is no `GenericWriter`. The following is the declaration. - -~~~~~~~~~~cpp -namespace rapidjson { - -template<typename OutputStream, typename SourceEncoding = UTF8<>, typename TargetEncoding = UTF8<>, typename Allocator = CrtAllocator<> > -class Writer { -public: - Writer(OutputStream& os, Allocator* allocator = 0, size_t levelDepth = kDefaultLevelDepth) -// ... -}; - -} // namespace rapidjson -~~~~~~~~~~ - -The `OutputStream` template parameter is the type of output stream. It cannot be deduced and must be specified by user. - -The `SourceEncoding` template parameter specifies the encoding to be used in `String(const Ch*, ...)`. - -The `TargetEncoding` template parameter specifies the encoding in the output stream. - -The last one, `Allocator` is the type of allocator, which is used for allocating internal data structure (a stack). - -Besides, the constructor of `Writer` has a `levelDepth` parameter. This parameter affects the initial memory allocated for storing information per hierarchy level. - -## PrettyWriter {#PrettyWriter} - -While the output of `Writer` is the most condensed JSON without white-spaces, suitable for network transfer or storage, it is not easily readable by human. - -Therefore, RapidJSON provides a `PrettyWriter`, which adds indentation and line feeds in the output. - -The usage of `PrettyWriter` is exactly the same as `Writer`, expect that `PrettyWriter` provides a `SetIndent(Ch indentChar, unsigned indentCharCount)` function. The default is 4 spaces. - -## Completeness and Reset {#CompletenessReset} - -A `Writer` can only output a single JSON, which can be any JSON type at the root. Once the singular event for root (e.g. `String()`), or the last matching `EndObject()` or `EndArray()` event, is handled, the output JSON is well-formed and complete. User can detect this state by calling `Writer::IsComplete()`. - -When a JSON is complete, the `Writer` cannot accept any new events. Otherwise the output will be invalid (i.e. having more than one root). To reuse the `Writer` object, user can call `Writer::Reset(OutputStream& os)` to reset all internal states of the `Writer` with a new output stream. - -# Techniques {#Techniques} - -## Parsing JSON to Custom Data Structure {#CustomDataStructure} - -`Document`'s parsing capability is completely based on `Reader`. Actually `Document` is a handler which receives events from a reader to build a DOM during parsing. - -User may uses `Reader` to build other data structures directly. This eliminates building of DOM, thus reducing memory and improving performance. - -In the following `messagereader` example, `ParseMessages()` parses a JSON which should be an object with key-string pairs. - -~~~~~~~~~~cpp -#include "rapidjson/reader.h" -#include "rapidjson/error/en.h" -#include <iostream> -#include <string> -#include <map> - -using namespace std; -using namespace rapidjson; - -typedef map<string, string> MessageMap; - -struct MessageHandler - : public BaseReaderHandler<UTF8<>, MessageHandler> { - MessageHandler() : state_(kExpectObjectStart) { - } - - bool StartObject() { - switch (state_) { - case kExpectObjectStart: - state_ = kExpectNameOrObjectEnd; - return true; - default: - return false; - } - } - - bool String(const char* str, SizeType length, bool) { - switch (state_) { - case kExpectNameOrObjectEnd: - name_ = string(str, length); - state_ = kExpectValue; - return true; - case kExpectValue: - messages_.insert(MessageMap::value_type(name_, string(str, length))); - state_ = kExpectNameOrObjectEnd; - return true; - default: - return false; - } - } - - bool EndObject(SizeType) { return state_ == kExpectNameOrObjectEnd; } - - bool Default() { return false; } // All other events are invalid. - - MessageMap messages_; - enum State { - kExpectObjectStart, - kExpectNameOrObjectEnd, - kExpectValue, - }state_; - std::string name_; -}; - -void ParseMessages(const char* json, MessageMap& messages) { - Reader reader; - MessageHandler handler; - StringStream ss(json); - if (reader.Parse(ss, handler)) - messages.swap(handler.messages_); // Only change it if success. - else { - ParseErrorCode e = reader.GetParseErrorCode(); - size_t o = reader.GetErrorOffset(); - cout << "Error: " << GetParseError_En(e) << endl;; - cout << " at offset " << o << " near '" << string(json).substr(o, 10) << "...'" << endl; - } -} - -int main() { - MessageMap messages; - - const char* json1 = "{ \"greeting\" : \"Hello!\", \"farewell\" : \"bye-bye!\" }"; - cout << json1 << endl; - ParseMessages(json1, messages); - - for (MessageMap::const_iterator itr = messages.begin(); itr != messages.end(); ++itr) - cout << itr->first << ": " << itr->second << endl; - - cout << endl << "Parse a JSON with invalid schema." << endl; - const char* json2 = "{ \"greeting\" : \"Hello!\", \"farewell\" : \"bye-bye!\", \"foo\" : {} }"; - cout << json2 << endl; - ParseMessages(json2, messages); - - return 0; -} -~~~~~~~~~~ - -~~~~~~~~~~ -{ "greeting" : "Hello!", "farewell" : "bye-bye!" } -farewell: bye-bye! -greeting: Hello! - -Parse a JSON with invalid schema. -{ "greeting" : "Hello!", "farewell" : "bye-bye!", "foo" : {} } -Error: Terminate parsing due to Handler error. - at offset 59 near '} }...' -~~~~~~~~~~ - -The first JSON (`json1`) was successfully parsed into `MessageMap`. Since `MessageMap` is a `std::map`, the printing order are sorted by the key. This order is different from the JSON's order. - -In the second JSON (`json2`), `foo`'s value is an empty object. As it is an object, `MessageHandler::StartObject()` will be called. However, at that moment `state_ = kExpectValue`, so that function returns `false` and cause the parsing process be terminated. The error code is `kParseErrorTermination`. - -## Filtering of JSON {#Filtering} - -As mentioned earlier, `Writer` can handle the events published by `Reader`. `condense` example simply set a `Writer` as handler of a `Reader`, so it can remove all white-spaces in JSON. `pretty` example uses the same relationship, but replacing `Writer` by `PrettyWriter`. So `pretty` can be used to reformat a JSON with indentation and line feed. - -Actually, we can add intermediate layer(s) to filter the contents of JSON via these SAX-style API. For example, `capitalize` example capitalize all strings in a JSON. - -~~~~~~~~~~cpp -#include "rapidjson/reader.h" -#include "rapidjson/writer.h" -#include "rapidjson/filereadstream.h" -#include "rapidjson/filewritestream.h" -#include "rapidjson/error/en.h" -#include <vector> -#include <cctype> - -using namespace rapidjson; - -template<typename OutputHandler> -struct CapitalizeFilter { - CapitalizeFilter(OutputHandler& out) : out_(out), buffer_() { - } - - bool Null() { return out_.Null(); } - bool Bool(bool b) { return out_.Bool(b); } - bool Int(int i) { return out_.Int(i); } - bool Uint(unsigned u) { return out_.Uint(u); } - bool Int64(int64_t i) { return out_.Int64(i); } - bool Uint64(uint64_t u) { return out_.Uint64(u); } - bool Double(double d) { return out_.Double(d); } - bool String(const char* str, SizeType length, bool) { - buffer_.clear(); - for (SizeType i = 0; i < length; i++) - buffer_.push_back(std::toupper(str[i])); - return out_.String(&buffer_.front(), length, true); // true = output handler need to copy the string - } - bool StartObject() { return out_.StartObject(); } - bool Key(const char* str, SizeType length, bool copy) { return String(str, length, copy); } - bool EndObject(SizeType memberCount) { return out_.EndObject(memberCount); } - bool StartArray() { return out_.StartArray(); } - bool EndArray(SizeType elementCount) { return out_.EndArray(elementCount); } - - OutputHandler& out_; - std::vector<char> buffer_; -}; - -int main(int, char*[]) { - // Prepare JSON reader and input stream. - Reader reader; - char readBuffer[65536]; - FileReadStream is(stdin, readBuffer, sizeof(readBuffer)); - - // Prepare JSON writer and output stream. - char writeBuffer[65536]; - FileWriteStream os(stdout, writeBuffer, sizeof(writeBuffer)); - Writer<FileWriteStream> writer(os); - - // JSON reader parse from the input stream and let writer generate the output. - CapitalizeFilter<Writer<FileWriteStream> > filter(writer); - if (!reader.Parse(is, filter)) { - fprintf(stderr, "\nError(%u): %s\n", (unsigned)reader.GetErrorOffset(), GetParseError_En(reader.GetParseErrorCode())); - return 1; - } - - return 0; -} -~~~~~~~~~~ - -Note that, it is incorrect to simply capitalize the JSON as a string. For example: -~~~~~~~~~~ -["Hello\nWorld"] -~~~~~~~~~~ - -Simply capitalizing the whole JSON would contain incorrect escape character: -~~~~~~~~~~ -["HELLO\NWORLD"] -~~~~~~~~~~ - -The correct result by `capitalize`: -~~~~~~~~~~ -["HELLO\nWORLD"] -~~~~~~~~~~ - -More complicated filters can be developed. However, since SAX-style API can only provide information about a single event at a time, user may need to book-keeping the contextual information (e.g. the path from root value, storage of other related values). Some processing may be easier to be implemented in DOM than SAX. |