1# SAX 2 3"SAX" 此术语源于 [Simple API for XML](http://en.wikipedia.org/wiki/Simple_API_for_XML)。我们借了此术语去套用在 JSON 的解析及生成。 4 5在 RapidJSON 中,`Reader`(`GenericReader<...>` 的 typedef)是 JSON 的 SAX 风格解析器,而 `Writer`(`GenericWriter<...>` 的 typedef)则是 JSON 的 SAX 风格生成器。 6 7[TOC] 8 9# Reader {#Reader} 10 11`Reader` 从输入流解析一个 JSON。当它从流中读取字符时,它会基于 JSON 的语法去分析字符,并向处理器发送事件。 12 13例如,以下是一个 JSON。 14 15~~~~~~~~~~js 16{ 17 "hello": "world", 18 "t": true , 19 "f": false, 20 "n": null, 21 "i": 123, 22 "pi": 3.1416, 23 "a": [1, 2, 3, 4] 24} 25~~~~~~~~~~ 26 27当一个 `Reader` 解析此 JSON 时,它会顺序地向处理器发送以下的事件: 28 29~~~~~~~~~~ 30StartObject() 31Key("hello", 5, true) 32String("world", 5, true) 33Key("t", 1, true) 34Bool(true) 35Key("f", 1, true) 36Bool(false) 37Key("n", 1, true) 38Null() 39Key("i") 40UInt(123) 41Key("pi") 42Double(3.1416) 43Key("a") 44StartArray() 45Uint(1) 46Uint(2) 47Uint(3) 48Uint(4) 49EndArray(4) 50EndObject(7) 51~~~~~~~~~~ 52 53除了一些事件参数需要再作解释,这些事件可以轻松地与 JSON 对上。我们可以看看 `simplereader` 例子怎样产生和以上完全相同的结果: 54 55~~~~~~~~~~cpp 56#include "rapidjson/reader.h" 57#include <iostream> 58 59using namespace rapidjson; 60using namespace std; 61 62struct MyHandler : public BaseReaderHandler<UTF8<>, MyHandler> { 63 bool Null() { cout << "Null()" << endl; return true; } 64 bool Bool(bool b) { cout << "Bool(" << boolalpha << b << ")" << endl; return true; } 65 bool Int(int i) { cout << "Int(" << i << ")" << endl; return true; } 66 bool Uint(unsigned u) { cout << "Uint(" << u << ")" << endl; return true; } 67 bool Int64(int64_t i) { cout << "Int64(" << i << ")" << endl; return true; } 68 bool Uint64(uint64_t u) { cout << "Uint64(" << u << ")" << endl; return true; } 69 bool Double(double d) { cout << "Double(" << d << ")" << endl; return true; } 70 bool String(const char* str, SizeType length, bool copy) { 71 cout << "String(" << str << ", " << length << ", " << boolalpha << copy << ")" << endl; 72 return true; 73 } 74 bool StartObject() { cout << "StartObject()" << endl; return true; } 75 bool Key(const char* str, SizeType length, bool copy) { 76 cout << "Key(" << str << ", " << length << ", " << boolalpha << copy << ")" << endl; 77 return true; 78 } 79 bool EndObject(SizeType memberCount) { cout << "EndObject(" << memberCount << ")" << endl; return true; } 80 bool StartArray() { cout << "StartArray()" << endl; return true; } 81 bool EndArray(SizeType elementCount) { cout << "EndArray(" << elementCount << ")" << endl; return true; } 82}; 83 84void main() { 85 const char json[] = " { \"hello\" : \"world\", \"t\" : true , \"f\" : false, \"n\": null, \"i\":123, \"pi\": 3.1416, \"a\":[1, 2, 3, 4] } "; 86 87 MyHandler handler; 88 Reader reader; 89 StringStream ss(json); 90 reader.Parse(ss, handler); 91} 92~~~~~~~~~~ 93 94注意 RapidJSON 使用模板去静态挷定 `Reader` 类型及处理器的类形,而不是使用含虚函数的类。这个范式可以通过把函数内联而改善性能。 95 96## 处理器 {#Handler} 97 98如前例所示,使用者需要实现一个处理器(handler),用于处理来自 `Reader` 的事件(函数调用)。处理器必须包含以下的成员函数。 99 100~~~~~~~~~~cpp 101class Handler { 102 bool Null(); 103 bool Bool(bool b); 104 bool Int(int i); 105 bool Uint(unsigned i); 106 bool Int64(int64_t i); 107 bool Uint64(uint64_t i); 108 bool Double(double d); 109 bool RawNumber(const Ch* str, SizeType length, bool copy); 110 bool String(const Ch* str, SizeType length, bool copy); 111 bool StartObject(); 112 bool Key(const Ch* str, SizeType length, bool copy); 113 bool EndObject(SizeType memberCount); 114 bool StartArray(); 115 bool EndArray(SizeType elementCount); 116}; 117~~~~~~~~~~ 118 119当 `Reader` 遇到 JSON null 值时会调用 `Null()`。 120 121当 `Reader` 遇到 JSON true 或 false 值时会调用 `Bool(bool)`。 122 123当 `Reader` 遇到 JSON number,它会选择一个合适的 C++ 类型映射,然后调用 `Int(int)`、`Uint(unsigned)`、`Int64(int64_t)`、`Uint64(uint64_t)` 及 `Double(double)` 的 * 其中之一个 *。 若开启了 `kParseNumbersAsStrings` 选项,`Reader` 便会改为调用 `RawNumber()`。 124 125当 `Reader` 遇到 JSON string,它会调用 `String(const char* str, SizeType length, bool copy)`。第一个参数是字符串的指针。第二个参数是字符串的长度(不包含空终止符号)。注意 RapidJSON 支持字串中含有空字符 `'\0'`。若出现这种情况,便会有 `strlen(str) < length`。最后的 `copy` 参数表示处理器是否需要复制该字符串。在正常解析时,`copy = true`。仅当使用原位解析时,`copy = false`。此外,还要注意字符的类型与目标编码相关,我们稍后会再谈这一点。 126 127当 `Reader` 遇到 JSON object 的开始之时,它会调用 `StartObject()`。JSON 的 object 是一个键值对(成员)的集合。若 object 包含成员,它会先为成员的名字调用 `Key()`,然后再按值的类型调用函数。它不断调用这些键值对,直至最终调用 `EndObject(SizeType memberCount)`。注意 `memberCount` 参数对处理器来说只是协助性质,使用者可能不需要此参数。 128 129JSON array 与 object 相似,但更简单。在 array 开始时,`Reader` 会调用 `BeginArary()`。若 array 含有元素,它会按元素的类型来读用函数。相似地,最后它会调用 `EndArray(SizeType elementCount)`,其中 `elementCount` 参数对处理器来说只是协助性质。 130 131每个处理器函数都返回一个 `bool`。正常它们应返回 `true`。若处理器遇到错误,它可以返回 `false` 去通知事件发送方停止继续处理。 132 133例如,当我们用 `Reader` 解析一个 JSON 时,处理器检测到该 JSON 并不符合所需的 schema,那么处理器可以返回 `false`,令 `Reader` 停止之后的解析工作。而 `Reader` 会进入一个错误状态,并以 `kParseErrorTermination` 错误码标识。 134 135## GenericReader {#GenericReader} 136 137前面提及,`Reader` 是 `GenericReader` 模板类的 typedef: 138 139~~~~~~~~~~cpp 140namespace rapidjson { 141 142template <typename SourceEncoding, typename TargetEncoding, typename Allocator = MemoryPoolAllocator<> > 143class GenericReader { 144 // ... 145}; 146 147typedef GenericReader<UTF8<>, UTF8<> > Reader; 148 149} // namespace rapidjson 150~~~~~~~~~~ 151 152`Reader` 使用 UTF-8 作为来源及目标编码。来源编码是指 JSON 流的编码。目标编码是指 `String()` 的 `str` 参数所用的编码。例如,要解析一个 UTF-8 流并输出至 UTF-16 string 事件,你需要这么定义一个 reader: 153 154~~~~~~~~~~cpp 155GenericReader<UTF8<>, UTF16<> > reader; 156~~~~~~~~~~ 157 158注意到 `UTF16` 的缺省类型是 `wchar_t`。因此这个 `reader` 需要调用处理器的 `String(const wchar_t*, SizeType, bool)`。 159 160第三个模板参数 `Allocator` 是内部数据结构(实际上是一个堆栈)的分配器类型。 161 162## 解析 {#SaxParsing} 163 164`Reader` 的唯一功能就是解析 JSON。 165 166~~~~~~~~~~cpp 167template <unsigned parseFlags, typename InputStream, typename Handler> 168bool Parse(InputStream& is, Handler& handler); 169 170// 使用 parseFlags = kDefaultParseFlags 171template <typename InputStream, typename Handler> 172bool Parse(InputStream& is, Handler& handler); 173~~~~~~~~~~ 174 175若在解析中出现错误,它会返回 `false`。使用者可调用 `bool HasParseEror()`, `ParseErrorCode GetParseErrorCode()` 及 `size_t GetErrorOffset()` 获取错误状态。实际上 `Document` 使用这些 `Reader` 函数去获取解析错误。请参考 [DOM](doc/dom.zh-cn.md) 去了解有关解析错误的细节。 176 177# Writer {#Writer} 178 179`Reader` 把 JSON 转换(解析)成为事件。`Writer` 做完全相反的事情。它把事件转换成 JSON。 180 181`Writer` 是非常容易使用的。若你的应用程序只需把一些数据转换成 JSON,可能直接使用 `Writer`,会比建立一个 `Document` 然后用 `Writer` 把它转换成 JSON 更加方便。 182 183在 `simplewriter` 例子里,我们做 `simplereader` 完全相反的事情。 184 185~~~~~~~~~~cpp 186#include "rapidjson/writer.h" 187#include "rapidjson/stringbuffer.h" 188#include <iostream> 189 190using namespace rapidjson; 191using namespace std; 192 193void main() { 194 StringBuffer s; 195 Writer<StringBuffer> writer(s); 196 197 writer.StartObject(); 198 writer.Key("hello"); 199 writer.String("world"); 200 writer.Key("t"); 201 writer.Bool(true); 202 writer.Key("f"); 203 writer.Bool(false); 204 writer.Key("n"); 205 writer.Null(); 206 writer.Key("i"); 207 writer.Uint(123); 208 writer.Key("pi"); 209 writer.Double(3.1416); 210 writer.Key("a"); 211 writer.StartArray(); 212 for (unsigned i = 0; i < 4; i++) 213 writer.Uint(i); 214 writer.EndArray(); 215 writer.EndObject(); 216 217 cout << s.GetString() << endl; 218} 219~~~~~~~~~~ 220 221~~~~~~~~~~ 222{"hello":"world","t":true,"f":false,"n":null,"i":123,"pi":3.1416,"a":[0,1,2,3]} 223~~~~~~~~~~ 224 225`String()` 及 `Key()` 各有两个重载。一个是如处理器 concept 般,有 3 个参数。它能处理含空字符的字符串。另一个是如上中使用的较简单版本。 226 227注意到,例子代码中的 `EndArray()` 及 `EndObject()` 并没有参数。可以传递一个 `SizeType` 的参数,但它会被 `Writer` 忽略。 228 229你可能会怀疑,为什么不使用 `sprintf()` 或 `std::stringstream` 去建立一个 JSON? 230 231这有几个原因: 2321. `Writer` 必然会输出一个结构良好(well-formed)的 JSON。若然有错误的事件次序(如 `Int()` 紧随 `StartObject()` 出现),它会在调试模式中产生断言失败。 2332. `Writer::String()` 可处理字符串转义(如把码点 `U+000A` 转换成 `\n`)及进行 Unicode 转码。 2343. `Writer` 一致地处理 number 的输出。 2354. `Writer` 实现了事件处理器 concept。可用于处理来自 `Reader`、`Document` 或其他事件发生器。 2365. `Writer` 可对不同平台进行优化。 237 238无论如何,使用 `Writer` API 去生成 JSON 甚至乎比这些临时方法更简单。 239 240## 模板 {#WriterTemplate} 241 242`Writer` 与 `Reader` 有少许设计区别。`Writer` 是一个模板类,而不是一个 typedef。 并没有 `GenericWriter`。以下是 `Writer` 的声明。 243 244~~~~~~~~~~cpp 245namespace rapidjson { 246 247template<typename OutputStream, typename SourceEncoding = UTF8<>, typename TargetEncoding = UTF8<>, typename Allocator = CrtAllocator<> > 248class Writer { 249public: 250 Writer(OutputStream& os, Allocator* allocator = 0, size_t levelDepth = kDefaultLevelDepth) 251// ... 252}; 253 254} // namespace rapidjson 255~~~~~~~~~~ 256 257`OutputStream` 模板参数是输出流的类型。它的类型不可以被自动推断,必须由使用者提供。 258 259`SourceEncoding` 模板参数指定了 `String(const Ch*, ...)` 的编码。 260 261`TargetEncoding` 模板参数指定输出流的编码。 262 263`Allocator` 是分配器的类型,用于分配内部数据结构(一个堆栈)。 264 265`writeFlags` 是以下位标志的组合: 266 267写入位标志 | 意义 268------------------------------|----------------------------------- 269`kWriteNoFlags` | 没有任何标志。 270`kWriteDefaultFlags` | 缺省的解析选项。它等于 `RAPIDJSON_WRITE_DEFAULT_FLAGS` 宏,此宏定义为 `kWriteNoFlags`。 271`kWriteValidateEncodingFlag` | 校验 JSON 字符串的编码。 272`kWriteNanAndInfFlag` | 容许写入 `Infinity`, `-Infinity` 及 `NaN`。 273 274此外,`Writer` 的构造函数有一 `levelDepth` 参数。存储每层阶信息的初始内存分配量受此参数影响。 275 276## PrettyWriter {#PrettyWriter} 277 278`Writer` 所输出的是没有空格字符的最紧凑 JSON,适合网络传输或储存,但不适合人类阅读。 279 280因此,RapidJSON 提供了一个 `PrettyWriter`,它在输出中加入缩进及换行。 281 282`PrettyWriter` 的用法与 `Writer` 几乎一样,不同之处是 `PrettyWriter` 提供了一个 `SetIndent(Ch indentChar, unsigned indentCharCount)` 函数。缺省的缩进是 4 个空格。 283 284## 完整性及重置 {#CompletenessReset} 285 286一个 `Writer` 只可输出单个 JSON,其根节点可以是任何 JSON 类型。当处理完单个根节点事件(如 `String()`),或匹配的最后 `EndObject()` 或 `EndArray()` 事件,输出的 JSON 是结构完整(well-formed)及完整的。使用者可调用 `Writer::IsComplete()` 去检测完整性。 287 288当 JSON 完整时,`Writer` 不能再接受新的事件。不然其输出便会是不合法的(例如有超过一个根节点)。为了重新利用 `Writer` 对象,使用者可调用 `Writer::Reset(OutputStream& os)` 去重置其所有内部状态及设置新的输出流。 289 290# 技巧 {#SaxTechniques} 291 292## 解析 JSON 至自定义结构 {#CustomDataStructure} 293 294`Document` 的解析功能完全依靠 `Reader`。实际上 `Document` 是一个处理器,在解析 JSON 时接收事件去建立一个 DOM。 295 296使用者可以直接使用 `Reader` 去建立其他数据结构。这消除了建立 DOM 的步骤,从而减少了内存开销并改善性能。 297 298在以下的 `messagereader` 例子中,`ParseMessages()` 解析一个 JSON,该 JSON 应该是一个含键值对的 object。 299 300~~~~~~~~~~cpp 301#include "rapidjson/reader.h" 302#include "rapidjson/error/en.h" 303#include <iostream> 304#include <string> 305#include <map> 306 307using namespace std; 308using namespace rapidjson; 309 310typedef map<string, string> MessageMap; 311 312struct MessageHandler 313 : public BaseReaderHandler<UTF8<>, MessageHandler> { 314 MessageHandler() : state_(kExpectObjectStart) { 315 } 316 317 bool StartObject() { 318 switch (state_) { 319 case kExpectObjectStart: 320 state_ = kExpectNameOrObjectEnd; 321 return true; 322 default: 323 return false; 324 } 325 } 326 327 bool String(const char* str, SizeType length, bool) { 328 switch (state_) { 329 case kExpectNameOrObjectEnd: 330 name_ = string(str, length); 331 state_ = kExpectValue; 332 return true; 333 case kExpectValue: 334 messages_.insert(MessageMap::value_type(name_, string(str, length))); 335 state_ = kExpectNameOrObjectEnd; 336 return true; 337 default: 338 return false; 339 } 340 } 341 342 bool EndObject(SizeType) { return state_ == kExpectNameOrObjectEnd; } 343 344 bool Default() { return false; } // All other events are invalid. 345 346 MessageMap messages_; 347 enum State { 348 kExpectObjectStart, 349 kExpectNameOrObjectEnd, 350 kExpectValue, 351 }state_; 352 std::string name_; 353}; 354 355void ParseMessages(const char* json, MessageMap& messages) { 356 Reader reader; 357 MessageHandler handler; 358 StringStream ss(json); 359 if (reader.Parse(ss, handler)) 360 messages.swap(handler.messages_); // Only change it if success. 361 else { 362 ParseErrorCode e = reader.GetParseErrorCode(); 363 size_t o = reader.GetErrorOffset(); 364 cout << "Error: " << GetParseError_En(e) << endl;; 365 cout << " at offset " << o << " near '" << string(json).substr(o, 10) << "...'" << endl; 366 } 367} 368 369int main() { 370 MessageMap messages; 371 372 const char* json1 = "{ \"greeting\" : \"Hello!\", \"farewell\" : \"bye-bye!\" }"; 373 cout << json1 << endl; 374 ParseMessages(json1, messages); 375 376 for (MessageMap::const_iterator itr = messages.begin(); itr != messages.end(); ++itr) 377 cout << itr->first << ": " << itr->second << endl; 378 379 cout << endl << "Parse a JSON with invalid schema." << endl; 380 const char* json2 = "{ \"greeting\" : \"Hello!\", \"farewell\" : \"bye-bye!\", \"foo\" : {} }"; 381 cout << json2 << endl; 382 ParseMessages(json2, messages); 383 384 return 0; 385} 386~~~~~~~~~~ 387 388~~~~~~~~~~ 389{ "greeting" : "Hello!", "farewell" : "bye-bye!" } 390farewell: bye-bye! 391greeting: Hello! 392 393Parse a JSON with invalid schema. 394{ "greeting" : "Hello!", "farewell" : "bye-bye!", "foo" : {} } 395Error: Terminate parsing due to Handler error. 396 at offset 59 near '} }...' 397~~~~~~~~~~ 398 399第一个 JSON(`json1`)被成功地解析至 `MessageMap`。由于 `MessageMap` 是一个 `std::map`,打印次序按键值排序。此次序与 JSON 中的次序不同。 400 401在第二个 JSON(`json2`)中,`foo` 的值是一个空 object。由于它是一个 object,`MessageHandler::StartObject()` 会被调用。然而,在 `state_ = kExpectValue` 的情况下,该函数会返回 `false`,并导致解析过程终止。错误代码是 `kParseErrorTermination`。 402 403## 过滤 JSON {#Filtering} 404 405如前面提及过,`Writer` 可处理 `Reader` 发出的事件。`example/condense/condense.cpp` 例子简单地设置 `Writer` 作为一个 `Reader` 的处理器,因此它能移除 JSON 中的所有空白字符。`example/pretty/pretty.cpp` 例子使用同样的关系,只是以 `PrettyWriter` 取代 `Writer`。因此 `pretty` 能够重新格式化 JSON,加入缩进及换行。 406 407实际上,我们可以使用 SAX 风格 API 去加入(多个)中间层去过滤 JSON 的内容。例如 `capitalize` 例子可以把所有 JSON string 改为大写。 408 409~~~~~~~~~~cpp 410#include "rapidjson/reader.h" 411#include "rapidjson/writer.h" 412#include "rapidjson/filereadstream.h" 413#include "rapidjson/filewritestream.h" 414#include "rapidjson/error/en.h" 415#include <vector> 416#include <cctype> 417 418using namespace rapidjson; 419 420template<typename OutputHandler> 421struct CapitalizeFilter { 422 CapitalizeFilter(OutputHandler& out) : out_(out), buffer_() { 423 } 424 425 bool Null() { return out_.Null(); } 426 bool Bool(bool b) { return out_.Bool(b); } 427 bool Int(int i) { return out_.Int(i); } 428 bool Uint(unsigned u) { return out_.Uint(u); } 429 bool Int64(int64_t i) { return out_.Int64(i); } 430 bool Uint64(uint64_t u) { return out_.Uint64(u); } 431 bool Double(double d) { return out_.Double(d); } 432 bool RawNumber(const char* str, SizeType length, bool copy) { return out_.RawNumber(str, length, copy); } 433 bool String(const char* str, SizeType length, bool) { 434 buffer_.clear(); 435 for (SizeType i = 0; i < length; i++) 436 buffer_.push_back(std::toupper(str[i])); 437 return out_.String(&buffer_.front(), length, true); // true = output handler need to copy the string 438 } 439 bool StartObject() { return out_.StartObject(); } 440 bool Key(const char* str, SizeType length, bool copy) { return String(str, length, copy); } 441 bool EndObject(SizeType memberCount) { return out_.EndObject(memberCount); } 442 bool StartArray() { return out_.StartArray(); } 443 bool EndArray(SizeType elementCount) { return out_.EndArray(elementCount); } 444 445 OutputHandler& out_; 446 std::vector<char> buffer_; 447}; 448 449int main(int, char*[]) { 450 // Prepare JSON reader and input stream. 451 Reader reader; 452 char readBuffer[65536]; 453 FileReadStream is(stdin, readBuffer, sizeof(readBuffer)); 454 455 // Prepare JSON writer and output stream. 456 char writeBuffer[65536]; 457 FileWriteStream os(stdout, writeBuffer, sizeof(writeBuffer)); 458 Writer<FileWriteStream> writer(os); 459 460 // JSON reader parse from the input stream and let writer generate the output. 461 CapitalizeFilter<Writer<FileWriteStream> > filter(writer); 462 if (!reader.Parse(is, filter)) { 463 fprintf(stderr, "\nError(%u): %s\n", (unsigned)reader.GetErrorOffset(), GetParseError_En(reader.GetParseErrorCode())); 464 return 1; 465 } 466 467 return 0; 468} 469~~~~~~~~~~ 470 471注意到,不可简单地把 JSON 当作字符串去改为大写。例如: 472~~~~~~~~~~ 473["Hello\nWorld"] 474~~~~~~~~~~ 475 476简单地把整个 JSON 转为大写的话会产生错误的转义符: 477~~~~~~~~~~ 478["HELLO\NWORLD"] 479~~~~~~~~~~ 480 481而 `capitalize` 就会产生正确的结果: 482~~~~~~~~~~ 483["HELLO\nWORLD"] 484~~~~~~~~~~ 485 486我们还可以开发更复杂的过滤器。然而,由于 SAX 风格 API 在某一时间点只能提供单一事件的信息,使用者需要自行记录一些上下文信息(例如从根节点起的路径、储存其他相关值)。对于处理某些情况,用 DOM 会比 SAX 更容易实现。 487 488