Prototype §

void *duk_alloc(duk_context *ctx, duk_size_t size);

Stack §

(No effect on value stack.)

Summary §

Like duk_alloc_raw() but may trigger a garbage collection to satisfy the request. However, the allocated memory itself is not automatically garbage collected. The allocation request may fail even after garbage collection, in which case a NULL is returned. The allocated memory is not automatically zeroed, and may contain arbitrary garbage.

Memory allocated with duk_alloc() can be freed with either duk_free() or duk_free_raw().

Example §

/* Although duk_alloc() triggers a GC if necessary, it can still fail to
 * allocate the desired amount of memory.  Caller must check for NULL
 * (however, if allocation size is 0, a NULL may be returned even in
 * a success case).
 */
void *buf = duk_alloc(ctx, 1024);
if (buf) {
    printf("allocation successful: %p\n", buf);
} else {
    printf("allocation failed\n");
}

See also §

• duk_alloc_raw

Prototype §

void *duk_alloc_raw(duk_context *ctx, duk_size_t size);

Stack §

(No effect on value stack.)

Summary §

Allocate size bytes using the raw allocation function registered to the context. If allocation fails, returns NULL. If size is zero, the call may either return a NULL or some non-NULL value which may be safely given to e.g. duk_free_raw(). The allocation cannot trigger a garbage collection, and the allocated memory is not automatically garbage collected. The allocated memory is not automatically zeroed, and may contain arbitrary garbage.

Memory allocated with duk_alloc_raw() can be freed with either duk_free() or duk_free_raw().

Example §

void *buf = duk_alloc_raw(ctx, 1024);
if (buf) {
    printf("allocation successful: %p\n", buf);
} else {
    printf("allocation failed\n");
}

See also §

• duk_alloc

Prototype §

void duk_base64_decode(duk_context *ctx, duk_idx_t idx);

Stack §

Summary §

Decodes a base-64 encoded value into a buffer as an in-place operation. If the input is invalid, throws an error.

Example §

duk_push_string(ctx, "Zm9v");
duk_base64_decode(ctx, -1);  /* buffer */
printf("base-64 decoded: %s\n", duk_to_string(ctx, -1));
duk_pop(ctx);

/* Output:
 * base-64 decoded: foo
 */

See also §

• duk_base64_encode

Prototype §

const char *duk_base64_encode(duk_context *ctx, duk_idx_t idx);

Stack §

Summary §

Coerces an arbitrary value into a buffer and then encodes the result into base-64 as an in-place operation. Returns a pointer to the resulting string for convenience.

Example §

duk_push_string(ctx, "foo");
printf("base-64 encoded: %s\n", duk_base64_encode(ctx, -1));

/* Output:
 * base-64 encoded: Zm9v
 */

See also §

• duk_base64_decode

Prototype §

const char *duk_buffer_to_string(duk_context *ctx, duk_idx_t idx);

Stack §

Summary §

Replace the buffer value (plain buffer or any buffer object) at idx with a string whose internal byte representation is taken 1:1 from the buffer (same as if the buffer data was pushed using duk_push_lstring()). Returns a non-NULL pointer to the read-only, NUL-terminated string data. A TypeError is thrown if (1) the argument is not a buffer value, (2) the argument is a buffer object whose backing buffer doesn't cover the apparent buffer size, (3) the index is invalid.

Because the buffer data is used as is for the string created, this API call allows creation of Symbol values unless the buffer data is first sanitized.

Example §

unsigned char *ptr;
ptr = (unsigned char *) duk_push_fixed_buffer(ctx, 4);
ptr[0] = 0x61;
ptr[1] = 0x62;
ptr[2] = 0x63;
ptr[3] = 0x64;  /* 61 62 63 64 */
printf("coerced string: %s\n", duk_buffer_to_string(ctx, -1));
duk_pop(ctx);

Prototype §

void duk_call(duk_context *ctx, duk_idx_t nargs);

Stack §

Summary §

Call target function func with nargs 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.

The target function this binding is initially set to undefined. If the target function is not strict, the binding is replaced by the global object before the function is invoked; see Entering Function Code. If you want to control the this binding, you can use duk_call_method() or duk_call_prop() instead.

This API call is equivalent to:

var retval = func(arg1, ..., argN);

or:

var retval = func.call(undefined, arg1, ..., argN);

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_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=%ld\n", (long) duk_get_int(ctx, -1));
duk_pop(ctx);

See also §

• duk_call_method
• duk_call_prop

Prototype §

void duk_call_method(duk_context *ctx, duk_idx_t nargs);

