Home | History | Annotate | Download | only in json 
      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 class Value;
     40 
     41 namespace internal {
     42 class JSONParser;
     43 }
     44 }
     45 
     46 namespace base {
     47 
     48 enum JSONParserOptions {
     49   // Parses the input strictly according to RFC 4627, except for where noted
     50   // above.
     51   JSON_PARSE_RFC = 0,
     52 
     53   // Allows commas to exist after the last element in structures.
     54   JSON_ALLOW_TRAILING_COMMAS = 1 << 0,
     55 
     56   // The parser can perform optimizations by placing hidden data in the root of
     57   // the JSON object, which speeds up certain operations on children. However,
     58   // if the child is Remove()d from root, it would result in use-after-free
     59   // unless it is DeepCopy()ed or this option is used.
     60   JSON_DETACHABLE_CHILDREN = 1 << 1,
     61 };
     62 
     63 class BASE_EXPORT JSONReader {
     64  public:
     65   // Error codes during parsing.
     66   enum JsonParseError {
     67     JSON_NO_ERROR = 0,
     68     JSON_INVALID_ESCAPE,
     69     JSON_SYNTAX_ERROR,
     70     JSON_UNEXPECTED_TOKEN,
     71     JSON_TRAILING_COMMA,
     72     JSON_TOO_MUCH_NESTING,
     73     JSON_UNEXPECTED_DATA_AFTER_ROOT,
     74     JSON_UNSUPPORTED_ENCODING,
     75     JSON_UNQUOTED_DICTIONARY_KEY,
     76   };
     77 
     78   // String versions of parse error codes.
     79   static const char* kInvalidEscape;
     80   static const char* kSyntaxError;
     81   static const char* kUnexpectedToken;
     82   static const char* kTrailingComma;
     83   static const char* kTooMuchNesting;
     84   static const char* kUnexpectedDataAfterRoot;
     85   static const char* kUnsupportedEncoding;
     86   static const char* kUnquotedDictionaryKey;
     87 
     88   // Constructs a reader with the default options, JSON_PARSE_RFC.
     89   JSONReader();
     90 
     91   // Constructs a reader with custom options.
     92   explicit JSONReader(int options);
     93 
     94   ~JSONReader();
     95 
     96   // Reads and parses |json|, returning a Value. The caller owns the returned
     97   // instance. If |json| is not a properly formed JSON string, returns NULL.
     98   static Value* Read(const StringPiece& json);
     99 
    100   // Reads and parses |json|, returning a Value owned by the caller. The
    101   // parser respects the given |options|. If the input is not properly formed,
    102   // returns NULL.
    103   static Value* Read(const StringPiece& json, int options);
    104 
    105   // Reads and parses |json| like Read(). |error_code_out| and |error_msg_out|
    106   // are optional. If specified and NULL is returned, they will be populated
    107   // an error code and a formatted error message (including error location if
    108   // appropriate). Otherwise, they will be unmodified.
    109   static Value* ReadAndReturnError(const StringPiece& json,
    110                                    int options,  // JSONParserOptions
    111                                    int* error_code_out,
    112                                    std::string* error_msg_out);
    113 
    114   // Converts a JSON parse error code into a human readable message.
    115   // Returns an empty string if error_code is JSON_NO_ERROR.
    116   static std::string ErrorCodeToString(JsonParseError error_code);
    117 
    118   // Parses an input string into a Value that is owned by the caller.
    119   Value* ReadToValue(const std::string& json);
    120 
    121   // Returns the error code if the last call to ReadToValue() failed.
    122   // Returns JSON_NO_ERROR otherwise.
    123   JsonParseError error_code() const;
    124 
    125   // Converts error_code_ to a human-readable string, including line and column
    126   // numbers if appropriate.
    127   std::string GetErrorMessage() const;
    128 
    129  private:
    130   scoped_ptr<internal::JSONParser> parser_;
    131 };
    132 
    133 }  // namespace base
    134 
    135 #endif  // BASE_JSON_JSON_READER_H_
    136