README.md 5.6 KB
Newer Older
I
Iñaki Baz Castillo 已提交
1
# JsonCpp
2

3 4
[![badge](https://img.shields.io/badge/conan.io-jsoncpp%2F1.8.0-green.svg?logo=data:image/png;base64%2CiVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAMAAAAolt3jAAAA1VBMVEUAAABhlctjlstkl8tlmMtlmMxlmcxmmcxnmsxpnMxpnM1qnc1sn85voM91oM11oc1xotB2oc56pNF6pNJ2ptJ8ptJ8ptN9ptN8p9N5qNJ9p9N9p9R8qtOBqdSAqtOAqtR%2BrNSCrNJ/rdWDrNWCsNWCsNaJs9eLs9iRvNuVvdyVv9yXwd2Zwt6axN6dxt%2Bfx%2BChyeGiyuGjyuCjyuGly%2BGlzOKmzOGozuKoz%2BKqz%2BOq0OOv1OWw1OWw1eWx1eWy1uay1%2Baz1%2Baz1%2Bez2Oe02Oe12ee22ujUGwH3AAAAAXRSTlMAQObYZgAAAAFiS0dEAIgFHUgAAAAJcEhZcwAACxMAAAsTAQCanBgAAAAHdElNRQfgBQkREyOxFIh/AAAAiklEQVQI12NgAAMbOwY4sLZ2NtQ1coVKWNvoc/Eq8XDr2wB5Ig62ekza9vaOqpK2TpoMzOxaFtwqZua2Bm4makIM7OzMAjoaCqYuxooSUqJALjs7o4yVpbowvzSUy87KqSwmxQfnsrPISyFzWeWAXCkpMaBVIC4bmCsOdgiUKwh3JojLgAQ4ZCE0AMm2D29tZwe6AAAAAElFTkSuQmCC)](http://www.conan.io/source/jsoncpp/1.8.0/theirix/ci)

5 6 7
[JSON][json-org] is a lightweight data-interchange format. It can represent
numbers, strings, ordered sequences of values, and collections of name/value
pairs.
8

9
[json-org]: http://json.org/
10

I
Iñaki Baz Castillo 已提交
11
JsonCpp is a C++ library that allows manipulating JSON values, including
12 13 14
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.
15

I
Iñaki Baz Castillo 已提交
16 17 18 19 20 21 22 23

## 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

C
Christopher Dunn 已提交
24

C
Christopher Dunn 已提交
25
## A note on backward-compatibility
I
Iñaki Baz Castillo 已提交
26

C
Christopher Dunn 已提交
27
* `1.y.z` is built with C++11.
28
* `0.y.z` can be used with older compilers.
C
Christopher Dunn 已提交
29
* Major versions maintain binary-compatibility.
30

I
Iñaki Baz Castillo 已提交
31 32
## Contributing to JsonCpp

C
Christopher Dunn 已提交
33 34
### 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.
35

C
Christopher Dunn 已提交
36
First, install both meson (which requires Python3) and ninja.
37

C
Christopher Dunn 已提交
38
Then,
39

C
Christopher Dunn 已提交
40 41 42 43 44 45 46
    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
47

C
Christopher Dunn 已提交
48 49
### Building and testing with other build systems
See https://github.com/open-source-parsers/jsoncpp/wiki/Building
50

I
Iñaki Baz Castillo 已提交
51 52
### Running the tests manually

53 54 55 56 57 58 59 60
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
61

62 63 64 65 66 67
    # 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
68

69 70
    # This will run the unit tests (mostly Value)
    python rununittests.py path/to/test_lib_json
71

72 73
    # You can run the tests using valgrind:
    python rununittests.py --valgrind path/to/test_lib_json
74

I
Iñaki Baz Castillo 已提交
75 76
### Building the documentation

77
Run the Python script `doxybuild.py` from the top directory:
78

C
Christopher Dunn 已提交
79
    python doxybuild.py --doxygen=$(which doxygen) --open --with-dot
80

81
See `doxybuild.py --help` for options.
82

I
Iñaki Baz Castillo 已提交
83 84
### Adding a reader/writer test

85
To add a test, you need to create two files in test/data:
86 87 88 89 90 91 92

* 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:

I
Iñaki Baz Castillo 已提交
93
* Each line represents a JSON element of the element tree represented by the
94
  input document.
I
Iñaki Baz Castillo 已提交
95
* Each line has two parts: the path to access the element separated from the
96 97
  element value by `=`. Array and object values are always empty (i.e.
  represented by either `[]` or `{}`).
I
Iñaki Baz Castillo 已提交
98
* Element path `.` represents the root element, and is used to separate object
99 100
  members. `[N]` is used to specify the value of an array element at index `N`.

I
Iñaki Baz Castillo 已提交
101
See the examples `test_complex_01.json` and `test_complex_01.expected` to better understand element paths.
102

I
Iñaki Baz Castillo 已提交
103 104 105
### 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:
106

107 108 109 110 111 112 113 114 115 116 117 118
* `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.
119

120 121 122 123 124 125 126 127
## Using JsonCpp in your project

### Amalgamated source
https://github.com/open-source-parsers/jsoncpp/wiki/Amalgamated

### Other ways
If you have trouble, see the Wiki, or post a question as an Issue.

I
Iñaki Baz Castillo 已提交
128 129
## License

130
See the `LICENSE` file for details. In summary, JsonCpp is licensed under the
131
MIT license, or public domain if desired and recognized in your jurisdiction.