Stack §

Summary §

Call target function func with an explicit this binding and nargs arguments (not counting the function or the this binding value). The function object, the this binding value, and the function arguments are replaced by a single return value. An error thrown during the function call is not automatically caught.

If the target function is not strict, the binding value seen by the target function may be modified by processing specified in Entering Function Code.

This API call is equivalent to:

var retval = func.call(this_binding, arg1, ..., argN);

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=%ld\n", (long) duk_get_int(ctx, -1));  /* prints 5 */
duk_pop(ctx);

Prototype §

void duk_call_prop(duk_context *ctx, duk_idx_t obj_idx, duk_idx_t nargs);

Stack §

Summary §

Call obj.key with nargs arguments, with this binding set to obj. 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.

If the target function is not strict, the binding value seen by the target function may be modified by processing specified in Entering Function Code.

This API call is equivalent to:

var retval = obj[key](arg1, ..., argN);

or:

var func = obj[key];
var retval = func.call(obj, arg1, ..., argN);

Example §

/* obj.myAdderMethod(2,3) -> 5 */
duk_idx_t 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=%ld\n", (long) duk_get_int(ctx, -1));
duk_pop(ctx);

Prototype §

void duk_cbor_decode(duk_context *ctx, duk_idx_t idx, duk_uint_t decode_flags);

Stack §

Summary §

Decodes a CBOR encoded value (given in any buffer type) as an in-place operation. The resulting value can be any ECMAScript value. No flags are defined at present, so pass in a 0 for flags.

Example §

duk_cbor_decode(ctx, -1, 0);

See also §

• duk_cbor_encode

Prototype §

void duk_cbor_encode(duk_context *ctx, duk_idx_t idx, duk_uint_t encode_flags);

Stack §

Summary §

Encodes an arbitrary value into its CBOR representation as an in-place operation. The resulting value is an ArrayBuffer (for now). No flags are defined at present, so pass in a 0 for flags.

Example §

unsigned char *buf;
duk_size_t len;

duk_push_object(ctx);
duk_push_int(ctx, 42);
duk_put_prop_string(ctx, -2, "meaningOfLife");
duk_cbor_encode(ctx, -1, 0);
buf = duk_require_buffer_data(ctx, -1, &len);
/* CBOR data is in buf[0] ... buf[len - 1]. */
duk_pop(ctx);

See also §

• duk_cbor_decode

Prototype §

duk_codepoint_t duk_char_code_at(duk_context *ctx, duk_idx_t idx, duk_size_t char_offset);

Stack §

Summary §

Get the codepoint of a character at character offset char_offset of a string at idx. If the value at idx is not a string, an error is thrown. If the string cannot be (extended) UTF-8 decoded, the result is U+FFFD (Unicode replacement character). If char_offset is invalid (outside the string) a zero is returned.

Example §

printf("char code at char index 12: %ld\n", (long) duk_char_code_at(ctx, -3, 12));

Prototype §

duk_bool_t duk_check_stack(duk_context *ctx, duk_idx_t extra);

Stack §

(No effect on value stack.)

Summary §

Ensure that the value stack has at least extra reserved (allocated) elements for caller's use, relative to the current stack top. Returns 1 if successful, 0 otherwise. If the call is successful, the caller is guaranteed that extra elements can be pushed to the value stack without a value stack related error (other errors like out-of-memory can still occur). The caller MUST NOT rely on being able to push more than extra values; although this is possible, such elements are reserved for Duktape's internal use.

Upon entry to a Duktape/C function and when outside any call there is an automatic reserve (of DUK_API_ENTRY_STACK elements) allocated for the caller in addition to call arguments on the value stack. If more value stack space is needed, the caller must reserve more space explicitly either in the beginning of the function (e.g. if the number of elements required is known or can be computed based on arguments) or dynamically (e.g. inside a loop). Note that an attempt to push a value beyond the currently allocated value stack causes an error: it does not cause the value stack to be automatically extended. This simplifies the internal implementation.

In addition to user reserved elements, Duktape keeps an automatic internal value stack reserve to ensure all API calls have enough value stack space to work without further allocations. The value stack is also extended in somewhat large steps to minimize memory reallocation activity. As a result the internal number of value stack elements available beyond the caller specified extra varies considerably. The caller does not need to take this into account and should never rely on any additional elements being available.

As a general rule duk_require_stack() should be used instead of this function to reserve more stack space. If value stack cannot be extended, there is almost never a useful recovery strategy except to throw an error and unwind.

Example §

