base/json/json_reader.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4 //
   5 // A JSON parser.  Converts strings of JSON into a Value object (see
   6 // base/values.h).
   7 // http://www.ietf.org/rfc/rfc4627.txt?number=4627
   8 //
   9 // Known limitations/deviations from the RFC:
  10 // - Only knows how to parse ints within the range of a signed 32 bit int and
  11 //   decimal numbers within a double.
  12 // - Assumes input is encoded as UTF8.  The spec says we should allow UTF-16
  13 //   (BE or LE) and UTF-32 (BE or LE) as well.
  14 // - We limit nesting to 100 levels to prevent stack overflow (this is allowed
  15 //   by the RFC).
  16 // - A Unicode FAQ ("http://unicode.org/faq/utf_bom.html") writes a data
  17 //   stream may start with a Unicode Byte-Order-Mark (U+FEFF), i.e. the input
  18 //   UTF-8 string for the JSONReader::JsonToValue() function may start with a
  19 //   UTF-8 BOM (0xEF, 0xBB, 0xBF).
  20 //   To avoid the function from mis-treating a UTF-8 BOM as an invalid
  21 //   character, the function skips a Unicode BOM at the beginning of the
  22 //   Unicode string (converted from the input UTF-8 string) before parsing it.
  23 //
  24 // TODO(tc): Add a parsing option to to relax object keys being wrapped in
  25 //   double quotes
  26 // TODO(tc): Add an option to disable comment stripping
  27
  28 #ifndef BASE_JSON_JSON_READER_H_
  29 #define BASE_JSON_JSON_READER_H_
  30
  31 #include <string>
  32
  33 #include "base/base_export.h"
  34 #include "base/basictypes.h"
  35 #include "base/memory/scoped_ptr.h"
  36 #include "base/strings/string_piece.h"
  37
  38 namespace base {
  39
  40 class Value;
  41
  42 namespace internal {
  43 class JSONParser;
  44 }
  45
  46 enum JSONParserOptions {
  47   // Parses the input strictly according to RFC 4627, except for where noted
  48   // above.
  49   JSON_PARSE_RFC = 0,
  50
  51   // Allows commas to exist after the last element in structures.
  52   JSON_ALLOW_TRAILING_COMMAS = 1 << 0,
  53
  54   // The parser can perform optimizations by placing hidden data in the root of
  55   // the JSON object, which speeds up certain operations on children. However,
  56   // if the child is Remove()d from root, it would result in use-after-free
  57   // unless it is DeepCopy()ed or this option is used.
  58   JSON_DETACHABLE_CHILDREN = 1 << 1,
  59 };
  60
  61 class BASE_EXPORT JSONReader {
  62  public:
  63   // Error codes during parsing.
  64   enum JsonParseError {
  65     JSON_NO_ERROR = 0,
  66     JSON_INVALID_ESCAPE,
  67     JSON_SYNTAX_ERROR,
  68     JSON_UNEXPECTED_TOKEN,
  69     JSON_TRAILING_COMMA,
  70     JSON_TOO_MUCH_NESTING,
  71     JSON_UNEXPECTED_DATA_AFTER_ROOT,
  72     JSON_UNSUPPORTED_ENCODING,
  73     JSON_UNQUOTED_DICTIONARY_KEY,
  74     JSON_PARSE_ERROR_COUNT
  75   };
  76
  77   // String versions of parse error codes.
  78   static const char kInvalidEscape[];
  79   static const char kSyntaxError[];
  80   static const char kUnexpectedToken[];
  81   static const char kTrailingComma[];
  82   static const char kTooMuchNesting[];
  83   static const char kUnexpectedDataAfterRoot[];
  84   static const char kUnsupportedEncoding[];
  85   static const char kUnquotedDictionaryKey[];
  86
  87   // Constructs a reader with the default options, JSON_PARSE_RFC.
  88   JSONReader();
  89
  90   // Constructs a reader with custom options.
  91   explicit JSONReader(int options);
  92
  93   ~JSONReader();
  94
  95   // Reads and parses |json|, returning a Value. The caller owns the returned
  96   // instance. If |json| is not a properly formed JSON string, returns NULL.
  97   static scoped_ptr<Value> Read(const StringPiece& json);
  98   // TODO(estade): remove this bare pointer version.
  99   static Value* DeprecatedRead(const StringPiece& json);
 100
 101   // Reads and parses |json|, returning a Value owned by the caller. The
 102   // parser respects the given |options|. If the input is not properly formed,
 103   // returns NULL.
 104   static scoped_ptr<Value> Read(const StringPiece& json, int options);
 105   // TODO(estade): remove this bare pointer version.
 106   static Value* DeprecatedRead(const StringPiece& json, int options);
 107
 108   // Reads and parses |json| like Read(). |error_code_out| and |error_msg_out|
 109   // are optional. If specified and NULL is returned, they will be populated
 110   // an error code and a formatted error message (including error location if
 111   // appropriate). Otherwise, they will be unmodified.
 112   static scoped_ptr<Value> ReadAndReturnError(const StringPiece& json,
 113                                               int options,  // JSONParserOptions
 114                                               int* error_code_out,
 115                                               std::string* error_msg_out);
 116   // TODO(estade): remove this bare pointer version.
 117   static Value* DeprecatedReadAndReturnError(const StringPiece& json,
 118                                              int options,  // JSONParserOptions
 119                                              int* error_code_out,
 120                                              std::string* error_msg_out);
 121
 122   // Converts a JSON parse error code into a human readable message.
 123   // Returns an empty string if error_code is JSON_NO_ERROR.
 124   static std::string ErrorCodeToString(JsonParseError error_code);
 125
 126   // Parses an input string into a Value that is owned by the caller.
 127   scoped_ptr<Value> ReadToValue(const std::string& json);
 128
 129   // Returns the error code if the last call to ReadToValue() failed.
 130   // Returns JSON_NO_ERROR otherwise.
 131   JsonParseError error_code() const;
 132
 133   // Converts error_code_ to a human-readable string, including line and column
 134   // numbers if appropriate.
 135   std::string GetErrorMessage() const;
 136
 137  private:
 138   scoped_ptr<internal::JSONParser> parser_;
 139 };
 140
 141 }  // namespace base
 142
 143 #endif  // BASE_JSON_JSON_READER_H_