Support symbol-named properties in API

include/v8.h

 // Copyright 2012 the V8 project authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 /** \mainpage V8 API Reference Guide
  *
  * V8 is Google's open source JavaScript engine.
  *
  * This set of documents provides reference material generated from the
  * V8 header file, include/v8.h.
@@ skipping 59 matching lines @@
 class Date;
 class DeclaredAccessorDescriptor;
 class External;
 class Function;
 class FunctionTemplate;
 class HeapProfiler;
 class ImplementationUtilities;
 class Int32;
 class Integer;
 class Isolate;
+class Name;
 class Number;
 class NumberObject;
 class Object;
 class ObjectOperationDescriptor;
 class ObjectTemplate;
 class Platform;
 class Primitive;
 class RawOperationDescriptor;
 class Script;
 class Signature;
@@ skipping 1232 matching lines @@
    * Returns true if this value is true.
    */
   bool IsTrue() const;
 
   /**
    * Returns true if this value is false.
    */
   bool IsFalse() const;
 
   /**
+   * Returns true if this value is a symbol or a string.
+   * This is an experimental feature.
+   */
+  bool IsName() const;
+
+  /**
    * Returns true if this value is an instance of the String type.
    * See ECMA-262 8.4.
    */
   V8_INLINE bool IsString() const;
 
   /**
    * Returns true if this value is a symbol.
    * This is an experimental feature.
    */
   bool IsSymbol() const;
@@ skipping 207 matching lines @@
  * or false value.
  */
 class V8_EXPORT Boolean : public Primitive {
  public:
   bool Value() const;
   V8_INLINE static Handle<Boolean> New(Isolate* isolate, bool value);
 };
 
 
 /**
+ * A superclass for symbols and strings.
+ */
+class V8_EXPORT Name : public Primitive {
+ public:
+  V8_INLINE static Name* Cast(v8::Value* obj);
+ private:
+  static void CheckCast(v8::Value* obj);
+};
+
+
+/**
  * A JavaScript string value (ECMA-262, 4.3.17).
  */