duk_idx_t nargs = duk_get_top(ctx);  /* number or arguments */

/* reserve space for one temporary for each input argument */
if (!duk_check_stack(ctx, nargs)) {
    /* return 'undefined' if cannot allocate space */
    printf("failed to reserve enough stack space\n");
    return 0;
}

/* ... */

See also §

• duk_require_stack

Prototype §

duk_bool_t duk_check_stack_top(duk_context *ctx, duk_idx_t top);

Stack §

(No effect on value stack.)

Summary §

Like duk_check_stack(), but ensures there is space up to top for caller's use. This is sometimes more convenient than specifying the number of additional elements (relative to current stack top) to reserve.

As a general rule duk_require_stack_top() should be used instead of this function to reserve more stack space. If value stack cannot be extended, there is almost never a useful recovery strategy except to throw an error and unwind.

Example §

if (duk_check_stack_top(ctx, 100)) {
    printf("value stack guaranteed up to index 99\n");
} else {
    printf("cannot get value stack space\n");
}

See also §

• duk_require_stack_top

Prototype §

duk_bool_t duk_check_type(duk_context *ctx, duk_idx_t idx, duk_int_t type);

Stack §

Summary §

Matches the type of the value at idx against type. Returns 1 if the type matches, zero otherwise.

Example §

if (duk_check_type(ctx, -3, DUK_TYPE_NUMBER)) {
    printf("value is a number\n");
}

Prototype §

duk_bool_t duk_check_type_mask(duk_context *ctx, duk_idx_t idx, duk_uint_t mask);

Stack §

Summary §

Matches the type of the value at idx against the type mask bits given in mask. Returns 1 if the value type matches one of the type mask bits and zero otherwise.

Example §

if (duk_check_type_mask(ctx, -3, DUK_TYPE_MASK_STRING |
                                 DUK_TYPE_MASK_NUMBER)) {
    printf("value is a string or a number\n");
}

Prototype §

void duk_compact(duk_context *ctx, duk_idx_t obj_idx);

Stack §

(No effect on value stack.)

Summary §

Resizes an object's internal memory allocation to minimize memory usage. If the value at obj_idx is not an object, does nothing. Although compaction is normally safe, it can fail due to an internal error (such as out-of-memory error). Compaction only affects to an object's "own properties", not its inherited properties.

Compaction is not a final operation and has no impact on object semantics. Adding new properties to the object is still possible (assuming the object is extensible), but causes an object resize. Existing property values can be changed (assuming the properties are writable) without affecting the object's internal memory allocation. An object can be compacted multiple times: for instance, if a new property is added to a previously compacted object, the object can be compacted again to minimize memory footprint after the property addition.

Compacting an object saves a small amount of memory per object. It is generally useful when (1) memory footprint is very important, (2) an object is unlikely to gain new properties, (3) an object is relatively long-lived, and (4) when compaction can be applied to enough many objects to make a significant difference.

If Object.seal(), Object.freeze(), or Object.preventExtensions() is called, an object is automatically compacted.

Example §

duk_push_object(ctx);                           /* [ ... obj ] */
duk_push_int(ctx, 42);                          /* [ ... obj 42 ] */
duk_put_prop_string(ctx, -2, "meaningOfLife");  /* [ ... obj ] */
duk_compact(ctx, -1);                           /* [ ... obj ] */

Prototype §

void duk_compile(duk_context *ctx, duk_uint_t flags);

Stack §

Summary §

Compile ECMAScript source code and replace it with a compiled function object (the code is not executed). The filename argument is stored as the fileName property of the resulting function, and is the name used in e.g. tracebacks to identify the function. May throw a SyntaxError for any compile-time errors (in addition to the usual internal errors like out-of-memory, internal limit errors, etc).

The following flags may be given:

The source code being compiled may be:

• Global code: compiles into a function with zero arguments, which executes like a top level ECMAScript program (default)
• Eval code: compiles into a function with zero arguments, which executes like an ECMAScript eval call (flag DUK_COMPILE_EVAL)
• Function code: compiles into a function with zero or more arguments (flag DUK_COMPILE_FUNCTION)

All of these have slightly different semantics in ECMAScript. See Establishing an Execution Context for a detailed discussion. One major difference is that global and eval contexts have an implicit return value: the last non-empty statement value is an automatic return value for the program or eval code, whereas functions don't have an automatic return value.

Global and eval code don't have an explicit function syntax. For instance, the following can be compiled both as a global and as an eval expression:

print("Hello world!");
123;  // implicit return value

