1 // Copyright 2007-2010 Baptiste Lepilleur 2 // Distributed under MIT license, or public domain if desired and 3 // recognized in your jurisdiction. 4 // See file LICENSE for detail or copy at http://jsoncpp.sourceforge.net/LICENSE 5 6 #ifndef JSON_WRITER_H_INCLUDED 7 #define JSON_WRITER_H_INCLUDED 8 9 #if !defined(JSON_IS_AMALGAMATION) 10 #include "value.h" 11 #endif // if !defined(JSON_IS_AMALGAMATION) 12 #include <vector> 13 #include <string> 14 #include <ostream> 15 16 // Disable warning C4251: <data member>: <type> needs to have dll-interface to 17 // be used by... 18 #if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING) 19 #pragma warning(push) 20 #pragma warning(disable : 4251) 21 #endif // if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING) 22 23 #pragma pack(push, 8) 24 25 namespace Json { 26 27 class Value; 28 29 /** 30 31 Usage: 32 \code 33 using namespace Json; 34 void writeToStdout(StreamWriter::Factory const& factory, Value const& value) { 35 std::unique_ptr<StreamWriter> const writer( 36 factory.newStreamWriter()); 37 writer->write(value, &std::cout); 38 std::cout << std::endl; // add lf and flush 39 } 40 \endcode 41 */ 42 class JSON_API StreamWriter { 43 protected: 44 JSONCPP_OSTREAM* sout_; // not owned; will not delete 45 public: 46 StreamWriter(); 47 virtual ~StreamWriter(); 48 /** Write Value into document as configured in sub-class. 49 Do not take ownership of sout, but maintain a reference during function. 50 \pre sout != NULL 51 \return zero on success (For now, we always return zero, so check the stream instead.) 52 \throw std::exception possibly, depending on configuration 53 */ 54 virtual int write(Value const& root, JSONCPP_OSTREAM* sout) = 0; 55 56 /** \brief A simple abstract factory. 57 */ 58 class JSON_API Factory { 59 public: 60 virtual ~Factory(); 61 /** \brief Allocate a CharReader via operator new(). 62 * \throw std::exception if something goes wrong (e.g. invalid settings) 63 */ 64 virtual StreamWriter* newStreamWriter() const = 0; 65 }; // Factory 66 }; // StreamWriter 67 68 /** \brief Write into stringstream, then return string, for convenience. 69 * A StreamWriter will be created from the factory, used, and then deleted. 70 */ 71 JSONCPP_STRING JSON_API writeString(StreamWriter::Factory const& factory, Value const& root); 72 73 74 /** \brief Build a StreamWriter implementation. 75 76 Usage: 77 \code 78 using namespace Json; 79 Value value = ...; 80 StreamWriterBuilder builder; 81 builder["commentStyle"] = "None"; 82 builder["indentation"] = " "; // or whatever you like 83 std::unique_ptr<Json::StreamWriter> writer( 84 builder.newStreamWriter()); 85 writer->write(value, &std::cout); 86 std::cout << std::endl; // add lf and flush 87 \endcode 88 */ 89 class JSON_API StreamWriterBuilder : public StreamWriter::Factory { 90 public: 91 // Note: We use a Json::Value so that we can add data-members to this class 92 // without a major version bump. 93 /** Configuration of this builder. 94 Available settings (case-sensitive): 95 - "commentStyle": "None" or "All" 96 - "indentation": "<anything>" 97 - "enableYAMLCompatibility": false or true 98 - slightly change the whitespace around colons 99 - "dropNullPlaceholders": false or true 100 - Drop the "null" string from the writer's output for nullValues. 101 Strictly speaking, this is not valid JSON. But when the output is being 102 fed to a browser's Javascript, it makes for smaller output and the 103 browser can handle the output just fine. 104 - "useSpecialFloats": false or true 105 - If true, outputs non-finite floating point values in the following way: 106 NaN values as "NaN", positive infinity as "Infinity", and negative infinity 107 as "-Infinity". 108 109 You can examine 'settings_` yourself 110 to see the defaults. You can also write and read them just like any 111 JSON Value. 112 \sa setDefaults() 113 */ 114 Json::Value settings_; 115 116 StreamWriterBuilder(); 117 ~StreamWriterBuilder() JSONCPP_OVERRIDE; 118 119 /** 120 * \throw std::exception if something goes wrong (e.g. invalid settings) 121 */ 122 StreamWriter* newStreamWriter() const JSONCPP_OVERRIDE; 123 124 /** \return true if 'settings' are legal and consistent; 125 * otherwise, indicate bad settings via 'invalid'. 126 */ 127 bool validate(Json::Value* invalid) const; 128 /** A simple way to update a specific setting. 129 */ 130 Value& operator[](JSONCPP_STRING key); 131 132 /** Called by ctor, but you can use this to reset settings_. 133 * \pre 'settings' != NULL (but Json::null is fine) 134 * \remark Defaults: 135 * \snippet src/lib_json/json_writer.cpp StreamWriterBuilderDefaults 136 */ 137 static void setDefaults(Json::Value* settings); 138 }; 139 140 /** \brief Abstract class for writers. 141 * \deprecated Use StreamWriter. (And really, this is an implementation detail.) 142 */ 143 class JSON_API Writer { 144 public: 145 virtual ~Writer(); 146 147 virtual JSONCPP_STRING write(const Value& root) = 0; 148 }; 149 150 /** \brief Outputs a Value in <a HREF="http://www.json.org">JSON</a> format 151 *without formatting (not human friendly). 152 * 153 * The JSON document is written in a single line. It is not intended for 'human' 154 *consumption, 155 * but may be usefull to support feature such as RPC where bandwith is limited. 156 * \sa Reader, Value 157 * \deprecated Use StreamWriterBuilder. 158 */ 159 class JSON_API FastWriter : public Writer { 160 161 public: 162 FastWriter(); ~FastWriter()163 ~FastWriter() JSONCPP_OVERRIDE {} 164 165 void enableYAMLCompatibility(); 166 167 /** \brief Drop the "null" string from the writer's output for nullValues. 168 * Strictly speaking, this is not valid JSON. But when the output is being 169 * fed to a browser's Javascript, it makes for smaller output and the 170 * browser can handle the output just fine. 171 */ 172 void dropNullPlaceholders(); 173 174 void omitEndingLineFeed(); 175 176 public: // overridden from Writer 177 JSONCPP_STRING write(const Value& root) JSONCPP_OVERRIDE; 178 179 private: 180 void writeValue(const Value& value); 181 182 JSONCPP_STRING document_; 183 bool yamlCompatiblityEnabled_; 184 bool dropNullPlaceholders_; 185 bool omitEndingLineFeed_; 186 }; 187 188 /** \brief Writes a Value in <a HREF="http://www.json.org">JSON</a> format in a 189 *human friendly way. 190 * 191 * The rules for line break and indent are as follow: 192 * - Object value: 193 * - if empty then print {} without indent and line break 194 * - if not empty the print '{', line break & indent, print one value per 195 *line 196 * and then unindent and line break and print '}'. 197 * - Array value: 198 * - if empty then print [] without indent and line break 199 * - if the array contains no object value, empty array or some other value 200 *types, 201 * and all the values fit on one lines, then print the array on a single 202 *line. 203 * - otherwise, it the values do not fit on one line, or the array contains 204 * object or non empty array, then print one value per line. 205 * 206 * If the Value have comments then they are outputed according to their 207 *#CommentPlacement. 208 * 209 * \sa Reader, Value, Value::setComment() 210 * \deprecated Use StreamWriterBuilder. 211 */ 212 class JSON_API StyledWriter : public Writer { 213 public: 214 StyledWriter(); ~StyledWriter()215 ~StyledWriter() JSONCPP_OVERRIDE {} 216 217 public: // overridden from Writer 218 /** \brief Serialize a Value in <a HREF="http://www.json.org">JSON</a> format. 219 * \param root Value to serialize. 220 * \return String containing the JSON document that represents the root value. 221 */ 222 JSONCPP_STRING write(const Value& root) JSONCPP_OVERRIDE; 223 224 private: 225 void writeValue(const Value& value); 226 void writeArrayValue(const Value& value); 227 bool isMultineArray(const Value& value); 228 void pushValue(const JSONCPP_STRING& value); 229 void writeIndent(); 230 void writeWithIndent(const JSONCPP_STRING& value); 231 void indent(); 232 void unindent(); 233 void writeCommentBeforeValue(const Value& root); 234 void writeCommentAfterValueOnSameLine(const Value& root); 235 bool hasCommentForValue(const Value& value); 236 static JSONCPP_STRING normalizeEOL(const JSONCPP_STRING& text); 237 238 typedef std::vector<JSONCPP_STRING> ChildValues; 239 240 ChildValues childValues_; 241 JSONCPP_STRING document_; 242 JSONCPP_STRING indentString_; 243 unsigned int rightMargin_; 244 unsigned int indentSize_; 245 bool addChildValues_; 246 }; 247 248 /** \brief Writes a Value in <a HREF="http://www.json.org">JSON</a> format in a 249 human friendly way, 250 to a stream rather than to a string. 251 * 252 * The rules for line break and indent are as follow: 253 * - Object value: 254 * - if empty then print {} without indent and line break 255 * - if not empty the print '{', line break & indent, print one value per 256 line 257 * and then unindent and line break and print '}'. 258 * - Array value: 259 * - if empty then print [] without indent and line break 260 * - if the array contains no object value, empty array or some other value 261 types, 262 * and all the values fit on one lines, then print the array on a single 263 line. 264 * - otherwise, it the values do not fit on one line, or the array contains 265 * object or non empty array, then print one value per line. 266 * 267 * If the Value have comments then they are outputed according to their 268 #CommentPlacement. 269 * 270 * \param indentation Each level will be indented by this amount extra. 271 * \sa Reader, Value, Value::setComment() 272 * \deprecated Use StreamWriterBuilder. 273 */ 274 class JSON_API StyledStreamWriter { 275 public: 276 StyledStreamWriter(JSONCPP_STRING indentation = "\t"); ~StyledStreamWriter()277 ~StyledStreamWriter() {} 278 279 public: 280 /** \brief Serialize a Value in <a HREF="http://www.json.org">JSON</a> format. 281 * \param out Stream to write to. (Can be ostringstream, e.g.) 282 * \param root Value to serialize. 283 * \note There is no point in deriving from Writer, since write() should not 284 * return a value. 285 */ 286 void write(JSONCPP_OSTREAM& out, const Value& root); 287 288 private: 289 void writeValue(const Value& value); 290 void writeArrayValue(const Value& value); 291 bool isMultineArray(const Value& value); 292 void pushValue(const JSONCPP_STRING& value); 293 void writeIndent(); 294 void writeWithIndent(const JSONCPP_STRING& value); 295 void indent(); 296 void unindent(); 297 void writeCommentBeforeValue(const Value& root); 298 void writeCommentAfterValueOnSameLine(const Value& root); 299 bool hasCommentForValue(const Value& value); 300 static JSONCPP_STRING normalizeEOL(const JSONCPP_STRING& text); 301 302 typedef std::vector<JSONCPP_STRING> ChildValues; 303 304 ChildValues childValues_; 305 JSONCPP_OSTREAM* document_; 306 JSONCPP_STRING indentString_; 307 unsigned int rightMargin_; 308 JSONCPP_STRING indentation_; 309 bool addChildValues_ : 1; 310 bool indented_ : 1; 311 }; 312 313 #if defined(JSON_HAS_INT64) 314 JSONCPP_STRING JSON_API valueToString(Int value); 315 JSONCPP_STRING JSON_API valueToString(UInt value); 316 #endif // if defined(JSON_HAS_INT64) 317 JSONCPP_STRING JSON_API valueToString(LargestInt value); 318 JSONCPP_STRING JSON_API valueToString(LargestUInt value); 319 JSONCPP_STRING JSON_API valueToString(double value); 320 JSONCPP_STRING JSON_API valueToString(bool value); 321 JSONCPP_STRING JSON_API valueToQuotedString(const char* value); 322 323 /// \brief Output using the StyledStreamWriter. 324 /// \see Json::operator>>() 325 JSON_API JSONCPP_OSTREAM& operator<<(JSONCPP_OSTREAM&, const Value& root); 326 327 } // namespace Json 328 329 #pragma pack(pop) 330 331 #if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING) 332 #pragma warning(pop) 333 #endif // if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING) 334 335 #endif // JSON_WRITER_H_INCLUDED 336