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