Function code follows the ECMAScript function syntax (the function name is optional):

function adder(x,y) {
    return x+y;
}

Compiling a function is equivalent to compiling eval code which contains a function expression. Note that the outermost parentheses are required, otherwise the eval code will register a global function named "adder" instead of returning a plain function value:

(function adder(x,y) {
    return x+y;
})

The bytecode generated for global and eval code is currently slower than that generated for functions: a "slow path" is used for all variable accesses in program and eval code, and the implicit return value handling of program and eval code generates some unnecessary bytecode. From a performance point of view (both memory and execution performance) it is thus preferable to have as much code inside functions as possible.

When compiling eval and global expressions, be careful to avoid the usual ECMAScript gotchas, such as:

/* Function at top level is a function declaration which registers a global
 * function, and is different from a function expression.  Use parentheses
 * around the top level expression.
 */

eval("function adder(x,y) { return x+y; }");   /* registers 'adder' to global */
eval("function (x,y) { return x+y; }");        /* not allowed */
eval("(function (x,y) { return x+y; })");      /* function expression (anonymous) */
eval("(function adder(x,y) { return x+y; })"); /* function expression (named) */

/* Opening curly brace at top level is interpreted as start of a block
 * expression, not an object literal.  Use parentheses around the top
 * level expression.
 */

