Line data Source code
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 0 : 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 0 : 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();
163 0 : ~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();
215 0 : ~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");
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
|
