1/**
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.
7
8Here is an example of JSON data:
9\verbatim
10{
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
22// 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",
30        "c++",  // trailing comment
31        "ruby"
32        ],
33
34    // Tab indent size
35    // (multi-line comment)
36    "indent" : { /*embedded comment*/ "length" : 3, "use_space": true }
37}
38\endcode
39
40\section _features Features
41- read and write JSON document
42- attach C++ style comments to element during parsing
43- rewrite JSON document preserving original comments
44
45Notes: Comments used to be supported in JSON but were removed for
46portability (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
52\code
53Json::Value root;   // 'root' will contain the root value after parsing.
54std::cin >> root;
55
56// You can also read into a particular sub-value.
57std::cin >> root["subtree"];
58
59// Get the value of the member of root named 'encoding',
60// and return 'UTF-8' if there is no such member.
61std::string encoding = root.get("encoding", "UTF-8" ).asString();
62
63// Get the value of the member of root named 'plug-ins'; return a 'null' value if
64// there is no such member.
65const Json::Value plugins = root["plug-ins"];
66
67// Iterate over the sequence elements.
68for ( int index = 0; index < plugins.size(); ++index )
69   loadPlugIn( plugins[index].asString() );
70
71// Try other datatypes. Some are auto-convertible to others.
72foo::setIndentLength( root["indent"].get("length", 3).asInt() );
73foo::setIndentUseSpace( root["indent"].get("use_space", true).asBool() );
74
75// Since Json::Value has an implicit constructor for all value types, it is not
76// necessary to explicitly construct the Json::Value object.
77root["encoding"] = foo::getCurrentEncoding();
78root["indent"]["length"] = foo::getCurrentIndentLength();
79root["indent"]["use_space"] = foo::getCurrentIndentUseSpace();
80
81// If you like the defaults, you can insert directly into a stream.
82std::cout << root;
83// Of course, you can write to `std::ostringstream` if you prefer.
84
85// If desired, remember to add a linefeed and flush.
86std::cout << std::endl;
87\endcode
88
89\section _advanced Advanced usage
90
91Configure *builders* to create *readers* and *writers*. For
92configuration, we use our own `Json::Value` (rather than
93standard setters/getters) so that we can add
94features without losing binary-compatibility.
95
96\code
97// For convenience, use `writeString()` with a specialized builder.
98Json::StreamWriterBuilder wbuilder;
99wbuilder["indentation"] = "\t";
100std::string document = Json::writeString(wbuilder, root);
101
102// Here, using a specialized Builder, we discard comments and
103// record errors as we parse.
104Json::CharReaderBuilder rbuilder;
105rbuilder["collectComments"] = false;
106std::string errs;
107bool ok = Json::parseFromStream(rbuilder, std::cin, &root, &errs);
108\endcode
109
110Yes, compile-time configuration-checking would be helpful,
111but `Json::Value` lets you
112write and read the builder configuration, which is better! In other words,
113you can configure your JSON parser using JSON.
114
115CharReaders and StreamWriters are not thread-safe, but they are re-usable.
116\code
117Json::CharReaderBuilder rbuilder;
118cfg >> rbuilder.settings_;
119std::unique_ptr<Json::CharReader> const reader(rbuilder.newCharReader());
120reader->parse(start, stop, &value1, &errs);
121// ...
122reader->parse(start, stop, &value2, &errs);
123// etc.
124\endcode
125
126\section _pbuild Build instructions
127The build instructions are located in the file
128<a HREF="https://github.com/open-source-parsers/jsoncpp/blob/master/README.md">README.md</a> in the top-directory of the project.
129
130The latest version of the source is available in the project's GitHub repository:
131<a HREF="https://github.com/open-source-parsers/jsoncpp/">
132jsoncpp</a>
133
134\section _news What's New?
135The description of latest changes can be found in
136<a HREF="https://github.com/open-source-parsers/jsoncpp/wiki/NEWS">
137  the NEWS wiki
138</a>.
139
140\section _rlinks Related links
141- <a HREF="http://www.json.org/">JSON</a> Specification and alternate language implementations.
142- <a HREF="http://www.yaml.org/">YAML</a> A data format designed for human readability.
143- <a HREF="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ</a>.
144
145\section _plinks Old project links
146- <a href="https://sourceforge.net/projects/jsoncpp/">https://sourceforge.net/projects/jsoncpp/</a>
147- <a href="http://jsoncpp.sourceforge.net">http://jsoncpp.sourceforge.net</a>
148- <a href="http://sourceforge.net/projects/jsoncpp/files/">http://sourceforge.net/projects/jsoncpp/files/</a>
149- <a href="http://jsoncpp.svn.sourceforge.net/svnroot/jsoncpp/trunk/">http://jsoncpp.svn.sourceforge.net/svnroot/jsoncpp/trunk/</a>
150- <a href="http://jsoncpp.sourceforge.net/old.html">http://jsoncpp.sourceforge.net/old.html</a>
151
152\section _license License
153See file <a href="https://github.com/open-source-parsers/jsoncpp/blob/master/LICENSE"><code>LICENSE</code></a> in the top-directory of the project.
154
155Basically JsonCpp is licensed under MIT license, or public domain if desired
156and recognized in your jurisdiction.
157
158\author Baptiste Lepilleur <blep@users.sourceforge.net> (originator)
159\author Christopher Dunn <cdunn2001@gmail.com> (primary maintainer)
160\version \include version
161We make strong guarantees about binary-compatibility, consistent with
162<a href="http://apr.apache.org/versioning.html">the Apache versioning scheme</a>.
163\sa version.h
164*/
165