1f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III* Introduction: 2f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III ============= 3f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 4f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIJSON (JavaScript Object Notation) is a lightweight data-interchange format. 5f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIIt can represent integer, real number, string, an ordered sequence of 6f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIvalue, and a collection of name/value pairs. 7f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 8f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIJsonCpp (http://jsoncpp.sourceforge.net/) is a simple API to manipulate 9f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIJSON value, handle serialization and unserialization to string. 10f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 11f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIIt can also preserve existing comment in unserialization/serialization steps, 12f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIImaking it a convenient format to store user input files. 13f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 14f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIUnserialization parsing is user friendly and provides precise error reports. 15f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 16f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 17f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III* Building/Testing: 18f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III ================= 19f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 20f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIJsonCpp uses Scons (http://www.scons.org) as a build system. Scons requires 21f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIpython to be installed (http://www.python.org). 22f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 23f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIYou download scons-local distribution from the following url: 24f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIhttp://sourceforge.net/projects/scons/files/scons-local/1.2.0/ 25f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 26f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIUnzip it in the directory where you found this README file. scons.py Should be 27f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIat the same level as README. 28f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 29f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIpython scons.py platform=PLTFRM [TARGET] 30f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIwhere PLTFRM may be one of: 31f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III suncc Sun C++ (Solaris) 32f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III vacpp Visual Age C++ (AIX) 33f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III mingw 34f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III msvc6 Microsoft Visual Studio 6 service pack 5-6 35f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III msvc70 Microsoft Visual Studio 2002 36f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III msvc71 Microsoft Visual Studio 2003 37f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III msvc80 Microsoft Visual Studio 2005 38f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III msvc90 Microsoft Visual Studio 2008 39f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III linux-gcc Gnu C++ (linux, also reported to work for Mac OS X) 40f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 41f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIINotes: if you are building with Microsoft Visual Studio 2008, you need to 42f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIsetup the environment by running vcvars32.bat (e.g. MSVC 2008 command prompt) 43f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIbefore running scons. 44f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 45f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIAdding platform is fairly simple. You need to change the Sconstruct file 46f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIto do so. 47f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 48f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIand TARGET may be: 49f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III check: build library and run unit tests. 50f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 51f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 52f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III* Running the test manually: 53f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III ========================== 54f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 55f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIINotes that test can be run by scons using the 'check' target (see above). 56f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 57f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIYou need to run test manually only if you are troubleshooting an issue. 58f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 59f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIIn the instruction below, replace "path to jsontest.exe" with the path 60f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIof the 'jsontest' executable that was compiled on your platform. 61f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 62f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIcd test 63f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III# This will run the Reader/Writer tests 64f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIpython runjsontests.py "path to jsontest.exe" 65f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 66f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III# This will run the Reader/Writer tests, using JSONChecker test suite 67f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III# (http://www.json.org/JSON_checker/). 68f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III# Notes: not all tests pass: JsonCpp is too lenient (for example, 69f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III# it allows an integer to start with '0'). The goal is to improve 70f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III# strict mode parsing to get all tests to pass. 71f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIpython runjsontests.py --with-json-checker "path to jsontest.exe" 72f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 73f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III# This will run the unit tests (mostly Value) 74f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIpython rununittests.py "path to test_lib_json.exe" 75f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 76f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIYou can run the tests using valgrind: 77f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIpython rununittests.py --valgrind "path to test_lib_json.exe" 78f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 79f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 80f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III* Building the documentation: 81f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III =========================== 82f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 83f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIRun the python script doxybuild.py from the top directory: 84f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 85f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIpython doxybuild.py --open --with-dot 86f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 87f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIISee doxybuild.py --help for options. 88f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 89f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIINotes that the documentation is also available for download as a tarball. 90f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIThe documentation of the latest release is available online at: 91f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIhttp://jsoncpp.sourceforge.net/ 92f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 93f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III* Generating amalgamated source and header 94f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III ======================================== 95f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 96f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIJsonCpp is provided with a script to generate a single header and a single 97f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIsource file to ease inclusion in an existing project. 98f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 99f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIThe amalgamated source can be generated at any time by running the following 100f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIcommand from the top-directory (requires python 2.6): 101f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 102f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIpython amalgamate.py 103f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 104f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIIt is possible to specify header name. See -h options for detail. By default, 105f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIthe following files are generated: 106f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- dist/jsoncpp.cpp: source file that need to be added to your project 107f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- dist/json/json.h: header file corresponding to use in your project. It is 108f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIequivalent to including json/json.h in non-amalgamated source. This header 109f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIonly depends on standard headers. 110f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- dist/json/json-forwards.h: header the provides forward declaration 111f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIof all JsonCpp types. This typically what should be included in headers to 112f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIspeed-up compilation. 113f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 114f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIThe amalgamated sources are generated by concatenating JsonCpp source in the 115f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIcorrect order and defining macro JSON_IS_AMALGAMATION to prevent inclusion 116f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIof other headers. 117f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 118f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III* Using json-cpp in your project: 119f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III =============================== 120f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 121f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIinclude/ should be added to your compiler include path. jsoncpp headers 122f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIshould be included as follow: 123f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 124f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III#include <json/json.h> 125f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 126f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 127f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III* Adding a reader/writer test: 128f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III ============================ 129f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 130f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIITo add a test, you need to create two files in test/data: 131f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- a TESTNAME.json file, that contains the input document in JSON format. 132f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- a TESTNAME.expected file, that contains a flatened representation of 133f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III the input document. 134f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 135f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIITESTNAME.expected file format: 136f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- each line represents a JSON element of the element tree represented 137f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III by the input document. 138f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- each line has two parts: the path to access the element separated from 139f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III the element value by '='. Array and object values are always empty 140f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III (e.g. represented by either [] or {}). 141f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- element path: '.' represented the root element, and is used to separate 142f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III object members. [N] is used to specify the value of an array element 143f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III at index N. 144f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIISee test_complex_01.json and test_complex_01.expected to better understand 145f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIelement path. 146f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 147f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 148f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III* Understanding reader/writer test output: 149f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III ======================================== 150f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 151f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIWhen a test is run, output files are generated aside the input test files. 152f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIBelow is a short description of the content of each file: 153f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 154f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- test_complex_01.json: input JSON document 155f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- test_complex_01.expected: flattened JSON element tree used to check if 156f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III parsing was corrected. 157f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 158f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- test_complex_01.actual: flattened JSON element tree produced by 159f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III jsontest.exe from reading test_complex_01.json 160f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- test_complex_01.rewrite: JSON document written by jsontest.exe using the 161f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III Json::Value parsed from test_complex_01.json and serialized using 162f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III Json::StyledWritter. 163f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III- test_complex_01.actual-rewrite: flattened JSON element tree produced by 164f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III jsontest.exe from reading test_complex_01.rewrite. 165f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIItest_complex_01.process-output: jsontest.exe output, typically useful to 166f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III understand parsing error. 167f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 168f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III* License 169f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III ======= 170f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 171f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIISee file LICENSE for details. Basically JsonCpp is licensed under 172f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins IIIMIT license, or public domain if desired and recognized in your jurisdiction. 173f59fb0e83fd0a4b41700d3f5eebdc8d21b173c2eLeon Scroggins III 174