js/public/JSON.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /*
   7  * JSON serialization and deserialization operations.
   8  */
   9
  10 #ifndef js_JSON_h
  11 #define js_JSON_h
  12
  13 #include <stdint.h>  // uint32_t
  14
  15 #include "jstypes.h"  // JS_PUBLIC_API
  16
  17 #include "js/TypeDecls.h"
  18
  19 using JSONWriteCallback = bool (*)(const char16_t* buf, uint32_t len,
  20                                    void* data);
  21
  22 /**
  23  * Performs the JSON.stringify operation, as specified by ECMAScript, except
  24  * writing stringified data by exactly one call of |callback|, passing |data| as
  25  * argument.
  26  *
  27  * In cases where JSON.stringify would return undefined, this function calls
  28  * |callback| with the string "null".
  29  */
  30 extern JS_PUBLIC_API bool JS_Stringify(JSContext* cx,
  31                                        JS::MutableHandle<JS::Value> value,
  32                                        JS::Handle<JSObject*> replacer,
  33                                        JS::Handle<JS::Value> space,
  34                                        JSONWriteCallback callback, void* data);
  35
  36 namespace JS {
  37
  38 /**
  39  * An API akin to JS_Stringify but with the goal of not having observable
  40  * side-effects when the stringification is performed.  This means it does not
  41  * allow a replacer or a custom space and has the following constraints on its
  42  * input:
  43  *
  44  * 1) The input must be a plain object or array, not an abitrary value.
  45  * 2) Every value in the graph reached by the algorithm starting with this
  46  *    object must be one of the following: null, undefined, a string (NOT a
  47  *    string object!), a boolean, a finite number (i.e. no NaN or Infinity or
  48  *    -Infinity), a plain object with no accessor properties, or an Array with
  49  *    no holes.
  50  *
  51  * The actual behavior differs from JS_Stringify only in asserting the above and
  52  * NOT attempting to get the "toJSON" property from things, since that could
  53  * clearly have side-effects.
  54  */
  55 extern JS_PUBLIC_API bool ToJSONMaybeSafely(JSContext* cx,
  56                                             JS::Handle<JSObject*> input,
  57                                             JSONWriteCallback callback,
  58                                             void* data);
  59
  60 /**
  61  * Performs the JSON.stringify operation, as specified by ECMAScript, except
  62  * writing stringified data by one call of |callback|, passing |data| as
  63  * argument.
  64  *
  65  * In cases where JSON.stringify would return undefined, this function does not
  66  * call |callback| at all.
  67  */
  68 extern JS_PUBLIC_API bool ToJSON(JSContext* cx, Handle<Value> value,
  69                                  Handle<JSObject*> replacer,
  70                                  Handle<Value> space,
  71                                  JSONWriteCallback callback, void* data);
  72
  73 } /* namespace JS */
  74
  75 /**
  76  * Performs the JSON.parse operation as specified by ECMAScript.
  77  */
  78 extern JS_PUBLIC_API bool JS_ParseJSON(JSContext* cx, const char16_t* chars,
  79                                        uint32_t len,
  80                                        JS::MutableHandle<JS::Value> vp);
  81
  82 /**
  83  * Performs the JSON.parse operation as specified by ECMAScript.
  84  */
  85 extern JS_PUBLIC_API bool JS_ParseJSON(JSContext* cx, JS::Handle<JSString*> str,
  86                                        JS::MutableHandle<JS::Value> vp);
  87
  88 /**
  89  * Performs the JSON.parse operation as specified by ECMAScript.
  90  */
  91 extern JS_PUBLIC_API bool JS_ParseJSON(JSContext* cx,
  92                                        const JS::Latin1Char* chars,
  93                                        uint32_t len,
  94                                        JS::MutableHandle<JS::Value> vp);
  95
  96 /**
  97  * Performs the JSON.parse operation as specified by ECMAScript, using the
  98  * given |reviver| argument as the corresponding optional argument to that
  99  * function.
 100  */
 101 extern JS_PUBLIC_API bool JS_ParseJSONWithReviver(
 102     JSContext* cx, const char16_t* chars, uint32_t len,
 103     JS::Handle<JS::Value> reviver, JS::MutableHandle<JS::Value> vp);
 104
 105 /**
 106  * Performs the JSON.parse operation as specified by ECMAScript, using the
 107  * given |reviver| argument as the corresponding optional argument to that
 108  * function.
 109  */
 110 extern JS_PUBLIC_API bool JS_ParseJSONWithReviver(
 111     JSContext* cx, JS::Handle<JSString*> str, JS::Handle<JS::Value> reviver,
 112     JS::MutableHandle<JS::Value> vp);
 113
 114 namespace JS {
 115
 116 /**
 117  * Returns true if the given text is valid JSON.
 118  */
 119 extern JS_PUBLIC_API bool IsValidJSON(const JS::Latin1Char* chars,
 120                                       uint32_t len);
 121 extern JS_PUBLIC_API bool IsValidJSON(const char16_t* chars, uint32_t len);
 122
 123 /**
 124  * Handler with callbacks for JS::ParseJSONWithHandler.
 125  *
 126  * Each method is called during parsing the JSON string. If the method returns
 127  * true, the parsing keeps going.  If the method returns false, the parsing
 128  * stops and fails.
 129  *
 130  * The error method is called when syntax error happens while parsing the input.
 131  * This method is not called when handler's method returns false.
 132  */
 133 class JSONParseHandler {
 134  public:
 135   JSONParseHandler() {}
 136   virtual ~JSONParseHandler() {}
 137
 138   // Called when '{' is found for an object.
 139   virtual bool startObject() = 0;
 140
 141   // Called when a property name is found for an object.
 142   // The character type depends on the input type and also the content of the
 143   // property name. The consumer should implement both methods.
 144   virtual bool propertyName(const JS::Latin1Char* name, size_t length) = 0;
 145   virtual bool propertyName(const char16_t* name, size_t length) = 0;
 146
 147   // Called when '}' is found for an object.
 148   virtual bool endObject() = 0;
 149
 150   // Called when '[' is found for an array.
 151   virtual bool startArray() = 0;
 152
 153   // Called when ']' is found for an array.
 154   virtual bool endArray() = 0;
 155
 156   // Called when a string is found.
 157   // The character type depends on the input type and also the content of the
 158   // string. The consumer should implement both methods.
 159   virtual bool stringValue(const JS::Latin1Char* str, size_t length) = 0;
 160   virtual bool stringValue(const char16_t* str, size_t length) = 0;
 161
 162   // Called when a number is found.
 163   virtual bool numberValue(double d) = 0;
 164
 165   // Called when a boolean is found.
 166   virtual bool booleanValue(bool v) = 0;
 167
 168   // Called when null is found.
 169   virtual bool nullValue() = 0;
 170
 171   // Called when syntax error happens.
 172   virtual void error(const char* msg, uint32_t line, uint32_t column) = 0;
 173 };
 174
 175 /**
 176  * Performs the JSON.parse operation as specified by ECMAScript, and call
 177  * callbacks defined by the handler.
 178  */
 179 extern JS_PUBLIC_API bool ParseJSONWithHandler(const JS::Latin1Char* chars,
 180                                                uint32_t len,
 181                                                JSONParseHandler* handler);
 182 extern JS_PUBLIC_API bool ParseJSONWithHandler(const char16_t* chars,
 183                                                uint32_t len,
 184                                                JSONParseHandler* handler);
 185
 186 }  // namespace JS
 187
 188 #endif /* js_JSON_h */