-class V8_EXPORT String : public Primitive {
+class V8_EXPORT String : public Name {
  public:
   enum Encoding {
     UNKNOWN_ENCODING = 0x1,
     TWO_BYTE_ENCODING = 0x0,
     ASCII_ENCODING = 0x4,
     ONE_BYTE_ENCODING = 0x4
   };
   /**
    * Returns the number of characters in this string.
    */
@@ skipping 318 matching lines @@
   void VerifyExternalStringResource(ExternalStringResource* val) const;
   static void CheckCast(v8::Value* obj);
 };
 
 
 /**
  * A JavaScript symbol (ECMA-262 edition 6)
  *
  * This is an experimental feature. Use at your own risk.
  */
-class V8_EXPORT Symbol : public Primitive {
+class V8_EXPORT Symbol : public Name {
  public:
   // Returns the print name string of the symbol, or undefined if none.
   Local<Value> Name() const;
 
   // Create a symbol. If name is not empty, it will be used as the description.
   static Local<Symbol> New(
       Isolate *isolate, Local<String> name = Local<String>());
 
   // Access global symbol registry.
   // Note that symbols created this way are never collected, so
@@ skipping 123 matching lines @@
 };
 
 /**
  * Accessor[Getter|Setter] are used as callback functions when
  * setting|getting a particular property. See Object and ObjectTemplate's
  * method SetAccessor.
  */
 typedef void (*AccessorGetterCallback)(
     Local<String> property,
     const PropertyCallbackInfo<Value>& info);
+typedef void (*AccessorSymbolGetterCallback)(
+    Local<Symbol> property,
+    const PropertyCallbackInfo<Value>& info);
 
 
 typedef void (*AccessorSetterCallback)(
     Local<String> property,
     Local<Value> value,
     const PropertyCallbackInfo<void>& info);
+typedef void (*AccessorSymbolSetterCallback)(
+    Local<Symbol> property,
+    Local<Value> value,
+    const PropertyCallbackInfo<void>& info);
 
 
 /**
  * Access control specifications.
  *
  * Some accessors should be accessible across contexts.  These
  * accessors have an explicit access control parameter which specifies
  * the kind of cross-context access that should be allowed.
  *
  * TODO(dcarney): Remove PROHIBITS_OVERWRITING as it is now unused.
@@ skipping 51 matching lines @@
   bool Has(uint32_t index);
 
   bool Delete(uint32_t index);
 
   bool SetAccessor(Handle<String> name,
                    AccessorGetterCallback getter,
                    AccessorSetterCallback setter = 0,
                    Handle<Value> data = Handle<Value>(),
                    AccessControl settings = DEFAULT,
                    PropertyAttribute attribute = None);
+  bool SetAccessor(Handle<Symbol> name,
+                   AccessorSymbolGetterCallback getter,
+                   AccessorSymbolSetterCallback setter = 0,
+                   Handle<Value> data = Handle<Value>(),
+                   AccessControl settings = DEFAULT,
+                   PropertyAttribute attribute = None);
 
   // This function is not yet stable and should not be used at this time.
-  bool SetDeclaredAccessor(Local<String> name,
+  bool SetDeclaredAccessor(Local<Name> name,
                            Local<DeclaredAccessorDescriptor> descriptor,
                            PropertyAttribute attribute = None,
                            AccessControl settings = DEFAULT);
 
-  void SetAccessorProperty(Local<String> name,
+  void SetAccessorProperty(Local<Name> name,
                            Local<Function> getter,
                            Handle<Function> setter = Handle<Function>(),
                            PropertyAttribute attribute = None,
                            AccessControl settings = DEFAULT);
 
   /**
    * Functionality for private properties.
    * This is an experimental feature, use at your own risk.
    * Note: Private properties are inherited. Do not rely on this, since it may
    * change.
@@ skipping 987 matching lines @@
 
 // --- Templates ---
 
 
 /**
  * The superclass of object and function templates.
  */
 class V8_EXPORT Template : public Data {
  public:
   /** Adds a property to each instance created by this template.*/
-  void Set(Handle<String> name, Handle<Data> value,
+  void Set(Handle<Name> name, Handle<Data> value,
            PropertyAttribute attributes = None);
   V8_INLINE void Set(Isolate* isolate, const char* name, Handle<Data> value);
 
   void SetAccessorProperty(
-     Local<String> name,
+     Local<Name> name,
      Local<FunctionTemplate> getter = Local<FunctionTemplate>(),
      Local<FunctionTemplate> setter = Local<FunctionTemplate>(),
      PropertyAttribute attribute = None,
      AccessControl settings = DEFAULT);
 
   /**
    * Whenever the property with the given name is accessed on objects
    * created from this Template the getter and setter callbacks
    * are called instead of getting and setting the property directly
    * on the JavaScript object.
@@ skipping 21 matching lines @@
    */
   void SetNativeDataProperty(Local<String> name,
                              AccessorGetterCallback getter,
                              AccessorSetterCallback setter = 0,
                              // TODO(dcarney): gcc can't handle Local below
                              Handle<Value> data = Handle<Value>(),
                              PropertyAttribute attribute = None,
                              Local<AccessorSignature> signature =
                                  Local<AccessorSignature>(),
                              AccessControl settings = DEFAULT);
+  void SetNativeDataProperty(Local<Symbol> name,
+                             AccessorSymbolGetterCallback getter,
+                             AccessorSymbolSetterCallback setter = 0,
+                             // TODO(dcarney): gcc can't handle Local below
+                             Handle<Value> data = Handle<Value>(),
+                             PropertyAttribute attribute = None,
+                             Local<AccessorSignature> signature =
+                                 Local<AccessorSignature>(),
+                             AccessControl settings = DEFAULT);
 
   // This function is not yet stable and should not be used at this time.
-  bool SetDeclaredAccessor(Local<String> name,
+  bool SetDeclaredAccessor(Local<Name> name,
                            Local<DeclaredAccessorDescriptor> descriptor,
                            PropertyAttribute attribute = None,
                            Local<AccessorSignature> signature =
                                Local<AccessorSignature>(),
                            AccessControl settings = DEFAULT);
 
  private:
   Template();
 
   friend class ObjectTemplate;
@@ skipping 41 matching lines @@
 
 
 /**
  * Returns an array containing the names of the properties the named
  * property getter intercepts.
  */
 typedef void (*NamedPropertyEnumeratorCallback)(
     const PropertyCallbackInfo<Array>& info);
 
 
+// TODO(wingo): Deprecate and remove previous typedefs, and replace
+// GenericNamedPropertyFooCallback with just NamedPropertyFooCallback.
+/**
+ * GenericNamedProperty[Getter|Setter] are used as interceptors on object.
+ * See ObjectTemplate::SetGenericNamedPropertyHandler.
+ */
+typedef void (*GenericNamedPropertyGetterCallback)(
+    Local<Name> property,
+    const PropertyCallbackInfo<Value>& info);
+
+
+/**
+ * Returns the value if the setter intercepts the request.
+ * Otherwise, returns an empty handle.
+ */
+typedef void (*GenericNamedPropertySetterCallback)(
+    Local<Name> property,
+    Local<Value> value,
+    const PropertyCallbackInfo<Value>& info);
+
+
+/**
+ * Returns a non-empty handle if the interceptor intercepts the request.
+ * The result is an integer encoding property attributes (like v8::None,
+ * v8::DontEnum, etc.)
+ */
+typedef void (*GenericNamedPropertyQueryCallback)(
+    Local<Name> property,
+    const PropertyCallbackInfo<Integer>& info);
+
+
+/**
+ * Returns a non-empty handle if the deleter intercepts the request.
+ * The return value is true if the property could be deleted and false
+ * otherwise.
+ */
+typedef void (*GenericNamedPropertyDeleterCallback)(
+    Local<Name> property,
+    const PropertyCallbackInfo<Boolean>& info);
+
+
+/**
+ * Returns an array containing the names of the properties the named
+ * property getter intercepts.
+ */
+typedef void (*GenericNamedPropertyEnumeratorCallback)(
+    const PropertyCallbackInfo<Array>& info);
+
+
 /**
  * Returns the value of the property if the getter intercepts the
  * request.  Otherwise, returns an empty handle.
  */
 typedef void (*IndexedPropertyGetterCallback)(
     uint32_t index,
     const PropertyCallbackInfo<Value>& info);
 
 
 /**
@@ skipping 287 matching lines @@
   void SetAccessor(Handle<String> name,
                    AccessorGetterCallback getter,
                    AccessorSetterCallback setter = 0,
                    Handle<Value> data = Handle<Value>(),
                    AccessControl settings = DEFAULT,
                    PropertyAttribute attribute = None,
                    Handle<AccessorSignature> signature =
                        Handle<AccessorSignature>());
 
   /**
+   * A version of SetAccessor for properties whose names are symbols.
+   *
+   * Whenever the property with the given name is accessed on objects
+   * created from this ObjectTemplate the getter and setter callbacks
+   * are called instead of getting and setting the property directly
+   * on the JavaScript object.
+   *
+   * \param name The name of the property for which an accessor is added.
+   * \param getter The callback to invoke when getting the property.
+   * \param setter The callback to invoke when setting the property.
+   * \param data A piece of data that will be passed to the getter and setter
+   *   callbacks whenever they are invoked.
+   * \param settings Access control settings for the accessor. This is a bit
+   *   field consisting of one of more of
+   *   DEFAULT = 0, ALL_CAN_READ = 1, or ALL_CAN_WRITE = 2.
+   *   The default is to not allow cross-context access.
+   *   ALL_CAN_READ means that all cross-context reads are allowed.
+   *   ALL_CAN_WRITE means that all cross-context writes are allowed.
+   *   The combination ALL_CAN_READ | ALL_CAN_WRITE can be used to allow all
+   *   cross-context access.
+   * \param attribute The attributes of the property for which an accessor
+   *   is added.
+   * \param signature The signature describes valid receivers for the accessor
+   *   and is used to perform implicit instance checks against them. If the
+   *   receiver is incompatible (i.e. is not an instance of the constructor as
+   *   defined by FunctionTemplate::HasInstance()), an implicit TypeError is
+   *   thrown and no callback is invoked.
+   */
+  void SetAccessor(Handle<Symbol> name,
+                   AccessorSymbolGetterCallback getter,
+                   AccessorSymbolSetterCallback setter = 0,
+                   Handle<Value> data = Handle<Value>(),
+                   AccessControl settings = DEFAULT,
+                   PropertyAttribute attribute = None,
+                   Handle<AccessorSignature> signature =
+                       Handle<AccessorSignature>());
+
+  /**
    * Sets a named property handler on the object template.
    *
-   * Whenever a named property is accessed on objects created from
-   * this object template, the provided callback is invoked instead of
+   * Whenever a property whose name is a string is accessed on objects created
+   * from this object template, the provided callback is invoked instead of
    * accessing the property directly on the JavaScript object.
    *
    * \param getter The callback to invoke when getting a property.
    * \param setter The callback to invoke when setting a property.
    * \param query The callback to invoke to check if a property is present,
    *   and if present, get its attributes.
    * \param deleter The callback to invoke when deleting a property.
    * \param enumerator The callback to invoke to enumerate all the named
    *   properties of an object.
    * \param data A piece of data that will be passed to the callbacks
    *   whenever they are invoked.
    */
   void SetNamedPropertyHandler(
       NamedPropertyGetterCallback getter,
       NamedPropertySetterCallback setter = 0,
       NamedPropertyQueryCallback query = 0,
       NamedPropertyDeleterCallback deleter = 0,
       NamedPropertyEnumeratorCallback enumerator = 0,
       Handle<Value> data = Handle<Value>());
 
   /**
+   * Sets a named property handler on the object template.
+   *
+   * Whenever a property is accessed on objects created from this object
+   * template, the provided callback is invoked instead of accessing the
+   * property directly on the JavaScript object.
+   *
+   * Unlike SetNamedPropertyHandler, this version also intercepts values whose
+   * names are symbols.
+   *
+   * \param getter The callback to invoke when getting a property.
+   * \param setter The callback to invoke when setting a property.
+   * \param query The callback to invoke to check if a property is present,
+   *   and if present, get its attributes.
+   * \param deleter The callback to invoke when deleting a property.
+   * \param enumerator The callback to invoke to enumerate all the named
+   *   properties of an object.
+   * \param data A piece of data that will be passed to the callbacks
+   *   whenever they are invoked.
+   */
+  void SetGenericNamedPropertyHandler(
+      GenericNamedPropertyGetterCallback getter,
+      GenericNamedPropertySetterCallback setter = 0,
+      GenericNamedPropertyQueryCallback query = 0,
+      GenericNamedPropertyDeleterCallback deleter = 0,
+      GenericNamedPropertyEnumeratorCallback enumerator = 0,
+      Handle<Value> data = Handle<Value>());
+
+  /**
    * Sets an indexed property handler on the object template.
    *
    * Whenever an indexed property is accessed on objects created from
    * this object template, the provided callback is invoked instead of
    * accessing the property directly on the JavaScript object.
    *
    * \param getter The callback to invoke when getting a property.
    * \param setter The callback to invoke when setting a property.
    * \param query The callback to invoke to check if an object has a property.
    * \param deleter The callback to invoke when deleting a property.
@@ skipping 2664 matching lines @@
   if (!I::HasHeapObjectTag(obj)) return false;
   return (I::GetInstanceType(obj) < I::kFirstNonstringType);
 }
 
 
 template <class T> Value* Value::Cast(T* value) {
   return static_cast<Value*>(value);
 }
 
 
+Name* Name::Cast(v8::Value* value) {
+#ifdef V8_ENABLE_CHECKS
+  CheckCast(value);
+#endif
+  return static_cast<Name*>(value);
+}
+
+
 Symbol* Symbol::Cast(v8::Value* value) {
 #ifdef V8_ENABLE_CHECKS
   CheckCast(value);
 #endif
   return static_cast<Symbol*>(value);
 }
 
 
 Number* Number::Cast(v8::Value* value) {
 #ifdef V8_ENABLE_CHECKS
@@ skipping 381 matching lines @@
  */
 
 
 }  // namespace v8
 
 
 #undef TYPE_CHECK
 
 
 #endif  // V8_H_