diff --git a/website/guide/programming.html b/website/guide/programming.html index 7dfad036..a5d8214b 100644 --- a/website/guide/programming.html +++ b/website/guide/programming.html @@ -312,3 +312,72 @@ int my_func(duk_context *ctx) { } +

Strictness

+ +

All Duktape/C functions are always "strict". For instance, attempt to +delete a non-configurable property using duk_del_prop() will +cause an error to be thrown. This is the case with a strict Ecmascript +function too:

+ +
+function f() {
+    'use strict';
+    var arr = [1, 2, 3];
+
+    // array 'length' is non-configurable
+    return delete arr.length;
+}
+
+// this throws an error because f() is strict
+print(f());
+
+ +

All API calls made from inside a Duktape/C call thus obey Ecmascript +strict semantics.

+ +

However, when API calls are made from outside a Duktape/C function +(when the call stack is empty), all API calls obey Ecmascript +non-strict semantics, as this is the Ecmascript default.

+ +

"This" binding and constructability of Duktape/C functions

+ +

Duktape/C functions are always considered strict. Because of this, the +this binding given to them is used directly as given by the caller. +Ecmascript semantics provide some coercion processing for the this +binding which reaches a non-strict function.

+ +

Duktape/C functions are currently always constructable, i.e. they can +always be used in new Foo() expressions. You can check whether +a function was called in constructor mode as follows:

+
+static int my_func(duk_context *ctx) {
+    if (duk_is_constructor_call(ctx)) {
+        printf("called as a constructor\n");
+    } else {
+        printf("called as a function\n");
+    }
+}
+
+ +

Storing state for a Duktape/C function

+ +

A Duktape/C function can use its Function object to store state or +parameters. A certain Duktape/C function (the actual C function) +is always represented by an Ecmascript Function object which is +magically associated with the underlying C function. The Function +object can be used to store properties related to that particular +instance of the function. Note that a certain Duktape/C function can +be associated with multiple independent Function objects and thus +independent states.

+ +

A Duktape/C function can also be called as a method, e.g.:

+
+foo.my_c_func()
+
+ +

In this case the Duktape/C function gets foo as its this +binding, and can access the foo object with duk_push_this(). +The object that a method "belongs to" can also be used to store state and +parameters. The different to using the Function object is that the same +object is shared by all methods.

+