deprecate old Writers

also, use withers instead of setters, and update docs

Author: cdunn2001

doc/jsoncpp.dox

@@ -73,24 +73,31 @@ for ( int index = 0; index < plugins.size(); ++index )  // Iterates over the seq
 setIndentLength( root["indent"].get("length", 3).asInt() );
 setIndentUseSpace( root["indent"].get("use_space", true).asBool() );
 
-// ...
-// At application shutdown to make the new configuration document:
 // Since Json::Value has implicit constructor for all value types, it is not
 // necessary to explicitly construct the Json::Value object:
 root["encoding"] = getCurrentEncoding();
 root["indent"]["length"] = getCurrentIndentLength();
 root["indent"]["use_space"] = getCurrentIndentUseSpace();
 
-Json::StyledWriter writer;
+// To write into a steam with minimal memory overhead,
+// create a Builder for a StreamWriter.
+Json::StreamWriter::Builder builder;
+builder.withIndentation("   ");  // or whatever you like
+
+// Then build a StreamWriter.
+// (Of course, you can write to std::ostringstream if you prefer.)
+std::shared_ptr<Json::StreamWriter> writer(
+    builder.newStreamWriter( &std::cout );
+
 // Make a new JSON document for the configuration. Preserve original comments.
-std::string outputConfig = writer.write( root );
+writer->write( root );
+
+// If you like the defaults, you can insert directly into a stream.
+std::cout << root;
 
-// You can also use streams.  This will put the contents of any JSON
+// 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.
 std::cin >> root["subtree"];
-
-// And you can write to a stream, using the StyledWriter automatically.
-std::cout << root;
 \endcode
 
 \section _pbuild Build instructions

include/json/writer.h

@@ -31,7 +31,7 @@ class StreamWriterBuilder;
   using namespace Json;
   Value value;
   StreamWriter::Builder builder;
-  builder.setCommentStyle(StreamWriter::CommentStyle::None);
+  builder.withCommentStyle(StreamWriter::CommentStyle::None);
   std::shared_ptr<StreamWriter> writer(
     builder.newStreamWriter(&std::cout));
   writer->write(value);
@@ -66,32 +66,32 @@ class JSON_API StreamWriter {
     Builder();
     ~Builder();  // delete underlying StreamWriterBuilder
 
-    void setCommentStyle(CommentStyle cs);  /// default: All
+    Builder& withCommentStyle(CommentStyle cs);  /// default: All
     /** \brief Write in human-friendly style.
 
         If "", then skip all indentation, newlines, and comments,
         which implies CommentStyle::None.
         Default: "\t"
     */
-    void setIndentation(std::string indentation);
+    Builder& withIndentation(std::string indentation);
     /** \brief Drop the "null" string from the writer's output for nullValues.
     * Strictly speaking, this is not valid JSON. But when the output is being
     * fed to a browser's Javascript, it makes for smaller output and the
     * browser can handle the output just fine.
     */
-    void setDropNullPlaceholders(bool v);
+    Builder& withDropNullPlaceholders(bool v);
     /** \brief Do not add \n at end of document.
      * Normally, we add an extra newline, just because.
      */
-    void setOmitEndingLineFeed(bool v);
+    Builder& withOmitEndingLineFeed(bool v);
     /** \brief Add a space after ':'.
      * If indentation is non-empty, we surround colon with whitespace,
      * e.g. " : "
      * This will add back the trailing space when there is no indentation.
      * This seems dubious when the entire document is on a single line,
      * but we leave this here to repduce the behavior of the old `FastWriter`.
      */
-    void setEnableYAMLCompatibility(bool v);
+    Builder& withEnableYAMLCompatibility(bool v);
 
     /// Do not take ownership of sout, but maintain a reference.
     StreamWriter* newStreamWriter(std::ostream* sout) const;
@@ -103,6 +103,7 @@ std::string writeString(Value const& root, StreamWriter::Builder const& builder)
 
 
 /** \brief Abstract class for writers.
+ * \deprecated Use StreamWriter::Builder.
  */
 class JSON_API Writer {
 public:
@@ -118,6 +119,7 @@ class JSON_API Writer {
  *consumption,
  * but may be usefull to support feature such as RPC where bandwith is limited.
  * \sa Reader, Value
+ * \deprecated Use StreamWriter::Builder.
  */
 class JSON_API FastWriter : public Writer {
 public:
@@ -169,6 +171,7 @@ class JSON_API FastWriter : public Writer {
  *#CommentPlacement.
  *
  * \sa Reader, Value, Value::setComment()
+ * \deprecated Use StreamWriter::Builder.
  */
 class JSON_API StyledWriter : public Writer {
 public:
@@ -230,6 +233,7 @@ class JSON_API StyledWriter : public Writer {
  *
  * \param indentation Each level will be indented by this amount extra.
  * \sa Reader, Value, Value::setComment()
+ * \deprecated Use StreamWriter::Builder.
  */
 class JSON_API StyledStreamWriter {
 public:

src/jsontestrunner/main.cpp

@@ -185,7 +185,7 @@ static std::string useBuiltStyledStreamWriter(
     Json::Value const& root)
 {
   Json::StreamWriter::Builder builder;
-  builder.setCommentStyle(Json::StreamWriter::CommentStyle::All);
+  builder.withCommentStyle(Json::StreamWriter::CommentStyle::All);
   return writeString(root, builder);
 }
 static int rewriteValueTree(

src/lib_json/json_writer.cpp

@@ -1058,25 +1058,30 @@ StreamWriter::Builder::Builder(Builder const&)
 {abort();}
 void StreamWriter::Builder::operator=(Builder const&)
 {abort();}
-void StreamWriter::Builder::setCommentStyle(CommentStyle v)
+StreamWriter::Builder& StreamWriter::Builder::withCommentStyle(CommentStyle v)
 {
   own_->setCommentStyle(v);
+  return *this;
 }
-void StreamWriter::Builder::setIndentation(std::string v)
+StreamWriter::Builder& StreamWriter::Builder::withIndentation(std::string v)
 {
   own_->setIndentation(v);
+  return *this;
 }
-void StreamWriter::Builder::setDropNullPlaceholders(bool v)
+StreamWriter::Builder& StreamWriter::Builder::withDropNullPlaceholders(bool v)
 {
   own_->setDropNullPlaceholders(v);
+  return *this;
 }
-void StreamWriter::Builder::setOmitEndingLineFeed(bool v)
+StreamWriter::Builder& StreamWriter::Builder::withOmitEndingLineFeed(bool v)
 {
   own_->setOmitEndingLineFeed(v);
+  return *this;
 }
-void StreamWriter::Builder::setEnableYAMLCompatibility(bool v)
+StreamWriter::Builder& StreamWriter::Builder::withEnableYAMLCompatibility(bool v)
 {
   own_->setEnableYAMLCompatibility(v);
+  return *this;
 }
 StreamWriter* StreamWriter::Builder::newStreamWriter(std::ostream* sout) const
 {
@@ -1092,8 +1097,8 @@ std::string writeString(Value const& root, StreamWriter::Builder const& builder)
 
 std::ostream& operator<<(std::ostream& sout, Value const& root) {
   StreamWriter::Builder builder;
-  builder.setCommentStyle(StreamWriter::CommentStyle::All);
-  builder.setIndentation("\t");
+  builder.withCommentStyle(StreamWriter::CommentStyle::All);
+  builder.withIndentation("\t");
   std::shared_ptr<StreamWriter> writer(builder.newStreamWriter(&sout));
   writer->write(root);
   return sout;