blob: 0954974da7ff6adf4df60a76ca0d3a58edccfe3c [file] [log] [blame]
Christopher Dunne0d72242007-06-14 17:58:59 +00001/**
2\mainpage
3\section _intro Introduction
4
5<a HREF="http://www.json.org/">JSON (JavaScript Object Notation)</a>
6 is a lightweight data-interchange format.
Christopher Dunne0d72242007-06-14 17:58:59 +00007
8Here is an example of JSON data:
9\verbatim
Christopher Dunn948f2902015-01-25 12:19:30 -060010{
11 "encoding" : "UTF-8",
12 "plug-ins" : [
13 "python",
14 "c++",
15 "ruby"
16 ],
17 "indent" : { "length" : 3, "use_space": true }
18}
19\endverbatim
20<b>JsonCpp</b> supports comments as <i>meta-data</i>:
21\code
Christopher Dunne0d72242007-06-14 17:58:59 +000022// Configuration options
23{
24 // Default encoding for text
25 "encoding" : "UTF-8",
26
27 // Plug-ins loaded at start-up
28 "plug-ins" : [
29 "python",
Christopher Dunn948f2902015-01-25 12:19:30 -060030 "c++", // trailing comment
Christopher Dunne0d72242007-06-14 17:58:59 +000031 "ruby"
32 ],
33
34 // Tab indent size
Christopher Dunn948f2902015-01-25 12:19:30 -060035 // (multi-line comment)
36 "indent" : { /*embedded comment*/ "length" : 3, "use_space": true }
Christopher Dunne0d72242007-06-14 17:58:59 +000037}
Christopher Dunn948f2902015-01-25 12:19:30 -060038\endcode
Christopher Dunne0d72242007-06-14 17:58:59 +000039
40\section _features Features
41- read and write JSON document
Christopher Dunn35bea412014-07-05 12:13:37 -070042- attach C++ style comments to element during parsing
Christopher Dunne0d72242007-06-14 17:58:59 +000043- rewrite JSON document preserving original comments
44
Christopher Dunn948f2902015-01-25 12:19:30 -060045Notes: Comments used to be supported in JSON but were removed for
Baptiste Lepilleure6a77412010-03-11 21:02:26 +000046portability (C like comments are not supported in Python). Since
47comments are useful in configuration/input file, this feature was
48preserved.
49
50\section _example Code example
51
Christopher Dunne0d72242007-06-14 17:58:59 +000052\code
Christopher Dunn948f2902015-01-25 12:19:30 -060053Json::Value root; // will contain the root value after parsing.
Christopher Dunne0d72242007-06-14 17:58:59 +000054Json::Reader reader;
55bool parsingSuccessful = reader.parse( config_doc, root );
56if ( !parsingSuccessful )
57{
58 // report to the user the failure and their locations in the document.
59 std::cout << "Failed to parse configuration\n"
Baptiste Lepilleurb2e8ccc2011-05-01 16:27:55 +000060 << reader.getFormattedErrorMessages();
Christopher Dunne0d72242007-06-14 17:58:59 +000061 return;
62}
63
64// Get the value of the member of root named 'encoding', return 'UTF-8' if there is no
65// such member.
66std::string encoding = root.get("encoding", "UTF-8" ).asString();
67// Get the value of the member of root named 'encoding', return a 'null' value if
68// there is no such member.
69const Json::Value plugins = root["plug-ins"];
70for ( int index = 0; index < plugins.size(); ++index ) // Iterates over the sequence elements.
71 loadPlugIn( plugins[index].asString() );
72
73setIndentLength( root["indent"].get("length", 3).asInt() );
74setIndentUseSpace( root["indent"].get("use_space", true).asBool() );
75
Christopher Dunne0d72242007-06-14 17:58:59 +000076// Since Json::Value has implicit constructor for all value types, it is not
Baptiste Lepilleure6a77412010-03-11 21:02:26 +000077// necessary to explicitly construct the Json::Value object:
Christopher Dunne0d72242007-06-14 17:58:59 +000078root["encoding"] = getCurrentEncoding();
79root["indent"]["length"] = getCurrentIndentLength();
80root["indent"]["use_space"] = getCurrentIndentUseSpace();
81
Christopher Dunn38042b32015-01-26 11:23:31 -060082// (NEW IN 1.4.0)
Christopher Dunnc7b39c22015-01-25 18:45:59 -060083// To write into a steam with minimal memory overhead,
84// create a Builder for a StreamWriter.
Christopher Dunn472d29f2015-01-26 11:04:03 -060085Json::StreamWriterBuilder builder;
86builder.indentation_ = " "; // or whatever you like
Christopher Dunne0d72242007-06-14 17:58:59 +000087
Christopher Dunnc7b39c22015-01-25 18:45:59 -060088// Then build a StreamWriter.
Christopher Dunnc7b39c22015-01-25 18:45:59 -060089std::shared_ptr<Json::StreamWriter> writer(
Christopher Dunn9da9f842015-01-25 19:20:43 -060090 builder.newStreamWriter( &std::cout ) );
Christopher Dunnc7b39c22015-01-25 18:45:59 -060091
92// Make a new JSON document for the configuration. Preserve original comments.
93writer->write( root );
94
95// If you like the defaults, you can insert directly into a stream.
96std::cout << root;
97
Christopher Dunn28a20912015-01-26 10:43:39 -060098// If desired, remember to add a linefeed and flush.
99std::cout << std::endl;
100
Christopher Dunn9da9f842015-01-25 19:20:43 -0600101// Of course, you can write to `std::ostringstream` if you prefer. Or
102// use `writeString()` for convenience.
103std::string document = Json::writeString( root, builder );
104
Christopher Dunnc7b39c22015-01-25 18:45:59 -0600105// You can also read from a stream. This will put the contents of any JSON
Christopher Dunne0d72242007-06-14 17:58:59 +0000106// stream at a particular sub-value, if you'd like.
107std::cin >> root["subtree"];
Christopher Dunne0d72242007-06-14 17:58:59 +0000108\endcode
109
Baptiste Lepilleura11e47d2010-03-12 10:17:46 +0000110\section _pbuild Build instructions
Baptiste Lepilleure6a77412010-03-11 21:02:26 +0000111The build instructions are located in the file
Christopher Dunn5a651322014-07-05 20:44:33 -0700112<a HREF="https://github.com/open-source-parsers/jsoncpp/blob/master/README.md">README.md</a> in the top-directory of the project.
Christopher Dunne0d72242007-06-14 17:58:59 +0000113
Christopher Dunn35bea412014-07-05 12:13:37 -0700114The latest version of the source is available in the project's GitHub repository:
Christopher Dunnbef834e2014-07-05 19:05:10 -0700115<a HREF="https://github.com/open-source-parsers/jsoncpp/">
Christopher Dunn35bea412014-07-05 12:13:37 -0700116jsoncpp</a>
Christopher Dunne0d72242007-06-14 17:58:59 +0000117
Baptiste Lepilleur130730f2010-03-13 11:14:49 +0000118\section _news What's New?
119The description of latest changes can be found in
Christopher Dunn5a651322014-07-05 20:44:33 -0700120<a HREF="https://github.com/open-source-parsers/jsoncpp/wiki/NEWS">
121 the NEWS wiki
122</a>.
Christopher Dunne0d72242007-06-14 17:58:59 +0000123
124\section _rlinks Related links
125- <a HREF="http://www.json.org/">JSON</a> Specification and alternate language implementations.
126- <a HREF="http://www.yaml.org/">YAML</a> A data format designed for human readability.
127- <a HREF="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ</a>.
128
Christopher Dunn35bea412014-07-05 12:13:37 -0700129\section _plinks Old project links
130- <a href="https://sourceforge.net/projects/jsoncpp/">https://sourceforge.net/projects/jsoncpp/</a>
131- <a href="http://jsoncpp.sourceforge.net">http://jsoncpp.sourceforge.net</a>
132- <a href="http://sourceforge.net/projects/jsoncpp/files/">http://sourceforge.net/projects/jsoncpp/files/</a>
133- <a href="http://jsoncpp.svn.sourceforge.net/svnroot/jsoncpp/trunk/">http://jsoncpp.svn.sourceforge.net/svnroot/jsoncpp/trunk/</a>
134- <a href="http://jsoncpp.sourceforge.net/old.html">http://jsoncpp.sourceforge.net/old.html</a>
135
Christopher Dunne0d72242007-06-14 17:58:59 +0000136\section _license License
Christopher Dunnbef834e2014-07-05 19:05:10 -0700137See file <a href="https://github.com/open-source-parsers/jsoncpp/blob/master/LICENSE"><code>LICENSE</code></a> in the top-directory of the project.
Baptiste Lepilleur7469f1d2010-04-20 21:35:19 +0000138
139Basically JsonCpp is licensed under MIT license, or public domain if desired
140and recognized in your jurisdiction.
Christopher Dunne0d72242007-06-14 17:58:59 +0000141
Christopher Dunn35bea412014-07-05 12:13:37 -0700142\author Baptiste Lepilleur <blep@users.sourceforge.net> (originator)
Christopher Dunn249fd182015-02-09 00:46:20 -0600143\version \include version
144\sa version.h
Christopher Dunne0d72242007-06-14 17:58:59 +0000145*/