README.md 6.1 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 38
If you wish to install to a directory other than /usr/local, set an environment variable called DESTDIR with the desired path:
    DESTDIR=/path/to/install/dir
39

C
Christopher Dunn 已提交
40
Then,
41

C
Christopher Dunn 已提交
42
    cd jsoncpp/
43 44 45 46
    BUILD_TYPE=debug
    #BUILD_TYPE=release
    LIB_TYPE=shared
    #LIB_TYPE=static
C
Christopher Dunn 已提交
47
    meson --buildtype ${BUILD_TYPE} --default-library ${LIB_TYPE} . build-${LIB_TYPE}
C
Christopher Dunn 已提交
48 49
    #ninja -v -C build-${LIB_TYPE} test # This stopped working on my Mac.
    ninja -v -C build-${LIB_TYPE}
50
    cd build-${LIB_TYPE}
C
Christopher Dunn 已提交
51
    meson test --no-rebuild --print-errorlogs
52
    sudo ninja install
53

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

I
Iñaki Baz Castillo 已提交
57 58
### Running the tests manually

59 60 61 62 63 64 65 66
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
67

68 69 70 71 72 73
    # 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
74

75 76
    # This will run the unit tests (mostly Value)
    python rununittests.py path/to/test_lib_json
77

78 79
    # You can run the tests using valgrind:
    python rununittests.py --valgrind path/to/test_lib_json
80

I
Iñaki Baz Castillo 已提交
81 82
### Building the documentation

83
Run the Python script `doxybuild.py` from the top directory:
84

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

87
See `doxybuild.py --help` for options.
88

I
Iñaki Baz Castillo 已提交
89 90
### Adding a reader/writer test

91
To add a test, you need to create two files in test/data:
92 93 94 95 96 97 98

* 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 已提交
99
* Each line represents a JSON element of the element tree represented by the
100
  input document.
I
Iñaki Baz Castillo 已提交
101
* Each line has two parts: the path to access the element separated from the
102 103
  element value by `=`. Array and object values are always empty (i.e.
  represented by either `[]` or `{}`).
I
Iñaki Baz Castillo 已提交
104
* Element path `.` represents the root element, and is used to separate object
105 106
  members. `[N]` is used to specify the value of an array element at index `N`.

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

I
Iñaki Baz Castillo 已提交
109 110 111
### 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:
112

113 114 115 116 117 118 119 120 121 122 123 124
* `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.
125

126 127 128 129 130
## Using JsonCpp in your project

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

131 132 133
### The Meson Build System
If you are using the [Meson Build System](http://mesonbuild.com), then you can get a wrap file by downloading it from [Meson WrapDB](https://wrapdb.mesonbuild.com/jsoncpp), or simply use `meson wrap install jsoncpp`.

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

I
Iñaki Baz Castillo 已提交
137 138
## License

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