Merge pull request open-source-parsers#163 from cdunn2001/master

Reimplement the new Builders.

Issue open-source-parsers#131.

Author: cdunn2001

doc/jsoncpp.dox

@@ -53,23 +53,26 @@ preserved.
 Json::Value root;   // 'root' will contain the root value after parsing.
 std::cin >> root;
 
+// You can also read into a particular sub-value.
+std::cin >> root["subtree"];
+
 // Get the value of the member of root named 'encoding', return 'UTF-8' if there is no
 // such member.
 std::string encoding = root.get("encoding", "UTF-8" ).asString();
-// Get the value of the member of root named 'encoding', return a 'null' value if
+// Get the value of the member of root named 'encoding'; return a 'null' value if
 // there is no such member.
 const Json::Value plugins = root["plug-ins"];
 for ( int index = 0; index < plugins.size(); ++index )  // Iterates over the sequence elements.
    loadPlugIn( plugins[index].asString() );
 
-setIndentLength( root["indent"].get("length", 3).asInt() );
-setIndentUseSpace( root["indent"].get("use_space", true).asBool() );
+foo::setIndentLength( root["indent"].get("length", 3).asInt() );
+foo::setIndentUseSpace( root["indent"].get("use_space", true).asBool() );
 
 // 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();
+root["encoding"] = foo::getCurrentEncoding();
+root["indent"]["length"] = foo::getCurrentIndentLength();
+root["indent"]["use_space"] = foo::getCurrentIndentUseSpace();
 
 // If you like the defaults, you can insert directly into a stream.
 std::cout << root;
@@ -80,27 +83,40 @@ std::cout << std::endl;
 \endcode
 
 \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
 
-// EXPERIMENTAL
-// Or use `writeString()` for convenience, with a specialized builder.
-Json::StreamWriterBuilder wbuilder;
-builder.indentation_ = "\t";
-std::string document = Json::writeString(root, wbuilder);
+Configure *builders* to create *readers* and *writers*. For
+configuration, we use our own `Json::Value` (rather than
+standard setters/getters) so that we can add
+features without losing binary-compatibility.
 
-// You can also read into a particular sub-value.
-std::cin >> root["subtree"];
+\code
+// For convenience, use `writeString()` with a specialized builder.
+Json::StreamWriterBuilder wbuilder;
+wbuilder.settings_["indentation"] = "\t";  // simple Json::Value
+std::string document = Json::writeString(wbuilder, root);
 
-// EXPERIMENTAL
-// Here we use a specialized Builder, discard comments, and
-// record errors.
+// Here, using a specialized Builder, we discard comments and
+// record errors as we parse.
 Json::CharReaderBuilder rbuilder;
-rbuilder.collectComments_ = false;
+rbuilder.settings_["collectComments"] = false;  // simple Json::Value
 std::string errs;
-Json::parseFromStream(rbuilder, std::cin, &root["subtree"], &errs);
+bool ok = Json::parseFromStream(rbuilder, std::cin, &root, &errs);
+\endcode
+
+Yes, compile-time configuration-checking would be helpful,
+but `Json::Value` lets you
+write and read the builder configuration, which is better! In other words,
+you can configure your JSON parser using JSON.
+
+CharReaders and StreamWriters are not thread-safe, but they are re-usable.
+\code
+Json::CharReaderBuilder rbuilder;
+cfg >> rbuilder.settings_;
+std::unique_ptr<Json::CharReader> const reader(rbuilder.newCharReader());
+reader->parse(start, stop, &value1, &errs);
+// ...
+reader->parse(start, stop, &value2, &errs);
+// etc.
 \endcode
 
 \section _pbuild Build instructions
@@ -137,5 +153,7 @@ and recognized in your jurisdiction.
 
 \author Baptiste Lepilleur <[email protected]> (originator)
 \version \include version
+We make strong guarantees about binary-compatibility, consistent with
+<a href="http://apr.apache.org/versioning.html">the Apache versioning scheme</a>.
 \sa version.h
 */

include/json/reader.h

@@ -270,7 +270,9 @@ class JSON_API CharReader {
 
   class Factory {
   public:
-    /// \brief Allocate a CharReader via operator new().
+    /** \brief Allocate a CharReader via operator new().
+     * \throw std::exception if something goes wrong (e.g. invalid settings)
+     */
     virtual CharReader* newCharReader() const = 0;
   };  // Factory
 };  // CharReader
