blob: 54079069e2216899cace9b14f954141a8ca3b5d1 [file] [log] [blame]
Baptiste Lepilleur7469f1d2010-04-20 21:35:19 +00001// 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
Christopher Dunn6d135cb2007-06-13 15:51:04 +00006#ifndef JSON_WRITER_H_INCLUDED
Aaron Jacobs9fa4e842014-07-01 08:48:54 +10007#define JSON_WRITER_H_INCLUDED
Christopher Dunn6d135cb2007-06-13 15:51:04 +00008
Baptiste Lepilleureadc4782011-05-02 21:09:30 +00009#if !defined(JSON_IS_AMALGAMATION)
Aaron Jacobs9fa4e842014-07-01 08:48:54 +100010#include "value.h"
Baptiste Lepilleureadc4782011-05-02 21:09:30 +000011#endif // if !defined(JSON_IS_AMALGAMATION)
Aaron Jacobs9fa4e842014-07-01 08:48:54 +100012#include <vector>
13#include <string>
Christopher Dunn6d135cb2007-06-13 15:51:04 +000014
Aaron Jacobs9fa4e842014-07-01 08:48:54 +100015// Disable warning C4251: <data member>: <type> needs to have dll-interface to
16// be used by...
Baptiste Lepilleureafd7022013-05-08 20:21:11 +000017#if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING)
Aaron Jacobs9fa4e842014-07-01 08:48:54 +100018#pragma warning(push)
19#pragma warning(disable : 4251)
Baptiste Lepilleureafd7022013-05-08 20:21:11 +000020#endif // if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING)
21
Christopher Dunn6d135cb2007-06-13 15:51:04 +000022namespace Json {
23
Aaron Jacobs9fa4e842014-07-01 08:48:54 +100024class Value;
Christopher Dunn489707f2015-01-22 15:25:30 -060025class StreamWriterBuilder;
26
27/**
28
29Usage:
Christopher Dunn9da9f842015-01-25 19:20:43 -060030\code
Christopher Dunn489707f2015-01-22 15:25:30 -060031 using namespace Json;
32 Value value;
Christopher Dunnfe3979c2015-01-24 13:54:28 -060033 StreamWriter::Builder builder;
Christopher Dunnc7b39c22015-01-25 18:45:59 -060034 builder.withCommentStyle(StreamWriter::CommentStyle::None);
Christopher Dunn77ce0572015-01-23 07:11:06 -060035 std::shared_ptr<StreamWriter> writer(
36 builder.newStreamWriter(&std::cout));
37 writer->write(value);
38 std::cout.flush();
Christopher Dunn9da9f842015-01-25 19:20:43 -060039\endcode
Christopher Dunn489707f2015-01-22 15:25:30 -060040*/
Christopher Dunn5fbfe3c2015-01-22 14:31:32 -060041class JSON_API StreamWriter {
42protected:
43 std::ostream& sout_; // not owned; will not delete
44public:
Christopher Dunn9da9f842015-01-25 19:20:43 -060045 /// Decide whether to write comments.
46 enum class CommentStyle {
47 None, ///< Drop all comments.
48 Most, ///< Recover odd behavior of previous versions (not implemented yet).
49 All ///< Keep all comments.
50 };
Christopher Dunn489707f2015-01-22 15:25:30 -060051
Christopher Dunnfe3979c2015-01-24 13:54:28 -060052 /// Keep a reference, but do not take ownership of `sout`.
Christopher Dunn5fbfe3c2015-01-22 14:31:32 -060053 StreamWriter(std::ostream* sout);
54 virtual ~StreamWriter();
55 /// Write Value into document as configured in sub-class.
56 /// \return zero on success
57 /// \throw std::exception possibly, depending on configuration
Christopher Dunnbeb6f352015-01-23 07:51:40 -060058 virtual int write(Value const& root) = 0;
Christopher Dunn5fbfe3c2015-01-22 14:31:32 -060059
Christopher Dunn489707f2015-01-22 15:25:30 -060060 /// Because this Builder is non-virtual, we can safely add
61 /// methods without a major version bump.
62 /// \see http://stackoverflow.com/questions/14875052/pure-virtual-functions-and-binary-compatibility
63 class Builder {
64 StreamWriterBuilder* own_;
Christopher Dunnfe3979c2015-01-24 13:54:28 -060065 Builder(Builder const&); // noncopyable
66 void operator=(Builder const&); // noncopyable
Christopher Dunn489707f2015-01-22 15:25:30 -060067 public:
Christopher Dunnfe3979c2015-01-24 13:54:28 -060068 Builder();
Christopher Dunn489707f2015-01-22 15:25:30 -060069 ~Builder(); // delete underlying StreamWriterBuilder
Christopher Dunn5fbfe3c2015-01-22 14:31:32 -060070
Christopher Dunnc7b39c22015-01-25 18:45:59 -060071 Builder& withCommentStyle(CommentStyle cs); /// default: All
Christopher Dunn4d649402015-01-22 16:08:21 -060072 /** \brief Write in human-friendly style.
73
74 If "", then skip all indentation, newlines, and comments,
75 which implies CommentStyle::None.
76 Default: "\t"
77 */
Christopher Dunnc7b39c22015-01-25 18:45:59 -060078 Builder& withIndentation(std::string indentation);
Christopher Dunnd78caa32015-01-25 18:15:54 -060079 /** \brief Drop the "null" string from the writer's output for nullValues.
80 * Strictly speaking, this is not valid JSON. But when the output is being
81 * fed to a browser's Javascript, it makes for smaller output and the
82 * browser can handle the output just fine.
83 */
Christopher Dunnc7b39c22015-01-25 18:45:59 -060084 Builder& withDropNullPlaceholders(bool v);
Christopher Dunnd78caa32015-01-25 18:15:54 -060085 /** \brief Do not add \n at end of document.
86 * Normally, we add an extra newline, just because.
87 */
Christopher Dunnc7b39c22015-01-25 18:45:59 -060088 Builder& withOmitEndingLineFeed(bool v);
Christopher Dunnd78caa32015-01-25 18:15:54 -060089 /** \brief Add a space after ':'.
90 * If indentation is non-empty, we surround colon with whitespace,
91 * e.g. " : "
92 * This will add back the trailing space when there is no indentation.
93 * This seems dubious when the entire document is on a single line,
94 * but we leave this here to repduce the behavior of the old `FastWriter`.
95 */
Christopher Dunnc7b39c22015-01-25 18:45:59 -060096 Builder& withEnableYAMLCompatibility(bool v);
Christopher Dunn489707f2015-01-22 15:25:30 -060097
98 /// Do not take ownership of sout, but maintain a reference.
Christopher Dunn9243d602015-01-23 08:38:32 -060099 StreamWriter* newStreamWriter(std::ostream* sout) const;
Christopher Dunn489707f2015-01-22 15:25:30 -0600100 };
Christopher Dunn5fbfe3c2015-01-22 14:31:32 -0600101};
102
103/// \brief Write into stringstream, then return string, for convenience.
Christopher Dunn9243d602015-01-23 08:38:32 -0600104std::string writeString(Value const& root, StreamWriter::Builder const& builder);
Christopher Dunn5fbfe3c2015-01-22 14:31:32 -0600105
106
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000107/** \brief Abstract class for writers.
Christopher Dunnc7b39c22015-01-25 18:45:59 -0600108 * \deprecated Use StreamWriter::Builder.
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000109 */
110class JSON_API Writer {
111public:
112 virtual ~Writer();
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000113
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000114 virtual std::string write(const Value& root) = 0;
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000115};
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000116
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000117/** \brief Outputs a Value in <a HREF="http://www.json.org">JSON</a> format
118 *without formatting (not human friendly).
119 *
120 * The JSON document is written in a single line. It is not intended for 'human'
121 *consumption,
122 * but may be usefull to support feature such as RPC where bandwith is limited.
123 * \sa Reader, Value
Christopher Dunnc7b39c22015-01-25 18:45:59 -0600124 * \deprecated Use StreamWriter::Builder.
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000125 */
126class JSON_API FastWriter : public Writer {
127public:
128 FastWriter();
129 virtual ~FastWriter() {}
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000130
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000131 void enableYAMLCompatibility();
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000132
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000133 /** \brief Drop the "null" string from the writer's output for nullValues.
134 * Strictly speaking, this is not valid JSON. But when the output is being
135 * fed to a browser's Javascript, it makes for smaller output and the
136 * browser can handle the output just fine.
137 */
138 void dropNullPlaceholders();
Aaron Jacobsae3c7a72012-03-12 04:53:57 +0000139
Don Milham5bf16102014-09-02 17:09:07 -0600140 void omitEndingLineFeed();
141
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000142public: // overridden from Writer
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000143 virtual std::string write(const Value& root);
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000144
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000145private:
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000146 void writeValue(const Value& value);
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000147
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000148 std::string document_;
149 bool yamlCompatiblityEnabled_;
150 bool dropNullPlaceholders_;
Don Milham5bf16102014-09-02 17:09:07 -0600151 bool omitEndingLineFeed_;
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000152};
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000153
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000154/** \brief Writes a Value in <a HREF="http://www.json.org">JSON</a> format in a
155 *human friendly way.
156 *
157 * The rules for line break and indent are as follow:
158 * - Object value:
159 * - if empty then print {} without indent and line break
160 * - if not empty the print '{', line break & indent, print one value per
161 *line
162 * and then unindent and line break and print '}'.
163 * - Array value:
164 * - if empty then print [] without indent and line break
165 * - if the array contains no object value, empty array or some other value
166 *types,
167 * and all the values fit on one lines, then print the array on a single
168 *line.
169 * - otherwise, it the values do not fit on one line, or the array contains
170 * object or non empty array, then print one value per line.
171 *
172 * If the Value have comments then they are outputed according to their
173 *#CommentPlacement.
174 *
175 * \sa Reader, Value, Value::setComment()
Christopher Dunnc7b39c22015-01-25 18:45:59 -0600176 * \deprecated Use StreamWriter::Builder.
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000177 */
178class JSON_API StyledWriter : public Writer {
179public:
180 StyledWriter();
181 virtual ~StyledWriter() {}
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000182
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000183public: // overridden from Writer
184 /** \brief Serialize a Value in <a HREF="http://www.json.org">JSON</a> format.
185 * \param root Value to serialize.
186 * \return String containing the JSON document that represents the root value.
187 */
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000188 virtual std::string write(const Value& root);
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000189
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000190private:
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000191 void writeValue(const Value& value);
192 void writeArrayValue(const Value& value);
193 bool isMultineArray(const Value& value);
194 void pushValue(const std::string& value);
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000195 void writeIndent();
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000196 void writeWithIndent(const std::string& value);
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000197 void indent();
198 void unindent();
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000199 void writeCommentBeforeValue(const Value& root);
200 void writeCommentAfterValueOnSameLine(const Value& root);
201 bool hasCommentForValue(const Value& value);
202 static std::string normalizeEOL(const std::string& text);
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000203
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000204 typedef std::vector<std::string> ChildValues;
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000205
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000206 ChildValues childValues_;
207 std::string document_;
208 std::string indentString_;
209 int rightMargin_;
210 int indentSize_;
211 bool addChildValues_;
212};
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000213
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000214/** \brief Writes a Value in <a HREF="http://www.json.org">JSON</a> format in a
215 human friendly way,
216 to a stream rather than to a string.
217 *
218 * The rules for line break and indent are as follow:
219 * - Object value:
220 * - if empty then print {} without indent and line break
221 * - if not empty the print '{', line break & indent, print one value per
222 line
223 * and then unindent and line break and print '}'.
224 * - Array value:
225 * - if empty then print [] without indent and line break
226 * - if the array contains no object value, empty array or some other value
227 types,
228 * and all the values fit on one lines, then print the array on a single
229 line.
230 * - otherwise, it the values do not fit on one line, or the array contains
231 * object or non empty array, then print one value per line.
232 *
233 * If the Value have comments then they are outputed according to their
234 #CommentPlacement.
235 *
236 * \param indentation Each level will be indented by this amount extra.
237 * \sa Reader, Value, Value::setComment()
Christopher Dunnc7b39c22015-01-25 18:45:59 -0600238 * \deprecated Use StreamWriter::Builder.
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000239 */
240class JSON_API StyledStreamWriter {
241public:
242 StyledStreamWriter(std::string indentation = "\t");
243 ~StyledStreamWriter() {}
Christopher Dunn605cd7e2007-06-13 15:55:50 +0000244
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000245public:
246 /** \brief Serialize a Value in <a HREF="http://www.json.org">JSON</a> format.
247 * \param out Stream to write to. (Can be ostringstream, e.g.)
248 * \param root Value to serialize.
249 * \note There is no point in deriving from Writer, since write() should not
250 * return a value.
251 */
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000252 void write(std::ostream& out, const Value& root);
Christopher Dunn605cd7e2007-06-13 15:55:50 +0000253
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000254private:
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000255 void writeValue(const Value& value);
256 void writeArrayValue(const Value& value);
257 bool isMultineArray(const Value& value);
258 void pushValue(const std::string& value);
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000259 void writeIndent();
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000260 void writeWithIndent(const std::string& value);
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000261 void indent();
262 void unindent();
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000263 void writeCommentBeforeValue(const Value& root);
264 void writeCommentAfterValueOnSameLine(const Value& root);
265 bool hasCommentForValue(const Value& value);
266 static std::string normalizeEOL(const std::string& text);
Christopher Dunn605cd7e2007-06-13 15:55:50 +0000267
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000268 typedef std::vector<std::string> ChildValues;
Christopher Dunn605cd7e2007-06-13 15:55:50 +0000269
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000270 ChildValues childValues_;
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000271 std::ostream* document_;
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000272 std::string indentString_;
273 int rightMargin_;
274 std::string indentation_;
Christopher Dunnd3830562015-01-23 13:09:43 -0600275 bool addChildValues_ : 1;
276 bool indented_ : 1;
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000277};
Christopher Dunn605cd7e2007-06-13 15:55:50 +0000278
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000279#if defined(JSON_HAS_INT64)
280std::string JSON_API valueToString(Int value);
281std::string JSON_API valueToString(UInt value);
282#endif // if defined(JSON_HAS_INT64)
283std::string JSON_API valueToString(LargestInt value);
284std::string JSON_API valueToString(LargestUInt value);
285std::string JSON_API valueToString(double value);
286std::string JSON_API valueToString(bool value);
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000287std::string JSON_API valueToQuotedString(const char* value);
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000288
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000289/// \brief Output using the StyledStreamWriter.
290/// \see Json::operator>>()
Aaron Jacobs11086dd2014-09-15 10:15:29 +1000291JSON_API std::ostream& operator<<(std::ostream&, const Value& root);
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000292
293} // namespace Json
294
Baptiste Lepilleureafd7022013-05-08 20:21:11 +0000295#if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING)
Aaron Jacobs9fa4e842014-07-01 08:48:54 +1000296#pragma warning(pop)
Baptiste Lepilleureafd7022013-05-08 20:21:11 +0000297#endif // if defined(JSONCPP_DISABLE_DLL_INTERFACE_WARNING)
298
Christopher Dunn6d135cb2007-06-13 15:51:04 +0000299#endif // JSON_WRITER_H_INCLUDED