Duktape feature defaults are, at a high level:
Proxy object which
+ is enabled by default.DUK_OPT_NO_PC2LINE.
DUK_OPT_NO_JSONX and DUK_OPT_NO_JSONC.DUK_OPT_NO_OBJECT_ES6_SETPROTOTYPEOF,
+ DUK_OPT_NO_OBJECT_ES6_PROTO_PROPERTY,
+ DUK_OPT_NO_ES6_PROXY.DUK_OPT_NO_REGEXP_SUPPORT.-DDUK_OPT_DEBUG_BUFSIZE=2048 to reduce
diff --git a/website/guide/duktapebuiltins.html b/website/guide/duktapebuiltins.html
index ff0cf48c..c4eef86e 100644
--- a/website/guide/duktapebuiltins.html
+++ b/website/guide/duktapebuiltins.html
@@ -13,6 +13,7 @@ values.
stdout.stderr.This section describes the small set of features Duktape borrows from the -current ES6 draft. -These features are not fully compliant; the intent is to minimize custom features -and to align with the coming ES6 specification.
+current ES6 draft +("Version: Rev 23, April 5, 2014 Draft"). These features are not fully compliant; +the intent is to minimize custom features and to align with the coming ES6 specification.Object.setPrototypeOf
allows user to set the internal prototype of an object which is not supported in
Ecmascript E5. The Ecmascript E6 draft also provides
-Object.prototype.__proto__
-which is an accessor property (setter/getter) which provides the same functionality
+Object.prototype.__proto__,
+an accessor property (setter/getter) which provides the same functionality
but is compatible with existing code base which has relied on a non-standard
__proto__ property for a while. Duktape does not support the
__proto__ property name in an object initializer.
These custom features can be disabled with feature options.
+These custom features can be disabled with the feature options
+DUK_OPT_NO_OBJECT_ES6_SETPROTOTYPEOF and
+DUK_OPT_NO_OBJECT_ES6_PROTO_PROPERTY.
FIXME.
+The Ecmascript E6 Proxy object allows property virtualization
+and fine-grained access control for accessing an underlying plain object.
+Duktape implements a strict subset of the Proxy object from the
+ES6 draft (Rev 23).
Limitations include:
+get, set, deleteProperty
+ handler methods; ES6 draft allows a lot more, e.g. to interact with
+ properties being called or constructed, enumeration, etc. This causes
+ odd behavior if you enumerate a proxy object, call
+ Object.defineProperty() with the proxy object as an argument,
+ etc.new Proxy() cannot
+ be proxy objects themselves. ES6 poses no such limitation, but Duktape
+ enforces it to simplify the internal implementation.This custom feature can be disabled with the feature option
+DUK_OPT_NO_ES6_PROXY.
The upcoming Ecmascript Edition 6 standard is not yet final. Duktape borrows -a few features from the E6 draft to minimize Duktape -custom features and aligning with the upcoming standard.
+a few features from the E6 draft: +setPrototypeOf/__proto__
and a subset of Proxy objectsprint() and alert() borrowed from
- browsers, Duktape specific built-ins in the Duktape global objectprint() and alert()Duktape global objectlua_dump()Metatables
-There is currently no equivalent of Lua metatables in Duktape (or -Ecmascript). The -ES6 proxy object -concept will most likely provide similar functionality at some point.
+There is no equivalent of Lua metatables in Ecmascript E5/E5.1, but +Ecmascript E6 Proxy objects +provide similar functionality. To allow property virtualization better than available in +E5/E5.1, Duktape implements an ES6 Proxy subset.
.This section describes the two different mechanisms Duktape provides +for interacting with property accesses programmatically.
+ +Ecmascript Edition 5 provides accessor properties (also called +"setters and getters") which allow property read/write operations to be +captured by a user function.
+ +For example, to capture writes to obj.color so that you
+can validate the color value and trigger a redraw as a side effect:
+var obj = {};
+
+Object.defineProperty(obj, 'color', {
+ enumerable: false,
+ configurable: false,
+ get: function () {
+ // current color is stored in the raw _color property here
+ return this._color;
+ },
+ set: function (v) {
+ if (!validateColor(v)) {
+ // only allow valid color formats to be assigned
+ throw new TypeError('invalid color: ' + v);
+ }
+ this._color = v;
+ redraw();
+ }
+});
+
+// Change to red and trigger a redraw.
+obj.color = '#ff0000';
+
+
+Setters and getters have the advantage of being part of the E5 standard +and of being widely implemented. However, they have significant limitations:
+In addition to accessors, Duktape provides a subset implementation of the
+Ecmascript E6 (draft) Proxy concept (see
+Proxy Objects (E6 draft)
+and Proxy (Mozilla)).
+The current subset is limited to get, set, and
+deleteProperty handler methods.
For example, to simply print a line whenever any property is accessed:
+
+// Underlying plain object.
+var target = { foo: 'bar' };
+
+// Handler table, provides methods for interaction (can be modified on-the-fly).
+var handler = {
+ get: function (targ, key, recv) {
+ print('get called for key=' + key);
+ return targ[key]; // return unmodified value
+ },
+
+ set: function (targ, key, val, recv) {
+ print('set called for key=' + key + ', val=' + val);
+ targ[key] = val; // must perform write to target manually if 'set' defined
+ return true; // true: indicate that property write was allowed
+ },
+
+ deleteProperty: function (targ, key) {
+ print('deleteProperty called for key=' + key);
+ delete targ[key]; // must perform delete to target manually if 'deleteProperty' defined
+ return true; // true: indicate that property delete was allowed
+ }
+};
+
+// Create proxy object.
+var proxy = new Proxy(target, handler);
+
+// Proxy object is then accessed normally.
+proxy.foo = 321;
+print(proxy.foo);
+delete proxy.foo;
+
+
+A Proxy object can also be used to create a read-only version of an +underlying object (which is quite tedious otherwise):
+
+var proxy = new Proxy(target, {
+ // get is omitted: reads go through to the target object automatically
+
+ // set returns false: rejects write
+ set: function () { return false; },
+
+ // deleteProperty returns false: rejects delete
+ deleteProperty: function () { return false; }
+});
+
+
+You can also create a write-only version of an object (which is not +possible otherwise):
+
+var proxy = new Proxy(target, {
+ get: function() { throw new TypeError('read not allowed'); }
+
+ // set and deleteProperty are omitted: write/delete operations
+ // are allowed and go through to the target automatically
+});
+
+
+The following is a more convoluted example combining multiple (somewhat +artificial) behaviors:
+
+var target = { foo: 'bar' };
+
+/*
+ * - 'color' behaves like in the getter/setter example, cannot be deleted
+ * (attempt to do so causes a TypeError)
+ *
+ * - all string values are uppercased when read
+ *
+ * - property names beginning with an underscore are read/write/delete
+ * protected in a few different ways
+ */
+
+var handler = {
+ get: function (targ, key, recv) {
+ // this binding: handler table
+ // targ: underlying plain object (= target, above)
+ // key: key (can be any value, not just a string)
+ // recv: object being read from (= the proxy object)
+
+ if (typeof key === 'string' && key[0] === '_') {
+ throw new TypeError('attempt to access a read-protected property');
+ }
+
+ // Return value: value provided as property lookup result.
+ var val = targ[key];
+ return (typeof val === 'string' ? val.toUpperCase() : val);
+ },
+
+ set: function (targ, key, val, recv) {
+ // this binding: handler table
+ // targ: underlying plain object (= target, above)
+ // key: key (can be any value, not just a string)
+ // val: value
+ // recv: object being read from (= the proxy object)
+
+ if (typeof key === 'string') {
+ if (key === 'color') {
+ if (!validateColor(val)) {
+ throw new TypeError('invalid color: ' + val);
+ }
+ targ.color = val;
+ redraw();
+
+ // True: indicates to caller that property write allowed.
+ return true;
+ } else if (key[0] === '_') {
+ // False: indicates to caller that property write rejected.
+ // In non-strict mode this is ignored silently, but in strict
+ // mode a TypeError is thrown.
+ return false;
+ }
+ }
+
+ // Write to target. We could also return true without writing to the
+ // target to simulate a successful write without changing the target.
+ targ[key] = val;
+ return true;
+ },
+
+ deleteProperty: function (targ, key) {
+ // this binding: handler table
+ // targ: underlying plain object (= target, above)
+ // key: key (can be any value, not just a string)
+
+ if (typeof key === 'string') {
+ if (key === 'color') {
+ // For 'color' a delete attempt causes an explicit error.
+ throw new TypeError('attempt to delete the color property');
+ } else if (key[0] === '_') {
+ // False: indicates to caller that property delete rejected.
+ // In non-strict mode this is ignored silently, but in strict
+ // mode a TypeError is thrown.
+ return false;
+ }
+ }
+
+ // Delete from target. We could also return true without deleting
+ // from the target to simulate a successful delete without changing
+ // the target.
+ delete targ[key];
+ return true;
+ }
+};
+
+
+The ES6 draft semantics reject some property accesses even if the handler +method would allow it. This happens if the proxy's target object has a non-configurable +conflicting property; see E6 draft Sections 9.5.8, 9.5.9, and 9.5.10 for details. +You can easily avoid any such behaviors by keeping the target object empty and, +if necessary, backing the virtual properties in an unrelated plain object.
+ +Also see:
+Proxy implementation.Proxy object.Proxy implemented in Firefox, contains a lot of examples.Main features: