Special-case /dev/null in open in the portability header
[folly.git] / folly / json.h
1 /*
2  * Copyright 2016 Facebook, Inc.
3  *
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
7  *
8  *   http://www.apache.org/licenses/LICENSE-2.0
9  *
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.
15  */
16
17 /**
18  *
19  * Serialize and deserialize folly::dynamic values as JSON.
20  *
21  * Before you use this you should probably understand the basic
22  * concepts in the JSON type system:
23  *
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
28  *    Null   : null
29  *    Bool   : true | false
30  *    Number : (representation unspecified)
31  *
32  * ... That's about it.  For more information see http://json.org or
33  * look up RFC 4627.
34  *
35  * If your dynamic has anything illegal with regard to this type
36  * system, the serializer will throw.
37  *
38  * @author Jordan DeLong <delong.j@fb.com>
39  */
40
41 #pragma once
42
43 #include <iosfwd>
44 #include <string>
45
46 #include <folly/dynamic.h>
47 #include <folly/Range.h>
48
49 namespace folly {
50
51 //////////////////////////////////////////////////////////////////////
52
53 namespace json {
54
55   struct serialization_opts {
56     explicit serialization_opts()
57         : allow_non_string_keys(false),
58           javascript_safe(false),
59           pretty_formatting(false),
60           encode_non_ascii(false),
61           validate_utf8(false),
62           allow_trailing_comma(false),
63           sort_keys(false),
64           skip_invalid_utf8(false),
65           allow_nan_inf(false),
66           double_mode(double_conversion::DoubleToStringConverter::SHORTEST),
67           double_num_digits(0), // ignored when mode is SHORTEST
68           double_fallback(false),
69           parse_numbers_as_strings(false),
70           recursion_limit(100) {}
71
72     // If true, keys in an object can be non-strings.  (In strict
73     // JSON, object keys must be strings.)  This is used by dynamic's
74     // operator<<.
75     bool allow_non_string_keys;
76
77     /*
78      * If true, refuse to serialize 64-bit numbers that cannot be
79      * precisely represented by fit a double---instead, throws an
80      * exception if the document contains this.
81      */
82     bool javascript_safe;
83
84     // If true, the serialized json will contain space and newlines to
85     // try to be minimally "pretty".
86     bool pretty_formatting;
87
88     // If true, non-ASCII utf8 characters would be encoded as \uXXXX.
89     bool encode_non_ascii;
90
91     // Check that strings are valid utf8
92     bool validate_utf8;
93
94     // Allow trailing comma in lists of values / items
95     bool allow_trailing_comma;
96
97     // Sort keys of all objects before printing out (potentially slow)
98     bool sort_keys;
99
100     // Replace invalid utf8 characters with U+FFFD and continue
101     bool skip_invalid_utf8;
102
103     // true to allow NaN or INF values
104     bool allow_nan_inf;
105
106     // Options for how to print floating point values.  See Conv.h
107     // toAppend implementation for floating point for more info
108     double_conversion::DoubleToStringConverter::DtoaMode double_mode;
109     unsigned int double_num_digits;
110
111     // Fallback to double when a value that looks like integer is too big to
112     // fit in an int64_t. Can result in loss a of precision.
113     bool double_fallback;
114
115     // Do not parse numbers. Instead, store them as strings and leave the
116     // conversion up to the user.
117     bool parse_numbers_as_strings;
118
119     // Recursion limit when parsing.
120     unsigned int recursion_limit;
121   };
122
123   /*
124    * Main JSON serialization routine taking folly::dynamic parameters.
125    * For the most common use cases there are simpler functions in the
126    * main folly namespace below.
127    */
128   std::string serialize(dynamic const&, serialization_opts const&);
129
130   /*
131    * Escape a string so that it is legal to print it in JSON text and
132    * append the result to out.
133    */
134
135   void escapeString(
136       StringPiece input,
137       std::string& out,
138       const serialization_opts& opts);
139
140   /*
141    * Strip all C99-like comments (i.e. // and / * ... * /)
142    */
143   std::string stripComments(StringPiece jsonC);
144 }
145
146 //////////////////////////////////////////////////////////////////////
147
148 /*
149  * Parse a json blob out of a range and produce a dynamic representing
150  * it.
151  */
152 dynamic parseJson(StringPiece, json::serialization_opts const&);
153 dynamic parseJson(StringPiece);
154
155 /*
156  * Serialize a dynamic into a json string.
157  */
158 std::string toJson(dynamic const&);
159
160 /*
161  * Same as the above, except format the json with some minimal
162  * indentation.
163  */
164 std::string toPrettyJson(dynamic const&);
165
166 /*
167  * Printer for GTest.
168  * Uppercase name to fill GTest's API, which calls this method through ADL.
169  */
170 void PrintTo(const dynamic&, std::ostream*);
171 //////////////////////////////////////////////////////////////////////
172
173 }