Merge pull request #162 from cdunn2001/master

Deprecate the new Builders.

doc/jsoncpp.dox

@@ -51,7 +51,7 @@ preserved.
 
 \code
 Json::Value root;   // 'root' will contain the root value after parsing.
-std::cin >> root;   // Or see CharReaderBuilder.
+std::cin >> root;
 
 // Get the value of the member of root named 'encoding', return 'UTF-8' if there is no
 // such member.
@@ -71,32 +71,36 @@ root["encoding"] = getCurrentEncoding();
 root["indent"]["length"] = getCurrentIndentLength();
 root["indent"]["use_space"] = getCurrentIndentUseSpace();
 
-// (NEW IN 1.4.0)
-// To write into a stream with minimal memory overhead,
-// create a Builder for a StreamWriter.
-Json::StreamWriterBuilder builder;
-builder.indentation_ = "   ";  // or whatever you like
-
-// Then build a StreamWriter.
-std::shared_ptr<Json::StreamWriter> writer(
-    builder.newStreamWriter( &std::cout ) );
-
-// Make a new JSON document for the configuration. Preserve original comments.
-writer->write( root );
-
 // If you like the defaults, you can insert directly into a stream.
 std::cout << root;
+// Of course, you can write to `std::ostringstream` if you prefer.
 
 // If desired, remember to add a linefeed and flush.
 std::cout << std::endl;
+\endcode
 
-// Of course, you can write to `std::ostringstream` if you prefer. Or
-// use `writeString()` for convenience.
-std::string document = Json::writeString( root, builder );
+\section _advanced Advanced usage
+We are finalizing the new *Builder* API, which will be in versions
+`1.4.0` and `0.8.0` when released. Until then, you may continue to
+use the old API, include `Writer`, `Reader`, and `Feature`.
+\code
 
-// You can also read from a stream.  This will put the contents of any JSON
-// stream at a particular sub-value, if you'd like.
+// EXPERIMENTAL
+// Or use `writeString()` for convenience, with a specialized builder.
+Json::StreamWriterBuilder wbuilder;
+builder.indentation_ = "\t";
+std::string document = Json::writeString(root, wbuilder);
+
+// You can also read into a particular sub-value.
 std::cin >> root["subtree"];
+
+// EXPERIMENTAL
+// Here we use a specialized Builder, discard comments, and
+// record errors.
+Json::CharReaderBuilder rbuilder;
+rbuilder.collectComments_ = false;
+std::string errs;
+Json::parseFromStream(rbuilder, std::cin, &root["subtree"], &errs);
 \endcode
 
 \section _pbuild Build instructions

doxybuild.py

@@ -130,7 +130,7 @@ def build_doc(options,  make_release=False):
     if not os.path.isdir(output_dir):
         os.makedirs(output_dir)
 
-    do_subst_in_file('doc/doxyfile', 'doc/doxyfile.in', subst_keys)
+    do_subst_in_file('doc/doxyfile', options.doxyfile_input_path, subst_keys)
     run_doxygen(options.doxygen_path, 'doc/doxyfile', 'doc', is_silent=options.silent)
     if not options.silent:
         print(open(warning_log_path, 'r').read())
@@ -169,6 +169,8 @@ def main():
         help="""Path to GraphViz dot tool. Must be full qualified path. [Default: %default]""")
     parser.add_option('--doxygen', dest="doxygen_path", action='store', default=find_program('doxygen'),
         help="""Path to Doxygen tool. [Default: %default]""")
+    parser.add_option('--in', dest="doxyfile_input_path", action='store', default='doc/doxyfile.in',
+        help="""Path to doxygen inputs. [Default: %default]""")
     parser.add_option('--with-html-help', dest="with_html_help", action='store_true', default=False,
         help="""Enable generation of Microsoft HTML HELP""")
     parser.add_option('--no-uml-look', dest="with_uml_look", action='store_false', default=True,

include/json/reader.h

@@ -28,6 +28,7 @@ namespace Json {
 /** \brief Unserialize a <a HREF="http://www.json.org">JSON</a> document into a
  *Value.
  *
+ * \deprecated Use CharReader and CharReaderBuilder.
  */
 class JSON_API Reader {
 public:
@@ -276,21 +277,29 @@ public:
 
 /** \brief Build a CharReader implementation.
 
+  \deprecated This is experimental and will be altered before the next release.
+
 Usage:
 \code
   using namespace Json;
   CharReaderBuilder builder;
-  builder.collectComments_ = true;
-  std::shared_ptr<CharReader> reader(
-    builder.newCharReader());
+  builder.collectComments_ = false;
   Value value;
   std::string errs;
-  bool ok = parseFromStream(std::cin, &value, &errs);
+  bool ok = parseFromStream(builder, std::cin, &value, &errs);
 \endcode
 */
 class CharReaderBuilder : public CharReader::Factory {
 public:
+  /** default: true
+   *
+   * It is possible to "allow" comments but still not "collect" them.
+   */
   bool collectComments_;
+  /** default: all()
+   *
+   * For historical reasons, Features is a separate structure.
+   */
   Features features_;
 
   CharReaderBuilder();

include/json/writer.h

@@ -75,14 +75,15 @@ std::string writeString(Value const& root, StreamWriter::Factory const& factory)
 
 /** \brief Build a StreamWriter implementation.
 
+  \deprecated This is experimental and will be altered before the next release.
+
 Usage:
 \code
   using namespace Json;
   Value value = ...;
   StreamWriterBuilder builder;
   builder.cs_ = StreamWriter::CommentStyle::None;
-  std::shared_ptr<StreamWriter> writer(
-    builder.newStreamWriter(&std::cout));
+  builder.indentation_ = "   ";  // or whatever you like
   writer->write(value);
   std::cout << std::endl;  // add lf and flush
 \endcode
@@ -120,7 +121,7 @@ public:
  *   OldCompressingStreamWriterBuilder b;
  *   b.dropNullPlaceHolders_ = true; // etc.
  *   StreamWriter* w = b.newStreamWriter(&std::cout);
- *   w.write(value);
+ *   w->write(value);
  *   delete w;
  * \endcode
  */

src/lib_json/json_writer.cpp

@@ -947,24 +947,6 @@ StreamWriter::StreamWriter(std::ostream* sout)
 StreamWriter::~StreamWriter()
 {
 }
-struct MyStreamWriter : public StreamWriter {
-public:
-  MyStreamWriter(std::ostream* sout);
-  virtual ~MyStreamWriter();
-  virtual int write(Value const& root) = 0;
-};
-MyStreamWriter::MyStreamWriter(std::ostream* sout)
-    : StreamWriter(sout)
-{
-}
-MyStreamWriter::~MyStreamWriter()
-{
-}
-int MyStreamWriter::write(Value const& root)
-{
-  sout_ << root;
-  return 0;
-}
 StreamWriter::Factory::~Factory()
 {}
 StreamWriterBuilder::StreamWriterBuilder()