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