* Introduction: ============= JSON (JavaScript Object Notation) is a lightweight data-interchange format. It can represent integer, real number, string, an ordered sequence of value, and a collection of name/value pairs. JsonCpp is a simple API to manipulate JSON value, handle serialization and unserialization to string. It can also preserve existing comment in unserialization/serialization steps, making it a convenient format to store user input files. Unserialization parsing is user friendly and provides precise error reports. * Building/Testing: ================= JsonCpp uses Scons (http://www.scons.org) as a build system. Scons requires python to be installed (http://www.python.org). You download scons-local distribution from the following url: http://sourceforge.net/project/showfiles.php?group_id=30337&package_id=67375 Unzip it in the directory where you found this README file. scons.py Should be at the same level as README. python scons.py platform=PLTFRM [TARGET] where PLTFRM may be one of: suncc Sun C++ (Solaris) vacpp Visual Age C++ (AIX) mingw msvc6 Microsoft Visual Studio 6 service pack 5-6 msvc70 Microsoft Visual Studio 2002 msvc71 Microsoft Visual Studio 2003 msvc80 Microsoft Visual Studio 2005 linux-gcc Gnu C++ (linux, also reported to work for Mac OS X) adding platform is fairly simple. You need to change the Sconstruct file to do so. and TARGET may be: check: build library and run unit tests. * Running the test manually: ========================== cd test # This will run the Reader/Writer tests python runjsontests.py "path to jsontest.exe" # 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.exe" # This will run the unit tests (mostly Value) python rununittests.py "path to test_lib_json.exe" You can run the tests using valgrind: python rununittests.py --valgrind "path to test_lib_json.exe" * Building the documentation: =========================== Run the python script doxybuild.py from the top directory: python doxybuild.py --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. TESTNAME.expected file format: - 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 (e.g. represented by either [] or {}). - element path: '.' represented 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 test_complex_01.json and test_complex_01.expected to better understand element path. * Understanding reader/writer test output: ======================================== When a test is run, output files are generated aside 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.exe from reading test_complex_01.json - test_complex_01.rewrite: JSON document written by jsontest.exe 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.exe from reading test_complex_01.rewrite. test_complex_01.process-output: jsontest.exe output, typically useful to understand parsing error.