Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 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. |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 7 | |
| 8 | Here is an example of JSON data: |
| 9 | \verbatim |
Christopher Dunn | 948f290 | 2015-01-25 12:19:30 -0600 | [diff] [blame] | 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 |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 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", |
Christopher Dunn | 948f290 | 2015-01-25 12:19:30 -0600 | [diff] [blame] | 30 | "c++", // trailing comment |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 31 | "ruby" |
| 32 | ], |
| 33 | |
| 34 | // Tab indent size |
Christopher Dunn | 948f290 | 2015-01-25 12:19:30 -0600 | [diff] [blame] | 35 | // (multi-line comment) |
| 36 | "indent" : { /*embedded comment*/ "length" : 3, "use_space": true } |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 37 | } |
Christopher Dunn | 948f290 | 2015-01-25 12:19:30 -0600 | [diff] [blame] | 38 | \endcode |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 39 | |
| 40 | \section _features Features |
| 41 | - read and write JSON document |
Christopher Dunn | 35bea41 | 2014-07-05 12:13:37 -0700 | [diff] [blame] | 42 | - attach C++ style comments to element during parsing |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 43 | - rewrite JSON document preserving original comments |
| 44 | |
Christopher Dunn | 948f290 | 2015-01-25 12:19:30 -0600 | [diff] [blame] | 45 | Notes: Comments used to be supported in JSON but were removed for |
Baptiste Lepilleur | e6a7741 | 2010-03-11 21:02:26 +0000 | [diff] [blame] | 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 | |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 52 | \code |
Christopher Dunn | 66a8ba2 | 2015-02-09 01:29:43 -0600 | [diff] [blame^] | 53 | Json::Value root; // 'root' will contain the root value after parsing. |
| 54 | std::cin >> root; // Or see CharReaderBuilder. |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 55 | |
| 56 | // Get the value of the member of root named 'encoding', return 'UTF-8' if there is no |
| 57 | // such member. |
| 58 | std::string encoding = root.get("encoding", "UTF-8" ).asString(); |
| 59 | // Get the value of the member of root named 'encoding', return a 'null' value if |
| 60 | // there is no such member. |
| 61 | const Json::Value plugins = root["plug-ins"]; |
| 62 | for ( int index = 0; index < plugins.size(); ++index ) // Iterates over the sequence elements. |
| 63 | loadPlugIn( plugins[index].asString() ); |
| 64 | |
| 65 | setIndentLength( root["indent"].get("length", 3).asInt() ); |
| 66 | setIndentUseSpace( root["indent"].get("use_space", true).asBool() ); |
| 67 | |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 68 | // Since Json::Value has implicit constructor for all value types, it is not |
Baptiste Lepilleur | e6a7741 | 2010-03-11 21:02:26 +0000 | [diff] [blame] | 69 | // necessary to explicitly construct the Json::Value object: |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 70 | root["encoding"] = getCurrentEncoding(); |
| 71 | root["indent"]["length"] = getCurrentIndentLength(); |
| 72 | root["indent"]["use_space"] = getCurrentIndentUseSpace(); |
| 73 | |
Christopher Dunn | 38042b3 | 2015-01-26 11:23:31 -0600 | [diff] [blame] | 74 | // (NEW IN 1.4.0) |
Christopher Dunn | 66a8ba2 | 2015-02-09 01:29:43 -0600 | [diff] [blame^] | 75 | // To write into a stream with minimal memory overhead, |
Christopher Dunn | c7b39c2 | 2015-01-25 18:45:59 -0600 | [diff] [blame] | 76 | // create a Builder for a StreamWriter. |
Christopher Dunn | 472d29f | 2015-01-26 11:04:03 -0600 | [diff] [blame] | 77 | Json::StreamWriterBuilder builder; |
| 78 | builder.indentation_ = " "; // or whatever you like |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 79 | |
Christopher Dunn | c7b39c2 | 2015-01-25 18:45:59 -0600 | [diff] [blame] | 80 | // Then build a StreamWriter. |
Christopher Dunn | c7b39c2 | 2015-01-25 18:45:59 -0600 | [diff] [blame] | 81 | std::shared_ptr<Json::StreamWriter> writer( |
Christopher Dunn | 9da9f84 | 2015-01-25 19:20:43 -0600 | [diff] [blame] | 82 | builder.newStreamWriter( &std::cout ) ); |
Christopher Dunn | c7b39c2 | 2015-01-25 18:45:59 -0600 | [diff] [blame] | 83 | |
| 84 | // Make a new JSON document for the configuration. Preserve original comments. |
| 85 | writer->write( root ); |
| 86 | |
| 87 | // If you like the defaults, you can insert directly into a stream. |
| 88 | std::cout << root; |
| 89 | |
Christopher Dunn | 28a2091 | 2015-01-26 10:43:39 -0600 | [diff] [blame] | 90 | // If desired, remember to add a linefeed and flush. |
| 91 | std::cout << std::endl; |
| 92 | |
Christopher Dunn | 9da9f84 | 2015-01-25 19:20:43 -0600 | [diff] [blame] | 93 | // Of course, you can write to `std::ostringstream` if you prefer. Or |
| 94 | // use `writeString()` for convenience. |
| 95 | std::string document = Json::writeString( root, builder ); |
| 96 | |
Christopher Dunn | c7b39c2 | 2015-01-25 18:45:59 -0600 | [diff] [blame] | 97 | // You can also read from a stream. This will put the contents of any JSON |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 98 | // stream at a particular sub-value, if you'd like. |
| 99 | std::cin >> root["subtree"]; |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 100 | \endcode |
| 101 | |
Baptiste Lepilleur | a11e47d | 2010-03-12 10:17:46 +0000 | [diff] [blame] | 102 | \section _pbuild Build instructions |
Baptiste Lepilleur | e6a7741 | 2010-03-11 21:02:26 +0000 | [diff] [blame] | 103 | The build instructions are located in the file |
Christopher Dunn | 5a65132 | 2014-07-05 20:44:33 -0700 | [diff] [blame] | 104 | <a HREF="https://github.com/open-source-parsers/jsoncpp/blob/master/README.md">README.md</a> in the top-directory of the project. |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 105 | |
Christopher Dunn | 35bea41 | 2014-07-05 12:13:37 -0700 | [diff] [blame] | 106 | The latest version of the source is available in the project's GitHub repository: |
Christopher Dunn | bef834e | 2014-07-05 19:05:10 -0700 | [diff] [blame] | 107 | <a HREF="https://github.com/open-source-parsers/jsoncpp/"> |
Christopher Dunn | 35bea41 | 2014-07-05 12:13:37 -0700 | [diff] [blame] | 108 | jsoncpp</a> |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 109 | |
Baptiste Lepilleur | 130730f | 2010-03-13 11:14:49 +0000 | [diff] [blame] | 110 | \section _news What's New? |
| 111 | The description of latest changes can be found in |
Christopher Dunn | 5a65132 | 2014-07-05 20:44:33 -0700 | [diff] [blame] | 112 | <a HREF="https://github.com/open-source-parsers/jsoncpp/wiki/NEWS"> |
| 113 | the NEWS wiki |
| 114 | </a>. |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 115 | |
| 116 | \section _rlinks Related links |
| 117 | - <a HREF="http://www.json.org/">JSON</a> Specification and alternate language implementations. |
| 118 | - <a HREF="http://www.yaml.org/">YAML</a> A data format designed for human readability. |
| 119 | - <a HREF="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ</a>. |
| 120 | |
Christopher Dunn | 35bea41 | 2014-07-05 12:13:37 -0700 | [diff] [blame] | 121 | \section _plinks Old project links |
| 122 | - <a href="https://sourceforge.net/projects/jsoncpp/">https://sourceforge.net/projects/jsoncpp/</a> |
| 123 | - <a href="http://jsoncpp.sourceforge.net">http://jsoncpp.sourceforge.net</a> |
| 124 | - <a href="http://sourceforge.net/projects/jsoncpp/files/">http://sourceforge.net/projects/jsoncpp/files/</a> |
| 125 | - <a href="http://jsoncpp.svn.sourceforge.net/svnroot/jsoncpp/trunk/">http://jsoncpp.svn.sourceforge.net/svnroot/jsoncpp/trunk/</a> |
| 126 | - <a href="http://jsoncpp.sourceforge.net/old.html">http://jsoncpp.sourceforge.net/old.html</a> |
| 127 | |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 128 | \section _license License |
Christopher Dunn | bef834e | 2014-07-05 19:05:10 -0700 | [diff] [blame] | 129 | 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. |
Baptiste Lepilleur | 7469f1d | 2010-04-20 21:35:19 +0000 | [diff] [blame] | 130 | |
| 131 | Basically JsonCpp is licensed under MIT license, or public domain if desired |
| 132 | and recognized in your jurisdiction. |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 133 | |
Christopher Dunn | 35bea41 | 2014-07-05 12:13:37 -0700 | [diff] [blame] | 134 | \author Baptiste Lepilleur <blep@users.sourceforge.net> (originator) |
Christopher Dunn | 249fd18 | 2015-02-09 00:46:20 -0600 | [diff] [blame] | 135 | \version \include version |
| 136 | \sa version.h |
Christopher Dunn | e0d7224 | 2007-06-14 17:58:59 +0000 | [diff] [blame] | 137 | */ |