mirror of https://github.com/svaarala/duktape.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
103 lines
3.7 KiB
103 lines
3.7 KiB
name: duk_pcall
|
|
|
|
proto: |
|
|
duk_int_t duk_pcall(duk_context *ctx, duk_idx_t nargs);
|
|
|
|
stack: |
|
|
[ ... func! arg1! ...! argN! ] -> [ ... retval! ] (if success, return value == 0)
|
|
[ ... func! arg1! ...! argN! ] -> [ ... err! ] (if failure, return value != 0)
|
|
|
|
summary: |
|
|
<p>Call target function <code>func</code> with <code>nargs</code> arguments
|
|
(not counting the function itself). The function and its arguments
|
|
are replaced by a single return value or a single error value.
|
|
An error thrown during the function call is caught.</p>
|
|
|
|
<p>The return value is:</p>
|
|
<ul>
|
|
<li><code>DUK_EXEC_SUCCESS</code> (0): call succeeded, <code>nargs</code> arguments are replaced
|
|
with a single return value. (This return code constant is guaranteed to be zero, so
|
|
that one can check for success with a "zero or non-zero" check.)</li>
|
|
<li><code>DUK_EXEC_ERROR</code>: call failed, <code>nargs</code> arguments are replaced with a
|
|
single error value. (In exceptional cases, e.g. when there are too few
|
|
arguments on the value stack, the call returns non-zero but may leave the stack
|
|
in an inconsistent state.)</li>
|
|
</ul>
|
|
|
|
<div class="note">
|
|
Unlike most Duktape API calls, this call returns zero on success. This allows
|
|
multiple error codes to be defined later.
|
|
</div>
|
|
|
|
<p>Error objects caught are typically instances of Error and have useful
|
|
properties like <code>.stack</code>, <code>.fileName</code>, and
|
|
<code>.lineNumber</code>. These can be accessed using the normal property
|
|
methods. However, arbitrary values can be thrown so you should avoid
|
|
assuming that's always the case.</p>
|
|
|
|
<p>The target function <code>this</code> binding is initially set to
|
|
<code>undefined</code>. 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">Entering Function Code</a>.
|
|
If you want to control the <code>this</code> binding, you can use
|
|
<code><a href="#duk_pcall_method">duk_pcall_method()</a></code> or
|
|
<code><a href="#duk_pcall_prop">duk_pcall_prop()</a></code> instead.</p>
|
|
|
|
example: |
|
|
/* Assume target function is already on stack at func_idx; the target
|
|
* function adds arguments and returns the result.
|
|
*/
|
|
|
|
duk_idx_t func_idx;
|
|
duk_int_t rc;
|
|
|
|
/* Basic example: function call and duk_safe_to_string() error print. */
|
|
|
|
duk_dup(ctx, func_idx);
|
|
duk_push_int(ctx, 2);
|
|
duk_push_int(ctx, 3);
|
|
rc = duk_pcall(ctx, 2); /* [ ... func 2 3 ] -> [ 5 ] */
|
|
if (rc == DUK_EXEC_SUCCESS) {
|
|
printf("2+3=%ld\n", (long) duk_get_int(ctx, -1));
|
|
} else {
|
|
/* Coercing with duk_safe_to_string() is a useful default, but you can
|
|
* also look up e.g. the .stack property of the error.
|
|
*/
|
|
printf("error: %s\n", duk_safe_to_string(ctx, -1));
|
|
}
|
|
duk_pop(ctx);
|
|
|
|
/* Accessing .stack to print a stack trace if the value caught is an
|
|
* Error instance.
|
|
*/
|
|
|
|
duk_dup(ctx, func_idx);
|
|
duk_push_int(ctx, 2);
|
|
duk_push_int(ctx, 3);
|
|
rc = duk_pcall(ctx, 2); /* [ ... func 2 3 ] -> [ 5 ] */
|
|
if (rc == DUK_EXEC_SUCCESS) {
|
|
printf("2+3=%ld\n", (long) duk_get_int(ctx, -1));
|
|
} else {
|
|
if (duk_is_error(ctx, -1)) {
|
|
/* Accessing .stack might cause an error to be thrown, so wrap this
|
|
* access in a duk_safe_call() if it matters.
|
|
*/
|
|
duk_get_prop_string(ctx, -1, "stack");
|
|
printf("error: %s\n", duk_safe_to_string(ctx, -1));
|
|
duk_pop(ctx);
|
|
} else {
|
|
/* Non-Error value, coerce safely to string. */
|
|
printf("error: %s\n", duk_safe_to_string(ctx, -1));
|
|
}
|
|
}
|
|
duk_pop(ctx);
|
|
|
|
tags:
|
|
- call
|
|
- protected
|
|
|
|
seealso:
|
|
- duk_pcall_method
|
|
- duk_pcall_prop
|
|
|
|
introduced: 1.0.0
|
|
|