folly/json.h

   1 /*
   2  * Copyright 2017 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/Function.h>
  47 #include <folly/Range.h>
  48 #include <folly/dynamic.h>
  49
  50 namespace folly {
  51
  52 //////////////////////////////////////////////////////////////////////
  53
  54 namespace json {
  55
  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),
  62         validate_utf8(false),
  63         allow_trailing_comma(false),
  64         sort_keys(false),
  65         skip_invalid_utf8(false),
  66         allow_nan_inf(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) {}
  72
  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
  75   // operator<<.
  76   bool allow_non_string_keys;
  77
  78   /*
  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.
  82    */
  83   bool javascript_safe;
  84
  85   // If true, the serialized json will contain space and newlines to
  86   // try to be minimally "pretty".
  87   bool pretty_formatting;
  88
  89   // If true, non-ASCII utf8 characters would be encoded as \uXXXX.
  90   bool encode_non_ascii;
  91
  92   // Check that strings are valid utf8
  93   bool validate_utf8;
  94
  95   // Allow trailing comma in lists of values / items
  96   bool allow_trailing_comma;
  97
  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.
 101   bool sort_keys;
 102
 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;
 106
 107   // Replace invalid utf8 characters with U+FFFD and continue
 108   bool skip_invalid_utf8;
 109
 110   // true to allow NaN or INF values
 111   bool allow_nan_inf;
 112
 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;
 117
 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;
 121
 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;
 125
 126   // Recursion limit when parsing.
 127   unsigned int recursion_limit;
 128 };
 129
 130 /*
 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.
 134  */
 135 std::string serialize(dynamic const&, serialization_opts const&);
 136
 137 /*
 138  * Escape a string so that it is legal to print it in JSON text and
 139  * append the result to out.
 140  */
 141
 142 void escapeString(
 143     StringPiece input,
 144     std::string& out,
 145     const serialization_opts& opts);
 146
 147 /*
 148  * Strip all C99-like comments (i.e. // and / * ... * /)
 149  */
 150 std::string stripComments(StringPiece jsonC);
 151 } // namespace json
 152
 153 //////////////////////////////////////////////////////////////////////
 154
 155 /*
 156  * Parse a json blob out of a range and produce a dynamic representing
 157  * it.
 158  */
 159 dynamic parseJson(StringPiece, json::serialization_opts const&);
 160 dynamic parseJson(StringPiece);
 161
 162 /*
 163  * Serialize a dynamic into a json string.
 164  */
 165 std::string toJson(dynamic const&);
 166
 167 /*
 168  * Same as the above, except format the json with some minimal
 169  * indentation.
 170  */
 171 std::string toPrettyJson(dynamic const&);
 172
 173 /*
 174  * Printer for GTest.
 175  * Uppercase name to fill GTest's API, which calls this method through ADL.
 176  */
 177 void PrintTo(const dynamic&, std::ostream*);
 178 //////////////////////////////////////////////////////////////////////
 179
 180 } // namespace folly