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/memory/scoped_ptr.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. The caller owns the returned
95  // instance. If |json| is not a properly formed JSON string, returns NULL.
96  static scoped_ptr<Value> Read(const StringPiece& json);
97
98  // Reads and parses |json|, returning a Value owned by the caller. The
99  // parser respects the given |options|. If the input is not properly formed,
100  // returns NULL.
101  static scoped_ptr<Value> Read(const 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 NULL 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 scoped_ptr<Value> ReadAndReturnError(const StringPiece& json,
108                                              int options,  // JSONParserOptions
109                                              int* error_code_out,
110                                              std::string* error_msg_out,
111                                              int* error_line_out = nullptr,
112                                              int* error_column_out = nullptr);
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  scoped_ptr<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