47efc8a3576cf454b5caf25582a384cd50b85369
[jsoncpp.git] / doc / jsoncpp.dox
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
8 Here 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
45 Notes: Comments used to be supported in JSON but were removed for
46 portability (C like comments are not supported in Python). Since
47 comments are useful in configuration/input file, this feature was
48 preserved.
49
50 \section _example Code example
51
52 \code
53 Json::Value root;   // 'root' will contain the root value after parsing.
54 std::cin >> root;
55
56 // You can also read into a particular sub-value.
57 std::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.
61 std::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.
65 const Json::Value plugins = root["plug-ins"];
66
67 // Iterate over the sequence elements.
68 for ( int index = 0; index < plugins.size(); ++index )
69    loadPlugIn( plugins[index].asString() );
70    
71 // Try other datatypes. Some are auto-convertible to others.
72 foo::setIndentLength( root["indent"].get("length", 3).asInt() );
73 foo::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.
77 root["encoding"] = foo::getCurrentEncoding();
78 root["indent"]["length"] = foo::getCurrentIndentLength();
79 root["indent"]["use_space"] = foo::getCurrentIndentUseSpace();
80
81 // If you like the defaults, you can insert directly into a stream.
82 std::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.
86 std::cout << std::endl;
87 \endcode
88
89 \section _advanced Advanced usage
90
91 Configure *builders* to create *readers* and *writers*. For
92 configuration, we use our own `Json::Value` (rather than
93 standard setters/getters) so that we can add
94 features without losing binary-compatibility.
95
96 \code
97 // For convenience, use `writeString()` with a specialized builder.
98 Json::StreamWriterBuilder wbuilder;
99 wbuilder["indentation"] = "\t";
100 std::string document = Json::writeString(wbuilder, root);
101
102 // Here, using a specialized Builder, we discard comments and
103 // record errors as we parse.
104 Json::CharReaderBuilder rbuilder;
105 rbuilder["collectComments"] = false;
106 std::string errs;
107 bool ok = Json::parseFromStream(rbuilder, std::cin, &root, &errs);
108 \endcode
109
110 Yes, compile-time configuration-checking would be helpful,
111 but `Json::Value` lets you
112 write and read the builder configuration, which is better! In other words,
113 you can configure your JSON parser using JSON.
114
115 CharReaders and StreamWriters are not thread-safe, but they are re-usable.
116 \code
117 Json::CharReaderBuilder rbuilder;
118 cfg >> rbuilder.settings_;
119 std::unique_ptr<Json::CharReader> const reader(rbuilder.newCharReader());
120 reader->parse(start, stop, &value1, &errs);
121 // ...
122 reader->parse(start, stop, &value2, &errs);
123 // etc.
124 \endcode
125
126 \section _pbuild Build instructions
127 The 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
130 The latest version of the source is available in the project's GitHub repository:
131 <a HREF="https://github.com/open-source-parsers/jsoncpp/">
132 jsoncpp</a>
133
134 \section _news What's New?
135 The 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
153 See 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
155 Basically JsonCpp is licensed under MIT license, or public domain if desired 
156 and 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
161 We 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 */