[api] Add PropertyDescriptor and DefineProperty().

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 77 matching lines @@
 class Maybe;
 class Name;
 class Number;
 class NumberObject;
 class Object;
 class ObjectOperationDescriptor;
 class ObjectTemplate;
 class Platform;
 class Primitive;
 class Promise;
+class PropertyDescriptor;
 class Proxy;
 class RawOperationDescriptor;
 class Script;
 class SharedArrayBuffer;
 class Signature;
 class StartupData;
 class StackFrame;
 class StackTrace;
 class String;
 class StringObject;
@@ skipping 2578 matching lines @@
   // Implements DefineOwnProperty.
   //
   // In general, CreateDataProperty will be faster, however, does not allow
   // for specifying attributes.
   //
   // Returns true on success.
   V8_WARN_UNUSED_RESULT Maybe<bool> DefineOwnProperty(
       Local<Context> context, Local<Name> key, Local<Value> value,
       PropertyAttribute attributes = None);
 
+  // Implements Object.DefineProperty(O, P, Attributes) as in ecma262 19.1.2.4.
+  //
+  // The defineProperty function is used to add an own property or
+  // update the attributes of an existing own property of an object.
+  //
+  // Both data and accessor descriptors can be used.
+  //
+  // In general, CreateDataProperty is faster, however, does not allow
+  // for specifying attributes or an accessor descriptor.
+  //
+  // Returns true on success.
+  V8_WARN_UNUSED_RESULT Maybe<bool> DefineProperty(
+      Local<Context> context, Local<Name> key,
+      const PropertyDescriptor& descriptor);
+
   // Sets an own property on this object bypassing interceptors and
   // overriding accessors or read-only properties.
   //
   // Note that if the object has an interceptor the property will be set
   // locally, but since the interceptor takes precedence the local property
   // will only be returned if the interceptor doesn't return a value.
   //
   // Note also that this only works for named properties.
   V8_DEPRECATED("Use CreateDataProperty / DefineOwnProperty",
                 bool ForceSet(Local<Value> key, Local<Value> value,
@@ skipping 724 matching lines @@
    */
   bool HasHandler();
 
   V8_INLINE static Promise* Cast(Value* obj);
 
  private:
   Promise();
   static void CheckCast(Value* obj);
 };
 
+/**
+ * An instance of a Property Descriptor, see Ecma-262 6.2.4.
+ *
+ * This property descriptor is immutable. An invalid descriptor that is both
+ * a data and accessor descriptor can not be generated. To determine if
+ * a descriptor is an accessor, data, or generic descriptor, use the
+ * has_x() functions for appropriate x.
+ *
+ * Empty handles for value, get, or set should be treated as undefined.

[jochen (gone - plz use gerrit), 2016/08/23 12:38:41]

so has_value = true and value.is_empty() is valid? why?

[Franzi, 2016/08/23 16:08:23]

Because desc = {value: undefined} is different form desc = {}. I changed the
comment. Does that make more sense?

[Toon Verwaest, 2016/08/23 18:01:43]

Empty handle would indicate that though. Unlike for accessors, this isn't
necessary for data properties I think.

+ *
+ * The difference between hax_x() = false and setting x to its default value
+ * is important when re-defining a property. When re-defining, has_x() = false
+ * does not cause a type error if x is already defined differently.
+ */
+class V8_EXPORT PropertyDescriptor {
+ public:
+  // GenericDescriptor
+  PropertyDescriptor(bool enumerable = false, bool has_enumerable = false,
+                     bool configurable = false, bool has_configurable = false)
+      : enumerable_(enumerable),
+        has_enumerable_(has_enumerable),
+        configurable_(configurable),
+        has_configurable_(has_configurable) {}
+
+  // DataDescriptor
+  PropertyDescriptor(Local<Value> value, bool has_value,

[jochen (gone - plz use gerrit), 2016/08/23 12:38:41]

it's a bit odd that has_get below has a default value, but has_value here
doesn't.

In general, I think we should avoid using default arguments unless it really
helps alot (at least that's what the styleguide says anyways).

What about having three constructors that take nothing (generic), a value (data)
or a getter & setter (accessor) and then e.g. set_enumerable() that implicitly
will has_enumerable_ to true?

[Franzi, 2016/08/23 16:08:23]

OK, I'll make the enumerable and configurable properties mutable and remove the
default arguments. Indeed, the long parameter lists with true/false are hard to
read. 

+                     bool enumerable = false, bool has_enumerable = false,
+                     bool configurable = false, bool has_configurable = false,
+                     bool writable = false, bool has_writable = false)
+      : value_(value),
+        has_value_(has_value),
+        enumerable_(enumerable),
+        has_enumerable_(has_enumerable),
+        configurable_(configurable),
+        has_configurable_(has_configurable),
+        writable_(writable),
+        has_writable_(has_writable) {}
+
+  // AccessorDescriptor
+  PropertyDescriptor(Local<Function> get, bool has_get = false,

[jochen (gone - plz use gerrit), 2016/08/23 12:38:41]

should we have a version that also takes a FunctionTemplate for getter / setter?

[Franzi, 2016/08/23 16:08:23]

My use case is going to be to convert an internal PropertyDescriptor to a
v8::PropertyDescriptor. I don't need a version for FunctionTemplates. Is it OK
if we leave it out until we need it? 

+                     Local<Function> set = Local<Function>(),
+                     bool has_set = false, bool enumerable = false,
+                     bool has_enumerable = false, bool configurable = false,
+                     bool has_configurable = false)
+      : get_(get),
+        has_get_(has_get),
+        set_(set),
+        has_set_(has_set),
+        enumerable_(enumerable),
+        has_enumerable_(has_enumerable),
+        configurable_(configurable),
+        has_configurable_(has_configurable) {}
+
+  Local<Value> value() const { return value_; }
+  bool has_value() const { return has_value_; }
+
+  Local<Function> get() const { return get_; }
+  bool has_get() const { return has_get_; }
+  Local<Function> set() const { return set_; }
+  bool has_set() const { return has_set_; }
+
+  bool enumerable() const { return enumerable_; }
+  bool has_enumerable() const { return has_enumerable_; }
+  bool configurable() const { return configurable_; }
+  bool has_configurable() const { return has_configurable_; }
+  bool writable() const { return writable_; }
+  bool has_writable() const { return has_writable_; }
+
+ private:
+  Local<Value> value_;
+  bool has_value_ = false;
+
+  Local<Function> get_;
+  bool has_get_ = false;
+  Local<Function> set_;
+  bool has_set_ = false;
+
+  bool enumerable_ = false;
+  bool has_enumerable_ = false;
+  bool configurable_ = false;
+  bool has_configurable_ = false;
+  bool writable_ = false;
+  bool has_writable_ = false;
+};

[jochen (gone - plz use gerrit), 2016/08/23 12:38:41]

this struct must not be copied / assigned to. just delete the default copy and
assignment operators.

[Franzi, 2016/08/23 16:08:22]

Done.

 
 /**
  * An instance of the built-in Proxy constructor (ECMA-262, 6th Edition,
  * 26.2.1).
  */
 class V8_EXPORT Proxy : public Object {
  public:
   Local<Object> GetTarget();
   Local<Value> GetHandler();
   bool IsRevoked();
@@ skipping 5536 matching lines @@
  */
 
 
 }  // namespace v8
 
 
 #undef TYPE_CHECK
 
 
 #endif  // INCLUDE_V8_H_