blob: 37ba0e8d3730af9460c2598c15d3ae8c6696d46b [file] [log] [blame]
* 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
added by Ramji - 10-20-2011.
* Installation:
========================================
- Upon successful building/testing completion, there should be a "libs" dir
under the json src dir.
There should be 2 json libraries located under the "libs" dir.
For example, on my box, running
"ls jsoncpp-src-0.5.0/libs/linux-gcc-3.4.3/"
shows
libjson_linux-gcc-3.4.3_libmt.a libjson_linux-gcc-3.4.3_libmt.so
- Create a json installation dir on the box where json is to be installed.
- Copy the "libs" dir and "include" dir recursively to this json installation
dir.
* Testing the installed json:
========================================
- Use the "main.cpp" from the "test" subdir and build it using the installed
json include files and the installed json libs.
A sample command line format for compilation would be
"g++ -g main.cpp -I <location of json include> <location of
libjson_linux-gcc-3.4.3_libmt.a>"
- Run the resulting binary "a.out" against an input json file, which looks
as follows.
-------------------------
{
"glossary": {
"title": "example glossary",
"GlossDiv": {
"title": "S",
"GlossList": {
"GlossEntry": {
"ID": "SGML",
"SortAs": "SGML",
"GlossTerm": "Standard Generalized
Marku p Language",
"Acronym": "SGML",
"Abbrev": "ISO 8879:1986",
"GlossDef": {
"para": "A meta-markup language, used to create markup
l anguages such as DocBook.",
"GlossSeeAlso": ["GML", "XML"]
},
"GlossSee": "markup"
}
}
}
}
}
----------------------------------------
- The output json file would look as follows.
.={}
.glossary={}
.glossary.GlossDiv={}
.glossary.GlossDiv.GlossList={}
.glossary.GlossDiv.GlossList.GlossEntry={}
.glossary.GlossDiv.GlossList.GlossEntry.Abbrev="ISO 8879:1986"
.glossary.GlossDiv.GlossList.GlossEntry.Acronym="SGML"
.glossary.GlossDiv.GlossList.GlossEntry.GlossDef={}
.glossary.GlossDiv.GlossList.GlossEntry.GlossDef.GlossSeeAlso=[]
.glossary.GlossDiv.GlossList.GlossEntry.GlossDef.GlossSeeAlso[0]="GML"
.glossary.GlossDiv.GlossList.GlossEntry.GlossDef.GlossSeeAlso[1]="XML"
.glossary.GlossDiv.GlossList.GlossEntry.GlossDef.para="A meta-markup language,
used to create markup languages such as DocBook."
.glossary.GlossDiv.GlossList.GlossEntry.GlossSee="markup"
.glossary.GlossDiv.GlossList.GlossEntry.GlossTerm="Standard Generalized Markup
Language"
.glossary.GlossDiv.GlossList.GlossEntry.ID="SGML"
.glossary.GlossDiv.GlossList.GlossEntry.SortAs="SGML"
.glossary.GlossDiv.title="S"
.glossary.title="example glossary"
---------------------------------------------