eval("{ myfunc: 1 }");   /* block with -label- "myfunc" and statement "1" (!) */
eval("({ myfunc: 1 })";  /* object literal { myfunc: 1 } */

Example §

/* Global code.  Note that the hello() function is a function
 * declaration which gets registered into the global object when
 * executed.  Implicit return value is 123.
 */

duk_push_string(ctx, "print('global');\n"
                     "function hello() { print('Hello world!'); }\n"
                     "123;");
duk_push_string(ctx, "hello");
duk_compile(ctx, 0);   /* [ source filename ] -> [ func ] */
duk_call(ctx, 0);      /* [ func ] -> [ result ] */
printf("program result: %lf\n", (double) duk_get_number(ctx, -1));
duk_pop(ctx);

/* Eval code */

duk_push_string(ctx, "2+3");
duk_push_string(ctx, "eval");
duk_compile(ctx, DUK_COMPILE_EVAL);
duk_call(ctx, 0);      /* [ func ] -> [ result ] */
printf("eval result: %lf\n", (double) duk_get_number(ctx, -1));
duk_pop(ctx);

/* Function code */

duk_push_string(ctx, "function (x,y) { return x+y; }");
duk_push_string(ctx, "function");
duk_compile(ctx, DUK_COMPILE_FUNCTION);
duk_push_int(ctx, 5);
duk_push_int(ctx, 6);
duk_call(ctx, 2);      /* [ func 5 6 ] -> [ result ] */
printf("function result: %lf\n", (double) duk_get_number(ctx, -1));
duk_pop(ctx);

See also §

• duk_pcompile
• duk_compile_string
• duk_compile_string_filename
• duk_compile_lstring
• duk_compile_lstring_filename

Prototype §

void duk_compile_lstring(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len);

Stack §

Summary §

Like duk_compile(), but the compile input is given as a C string with explicit length. The filename associated with the function is "input".

Example §

const char *src = /* ... */;
duk_size_t len = /* ... */;

duk_compile_lstring(ctx, 0, src, len);

Prototype §

void duk_compile_lstring_filename(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len);

Stack §

Summary §

Like duk_compile(), but the compile input is given as a C string with explicit length.

Example §

const char *src = /* ... */;
duk_size_t len = /* ... */;

duk_push_string(ctx, "myFile.js");
duk_compile_lstring_filename(ctx, 0, src, len);

Prototype §

void duk_compile_string(duk_context *ctx, duk_uint_t flags, const char *src);

Stack §

Summary §

Like duk_compile(), but the compile input is given as a C string. The filename associated with the function is "input".

Example §

duk_compile_string(ctx, 0, "print('program code');");

Prototype §

void duk_compile_string_filename(duk_context *ctx, duk_uint_t flags, const char *src);

Stack §

Summary §

Like duk_compile(), but the compile input is given as a C string.

Example §

duk_push_string(ctx, "myFile.js");
duk_compile_string_filename(ctx, 0, "print('program code');");

Prototype §

duk_double_t duk_components_to_time(duk_context *ctx, duk_time_components *comp);

Stack §

(No effect on value stack.)

Summary §

Convert components (year, month, day, etc), interpreted in UTC, into a time value. The comp->weekday argument is ignored in the conversion. If the component values are invalid, an error is thrown.

There are some differences to the ECMAScript Date.UTC() built-in:

• There's no special handling of two-digit years. For example, Date.UTC(99, 0, 1) gets interpreted as 1999-01-01. If comp->time is 99, it's interpreted as the year 99.
• The milliseconds component is allowed fractions (sub-millisecond resolution) so that the resulting time value may have fractions.

Like the ECMAScript primitives, the components can exceed their natural range and are normalized. For example, specifying comp->minutes as 120 is interpreted as adding 2 hours to the time value. The components are expressed as IEEE doubles to allow large and negative values to be used.

Example §

duk_time_components comp;
duk_double_t time;

memset((void *) &comp, 0, sizeof(comp));  /* good practice even if fully initialized */
comp.year = 2016;
comp.month = 0;  /* 0-based, 1=January */
comp.day = 2;    /* 1-based: second of January */
comp.hours = 3;
comp.minutes = 4;
comp.seconds = 5;
comp.milliseconds = 6.0;  /* allows sub-millisecond resolution */
comp.weekday = 0;  /* ignored */

time = duk_components_to_time(ctx, &comp);
printf("2016-01-02 03:04:05.006Z -> %lf\n", (double) time);

See also §

• duk_time_to_components

Prototype §

void duk_concat(duk_context *ctx, duk_idx_t count);

Stack §

Summary §

Concatenate zero or more values into a result string. The input values are automatically coerced with ToString().

This primitive minimizes the number of intermediate string interning operations and is better than concatenating strings manually.

Example §

duk_push_string(ctx, "foo");
duk_push_int(ctx, 123);
duk_push_true(ctx);
duk_concat(ctx, 3);

printf("result: %s\n", duk_get_string(ctx, -1));  /* "foo123true" */
duk_pop(ctx);

See also §

• duk_join

Prototype §

void duk_config_buffer(duk_context *ctx, duk_idx_t idx, void *ptr, duk_size_t len);

Stack §

Summary §

Set the external buffer pointer and length of an external buffer value.

Example §

/* Create an external buffer and point it to my_buffer containing
 * my_length bytes.
 */
duk_push_external_buffer(ctx);
duk_config_buffer(ctx, -1, my_buffer, my_length);

See also §

• duk_push_external_buffer

Prototype §

void duk_copy(duk_context *ctx, duk_idx_t from_idx, duk_idx_t to_idx);

Stack §

Summary §

Copy a value from from_idx to to_idx, overwriting the previous value. If either index is invalid, throws an error.

This is a shorthand for:

/* to_index must be normalized in case it is negative and would change its
 * meaning after duk_dup().
 */
to_idx = duk_normalize_idx(ctx, to_idx);
duk_dup(ctx, from_idx);
duk_replace(ctx, to_idx);

Example §

duk_copy(ctx, -3, 1);

See also §

• duk_insert
• duk_replace

Prototype §

duk_context *duk_create_heap(duk_alloc_function alloc_func,
                             duk_realloc_function realloc_func,
                             duk_free_function free_func,
                             void *heap_udata,
                             duk_fatal_function fatal_handler);

Stack §

(No effect on value stack.)

Summary §

Create a new Duktape heap and return an initial context (thread). If heap initialization fails, a NULL is returned. There is currently no way to obtain more detailed error information.

The caller may provide custom memory management functions in alloc_func, realloc_func, and free_func; the pointers must either all be NULL or all be non-NULL. If the pointers are NULL, default memory management functions (ANSI C malloc(), realloc() , and free()) are used. The memory management functions share the same opaque userdata pointer, heap_udata. This userdata pointer is also used for other Duktape features like fatal error handling and low memory pointer compression macros.

A fatal error handler is provided in fatal_handler. This handler is called in unrecoverable error situations such as uncaught errors, out-of-memory errors not resolved by garbage collection, self test errors, etc. A caller SHOULD implement a fatal error handler in most applications. If not given, a default fatal error handler built into Duktape is used instead. The default fatal error handler (unless overridden by duk_config.h) calls abort() with no error message printed to stdout or stderr. See How to handle fatal errors for more detail and examples.

To create a Duktape heap with default settings, use duk_create_heap_default().

New contexts linked to the same heap can be created with duk_push_thread() and duk_push_thread_new_globalenv().

Example §

/*
 *  Simple case: use default allocation functions and fatal error handler
 */

duk_context *ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL);
if (ctx) {
    /* success */
} else {
    /* error */
}

/*
 *  Customized handlers
 */

