| 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 |
~~~~~~~~~~ |
| 30 |
StartObject() |
| 31 |
Key("hello", 5, true) |
| 32 |
String("world", 5, true) |
| 33 |
Key("t", 1, true) |
| 34 |
Bool(true) |
| 35 |
Key("f", 1, true) |
| 36 |
Bool(false) |
| 37 |
Key("n", 1, true) |
| 38 |
Null() |
| 39 |
Key("i") |
| 40 |
Uint(123) |
| 41 |
Key("pi") |
| 42 |
Double(3.1416) |
| 43 |
Key("a") |
| 44 |
StartArray() |
| 45 |
Uint(1) |
| 46 |
Uint(2) |
| 47 |
Uint(3) |
| 48 |
Uint(4) |
| 49 |
EndArray(4) |
| 50 |
EndObject(7) |
| 51 |
~~~~~~~~~~ |
| 52 |
|
| 53 |
除了一些事件参数需要再作解释,这些事件可以轻松地与 JSON 对上。我们可以看看 `simplereader` 例子怎样产生和以上完全相同的结果: |
| 54 |
|
| 55 |
~~~~~~~~~~cpp |
| 56 |
#include "rapidjson/reader.h" |
| 57 |
#include <iostream> |
| 58 |
|
| 59 |
using namespace rapidjson; |
| 60 |
using namespace std; |
| 61 |
|
| 62 |
struct 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 |
|
| 84 |
void 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 |
| 101 |
class 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 |
|
| 129 |
JSON 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 |
| 140 |
namespace rapidjson { |
| 141 |
|
| 142 |
template <typename SourceEncoding, typename TargetEncoding, typename Allocator = MemoryPoolAllocator<> > |
| 143 |
class GenericReader { |
| 144 |
// ... |
| 145 |
}; |
| 146 |
|
| 147 |
typedef 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 |
| 155 |
GenericReader<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 |
| 167 |
template <unsigned parseFlags, typename InputStream, typename Handler> |
| 168 |
bool Parse(InputStream& is, Handler& handler); |
| 169 |
|
| 170 |
// 使用 parseFlags = kDefaultParseFlags |
| 171 |
template <typename InputStream, typename Handler> |
| 172 |
bool 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 |
|
| 190 |
using namespace rapidjson; |
| 191 |
using namespace std; |
| 192 |
|
| 193 |
void 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 |
这有几个原因: |
| 232 |
1. `Writer` 必然会输出一个结构良好(well-formed)的 JSON。若然有错误的事件次序(如 `Int()` 紧随 `StartObject()` 出现),它会在调试模式中产生断言失败。 |
| 233 |
2. `Writer::String()` 可处理字符串转义(如把码点 `U+000A` 转换成 `\n`)及进行 Unicode 转码。 |
| 234 |
3. `Writer` 一致地处理 number 的输出。 |
| 235 |
4. `Writer` 实现了事件处理器 concept。可用于处理来自 `Reader`、`Document` 或其他事件发生器。 |
| 236 |
5. `Writer` 可对不同平台进行优化。 |
| 237 |
|
| 238 |
无论如何,使用 `Writer` API 去生成 JSON 甚至乎比这些临时方法更简单。 |
| 239 |
|
| 240 |
## 模板 {#WriterTemplate} |
| 241 |
|
| 242 |
`Writer` 与 `Reader` 有少许设计区别。`Writer` 是一个模板类,而不是一个 typedef。 并没有 `GenericWriter`。以下是 `Writer` 的声明。 |
| 243 |
|
| 244 |
~~~~~~~~~~cpp |
| 245 |
namespace rapidjson { |
| 246 |
|
| 247 |
template<typename OutputStream, typename SourceEncoding = UTF8<>, typename TargetEncoding = UTF8<>, typename Allocator = CrtAllocator<> > |
| 248 |
class Writer { |
| 249 |
public: |
| 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 |
|
| 307 |
using namespace std; |
| 308 |
using namespace rapidjson; |
| 309 |
|
| 310 |
typedef map<string, string> MessageMap; |
| 311 |
|
| 312 |
struct 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 |
|
| 355 |
void 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 |
|
| 369 |
int 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!" } |
| 390 |
farewell: bye-bye! |
| 391 |
greeting: Hello! |
| 392 |
|
| 393 |
Parse a JSON with invalid schema. |
| 394 |
{ "greeting" : "Hello!", "farewell" : "bye-bye!", "foo" : {} } |
| 395 |
Error: 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 |
|
| 418 |
using namespace rapidjson; |
| 419 |
|
| 420 |
template<typename OutputHandler> |
| 421 |
struct 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 |
|
| 449 |
int 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 |
|