api doc and tests for duk_call(), duk_call_method(), duk_call_prop()

api-testcases/test-call-method.c

@@ -0,0 +1,78 @@
+/*===
+this binding: 'my this binding'
+result=33
+final top: 0
+rc=0, result='undefined'
+this binding: 'my this binding'
+rc=1, result='TypeError: argument 2 is not a number'
+===*/
+
+int my_adder(duk_context *ctx) {
+	int i, n;
+	double res = 0.0;
+
+	duk_push_this(ctx);
+	printf("this binding: '%s'\n", duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	n = duk_get_top(ctx);
+	for (i = 0; i < n; i++) {
+		if (!duk_is_number(ctx, i)) {
+			duk_error(ctx, DUK_ERR_TYPE_ERROR, "argument %d is not a number", i);
+		}
+		res += duk_get_number(ctx, i);
+	}
+
+	duk_push_number(ctx, res);
+	return 1;
+}
+
+int test_1(duk_context *ctx) {
+	duk_set_top(ctx, 0);
+
+	duk_push_new_c_function(ctx, my_adder, 3 /*nargs*/);
+	duk_push_string(ctx, "my this binding");
+	duk_push_int(ctx, 10);
+	duk_push_int(ctx, 11);
+	duk_push_int(ctx, 12);
+	duk_push_int(ctx, 13);  /* clipped */
+	duk_push_int(ctx, 14);  /* clipped */
+	duk_call_method(ctx, 5);
+
+	printf("result=%s\n", duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	printf("final top: %d\n", duk_get_top(ctx));
+	return 0;
+}
+
+int test_2(duk_context *ctx) {
+	duk_set_top(ctx, 0);
+
+	duk_push_new_c_function(ctx, my_adder, 3 /*nargs*/);
+	duk_push_string(ctx, "my this binding");
+	duk_push_int(ctx, 10);
+	duk_push_int(ctx, 11);
+	duk_push_string(ctx, "foo");  /* causes error */
+	duk_push_int(ctx, 13);  /* clipped */
+	duk_push_int(ctx, 14);  /* clipped */
+	duk_call_method(ctx, 5);
+
+	printf("result=%s\n", duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	printf("final top: %d\n", duk_get_top(ctx));
+	return 0;
+}
+
+void test(duk_context *ctx) {
+	int rc;
+
+	rc = duk_safe_call(ctx, test_1, 0, 1, DUK_INVALID_INDEX);
+	printf("rc=%d, result='%s'\n", rc, duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	rc = duk_safe_call(ctx, test_2, 0, 1, DUK_INVALID_INDEX);
+	printf("rc=%d, result='%s'\n", rc, duk_to_string(ctx, -1));
+	duk_pop(ctx);
+}

api-testcases/test-call-prop.c

@@ -0,0 +1,111 @@
+/*===
+[object Object]
+result=33
+final top: 1
+rc=0, result='undefined'
+[object Object]
+rc=1, result='Error: my error'
+object 1 [object Number]
+result=undefined
+number 1 [object Number]
+result=undefined
+final top: 1
+rc=0, result='undefined'
+===*/
+
+int test_1(duk_context *ctx) {
+	duk_set_top(ctx, 0);
+
+	duk_eval_string(ctx, "({ myfunc: function(x,y,z) { print(this); return x+y+z; } })");
+	duk_push_string(ctx, "myfunc");
+	duk_push_int(ctx, 10);
+	duk_push_int(ctx, 11);
+	duk_push_int(ctx, 12);
+	duk_push_int(ctx, 13);  /* clipped */
+	duk_push_int(ctx, 14);  /* clipped */
+
+	/* [ ... obj "myfunc" 10 11 12 13 14 ] */
+
+	duk_call_prop(ctx, 0, 5);
+
+	/* [ ... obj res ] */
+
+	printf("result=%s\n", duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	printf("final top: %d\n", duk_get_top(ctx));
+	return 0;
+}
+
+int test_2(duk_context *ctx) {
+	duk_set_top(ctx, 0);
+
+	duk_eval_string(ctx, "({ myfunc: function(x,y,z) { print(this); throw new Error('my error'); } })");
+	duk_push_string(ctx, "myfunc");
+	duk_push_int(ctx, 10);
+	duk_push_int(ctx, 11);
+	duk_push_int(ctx, 12);
+	duk_push_int(ctx, 13);  /* clipped */
+	duk_push_int(ctx, 14);  /* clipped */
+
+	/* [ ... obj "myfunc" 10 11 12 13 14 ] */
+
+	duk_call_prop(ctx, 0, 5);
+
+	/* [ ... obj res ] */
+
+	printf("result=%s\n", duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+
+	printf("final top: %d\n", duk_get_top(ctx));
+	return 0;
+}
+
+/* test this coercion in strict/non-strict functions */
+int test_3(duk_context *ctx) {
+	duk_set_top(ctx, 0);
+
+	/* Use Number.prototype to stash new functions, and call "through" a
+	 * plain number value.  The 'this' binding is initially the plain number.
+	 * A strict function gets the plain number as is, a non-strict function
+	 * gets an object coerced version.
+	 */
+
+	duk_eval_string(ctx, "Number.prototype.myfunc1 = function() { print(typeof this, this, Object.prototype.toString.call(this)); };");
+	duk_pop(ctx);
+	duk_eval_string(ctx, "Number.prototype.myfunc2 = function() { 'use strict'; print(typeof this, this, Object.prototype.toString.call(this)); };");
+	duk_pop(ctx);
+
+	duk_push_int(ctx, 1);  /* use '1' as 'obj' */
+
+	duk_push_string(ctx, "myfunc1");  /* -> [ ... obj "myfunc1" ] */
+	duk_call_prop(ctx, 0, 0);        /* -> [ ... obj res ] */
+	printf("result=%s\n", duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	duk_push_string(ctx, "myfunc2");  /* -> [ ... obj "myfunc2" ] */
+	duk_call_prop(ctx, 0, 0);        /* -> [ ... obj res ] */
+	printf("result=%s\n", duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	printf("final top: %d\n", duk_get_top(ctx));
+	return 0;
+}
+
+
+void test(duk_context *ctx) {
+	int rc;
+
+	rc = duk_safe_call(ctx, test_1, 0, 1, DUK_INVALID_INDEX);
+	printf("rc=%d, result='%s'\n", rc, duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	rc = duk_safe_call(ctx, test_2, 0, 1, DUK_INVALID_INDEX);
+	printf("rc=%d, result='%s'\n", rc, duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	rc = duk_safe_call(ctx, test_3, 0, 1, DUK_INVALID_INDEX);
+	printf("rc=%d, result='%s'\n", rc, duk_to_string(ctx, -1));
+	duk_pop(ctx);
+}

api-testcases/test-call.c

@@ -0,0 +1,76 @@
+/*===
+this binding: 'undefined'
+result=33
+final top: 0
+rc=0, result='undefined'
+this binding: 'undefined'
+rc=1, result='TypeError: argument 2 is not a number'
+===*/
+
+int my_adder(duk_context *ctx) {
+	int i, n;
+	double res = 0.0;
+
+	duk_push_this(ctx);
+	printf("this binding: '%s'\n", duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	n = duk_get_top(ctx);
+	for (i = 0; i < n; i++) {
+		if (!duk_is_number(ctx, i)) {
+			duk_error(ctx, DUK_ERR_TYPE_ERROR, "argument %d is not a number", i);
+		}
+		res += duk_get_number(ctx, i);
+	}
+
+	duk_push_number(ctx, res);
+	return 1;
+}
+
+int test_1(duk_context *ctx) {
+	duk_set_top(ctx, 0);
+
+	duk_push_new_c_function(ctx, my_adder, 3 /*nargs*/);
+	duk_push_int(ctx, 10);
+	duk_push_int(ctx, 11);
+	duk_push_int(ctx, 12);
+	duk_push_int(ctx, 13);  /* clipped */
+	duk_push_int(ctx, 14);  /* clipped */
+	duk_call(ctx, 5);
+
+	printf("result=%s\n", duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	printf("final top: %d\n", duk_get_top(ctx));
+	return 0;
+}
+
+int test_2(duk_context *ctx) {
+	duk_set_top(ctx, 0);
+
+	duk_push_new_c_function(ctx, my_adder, 3 /*nargs*/);
+	duk_push_int(ctx, 10);
+	duk_push_int(ctx, 11);
+	duk_push_string(ctx, "foo");  /* causes error */
+	duk_push_int(ctx, 13);  /* clipped */
+	duk_push_int(ctx, 14);  /* clipped */
+	duk_call(ctx, 5);
+
+	printf("result=%s\n", duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	printf("final top: %d\n", duk_get_top(ctx));
+	return 0;
+}
+
+void test(duk_context *ctx) {
+	int rc;
+
+	rc = duk_safe_call(ctx, test_1, 0, 1, DUK_INVALID_INDEX);
+	printf("rc=%d, result='%s'\n", rc, duk_to_string(ctx, -1));
+	duk_pop(ctx);
+
+	rc = duk_safe_call(ctx, test_2, 0, 1, DUK_INVALID_INDEX);
+	printf("rc=%d, result='%s'\n", rc, duk_to_string(ctx, -1));
+	duk_pop(ctx);
+}

website/api/duk_call.txt

@@ -0,0 +1,42 @@
+=proto
+void duk_call(duk_context *ctx, int nargs);
+
+=stack
+[ ... func! arg1! ...! argN! ] -> [ ... retval! ]
+
+=summary
+<p>Call target function <tt>func</tt> with <tt>nargs</tt> arguments
+(not counting the function itself).  The function and its arguments
+are replaced by a single return value.  An error thrown during the
+function call is not automatically caught.
+</p>
+
+<p>The target function <tt>this</tt> binding is initially set to
+<tt>undefined</tt>.  If the target function is not strict, the binding
+is replaced by the global object before the function is invoked; see
+<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-10.4.3">E5.1 Section 10.4.3</a>.
+If you want to control the <tt>this</tt> binding, you can use
+<tt><a href="#duk_call_method">duk_call_method()</a></tt> instead.</p>
+
+<p>This API call is equivalent to:</p>
+<pre class="ecmascript-code">
+var retval = func(arg1, ..., argN);
+</pre>
+
+<p>or:</p>
+<pre class="ecmascript-code">
+var retval = func.call(undefined, arg1, ..., argN);
+</pre>
+
+=example
+/* Assume target function is already on stack at func_idx; the target
+ * function adds arguments and returns the result.
+ */
+int func_idx;
+
+duk_dup(ctx, func_idx);
+duk_push_int(ctx, 2);
+duk_push_int(ctx, 3);
+duk_call(ctx, 2);  /* [ ... func 2 3 ] -> [ 5 ] */
+printf("2+3=%d\n", duk_get_int(ctx, -1));
+duk_pop(ctx);

website/api/duk_call_method.txt

@@ -0,0 +1,43 @@
+=proto
+void duk_call_method(duk_context *ctx, int nargs);
+
+=stack
+[ ... func! this! arg! ...! argN! ] -> [ ... retval! ]
+
+=summary
+<p>Call target function <tt>func</tt> with an explicit <tt>this</tt>
+binding and <tt>nargs</tt> arguments (not counting the function and
+the <tt>this</tt> binding value).  The function object, the <tt>this</tt>
+binding value, and the function arguments are replaced by a single
+return value.  An error thrown during the function call is not
+automatically caught.</p>
+
+<p>If the target function is not strict, the binding value seen by the
+target function may be modified by processing specified in
+<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-10.4.3">E5.1 Section 10.4.3</a>.
+</p>
+
+<p>This API call is equivalent to:</p>
+<pre class="ecmascript-code">
+var retval = func.call(this_binding, arg1, ..., argN);
+</pre>
+
+=example
+/* The target function here prints:
+ *
+ *    this: 123
+ *    2 3
+ *
+ * and returns 5.
+ */
+
+duk_push_string(ctx, "function(x,y) { print('this:', this); "
+                     "print(x,y); return x+y; }");
+duk_eval(ctx);  /* -> [ ... func ] */
+duk_push_int(ctx, 123);
+duk_push_int(ctx, 2);
+duk_push_int(ctx, 3);
+duk_call_method(ctx, 2);  /* [ ... func 123 2 3 ] -> [ 5 ] */
+printf("2+3=%d\n", duk_get_int(ctx, -1));  /* prints 5 */
+duk_pop(ctx);
+

website/api/duk_call_prop.txt

@@ -0,0 +1,38 @@
+=proto
+void duk_call_prop(duk_context *ctx, int obj_index, int nargs);
+
+=stack
+[ ... obj! ... key! arg1! ...! argN! ] -> [ ... obj! ... retval! ]
+
+=summary
+<p>Call <tt>obj.key</tt> with <tt>nargs</tt> arguments, with <tt>this</tt>
+binding set to <tt>obj</tt>.  The property name and the function arguments
+are replaced by a single return value; the target object is not touched.
+An error during the function call is not automatically caught.</p>
+
+<p>If the target function is not strict, the binding value seen by the
+target function may be modified by processing specified in
+<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-10.4.3">E5.1 Section 10.4.3</a>.
+</p>
+
+<p>This API call is equivalent to:</p>
+<pre class="ecmascript-code">
+var retval = obj[key](arg1, ..., argN);
+</pre>
+
+<p>or:</p>
+<pre class="ecmascript-code">
+var func = obj[key];
+var retval = func.call(obj, arg1, ..., argN);
+</pre>
+
+=example
+/* obj.myAdderMethod(2,3) -> 5 */
+int obj_idx;
+
+duk_push_string(ctx, "myAdderMethod");
+duk_push_int(ctx, 2);
+duk_push_int(ctx, 3);
+duk_call_prop(ctx, obj_idx, 2);  /* [ ... "myAdderMethod" 2 3 ] -> [ ... 5 ] */
+printf("2+3=%d\n", duk_get_int(ctx, -1));
+duk_pop(ctx);