duk_context *ctx = duk_create_heap(my_alloc, my_realloc, my_free,
                                   (void *) 0xdeadbeef, my_fatal);
if (ctx) {
    /* success */

    /* ... after heap is no longer needed: */
    duk_destroy_heap(ctx);
} else {
    /* error */
}

See also §

• duk_create_heap_default
• duk_destroy_heap

Prototype §

duk_context *duk_create_heap_default(void);

Stack §

(No effect on value stack.)

Summary §

Create a new Duktape heap and return an initial context (thread). If heap initialization fails, a NULL is returned. There is currently no way to obtain more detailed error information.

The created heap will use default memory management and fatal error handler functions. This API call is equivalent to:

ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL);

Example §

duk_context *ctx = duk_create_heap_default();
if (ctx) {
    /* success */

    /* ... after heap is no longer needed: */
    duk_destroy_heap(ctx);
} else {
    /* error */
}

Prototype §

void duk_debugger_attach(duk_context *ctx,
                         duk_debug_read_function read_cb,
                         duk_debug_write_function write_cb,
                         duk_debug_peek_function peek_cb,
                         duk_debug_read_flush_function read_flush_cb,
                         duk_debug_write_flush_function write_flush_cb,
                         duk_debug_request_function request_cb,
                         duk_debug_detached_function detached_cb,
                         void *udata);

Stack §

(No effect on value stack.)

Summary §

Attach a debugger to the Duktape heap. The debugger will automatically enter paused state when the attach is complete. If debugger support is not compiled into Duktape, throws an error. See debugger.rst for more information on debugger integration. The callbacks are as follows, optional callbacks may be NULL:

Important: The callbacks are not allowed to call any Duktape API functions (doing so may cause memory unsafe behavior) except for the following:

• The request_cb AppRequest callback may use the value stack within the guidelines described in debugger.rst.
• Since Duktape 1.4.0 the debugger detached callback is allowed to call duk_debugger_attach() to immediately reattach the debugger. Before Duktape 1.4.0 the immediate reattach potentially caused some issues.

Example §

duk_debugger_attach(ctx,
                    my_read_cb,
                    my_write_cb,
                    my_peek_cb,
                    NULL,
                    NULL,
                    NULL,
                    my_detached_cb,
                    my_udata);

See also §

• duk_debugger_detach
• duk_debugger_cooperate
• duk_debugger_notify

Prototype §

void duk_debugger_cooperate(duk_context *ctx);

Stack §

(No effect on value stack.)

Summary §

Check for and execute inbound debug commands without blocking. Debug commands are executed in the context of the ctx argument. May only be called when no calls into Duktape are in progress (from any context). See debugger.rst for more information.

Example §

duk_debugger_cooperate(ctx);

See also §

• duk_debugger_attach
• duk_debugger_detach

Prototype §

void duk_debugger_detach(duk_context *ctx);

Stack §

(No effect on value stack.)

Summary §

Detach a debugger from the Duktape heap. If debugger support is not compiled into Duktape, throws an error. See debugger.rst for more information.

Example §

duk_debugger_detach(ctx);

See also §

• duk_debugger_attach
• duk_debugger_cooperate

Prototype §

duk_bool_t duk_debugger_notify(duk_context *ctx, duk_idx_t nvalues);

Stack §

Summary §

Send an application specific debugger notify (AppNotify) containing the nvalues values on the value stack top mapped to debug protocol dvalues. The return value indicates whether the notify was successfully sent (non-zero) or not (zero). The nvalues arguments are always popped off the stack top. The call is a no-op if debugger support has not been compiled in, or if the debugger is not attached; in both cases the call will return zero to indicate that the notify was not sent.

See the debugger documentation for more information and examples on how to use application specific notifications.

Example §

/* Causes the following notify to be sent over the debugger protocol:
 *
 *   NFY AppNotify "BatteryStatus" 740 1000 true EOM
 */
int battery_current = 740;
int battery_limit = 1000;
int battery_charging = 1;

duk_push_string(ctx, "BatteryStatus");
duk_push_int(ctx, battery_current);
duk_push_int(ctx, battery_limit);
duk_push_boolean(ctx, battery_charging);
if (duk_debugger_notify(ctx, 4 /*nvalues*/)) {
    printf("battery status notification sent\n");
} else {
    printf("battery status notification not sent\n");
}

Prototype §

void duk_debugger_pause(duk_context *ctx);

Stack §

(No effect on value stack.)

Summary §

Request a debugger pause as soon as possible and return without blocking. The pause will be triggered the next time ECMAScript bytecode is executed, which is usually almost immediate. However, if a native call such as a Duktape/C function is in progress or no ECMAScript code is currently executing, it may take longer for the pause to take effect.

