=============
KJSONPlusPlus
=============

A clean, elegant and portable JavaScript Object Notation library for C++.
This is a C++ library enabling programmers to generate and consume JSON data.

=========
Features:
=========

* The library is fully compliant with the JSON standard.
	See http://www.json.org/
* The library enables extended data types in addition to the standard ones:
	- DateTime in ISO-8601 format.
	- Arbitrary binary data encoded in Base85 format.
	These extended data types are encoded inside the string standard data type.
	They are automatically recognized as extended types by the library. This
	makes the data generated by this library always standard-compliant. If the
	generated data is consumed by another JSON parser the data will still be
	readable and well-formatted.
* The library is standalone. It only depends on C++ STL and C runtime.
* The library's JSON scanner is automatically generated via RE2C.
	See http://re2c.org/
	This delivers a very fast and flexible JSON scanner.
* The library's JSON parser is automatically generated via Bison.
	See http://www.gnu.org/s/bison/
	See http://gnuwin32.sourceforge.net/
	This enables a very clean JSON parser.
* The library is hierarchically divided into modules of classes that further
	localize responsibilities.
* JSON data source can be a file or a memory block or virtually any
	character-based data source.
* In case of JSON format errors in the source data, the library parser reports
	the nature and location of errors: line/column of the error and
	a description of what was wrong.
* JSON data can be encoded in UTF-8 or in Unicode. Internally all string data
	is encoded in Unicode. Conversions happen only when needed, and happen
	automatically.
* JSON data is loaded from the source into a hierarchy of objects in memory.
	The representation is based on native C++ objects and primitive variables.
	Representation persistence (saving back to a file) is fully supported and
	happens via a single method call.
* Dynamic exploration and navigation in JSON data is possible. No preliminary
	knowledge on data structure is required in order to use the data. However,
	preliminary knowledge of data structure can speed up data consumption
	and lower its complexity.
* A JSON value can be treated generically as a value, or specifically given its
	data type. i.e. An object can be treated merely as a value when it is to be
	deleted, and can be treated an an object value when one wants to explore
	its child values.
* Many data conversions are automatically supported by the native objects in
	memory. e.g. String value to integer, DataTime value to String,...
* Generated JSON data is well-formatted and spaced and indented as required.
	This allows for much better human-readability, but it reduces the parsing
	performance a bit.
* The library does not use C++ exceptions. It reports errors via errno and
	returns values that indicate errno values.

============
Limitations:
============

* Progressive loading of JSON data is not supported.
* ISO-8601 date & time format is not fully supported. Only the most common
	form is supported. This should be enough for most usage cases.
* No support for XPath-like access protocol.
	
========
Licence:
========
Copyright 2011-2011 Koutheir Attouchi. All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY KOUTHEIR ATTOUCHI ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL KOUTHEIR ATTOUCHI OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those
of the authors and should not be interpreted as representing official policies,
either expressed or implied, of Koutheir Attouchi.