folly/json.h

   1 /*
   2  * Copyright 2013 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 #ifndef FOLLY_JSON_H_
  42 #define FOLLY_JSON_H_
  43
  44 #include "folly/dynamic.h"
  45 #include "folly/FBString.h"
  46 #include "folly/Range.h"
  47
  48 namespace folly {
  49
  50 //////////////////////////////////////////////////////////////////////
  51
  52 namespace json {
  53
  54   struct serialization_opts {
  55     explicit serialization_opts()
  56       : allow_non_string_keys(false)
  57       , javascript_safe(false)
  58       , pretty_formatting(false)
  59       , encode_non_ascii(false)
  60       , validate_utf8(false)
  61     {}
  62
  63     // If true, keys in an object can be non-strings.  (In strict
  64     // JSON, object keys must be strings.)  This is used by dynamic's
  65     // operator<<.
  66     bool allow_non_string_keys;
  67
  68     /*
  69      * If true, refuse to serialize 64-bit numbers that cannot be
  70      * precisely represented by fit a double---instead, throws an
  71      * exception if the document contains this.
  72      */
  73     bool javascript_safe;
  74
  75     // If true, the serialized json will contain space and newlines to
  76     // try to be minimally "pretty".
  77     bool pretty_formatting;
  78
  79     // If true, non-ASCII utf8 characters would be encoded as \uXXXX.
  80     bool encode_non_ascii;
  81
  82     // Check that strings are valid utf8
  83     bool validate_utf8;
  84   };
  85
  86   /*
  87    * Main JSON serialization routine taking folly::dynamic parameters.
  88    * For the most common use cases there are simpler functions in the
  89    * main folly namespace below.
  90    */
  91   fbstring serialize(dynamic const&, serialization_opts const&);
  92
  93   /*
  94    * Escape a string so that it is legal to print it in JSON text and
  95    * append the result to out.
  96    */
  97
  98   void escapeString(StringPiece input,
  99                     fbstring& out,
 100                     const serialization_opts& opts);
 101 }
 102
 103 //////////////////////////////////////////////////////////////////////
 104
 105 /*
 106  * Parse a json blob out of a range and produce a dynamic representing
 107  * it.
 108  */
 109 dynamic parseJson(StringPiece, json::serialization_opts const&);
 110 dynamic parseJson(StringPiece);
 111
 112 /*
 113  * Serialize a dynamic into a json string.
 114  */
 115 fbstring toJson(dynamic const&);
 116
 117 /*
 118  * Same as the above, except format the json with some minimal
 119  * indentation.
 120  */
 121 fbstring toPrettyJson(dynamic const&);
 122
 123 //////////////////////////////////////////////////////////////////////
 124
 125 }
 126
 127 #endif