2 * Copyright 2017 Facebook, Inc.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
19 * Serialize and deserialize folly::dynamic values as JSON.
21 * Before you use this you should probably understand the basic
22 * concepts in the JSON type system:
24 * Value : String | Bool | Null | Object | Array | Number
25 * String : UTF-8 sequence
26 * Object : (String, Value) pairs, with unique String keys
27 * Array : ordered list of Values
30 * Number : (representation unspecified)
32 * ... That's about it. For more information see http://json.org or
35 * If your dynamic has anything illegal with regard to this type
36 * system, the serializer will throw.
38 * @author Jordan DeLong <delong.j@fb.com>
46 #include <folly/Function.h>
47 #include <folly/Range.h>
48 #include <folly/dynamic.h>
52 //////////////////////////////////////////////////////////////////////
56 struct serialization_opts {
57 explicit serialization_opts()
58 : allow_non_string_keys(false),
59 javascript_safe(false),
60 pretty_formatting(false),
61 encode_non_ascii(false),
63 allow_trailing_comma(false),
65 skip_invalid_utf8(false),
67 double_mode(double_conversion::DoubleToStringConverter::SHORTEST),
68 double_num_digits(0), // ignored when mode is SHORTEST
69 double_fallback(false),
70 parse_numbers_as_strings(false),
71 recursion_limit(100) {}
73 // If true, keys in an object can be non-strings. (In strict
74 // JSON, object keys must be strings.) This is used by dynamic's
76 bool allow_non_string_keys;
79 * If true, refuse to serialize 64-bit numbers that cannot be
80 * precisely represented by fit a double---instead, throws an
81 * exception if the document contains this.
85 // If true, the serialized json will contain space and newlines to
86 // try to be minimally "pretty".
87 bool pretty_formatting;
89 // If true, non-ASCII utf8 characters would be encoded as \uXXXX.
90 bool encode_non_ascii;
92 // Check that strings are valid utf8
95 // Allow trailing comma in lists of values / items
96 bool allow_trailing_comma;
98 // Sort keys of all objects before printing out (potentially slow)
99 // using dynamic::operator<.
100 // Has no effect if sort_keys_by is set.
103 // Sort keys of all objects before printing out (potentially slow)
104 // using the provided less functor.
105 Function<bool(dynamic const&, dynamic const&) const> sort_keys_by;
107 // Replace invalid utf8 characters with U+FFFD and continue
108 bool skip_invalid_utf8;
110 // true to allow NaN or INF values
113 // Options for how to print floating point values. See Conv.h
114 // toAppend implementation for floating point for more info
115 double_conversion::DoubleToStringConverter::DtoaMode double_mode;
116 unsigned int double_num_digits;
118 // Fallback to double when a value that looks like integer is too big to
119 // fit in an int64_t. Can result in loss a of precision.
120 bool double_fallback;
122 // Do not parse numbers. Instead, store them as strings and leave the
123 // conversion up to the user.
124 bool parse_numbers_as_strings;
126 // Recursion limit when parsing.
127 unsigned int recursion_limit;
131 * Main JSON serialization routine taking folly::dynamic parameters.
132 * For the most common use cases there are simpler functions in the
133 * main folly namespace below.
135 std::string serialize(dynamic const&, serialization_opts const&);
138 * Escape a string so that it is legal to print it in JSON text and
139 * append the result to out.
145 const serialization_opts& opts);
148 * Strip all C99-like comments (i.e. // and / * ... * /)
150 std::string stripComments(StringPiece jsonC);
153 //////////////////////////////////////////////////////////////////////
156 * Parse a json blob out of a range and produce a dynamic representing
159 dynamic parseJson(StringPiece, json::serialization_opts const&);
160 dynamic parseJson(StringPiece);
163 * Serialize a dynamic into a json string.
165 std::string toJson(dynamic const&);
168 * Same as the above, except format the json with some minimal
171 std::string toPrettyJson(dynamic const&);
175 * Uppercase name to fill GTest's API, which calls this method through ADL.
177 void PrintTo(const dynamic&, std::ostream*);
178 //////////////////////////////////////////////////////////////////////