The call is a no-op if (1) debugger support has not been compiled in, (2) the debugger is not attached, or (3) Duktape is already paused. This mimics the semantics of the ECMAScript debugger statement.

Example §

/* In your event loop: */
if (key_pressed == KEY_F12) {
    duk_debugger_pause(ctx);
}

Prototype §

void duk_decode_string(duk_context *ctx, duk_idx_t idx, duk_decode_char_function callback, void *udata);

Stack §

Summary §

Process string at idx, calling callback for each codepoint of the string. The callback is given the udata argument and a codepoint. The input string is not modified. If the value is not a string or the index is invalid, throws an error.

Example §

static void decode_char(void *udata, duk_codepoint_t codepoint) {
    printf("codepoint: %ld\n", (long) codepoint);
}

duk_push_string(ctx, "test_string");
duk_decode_string(ctx, -1, decode_char, NULL);

See also §

• duk_map_string

Prototype §

void duk_def_prop(duk_context *ctx, duk_idx_t obj_idx, duk_uint_t flags);

Stack §

Summary §

Create or alter the attributes of property key of object at obj_idx, with semantics like Object.defineProperty(). When the requested change is not allowed (e.g. property is not configurable), a TypeError is thrown. If the target is not an object (or the index is invalid) an error is thrown.

The flags field provides "have" flags to indicate what property attributes are changed, which models the partial property descriptors allowed by Object.defineProperty(). Values for the writable, configurable, and enumerable attributes are given in the flags field, while property value, getter, and setter are given as value stack arguments. When creating a new property, missing attribute values cause ECMAScript defaults to be used (false for all boolean attributes, undefined for value, getter, setter); when modifying an existing property missing attribute values mean that existing attribute values are not touched.

As a concrete example:

// Set value, set writable, clear enumerable, leave configurable untouched.
Object.defineProperty(obj, { value: 123, writable: true, enumerable: false });

Would map to:

duk_push_uint(ctx, 123);  /* value is taken from stack */
duk_def_prop(ctx, obj_idx,
             DUK_DEFPROP_HAVE_VALUE |  /* <=> value: 123 */
             DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE |  /* <=> writable: true */
             DUK_DEFPROP_HAVE_ENUMERABLE);  /* <=> enumerable: false */

With the DUK_DEFPROP_FORCE flag property changes can be forced even when an operation would normally fail due to a non-extensible target object or a non-configurable property. This cannot be done from ECMAScript code with Object.defineProperty() and is useful for e.g. sandboxing setup. In some cases even a forced change is not possible and will cause an error to be thrown. For instance, properties implemented internally as virtual properties may not be modifiable (such as string .length and index properties) or may have limitations (such as array .length property which cannot be made configurable or enumerable due to internal limitations).

The following base flags are defined:

There are a also convenience defines mapping to common flag combinations. For example, DUK_DEFPROP_SET_WRITABLE is equivalent to DUK_DEFPROP_HAVE_WRITABLE and DUK_DEFPROP_WRITABLE. Currently the following are defined:

Some examples (see more examples below):

• To set value, set writable, clear enumerable, and set configurable, push the value onto the value stack and set flags to:
  • Base flags: DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE | DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_HAVE_CONFIGURABLE | DUK_DEFPROP_CONFIGURABLE; or
  • Convenience: DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_ATTR_WC.
• To clear the writable attribute (leaving other attributes untouched), set flags to:
  • Base flags: DUK_DEFPROP_HAVE_WRITABLE; or
  • Convenience: DUK_DEFPROP_CLEAR_WRITABLE; or
  • Convenience: DUK_DEFPROP_CLEAR_W.
• To set value, clear writable, and set enumerable (leaving other attributes untouched), push the value onto the value stack and set flags to:
  • Base flags: DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_ENUMERABLE; or
  • Convenience: DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_CLEAR_W | DUK_DEFPROP_SET_E; or
  • Convenience: DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_HAVE_WE | DUK_DEFPROP_E.

This API call is useful for various things:

• To create properties with non-default attributes directly from C code.
• To create accessor (getter/setter) properties directly from C code.
• To modify the property attributes of existing properties directly from C code.

See API testcase test-def-prop.c for more examples.

Example §

duk_idx_t obj_idx = /* ... */;

/* Create an ordinary property which is writable and configurable, but
 * not enumerable.  Equivalent to:
 *
 *   Object.defineProperty(obj, 'my_prop_1', {
 *      value: 123, writable: true, enumerable: false, configurable: true
 *   });
 */

