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 38namespace base { 39 40class Value; 41 42namespace internal { 43class JSONParser; 44} 45 46enum 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 61class 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 Value* Read(const StringPiece& json); 98 99 // Reads and parses |json|, returning a Value owned by the caller. The 100 // parser respects the given |options|. If the input is not properly formed, 101 // returns NULL. 102 static Value* Read(const StringPiece& json, int options); 103 104 // Reads and parses |json| like Read(). |error_code_out| and |error_msg_out| 105 // are optional. If specified and NULL is returned, they will be populated 106 // an error code and a formatted error message (including error location if 107 // appropriate). Otherwise, they will be unmodified. 108 static Value* ReadAndReturnError(const StringPiece& json, 109 int options, // JSONParserOptions 110 int* error_code_out, 111 std::string* error_msg_out); 112 113 // Converts a JSON parse error code into a human readable message. 114 // Returns an empty string if error_code is JSON_NO_ERROR. 115 static std::string ErrorCodeToString(JsonParseError error_code); 116 117 // Parses an input string into a Value that is owned by the caller. 118 Value* ReadToValue(const std::string& json); 119 120 // Returns the error code if the last call to ReadToValue() failed. 121 // Returns JSON_NO_ERROR otherwise. 122 JsonParseError error_code() const; 123 124 // Converts error_code_ to a human-readable string, including line and column 125 // numbers if appropriate. 126 std::string GetErrorMessage() const; 127 128 private: 129 scoped_ptr<internal::JSONParser> parser_; 130}; 131 132} // namespace base 133 134#endif // BASE_JSON_JSON_READER_H_ 135