mirror of
https://github.com/open-source-parsers/jsoncpp.git
synced 2024-12-12 10:03:51 +01:00
165 lines
7.0 KiB
Markdown
165 lines
7.0 KiB
Markdown
# JsonCpp
|
|
|
|
[](http://www.conan.io/source/jsoncpp/1.8.0/theirix/ci)
|
|
|
|
[JSON][json-org] is a lightweight data-interchange format. It can represent
|
|
numbers, strings, ordered sequences of values, and collections of name/value
|
|
pairs.
|
|
|
|
[json-org]: http://json.org/
|
|
|
|
JsonCpp is a C++ library that allows manipulating JSON values, including
|
|
serialization and deserialization to and from strings. It can also preserve
|
|
existing comment in unserialization/serialization steps, making it a convenient
|
|
format to store user input files.
|
|
|
|
|
|
## Documentation
|
|
|
|
[JsonCpp documentation][JsonCpp-documentation] is generated using [Doxygen][].
|
|
|
|
[JsonCpp-documentation]: http://open-source-parsers.github.io/jsoncpp-docs/doxygen/index.html
|
|
[Doxygen]: http://www.doxygen.org
|
|
|
|
|
|
## A note on backward-compatibility
|
|
|
|
* `1.y.z` is built with C++11.
|
|
* `0.y.z` can be used with older compilers.
|
|
* Major versions maintain binary-compatibility.
|
|
|
|
|
|
## Using JsonCpp in your project
|
|
|
|
The recommended approach to integrating JsonCpp in your project is to include
|
|
the [amalgamated source](#generating-amalgamated-source-and-header) (a single
|
|
`.cpp` file and two `.h` files) in your project, and compile and build as you
|
|
would any other source file. This ensures consistency of compilation flags and
|
|
ABI compatibility, issues which arise when building shared or static
|
|
libraries. See the next section for instructions.
|
|
|
|
The `include/` should be added to your compiler include path. JsonCpp headers
|
|
should be included as follow:
|
|
|
|
#include <json/json.h>
|
|
|
|
If JsonCpp was built as a dynamic library on Windows, then your project needs to define the macro `JSON_DLL`.
|
|
|
|
### Generating amalgamated source and header
|
|
|
|
JsonCpp is provided with a script to generate a single header and a single
|
|
source file to ease inclusion into an existing project. The amalgamated source
|
|
can be generated at any time by running the following command from the
|
|
top-directory (this requires Python 2.6):
|
|
|
|
python amalgamate.py
|
|
|
|
It is possible to specify header name. See the `-h` option for detail.
|
|
|
|
By default, the following files are generated:
|
|
|
|
* `dist/jsoncpp.cpp`: source file that needs to be added to your project.
|
|
* `dist/json/json.h`: corresponding header file for use in your project. It is
|
|
equivalent to including `json/json.h` in non-amalgamated source. This header
|
|
only depends on standard headers.
|
|
* `dist/json/json-forwards.h`: header that provides forward declaration of all
|
|
JsonCpp types.
|
|
|
|
The amalgamated sources are generated by concatenating JsonCpp source in the
|
|
correct order and defining the macro `JSON_IS_AMALGAMATION` to prevent inclusion of other headers.
|
|
|
|
|
|
## Contributing to JsonCpp
|
|
|
|
### Building and testing with Meson/Ninja
|
|
Thanks to David Seifert (@SoapGentoo), we (the maintainers) now use [meson](http://mesonbuild.com/) and [ninja](https://ninja-build.org/) to build for debugging, as well as for continuous integration (see [`travis.sh`](travis.sh) ). Other systems may work, but minor things like version strings might break.
|
|
|
|
First, install both meson (which requires Python3) and ninja.
|
|
|
|
Then,
|
|
|
|
cd jsoncpp/
|
|
BUILD_TYPE=shared
|
|
#BUILD_TYPE=static
|
|
LIB_TYPE=debug
|
|
#LIB_TYPE=release
|
|
meson --buildtype ${BUILD_TYPE} --default-library ${LIB_TYPE} . build-${LIB_TYPE}
|
|
ninja -v -C build-${LIB_TYPE} test
|
|
|
|
### Building and testing with other build systems
|
|
See https://github.com/open-source-parsers/jsoncpp/wiki/Building
|
|
|
|
### Running the tests manually
|
|
|
|
You need to run tests manually only if you are troubleshooting an issue.
|
|
|
|
In the instructions below, replace `path/to/jsontest` with the path of the
|
|
`jsontest` executable that was compiled on your platform.
|
|
|
|
cd test
|
|
# This will run the Reader/Writer tests
|
|
python runjsontests.py path/to/jsontest
|
|
|
|
# This will run the Reader/Writer tests, using JSONChecker test suite
|
|
# (http://www.json.org/JSON_checker/).
|
|
# Notes: not all tests pass: JsonCpp is too lenient (for example,
|
|
# it allows an integer to start with '0'). The goal is to improve
|
|
# strict mode parsing to get all tests to pass.
|
|
python runjsontests.py --with-json-checker path/to/jsontest
|
|
|
|
# This will run the unit tests (mostly Value)
|
|
python rununittests.py path/to/test_lib_json
|
|
|
|
# You can run the tests using valgrind:
|
|
python rununittests.py --valgrind path/to/test_lib_json
|
|
|
|
### Building the documentation
|
|
|
|
Run the Python script `doxybuild.py` from the top directory:
|
|
|
|
python doxybuild.py --doxygen=$(which doxygen) --open --with-dot
|
|
|
|
See `doxybuild.py --help` for options.
|
|
|
|
### Adding a reader/writer test
|
|
|
|
To add a test, you need to create two files in test/data:
|
|
|
|
* a `TESTNAME.json` file, that contains the input document in JSON format.
|
|
* a `TESTNAME.expected` file, that contains a flatened representation of the
|
|
input document.
|
|
|
|
The `TESTNAME.expected` file format is as follows:
|
|
|
|
* Each line represents a JSON element of the element tree represented by the
|
|
input document.
|
|
* Each line has two parts: the path to access the element separated from the
|
|
element value by `=`. Array and object values are always empty (i.e.
|
|
represented by either `[]` or `{}`).
|
|
* Element path `.` represents the root element, and is used to separate object
|
|
members. `[N]` is used to specify the value of an array element at index `N`.
|
|
|
|
See the examples `test_complex_01.json` and `test_complex_01.expected` to better understand element paths.
|
|
|
|
### Understanding reader/writer test output
|
|
|
|
When a test is run, output files are generated beside the input test files. Below is a short description of the content of each file:
|
|
|
|
* `test_complex_01.json`: input JSON document.
|
|
* `test_complex_01.expected`: flattened JSON element tree used to check if
|
|
parsing was corrected.
|
|
* `test_complex_01.actual`: flattened JSON element tree produced by `jsontest`
|
|
from reading `test_complex_01.json`.
|
|
* `test_complex_01.rewrite`: JSON document written by `jsontest` using the
|
|
`Json::Value` parsed from `test_complex_01.json` and serialized using
|
|
`Json::StyledWritter`.
|
|
* `test_complex_01.actual-rewrite`: flattened JSON element tree produced by
|
|
`jsontest` from reading `test_complex_01.rewrite`.
|
|
* `test_complex_01.process-output`: `jsontest` output, typically useful for
|
|
understanding parsing errors.
|
|
|
|
## License
|
|
|
|
See the `LICENSE` file for details. In summary, JsonCpp is licensed under the
|
|
MIT license, or public domain if desired and recognized in your jurisdiction.
|