duk_push_string(ctx, "my_prop_1");
duk_push_int(ctx, 123);  /* prop value */
duk_def_prop(ctx,
             obj_idx,
             DUK_DEFPROP_HAVE_VALUE |
             DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE |
             DUK_DEFPROP_HAVE_ENUMERABLE | 0 |
             DUK_DEFPROP_HAVE_CONFIGURABLE | DUK_DEFPROP_CONFIGURABLE);

/* The same but more readable using convenience flags. */

duk_push_string(ctx, "my_prop_1");
duk_push_int(ctx, 123);  /* prop value */
duk_def_prop(ctx, obj_idx, DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_ATTR_WC);

/* Change the property value and make it non-writable.  Don't touch other
 * attributes.  Equivalent to:
 *
 *   Object.defineProperty(obj, 'my_prop_1', {
 *      value: 321, writable: false
 *   });
 */

duk_push_string(ctx, "my_prop_1");
duk_push_int(ctx, 321);
duk_def_prop(ctx,
             obj_idx,
             DUK_DEFPROP_HAVE_VALUE |
             DUK_DEFPROP_HAVE_WRITABLE | 0);

/* The same but more readable using convenience flags. */

duk_push_string(ctx, "my_prop_1");
duk_push_int(ctx, 321);
duk_def_prop(ctx,
             obj_idx,
             DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_CLEAR_WRITABLE);

/* Make the property non-configurable, don't touch value or other attributes.
 * Equivalent to:
 *
 *   Object.defineProperty(obj, 'my_prop_1', {
 *      configurable: false
 *   });
 */

duk_push_string(ctx, "my_prop_1");
duk_def_prop(ctx,
             obj_idx,
             DUK_DEFPROP_HAVE_CONFIGURABLE | 0);

/* The same but more readable using convenience flags. */

duk_push_string(ctx, "my_prop_1");
duk_def_prop(ctx, obj_idx, DUK_DEFPROP_CLEAR_CONFIGURABLE);

/* Create an accessor property which is non-configurable and non-enumerable.
 * Attribute flags are not given so they default to ECMAScript defaults
 * (false) automatically.  Equivalent to:
 *
 *   object.defineproperty(obj, 'my_accessor_1', {
 *      get: my_getter, set: my_setter
 *   });
 */

duk_push_string(ctx, "my_accessor_1");
duk_push_c_function(ctx, my_getter, 0 /*nargs*/);
duk_push_c_function(ctx, my_setter, 1 /*nargs*/);
duk_def_prop(ctx,
             obj_idx,
             DUK_DEFPROP_HAVE_GETTER |
             DUK_DEFPROP_HAVE_SETTER);

/* Create an accessor property which is non-configurable but enumerable.
 * Attribute flags are given explicitly which is easier to read without
 * knowing about ECMAScript attribute default values.  Equivalent to:
 *
 *   Object.defineProperty(obj, 'my_accessor_2', {
 *      get: my_getter, set: my_setter, enumerable: true, configurable: false
 *   });
 */

duk_push_string(ctx, "my_accessor_2");
duk_push_c_function(ctx, my_getter, 0 /*nargs*/);
duk_push_c_function(ctx, my_setter, 1 /*nargs*/);
duk_def_prop(ctx,
             obj_idx,
             DUK_DEFPROP_HAVE_GETTER |
             DUK_DEFPROP_HAVE_SETTER |
             DUK_DEFPROP_HAVE_CONFIGURABLE |  /* clear */
             DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_ENUMERABLE);  /* set */

/* The same but more readable with convenience flags. */

duk_push_string(ctx, "my_accessor_2");
duk_push_c_function(ctx, my_getter, 0 /*nargs*/);
duk_push_c_function(ctx, my_setter, 1 /*nargs*/);
duk_def_prop(ctx,
             obj_idx,
             DUK_DEFPROP_HAVE_GETTER |
             DUK_DEFPROP_HAVE_SETTER |
             DUK_DEFPROP_HAVE_CLEAR_CONFIGURABLE |
             DUK_DEFPROP_HAVE_SET_ENUMERABLE);

/* Change the value of a non-configurable property by force.
 * No ECMAScript equivalent.
 */

duk_push_string(ctx, "my_nonconfigurable_prop");
duk_push_value(ctx, 321);
duk_def_prop(ctx,
             obj_idx,
             DUK_DEFPROP_HAVE_VALUE |
             DUK_DEFPROP_FORCE);