JsonCpp project page Classes Namespace JsonCpp home page

JsonCpp

Introduction

JSON (JavaScript Object Notation) is a lightweight data-interchange format.

Here is an example of JSON data:

{
    "encoding" : "UTF-8",
    "plug-ins" : [
        "python",
        "c++",
        "ruby"
        ],
    "indent" : { "length" : 3, "use_space": true }
}

JsonCpp supports comments as meta-data:

// Configuration options
{
// Default encoding for text
"encoding" : "UTF-8",
// Plug-ins loaded at start-up
"plug-ins" : [
"python",
"c++", // trailing comment
"ruby"
],
// Tab indent size
// (multi-line comment)
"indent" : { /*embedded comment*/ "length" : 3, "use_space": true }
}

Features

  • read and write JSON document
  • attach C++ style comments to element during parsing
  • rewrite JSON document preserving original comments

Notes: Comments used to be supported in JSON but were removed for portability (C like comments are not supported in Python). Since comments are useful in configuration/input file, this feature was preserved.

Code example

Json::Value root; // 'root' will contain the root value after parsing.
std::cin >> root;
// You can also read into a particular sub-value.
std::cin >> root["subtree"];
// Get the value of the member of root named 'encoding',
// and return 'UTF-8' if there is no such member.
std::string encoding = root.get("encoding", "UTF-8" ).asString();
// Get the value of the member of root named 'plug-ins'; return a 'null' value if
// there is no such member.
const Json::Value plugins = root["plug-ins"];
// Iterate over the sequence elements.
for ( int index = 0; index < plugins.size(); ++index )
loadPlugIn( plugins[index].asString() );
// Try other datatypes. Some are auto-convertible to others.
foo::setIndentLength( root["indent"].get("length", 3).asInt() );
foo::setIndentUseSpace( root["indent"].get("use_space", true).asBool() );
// Since Json::Value has an implicit constructor for all value types, it is not
// necessary to explicitly construct the Json::Value object.
root["encoding"] = foo::getCurrentEncoding();
root["indent"]["length"] = foo::getCurrentIndentLength();
root["indent"]["use_space"] = foo::getCurrentIndentUseSpace();
// If you like the defaults, you can insert directly into a stream.
std::cout << root;
// Of course, you can write to `std::ostringstream` if you prefer.
// If desired, remember to add a linefeed and flush.
std::cout << std::endl;
Represents a JSON value.
Definition value.h:193
Value get(ArrayIndex index, const Value &defaultValue) const
If the array contains at least index+1 elements, returns the element value, otherwise returns default...
ArrayIndex size() const
Number of values in array or object.
String asString() const
Embedded zeroes are possible.

Advanced usage

Configure builders to create readers and writers. For configuration, we use our own Json::Value (rather than standard setters/getters) so that we can add features without losing binary-compatibility.

// For convenience, use `writeString()` with a specialized builder.
wbuilder["indentation"] = "\t";
std::string document = Json::writeString(wbuilder, root);
// Here, using a specialized Builder, we discard comments and
// record errors as we parse.
rbuilder["collectComments"] = false;
std::string errs;
bool ok = Json::parseFromStream(rbuilder, std::cin, &root, &errs);
Build a CharReader implementation.
Definition reader.h:288
Build a StreamWriter implementation.
Definition writer.h:89
String writeString(StreamWriter::Factory const &factory, Value const &root)
Write into stringstream, then return string, for convenience.
bool parseFromStream(CharReader::Factory const &, IStream &, Value *root, String *errs)
Consume entire stream and use its begin/end.

Yes, compile-time configuration-checking would be helpful, but Json::Value lets you write and read the builder configuration, which is better! In other words, you can configure your JSON parser using JSON.

CharReaders and StreamWriters are not thread-safe, but they are re-usable.

cfg >> rbuilder.settings_;
std::unique_ptr<Json::CharReader> const reader(rbuilder.newCharReader());
reader->parse(start, stop, &value1, &errs);
// ...
reader->parse(start, stop, &value2, &errs);
// etc.
CharReader * newCharReader() const override
Allocate a CharReader via operator new().
Json::Value settings_
Configuration of this builder.
Definition reader.h:334

Build instructions

The build instructions are located in the file README.md in the top-directory of the project.

The latest version of the source is available in the project's GitHub repository: jsoncpp

What's New?

The description of latest changes can be found in the NEWS wiki .

Related links

Old project links

License

See file LICENSE in the top-directory of the project.

Basically JsonCpp is licensed under MIT license, or public domain if desired and recognized in your jurisdiction.

Author
Baptiste Lepilleur blep@.nosp@m.user.nosp@m.s.sou.nosp@m.rcef.nosp@m.orge..nosp@m.net (originator)
Christopher Dunn cdunn.nosp@m.2001.nosp@m.@gmai.nosp@m.l.co.nosp@m.m (primary maintainer)
Version
We make strong guarantees about binary-compatibility, consistent with the Apache versioning scheme.
See also
version.h