Debian Codegraph @

Utilities/cmjsoncpp/include/json/writer.h

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