| 1 |
 |
| 2 |
|
| 3 |
 |
| 4 |
|
| 5 |
## A fast JSON parser/generator for C++ with both SAX/DOM style API |
| 6 |
|
| 7 |
Tencent is pleased to support the open source community by making RapidJSON available. |
| 8 |
|
| 9 |
Copyright (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip. |
| 10 |
|
| 11 |
* [RapidJSON GitHub](https://github.com/Tencent/rapidjson/) |
| 12 |
* RapidJSON Documentation |
| 13 |
* [English](http://rapidjson.org/) |
| 14 |
* [简体中文](http://rapidjson.org/zh-cn/) |
| 15 |
* [GitBook](https://www.gitbook.com/book/miloyip/rapidjson/) with downloadable PDF/EPUB/MOBI, without API reference. |
| 16 |
|
| 17 |
## Build status |
| 18 |
|
| 19 |
| [Linux][lin-link] | [Windows][win-link] | [Coveralls][cov-link] | |
| 20 |
| :---------------: | :-----------------: | :-------------------: | |
| 21 |
| ![lin-badge] | ![win-badge] | ![cov-badge] | |
| 22 |
|
| 23 |
[lin-badge]: https://travis-ci.org/Tencent/rapidjson.svg?branch=master "Travis build status" |
| 24 |
[lin-link]: https://travis-ci.org/Tencent/rapidjson "Travis build status" |
| 25 |
[win-badge]: https://ci.appveyor.com/api/projects/status/l6qulgqahcayidrf/branch/master?svg=true "AppVeyor build status" |
| 26 |
[win-link]: https://ci.appveyor.com/project/miloyip/rapidjson-0fdqj/branch/master "AppVeyor build status" |
| 27 |
[cov-badge]: https://coveralls.io/repos/Tencent/rapidjson/badge.svg?branch=master "Coveralls coverage" |
| 28 |
[cov-link]: https://coveralls.io/r/Tencent/rapidjson?branch=master "Coveralls coverage" |
| 29 |
|
| 30 |
## Introduction |
| 31 |
|
| 32 |
RapidJSON is a JSON parser and generator for C++. It was inspired by [RapidXml](http://rapidxml.sourceforge.net/). |
| 33 |
|
| 34 |
* RapidJSON is **small** but **complete**. It supports both SAX and DOM style API. The SAX parser is only a half thousand lines of code. |
| 35 |
|
| 36 |
* RapidJSON is **fast**. Its performance can be comparable to `strlen()`. It also optionally supports SSE2/SSE4.2 for acceleration. |
| 37 |
|
| 38 |
* RapidJSON is **self-contained** and **header-only**. It does not depend on external libraries such as BOOST. It even does not depend on STL. |
| 39 |
|
| 40 |
* RapidJSON is **memory-friendly**. Each JSON value occupies exactly 16 bytes for most 32/64-bit machines (excluding text string). By default it uses a fast memory allocator, and the parser allocates memory compactly during parsing. |
| 41 |
|
| 42 |
* RapidJSON is **Unicode-friendly**. It supports UTF-8, UTF-16, UTF-32 (LE & BE), and their detection, validation and transcoding internally. For example, you can read a UTF-8 file and let RapidJSON transcode the JSON strings into UTF-16 in the DOM. It also supports surrogates and "\u0000" (null character). |
| 43 |
|
| 44 |
More features can be read [here](doc/features.md). |
| 45 |
|
| 46 |
JSON(JavaScript Object Notation) is a light-weight data exchange format. RapidJSON should be in full compliance with RFC7159/ECMA-404, with optional support of relaxed syntax. More information about JSON can be obtained at |
| 47 |
* [Introducing JSON](http://json.org/) |
| 48 |
* [RFC7159: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc7159) |
| 49 |
* [Standard ECMA-404: The JSON Data Interchange Format](https://www.ecma-international.org/publications/standards/Ecma-404.htm) |
| 50 |
|
| 51 |
## Highlights in v1.1 (2016-8-25) |
| 52 |
|
| 53 |
* Added [JSON Pointer](doc/pointer.md) |
| 54 |
* Added [JSON Schema](doc/schema.md) |
| 55 |
* Added [relaxed JSON syntax](doc/dom.md) (comment, trailing comma, NaN/Infinity) |
| 56 |
* Iterating array/object with [C++11 Range-based for loop](doc/tutorial.md) |
| 57 |
* Reduce memory overhead of each `Value` from 24 bytes to 16 bytes in x86-64 architecture. |
| 58 |
|
| 59 |
For other changes please refer to [change log](CHANGELOG.md). |
| 60 |
|
| 61 |
## Compatibility |
| 62 |
|
| 63 |
RapidJSON is cross-platform. Some platform/compiler combinations which have been tested are shown as follows. |
| 64 |
* Visual C++ 2008/2010/2013 on Windows (32/64-bit) |
| 65 |
* GNU C++ 3.8.x on Cygwin |
| 66 |
* Clang 3.4 on Mac OS X (32/64-bit) and iOS |
| 67 |
* Clang 3.4 on Android NDK |
| 68 |
|
| 69 |
Users can build and run the unit tests on their platform/compiler. |
| 70 |
|
| 71 |
## Installation |
| 72 |
|
| 73 |
RapidJSON is a header-only C++ library. Just copy the `include/rapidjson` folder to system or project's include path. |
| 74 |
|
| 75 |
Alternatively, if you are using the [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager you can download and install rapidjson with CMake integration in a single command: |
| 76 |
* vcpkg install rapidjson |
| 77 |
|
| 78 |
RapidJSON uses following software as its dependencies: |
| 79 |
* [CMake](https://cmake.org/) as a general build tool |
| 80 |
* (optional) [Doxygen](http://www.doxygen.org) to build documentation |
| 81 |
* (optional) [googletest](https://github.com/google/googletest) for unit and performance testing |
| 82 |
|
| 83 |
To generate user documentation and run tests please proceed with the steps below: |
| 84 |
|
| 85 |
1. Execute `git submodule update --init` to get the files of thirdparty submodules (google test). |
| 86 |
2. Create directory called `build` in rapidjson source directory. |
| 87 |
3. Change to `build` directory and run `cmake ..` command to configure your build. Windows users can do the same with cmake-gui application. |
| 88 |
4. On Windows, build the solution found in the build directory. On Linux, run `make` from the build directory. |
| 89 |
|
| 90 |
On successful build you will find compiled test and example binaries in `bin` |
| 91 |
directory. The generated documentation will be available in `doc/html` |
| 92 |
directory of the build tree. To run tests after finished build please run `make |
| 93 |
test` or `ctest` from your build tree. You can get detailed output using `ctest |
| 94 |
-V` command. |
| 95 |
|
| 96 |
It is possible to install library system-wide by running `make install` command |
| 97 |
from the build tree with administrative privileges. This will install all files |
| 98 |
according to system preferences. Once RapidJSON is installed, it is possible |
| 99 |
to use it from other CMake projects by adding `find_package(RapidJSON)` line to |
| 100 |
your CMakeLists.txt. |
| 101 |
|
| 102 |
## Usage at a glance |
| 103 |
|
| 104 |
This simple example parses a JSON string into a document (DOM), make a simple modification of the DOM, and finally stringify the DOM to a JSON string. |
| 105 |
|
| 106 |
~~~~~~~~~~cpp |
| 107 |
// rapidjson/example/simpledom/simpledom.cpp` |
| 108 |
#include "rapidjson/document.h" |
| 109 |
#include "rapidjson/writer.h" |
| 110 |
#include "rapidjson/stringbuffer.h" |
| 111 |
#include <iostream> |
| 112 |
|
| 113 |
using namespace rapidjson; |
| 114 |
|
| 115 |
int main() { |
| 116 |
// 1. Parse a JSON string into DOM. |
| 117 |
const char* json = "{\"project\":\"rapidjson\",\"stars\":10}"; |
| 118 |
Document d; |
| 119 |
d.Parse(json); |
| 120 |
|
| 121 |
// 2. Modify it by DOM. |
| 122 |
Value& s = d["stars"]; |
| 123 |
s.SetInt(s.GetInt() + 1); |
| 124 |
|
| 125 |
// 3. Stringify the DOM |
| 126 |
StringBuffer buffer; |
| 127 |
Writer<StringBuffer> writer(buffer); |
| 128 |
d.Accept(writer); |
| 129 |
|
| 130 |
// Output {"project":"rapidjson","stars":11} |
| 131 |
std::cout << buffer.GetString() << std::endl; |
| 132 |
return 0; |
| 133 |
} |
| 134 |
~~~~~~~~~~ |
| 135 |
|
| 136 |
Note that this example did not handle potential errors. |
| 137 |
|
| 138 |
The following diagram shows the process. |
| 139 |
|
| 140 |
 |
| 141 |
|
| 142 |
More [examples](https://github.com/Tencent/rapidjson/tree/master/example) are available: |
| 143 |
|
| 144 |
* DOM API |
| 145 |
* [tutorial](https://github.com/Tencent/rapidjson/blob/master/example/tutorial/tutorial.cpp): Basic usage of DOM API. |
| 146 |
|
| 147 |
* SAX API |
| 148 |
* [simplereader](https://github.com/Tencent/rapidjson/blob/master/example/simplereader/simplereader.cpp): Dumps all SAX events while parsing a JSON by `Reader`. |
| 149 |
* [condense](https://github.com/Tencent/rapidjson/blob/master/example/condense/condense.cpp): A command line tool to rewrite a JSON, with all whitespaces removed. |
| 150 |
* [pretty](https://github.com/Tencent/rapidjson/blob/master/example/pretty/pretty.cpp): A command line tool to rewrite a JSON with indents and newlines by `PrettyWriter`. |
| 151 |
* [capitalize](https://github.com/Tencent/rapidjson/blob/master/example/capitalize/capitalize.cpp): A command line tool to capitalize strings in JSON. |
| 152 |
* [messagereader](https://github.com/Tencent/rapidjson/blob/master/example/messagereader/messagereader.cpp): Parse a JSON message with SAX API. |
| 153 |
* [serialize](https://github.com/Tencent/rapidjson/blob/master/example/serialize/serialize.cpp): Serialize a C++ object into JSON with SAX API. |
| 154 |
* [jsonx](https://github.com/Tencent/rapidjson/blob/master/example/jsonx/jsonx.cpp): Implements a `JsonxWriter` which stringify SAX events into [JSONx](https://www-01.ibm.com/support/knowledgecenter/SS9H2Y_7.1.0/com.ibm.dp.doc/json_jsonx.html) (a kind of XML) format. The example is a command line tool which converts input JSON into JSONx format. |
| 155 |
|
| 156 |
* Schema |
| 157 |
* [schemavalidator](https://github.com/Tencent/rapidjson/blob/master/example/schemavalidator/schemavalidator.cpp) : A command line tool to validate a JSON with a JSON schema. |
| 158 |
|
| 159 |
* Advanced |
| 160 |
* [prettyauto](https://github.com/Tencent/rapidjson/blob/master/example/prettyauto/prettyauto.cpp): A modified version of [pretty](https://github.com/Tencent/rapidjson/blob/master/example/pretty/pretty.cpp) to automatically handle JSON with any UTF encodings. |
| 161 |
* [parsebyparts](https://github.com/Tencent/rapidjson/blob/master/example/parsebyparts/parsebyparts.cpp): Implements an `AsyncDocumentParser` which can parse JSON in parts, using C++11 thread. |
| 162 |
* [filterkey](https://github.com/Tencent/rapidjson/blob/master/example/filterkey/filterkey.cpp): A command line tool to remove all values with user-specified key. |
| 163 |
* [filterkeydom](https://github.com/Tencent/rapidjson/blob/master/example/filterkeydom/filterkeydom.cpp): Same tool as above, but it demonstrates how to use a generator to populate a `Document`. |
| 164 |
|
| 165 |
## Contributing |
| 166 |
|
| 167 |
RapidJSON welcomes contributions. When contributing, please follow the code below. |
| 168 |
|
| 169 |
### Issues |
| 170 |
|
| 171 |
Feel free to submit issues and enhancement requests. |
| 172 |
|
| 173 |
Please help us by providing **minimal reproducible examples**, because source code is easier to let other people understand what happens. |
| 174 |
For crash problems on certain platforms, please bring stack dump content with the detail of the OS, compiler, etc. |
| 175 |
|
| 176 |
Please try breakpoint debugging first, tell us what you found, see if we can start exploring based on more information been prepared. |
| 177 |
|
| 178 |
### Workflow |
| 179 |
|
| 180 |
In general, we follow the "fork-and-pull" Git workflow. |
| 181 |
|
| 182 |
1. **Fork** the repo on GitHub |
| 183 |
2. **Clone** the project to your own machine |
| 184 |
3. **Checkout** a new branch on your fork, start developing on the branch |
| 185 |
4. **Test** the change before commit, Make sure the changes pass all the tests, including `unittest` and `preftest`, please add test case for each new feature or bug-fix if needed. |
| 186 |
5. **Commit** changes to your own branch |
| 187 |
6. **Push** your work back up to your fork |
| 188 |
7. Submit a **Pull request** so that we can review your changes |
| 189 |
|
| 190 |
NOTE: Be sure to merge the latest from "upstream" before making a pull request! |
| 191 |
|
| 192 |
### Copyright and Licensing |
| 193 |
|
| 194 |
You can copy and paste the license summary from below. |
| 195 |
|
| 196 |
``` |
| 197 |
Tencent is pleased to support the open source community by making RapidJSON available. |
| 198 |
|
| 199 |
Copyright (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip. |
| 200 |
|
| 201 |
Licensed under the MIT License (the "License"); you may not use this file except |
| 202 |
in compliance with the License. You may obtain a copy of the License at |
| 203 |
|
| 204 |
http://opensource.org/licenses/MIT |
| 205 |
|
| 206 |
Unless required by applicable law or agreed to in writing, software distributed |
| 207 |
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR |
| 208 |
CONDITIONS OF ANY KIND, either express or implied. See the License for the |
| 209 |
specific language governing permissions and limitations under the License. |
| 210 |
``` |