Home | History | Annotate | Download | only in doc 
      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 It can represent integer, real number, string, an ordered sequence of value, and
      8 a collection of name/value pairs.
      9 
     10 Here is an example of JSON data:
     11 \verbatim
     12 // Configuration options
     13 {
     14     // Default encoding for text
     15     "encoding" : "UTF-8",
     16 
     17     // Plug-ins loaded at start-up
     18     "plug-ins" : [
     19         "python",
     20         "c++",
     21         "ruby"
     22         ],
     23 
     24     // Tab indent size
     25     "indent" : { "length" : 3, "use_space": true }
     26 }
     27 \endverbatim
     28 
     29 \section _features Features
     30 - read and write JSON document
     31 - attach C and C++ style comments to element during parsing
     32 - rewrite JSON document preserving original comments
     33 
     34 Notes: Comments used to be supported in JSON but where removed for
     35 portability (C like comments are not supported in Python). Since
     36 comments are useful in configuration/input file, this feature was
     37 preserved.
     38 
     39 \section _example Code example
     40 
     41 \code
     42 Json::Value root;   // will contains the root value after parsing.
     43 Json::Reader reader;
     44 bool parsingSuccessful = reader.parse( config_doc, root );
     45 if ( !parsingSuccessful )
     46 {
     47     // report to the user the failure and their locations in the document.
     48     std::cout  << "Failed to parse configuration\n"
     49                << reader.getFormattedErrorMessages();
     50     return;
     51 }
     52 
     53 // Get the value of the member of root named 'encoding', return 'UTF-8' if there is no
     54 // such member.
     55 std::string encoding = root.get("encoding", "UTF-8" ).asString();
     56 // Get the value of the member of root named 'encoding', return a 'null' value if
     57 // there is no such member.
     58 const Json::Value plugins = root["plug-ins"];
     59 for ( int index = 0; index < plugins.size(); ++index )  // Iterates over the sequence elements.
     60    loadPlugIn( plugins[index].asString() );
     61 
     62 setIndentLength( root["indent"].get("length", 3).asInt() );
     63 setIndentUseSpace( root["indent"].get("use_space", true).asBool() );
     64 
     65 // ...
     66 // At application shutdown to make the new configuration document:
     67 // Since Json::Value has implicit constructor for all value types, it is not
     68 // necessary to explicitly construct the Json::Value object:
     69 root["encoding"] = getCurrentEncoding();
     70 root["indent"]["length"] = getCurrentIndentLength();
     71 root["indent"]["use_space"] = getCurrentIndentUseSpace();
     72 
     73 Json::StyledWriter writer;
     74 // Make a new JSON document for the configuration. Preserve original comments.
     75 std::string outputConfig = writer.write( root );
     76 
     77 // You can also use streams.  This will put the contents of any JSON
     78 // stream at a particular sub-value, if you'd like.
     79 std::cin >> root["subtree"];
     80 
     81 // And you can write to a stream, using the StyledWriter automatically.
     82 std::cout << root;
     83 \endcode
     84 
     85 \section _pbuild Build instructions
     86 The build instructions are located in the file
     87 <a HREF="README.txt">README.txt</a> in the top-directory of the project.
     88 
     89 Permanent link to the latest revision of the file in subversion:
     90 <a HREF="http://jsoncpp.svn.sourceforge.net/viewvc/jsoncpp/trunk/jsoncpp/README.txt?view=markup">latest README.txt</a>
     91 
     92 \section _pdownload Download
     93 The sources can be downloaded from
     94 <a HREF="http://sourceforge.net/projects/jsoncpp/files/">SourceForge download page</a>.
     95 
     96 The latest version of the source is available in the project's subversion repository:
     97 <a HREF="http://jsoncpp.svn.sourceforge.net/svnroot/jsoncpp/trunk/">
     98 http://jsoncpp.svn.sourceforge.net/svnroot/jsoncpp/trunk/</a>
     99 
    100 To checkout the source, see the following
    101 <a HREF="http://sourceforge.net/scm/?type=svn&group_id=144446">instructions</a>.
    102 
    103 \section _news What's New?
    104 The description of latest changes can be found in
    105 <a HREF="NEWS.txt">NEWS.txt</a> in the top-directory of the project.
    106 
    107 Permanent link to the latest revision of the file in subversion:
    108 <a HREF="http://svn.sourceforge.net/viewcvs.cgi/jsoncpp/README.txt?view=markup">latest NEWS.txt</a>
    109 
    110 \section _plinks Project links
    111 - <a HREF="http://jsoncpp.sourceforge.net">json-cpp home</a>
    112 - <a HREF="http://www.sourceforge.net/projects/jsoncpp/">json-cpp sourceforge project</a>
    113 
    114 \section _rlinks Related links
    115 - <a HREF="http://www.json.org/">JSON</a> Specification and alternate language implementations.
    116 - <a HREF="http://www.yaml.org/">YAML</a> A data format designed for human readability.
    117 - <a HREF="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ</a>.
    118 
    119 \section _license License
    120 See file <a HREF="LICENSE">LICENSE</a> in the top-directory of the project.
    121 
    122 Basically JsonCpp is licensed under MIT license, or public domain if desired
    123 and recognized in your jurisdiction.
    124 
    125 \author Baptiste Lepilleur <blep (at) users.sourceforge.net>
    126 */
    127