@@ -283,29 +285,53 @@ class JSON_API CharReader {
 \code
   using namespace Json;
   CharReaderBuilder builder;
-  builder.collectComments_ = false;
+  builder.settings_["collectComments"] = false;
   Value value;
   std::string errs;
   bool ok = parseFromStream(builder, std::cin, &value, &errs);
 \endcode
 */
-class CharReaderBuilder : public CharReader::Factory {
+class JSON_API 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_;
+  // Note: We use a Json::Value so that we can add data-members to this class
+  // without a major version bump.
+  /** Configuration of this builder.
+    These are case-sensitive.
+    Available settings (case-sensitive):
+    - "collectComments": false or true
+    - "allowComments"
+    - "strictRoot"
+    - "allowDroppedNullPlaceholders"
+    - "allowNumericKeys"
+
+    You can examine 'settings_` yourself
+    to see the defaults. You can also write and read them just like any
+    JSON Value.
+    \sa setDefaults()
+    */
+  Json::Value settings_;
 
   CharReaderBuilder();
   virtual ~CharReaderBuilder();
 
   virtual CharReader* newCharReader() const;
+
+  /** \return true if 'settings' are legal and consistent;
+   *   otherwise, indicate bad settings via 'invalid'.
+   */
+  bool validate(Json::Value* invalid) const;
+  /** Called by ctor, but you can use this to reset settings_.
+   * \pre 'settings' != NULL (but Json::null is fine)
+   * \remark Defaults:
+   * \snippet src/lib_json/json_reader.cpp CharReaderBuilderStrictMode
+   */
+  static void setDefaults(Json::Value* settings);
+  /** Same as old Features::strictMode().
+   * \pre 'settings' != NULL (but Json::null is fine)
+   * \remark Defaults:
+   * \snippet src/lib_json/json_reader.cpp CharReaderBuilderDefaults
+   */
+  static void strictMode(Json::Value* settings);
 };
 
 /** Consume entire stream and use its begin/end.

include/json/writer.h

@@ -31,85 +31,93 @@ class Value;
   using namespace Json;
   void writeToStdout(StreamWriter::Factory const& factory, Value const& value) {
     std::unique_ptr<StreamWriter> const writer(
-      factory.newStreamWriter(&std::cout));
-    writer->write(value);
+      factory.newStreamWriter());
+    writer->write(value, &std::cout);
     std::cout << std::endl;  // add lf and flush
   }
 \endcode
 */
 class JSON_API StreamWriter {
 protected:
-  std::ostream& sout_;  // not owned; will not delete
+  std::ostream* sout_;  // not owned; will not delete
 public:
-  /// Scoped enums are not available until C++11.
-  struct CommentStyle {
-    /// Decide whether to write comments.
-    enum Enum {
-      None,  ///< Drop all comments.
-      Most,  ///< Recover odd behavior of previous versions (not implemented yet).
-      All  ///< Keep all comments.
-    };
-  };
-
-  /// Keep a reference, but do not take ownership of `sout`.
-  StreamWriter(std::ostream* sout);
+  StreamWriter();
   virtual ~StreamWriter();
-  /// Write Value into document as configured in sub-class.
-  /// \return zero on success
-  /// \throw std::exception possibly, depending on configuration
-  virtual int write(Value const& root) = 0;
+  /** Write Value into document as configured in sub-class.
+      Do not take ownership of sout, but maintain a reference during function.
+      \pre sout != NULL
+      \return zero on success
+      \throw std::exception possibly, depending on configuration
+   */
+  virtual int write(Value const& root, std::ostream* sout) = 0;
 
   /** \brief A simple abstract factory.
    */
   class JSON_API Factory {
   public:
     virtual ~Factory();
-    /// Do not take ownership of sout, but maintain a reference.
-    virtual StreamWriter* newStreamWriter(std::ostream* sout) const = 0;
+    /** \brief Allocate a CharReader via operator new().
+     * \throw std::exception if something goes wrong (e.g. invalid settings)
+     */
+    virtual StreamWriter* newStreamWriter() const = 0;
   };  // Factory
 };  // StreamWriter
 
-/// \brief Write into stringstream, then return string, for convenience.
-std::string writeString(Value const& root, StreamWriter::Factory const& factory);
+/** \brief Write into stringstream, then return string, for convenience.
+ * A StreamWriter will be created from the factory, used, and then deleted.
+ */
+std::string writeString(StreamWriter::Factory const& factory, Value const& root);
 
 
 /** \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;
-  builder.indentation_ = "   ";  // or whatever you like
-  writer->write(value);
+  builder.settings_["commentStyle"] = "None";
+  builder.settings_["indentation"] = "   ";  // or whatever you like
+  std::unique_ptr<Json::StreamWriter> writer(
+      builder.newStreamWriter());
+  writer->write(value, &std::cout);
   std::cout << std::endl;  // add lf and flush
 \endcode
 */
 class JSON_API StreamWriterBuilder : public StreamWriter::Factory {
 public:
-  // Note: We cannot add data-members to this class without a major version bump.
-  // So these might as well be completely exposed.
-
-  /** \brief How to write comments.
-   * Default: All
-   */
-  StreamWriter::CommentStyle::Enum cs_;
-  /** \brief Write in human-friendly style.
-
-      If "", then skip all indentation and newlines.
-      In that case, you probably want CommentStyle::None also.
-      Default: "\t"
-  */
-  std::string indentation_;
+  // Note: We use a Json::Value so that we can add data-members to this class
+  // without a major version bump.
+  /** Configuration of this builder.
+    Available settings (case-sensitive):
+    - "commentStyle": "None", "Some", or "All"
+    - "indentation":  "<anything>"
+
+    You can examine 'settings_` yourself
+    to see the defaults. You can also write and read them just like any
+    JSON Value.
+    \sa setDefaults()
+    */
+  Json::Value settings_;
 
   StreamWriterBuilder();
   virtual ~StreamWriterBuilder();
 
-  /// Do not take ownership of sout, but maintain a reference.
-  virtual StreamWriter* newStreamWriter(std::ostream* sout) const;
+  /**
+   * \throw std::exception if something goes wrong (e.g. invalid settings)
+   */
+  virtual StreamWriter* newStreamWriter() const;
+
+  /** \return true if 'settings' are legal and consistent;
+   *   otherwise, indicate bad settings via 'invalid'.
+   */
+  bool validate(Json::Value* invalid) const;
+  /** Called by ctor, but you can use this to reset settings_.
+   * \pre 'settings' != NULL (but Json::null is fine)
+   * \remark Defaults:
+   * \snippet src/lib_json/json_writer.cpp StreamWriterBuilderDefaults
+   */
+  static void setDefaults(Json::Value* settings);
 };
 
 /** \brief Build a StreamWriter implementation.
@@ -120,10 +128,12 @@ class JSON_API StreamWriterBuilder : public StreamWriter::Factory {
  * \code
  *   OldCompressingStreamWriterBuilder b;
  *   b.dropNullPlaceHolders_ = true; // etc.
- *   StreamWriter* w = b.newStreamWriter(&std::cout);
- *   w->write(value);
+ *   StreamWriter* w = b.newStreamWriter();
+ *   w->write(value, &std::cout);
  *   delete w;
  * \endcode
+ *
+ * \deprecated Use StreamWriterBuilder
  */
 class JSON_API OldCompressingStreamWriterBuilder : public StreamWriter::Factory
 {
@@ -155,7 +165,7 @@ class JSON_API OldCompressingStreamWriterBuilder : public StreamWriter::Factory
     , omitEndingLineFeed_(false)
     , enableYAMLCompatibility_(false)
   {}
-  virtual StreamWriter* newStreamWriter(std::ostream*) const;
+  virtual StreamWriter* newStreamWriter() const;
 };
 
 /** \brief Abstract class for writers.

src/jsontestrunner/main.cpp

@@ -185,7 +185,7 @@ static std::string useBuiltStyledStreamWriter(
     Json::Value const& root)
 {
   Json::StreamWriterBuilder builder;
-  return writeString(root, builder);
+  return Json::writeString(builder, root);
 }
 static int rewriteValueTree(
     const std::string& rewritePath,