writer.h

00001 // Copyright 2007-2010 Baptiste Lepilleur and The JsonCpp Authors
00002 // Distributed under MIT license, or public domain if desired and
00003 // recognized in your jurisdiction.
00004 // See file LICENSE for detail or copy at http://jsoncpp.sourceforge.net/LICENSE
00005 
00006 #ifndef JSON_WRITER_H_INCLUDED
00007 #define JSON_WRITER_H_INCLUDED
00008 
00009 #if !defined(JSON_IS_AMALGAMATION)
00010 #include "value.h"
00011 #endif // if !defined(JSON_IS_AMALGAMATION)
00012 #include <vector>
00013 #include <string>
00014 #include <ostream>
00015 
00016 // Disable warning C4251: <data member>: <type> needs to have dll-interface to
00017 // be used by...
00018 #if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING) && defined(_MSC_VER)
00019 #pragma warning(push)
00020 #pragma warning(disable : 4251)
00021 #endif // if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING)
00022 
00023 #pragma pack(push, 8)
00024 
00025 namespace Json {
00026 
00027 class Value;
00028 
00029 /**
00030 
00031 Usage:
00032 \code
00033   using namespace Json;
00034   void writeToStdout(StreamWriter::Factory const& factory, Value const& value) {
00035     std::unique_ptr<StreamWriter> const writer(
00036       factory.newStreamWriter());
00037     writer->write(value, &std::cout);
00038     std::cout << std::endl;  // add lf and flush
00039   }
00040 \endcode
00041 */
00042 class JSON_API StreamWriter {
00043 protected:
00044   JSONCPP_OSTREAM* sout_;  // not owned; will not delete
00045 public:
00046   StreamWriter();
00047   virtual ~StreamWriter();
00048   /** Write Value into document as configured in sub-class.
00049       Do not take ownership of sout, but maintain a reference during function.
00050       \pre sout != NULL
00051       \return zero on success (For now, we always return zero, so check the stream instead.)
00052       \throw std::exception possibly, depending on configuration
00053    */
00054   virtual int write(Value const& root, JSONCPP_OSTREAM* sout) = 0;
00055 
00056   /** \brief A simple abstract factory.
00057    */
00058   class JSON_API Factory {
00059   public:
00060     virtual ~Factory();
00061     /** \brief Allocate a CharReader via operator new().
00062      * \throw std::exception if something goes wrong (e.g. invalid settings)
00063      */
00064     virtual StreamWriter* newStreamWriter() const = 0;
00065   };  // Factory
00066 };  // StreamWriter
00067 
00068 /** \brief Write into stringstream, then return string, for convenience.
00069  * A StreamWriter will be created from the factory, used, and then deleted.
00070  */
00071 JSONCPP_STRING JSON_API writeString(StreamWriter::Factory const& factory, Value const& root);
00072 
00073 
00074 /** \brief Build a StreamWriter implementation.
00075 
00076 Usage:
00077 \code
00078   using namespace Json;
00079   Value value = ...;
00080   StreamWriterBuilder builder;
00081   builder["commentStyle"] = "None";
00082   builder["indentation"] = "   ";  // or whatever you like
00083   std::unique_ptr<Json::StreamWriter> writer(
00084       builder.newStreamWriter());
00085   writer->write(value, &std::cout);
00086   std::cout << std::endl;  // add lf and flush
00087 \endcode
00088 */
00089 class JSON_API StreamWriterBuilder : public StreamWriter::Factory {
00090 public:
00091   // Note: We use a Json::Value so that we can add data-members to this class
00092   // without a major version bump.
00093   /** Configuration of this builder.
00094     Available settings (case-sensitive):
00095     - "commentStyle": "None" or "All"
00096     - "indentation":  "<anything>"
00097     - "enableYAMLCompatibility": false or true
00098       - slightly change the whitespace around colons
00099     - "dropNullPlaceholders": false or true
00100       - Drop the "null" string from the writer's output for nullValues.
00101         Strictly speaking, this is not valid JSON. But when the output is being
00102         fed to a browser's JavaScript, it makes for smaller output and the
00103         browser can handle the output just fine.
00104     - "useSpecialFloats": false or true
00105       - If true, outputs non-finite floating point values in the following way:
00106         NaN values as "NaN", positive infinity as "Infinity", and negative infinity
00107         as "-Infinity".
00108 
00109     You can examine 'settings_` yourself
00110     to see the defaults. You can also write and read them just like any
00111     JSON Value.
00112     \sa setDefaults()
00113     */
00114   Json::Value settings_;
00115 
00116   StreamWriterBuilder();
00117   ~StreamWriterBuilder() JSONCPP_OVERRIDE;
00118 
00119   /**
00120    * \throw std::exception if something goes wrong (e.g. invalid settings)
00121    */
00122   StreamWriter* newStreamWriter() const JSONCPP_OVERRIDE;
00123 
00124   /** \return true if 'settings' are legal and consistent;
00125    *   otherwise, indicate bad settings via 'invalid'.
00126    */
00127   bool validate(Json::Value* invalid) const;
00128   /** A simple way to update a specific setting.
00129    */
00130   Value& operator[](JSONCPP_STRING key);
00131 
00132   /** Called by ctor, but you can use this to reset settings_.
00133    * \pre 'settings' != NULL (but Json::null is fine)
00134    * \remark Defaults:
00135    * \snippet src/lib_json/json_writer.cpp StreamWriterBuilderDefaults
00136    */
00137   static void setDefaults(Json::Value* settings);
00138 };
00139 
00140 /** \brief Abstract class for writers.
00141  * \deprecated Use StreamWriter. (And really, this is an implementation detail.)
00142  */
00143 class JSONCPP_DEPRECATED("Use StreamWriter instead") JSON_API Writer {
00144 public:
00145   virtual ~Writer();
00146 
00147   virtual JSONCPP_STRING write(const Value& root) = 0;
00148 };
00149 
00150 /** \brief Outputs a Value in <a HREF="http://www.json.org">JSON</a> format
00151  *without formatting (not human friendly).
00152  *
00153  * The JSON document is written in a single line. It is not intended for 'human'
00154  *consumption,
00155  * but may be usefull to support feature such as RPC where bandwith is limited.
00156  * \sa Reader, Value
00157  * \deprecated Use StreamWriterBuilder.
00158  */
00159 #if defined(_MSC_VER)
00160 #pragma warning(push)
00161 #pragma warning(disable:4996) // Deriving from deprecated class
00162 #endif
00163 class JSONCPP_DEPRECATED("Use StreamWriterBuilder instead") JSON_API FastWriter : public Writer {
00164 public:
00165   FastWriter();
00166   ~FastWriter() JSONCPP_OVERRIDE {}
00167 
00168   void enableYAMLCompatibility();
00169 
00170   /** \brief Drop the "null" string from the writer's output for nullValues.
00171    * Strictly speaking, this is not valid JSON. But when the output is being
00172    * fed to a browser's JavaScript, it makes for smaller output and the
00173    * browser can handle the output just fine.
00174    */
00175   void dropNullPlaceholders();
00176 
00177   void omitEndingLineFeed();
00178 
00179 public: // overridden from Writer
00180   JSONCPP_STRING write(const Value& root) JSONCPP_OVERRIDE;
00181 
00182 private:
00183   void writeValue(const Value& value);
00184 
00185   JSONCPP_STRING document_;
00186   bool yamlCompatibilityEnabled_;
00187   bool dropNullPlaceholders_;
00188   bool omitEndingLineFeed_;
00189 };
00190 #if defined(_MSC_VER)
00191 #pragma warning(pop)
00192 #endif
00193 
00194 /** \brief Writes a Value in <a HREF="http://www.json.org">JSON</a> format in a
00195  *human friendly way.
00196  *
00197  * The rules for line break and indent are as follow:
00198  * - Object value:
00199  *     - if empty then print {} without indent and line break
00200  *     - if not empty the print '{', line break & indent, print one value per
00201  *line
00202  *       and then unindent and line break and print '}'.
00203  * - Array value:
00204  *     - if empty then print [] without indent and line break
00205  *     - if the array contains no object value, empty array or some other value
00206  *types,
00207  *       and all the values fit on one lines, then print the array on a single
00208  *line.
00209  *     - otherwise, it the values do not fit on one line, or the array contains
00210  *       object or non empty array, then print one value per line.
00211  *
00212  * If the Value have comments then they are outputed according to their
00213  *#CommentPlacement.
00214  *
00215  * \sa Reader, Value, Value::setComment()
00216  * \deprecated Use StreamWriterBuilder.
00217  */
00218 #if defined(_MSC_VER)
00219 #pragma warning(push)
00220 #pragma warning(disable:4996) // Deriving from deprecated class
00221 #endif
00222 class JSONCPP_DEPRECATED("Use StreamWriterBuilder instead") JSON_API StyledWriter : public Writer {
00223 public:
00224   StyledWriter();
00225   ~StyledWriter() JSONCPP_OVERRIDE {}
00226 
00227 public: // overridden from Writer
00228   /** \brief Serialize a Value in <a HREF="http://www.json.org">JSON</a> format.
00229    * \param root Value to serialize.
00230    * \return String containing the JSON document that represents the root value.
00231    */
00232   JSONCPP_STRING write(const Value& root) JSONCPP_OVERRIDE;
00233 
00234 private:
00235   void writeValue(const Value& value);
00236   void writeArrayValue(const Value& value);
00237   bool isMultilineArray(const Value& value);
00238   void pushValue(const JSONCPP_STRING& value);
00239   void writeIndent();
00240   void writeWithIndent(const JSONCPP_STRING& value);
00241   void indent();
00242   void unindent();
00243   void writeCommentBeforeValue(const Value& root);
00244   void writeCommentAfterValueOnSameLine(const Value& root);
00245   bool hasCommentForValue(const Value& value);
00246   static JSONCPP_STRING normalizeEOL(const JSONCPP_STRING& text);
00247 
00248   typedef std::vector<JSONCPP_STRING> ChildValues;
00249 
00250   ChildValues childValues_;
00251   JSONCPP_STRING document_;
00252   JSONCPP_STRING indentString_;
00253   unsigned int rightMargin_;
00254   unsigned int indentSize_;
00255   bool addChildValues_;
00256 };
00257 #if defined(_MSC_VER)
00258 #pragma warning(pop)
00259 #endif
00260 
00261 /** \brief Writes a Value in <a HREF="http://www.json.org">JSON</a> format in a
00262  human friendly way,
00263      to a stream rather than to a string.
00264  *
00265  * The rules for line break and indent are as follow:
00266  * - Object value:
00267  *     - if empty then print {} without indent and line break
00268  *     - if not empty the print '{', line break & indent, print one value per
00269  line
00270  *       and then unindent and line break and print '}'.
00271  * - Array value:
00272  *     - if empty then print [] without indent and line break
00273  *     - if the array contains no object value, empty array or some other value
00274  types,
00275  *       and all the values fit on one lines, then print the array on a single
00276  line.
00277  *     - otherwise, it the values do not fit on one line, or the array contains
00278  *       object or non empty array, then print one value per line.
00279  *
00280  * If the Value have comments then they are outputed according to their
00281  #CommentPlacement.
00282  *
00283  * \sa Reader, Value, Value::setComment()
00284  * \deprecated Use StreamWriterBuilder.
00285  */
00286 #if defined(_MSC_VER)
00287 #pragma warning(push)
00288 #pragma warning(disable:4996) // Deriving from deprecated class
00289 #endif
00290 class JSONCPP_DEPRECATED("Use StreamWriterBuilder instead") JSON_API StyledStreamWriter {
00291 public:
00292 /**
00293  * \param indentation Each level will be indented by this amount extra.
00294  */
00295   StyledStreamWriter(JSONCPP_STRING indentation = "\t");
00296   ~StyledStreamWriter() {}
00297 
00298 public:
00299   /** \brief Serialize a Value in <a HREF="http://www.json.org">JSON</a> format.
00300    * \param out Stream to write to. (Can be ostringstream, e.g.)
00301    * \param root Value to serialize.
00302    * \note There is no point in deriving from Writer, since write() should not
00303    * return a value.
00304    */
00305   void write(JSONCPP_OSTREAM& out, const Value& root);
00306 
00307 private:
00308   void writeValue(const Value& value);
00309   void writeArrayValue(const Value& value);
00310   bool isMultilineArray(const Value& value);
00311   void pushValue(const JSONCPP_STRING& value);
00312   void writeIndent();
00313   void writeWithIndent(const JSONCPP_STRING& value);
00314   void indent();
00315   void unindent();
00316   void writeCommentBeforeValue(const Value& root);
00317   void writeCommentAfterValueOnSameLine(const Value& root);
00318   bool hasCommentForValue(const Value& value);
00319   static JSONCPP_STRING normalizeEOL(const JSONCPP_STRING& text);
00320 
00321   typedef std::vector<JSONCPP_STRING> ChildValues;
00322 
00323   ChildValues childValues_;
00324   JSONCPP_OSTREAM* document_;
00325   JSONCPP_STRING indentString_;
00326   unsigned int rightMargin_;
00327   JSONCPP_STRING indentation_;
00328   bool addChildValues_ : 1;
00329   bool indented_ : 1;
00330 };
00331 #if defined(_MSC_VER)
00332 #pragma warning(pop)
00333 #endif
00334 
00335 #if defined(JSON_HAS_INT64)
00336 JSONCPP_STRING JSON_API valueToString(Int value);
00337 JSONCPP_STRING JSON_API valueToString(UInt value);
00338 #endif // if defined(JSON_HAS_INT64)
00339 JSONCPP_STRING JSON_API valueToString(LargestInt value);
00340 JSONCPP_STRING JSON_API valueToString(LargestUInt value);
00341 JSONCPP_STRING JSON_API valueToString(double value);
00342 JSONCPP_STRING JSON_API valueToString(bool value);
00343 JSONCPP_STRING JSON_API valueToQuotedString(const char* value);
00344 
00345 /// \brief Output using the StyledStreamWriter.
00346 /// \see Json::operator>>()
00347 JSON_API JSONCPP_OSTREAM& operator<<(JSONCPP_OSTREAM&, const Value& root);
00348 
00349 } // namespace Json
00350 
00351 #pragma pack(pop)
00352 
00353 #if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING)
00354 #pragma warning(pop)
00355 #endif // if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING)
00356 
00357 #endif // JSON_WRITER_H_INCLUDED