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 {
39class Value;
40
41namespace internal {
42class JSONParser;
43}
44}
45
46namespace base {
47
48enum 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
63class 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