Duktape built-ins

This section describes Duktape-specific built-in objects, methods, and values.

Additional global object properties

print and alert

print() writes to stdout with an automatic flush afterwards. The bytes written depend on the arguments:

• If given a single buffer argument, the contents of that buffer are written to stdout as is. This allows raw byte streams to be reliably written.
• Otherwise arguments are string coerced, joined with a single space character, a newline (0x0a) is appended, and the result is written to stdout. For instance, print('foo', 'bar') would write the bytes 66 6f 6f 20 62 61 72 0a. Non-ASCII characters are written directly in their internal extended UTF-8 representation; for most strings this means that output data is properly UTF-8 encoded. Terminal encoding, locale, platform newline conventions etc. have no effect on the output.

alert() behaves the same way, but writes to stderr. Unlike a browser alert(), the call does not block.

The Duktape object

version

The version property allows version-based feature detection and behavior. Version numbers can be compared directly: a logically higher version will also be numerically higher. For example:

if (typeof Duktape !== 'object') {
    print('not Duktape');
} else if (Duktape.version >= 10203) {
    print('Duktape 1.2.3 or higher');
} else if (Duktape.version >= 800) {
    print('Duktape 0.8.0 or higher (but lower than 1.2.3)');
} else {
    print('Duktape lower than 0.8.0');
}

Unofficial development snapshots have patch level set to 99. For example, version 0.11.99 (1199) would be a development snapshot after 0.11.0 but before the next official release.

Remember to check for existence of Duktape when doing feature detection. Your code should typically work on as many engines as possible. Avoid the common pitfall of using a direct identifier reference in the check:

// Bad idea: ReferenceError if missing
if (!Duktape) {
    print('not Duktape');
}

// Better: check through 'this' (bound to global)
if (!this.Duktape) {
    print('not Duktape');
}

// Better: use typeof to check also type explicitly
if (typeof Duktape !== 'object') {
    print('not Duktape');
}

env

env summarizes the most important effective compile options in a version specific, quite cryptic manner. The format is version specific and is not intended to be parsed programmatically. This is mostly useful for developers (see duk_hthread_builtins.c for the code which sets the value).

Example from Duktape 0.10.0:

ll u p2 a4 x64     // l|b|m integer endianness, l|b|m double endianness,
                   // p|u packed/unpacked tval, p1|p2 prop memory layout,
                   // a1/a4/a8 align target, arch

fin()

When called with a single argument, gets the current finalizer of an object:

var currFin = Duktape.fin(o);

When called with two arguments, sets the finalizer of an object (returns undefined):

Duktape.fin(o, function(x) { print('finalizer called'); });
Duktape.fin(o, undefined);  // disable

enc()

enc() encodes its argument value into chosen format. The first argument is a format (currently supported are "hex", "base64", "jx" and "jc"), second argument is the value to encode, and any further arguments are format specific.

For "hex" and "base64", buffer values are encoded as is, other values are string coerced and the internal byte representation (extended UTF-8) is then encoded. The result is a string. For example, to encode a string into base64:

var result = Duktape.enc('base64', 'foo');
print(result);  // prints 'Zm9v'

For "jx" and "jc" the argument list following the format name is the same as for JSON.stringify(): value, replacer (optional), space (optional). For example:

var result = Duktape.enc('jx', { foo: 123 }, null, 4);
print(result);  // prints JX encoded {foo:123} with 4-space indent

dec()

dec() provides the reverse function of enc().

For "hex" and "base64" the input value is first string coerced (it only really makes sense to decode strings). The result is always a buffer. For example:

var result = Duktape.dec('base64', 'Zm9v');
print(typeof result, result);  // prints 'buffer foo'

If you wish to get back a string value, you can simply:

var result = String(Duktape.dec('base64', 'Zm9v'));
print(typeof result, result);  // prints 'string foo'

For "jx" and "jc" the argument list following the format name is the same as for JSON.parse(): text, reviver (optional). For example:

var result = Duktape.dec('jx', "{foo:123}");
print(result.foo);  // prints 123

info()

When given an arbitrary input value, Duktape.info() returns an array of values with internal information related to the value. The format of of the values in the array is version specific. This is mainly useful for debugging and diagnosis, e.g. when estimating rough memory usage of objects.

The current result array format is described in the table below. Notes:

• Memory sizes do not include any heap overhead (which may be 8-16 bytes or more, depending on what kind of allocation algorithm is used).
• Reference counts are not adjusted in any way, and include references to the value caused by the info() call.
• "type tag" is a number matching DUK_TYPE_xxx from duktape.h.
• The number of entries allocated for object properties is given by "prop entry count", while "prop entry used" indicates how many of the entries are in used. If an array part is present, "prop array count" indicates the number of entries currently allocated (there is no value to indicate the number of used array part entries). Finally, "prop hash count" indicates the number of entries in a hash lookup table if present (it is not present for typical, small objects). These numbers are counts, not byte sizes.
• Function data contains bytecode instructions, constants, etc. It is shared between all instances (closures) of a certain function template.

line()

Get the line number of the call site. This may be useful for debugging, e.g.:

log.info('reached line:', Duktape.line());

act()

Get information about a call stack entry. Takes a single number argument indicating depth in the call stack: -1 is the top entry, -2 is the one below that etc. Returns an object describing the call stack entry, or undefined if the entry doesn't exist. Example:

function dump() {
    var i, t;
    for (i = -1; ; i--) {
        t = Duktape.act(i);
        if (!t) { break; }
        print(i, t.lineNumber, t.function.name, Duktape.enc('jx', t));
    }
}

dump();

The example, when executed with the command line tool, currently prints something like:

-1 0 act {lineNumber:0,pc:0,function:{_func:true}}
-2 4 dump {lineNumber:4,pc:16,function:{_func:true}}
-3 10 global {lineNumber:10,pc:5,function:{_func:true}}

The interesting entries are lineNumber and function which provides e.g. the function name.

You can also implement a helper to get the current line number using Duktape.act():

function getCurrentLine() {
    // indices: -1 = Duktape.act, -2 = getCurrentLine, -3 = caller
    var a = Duktape.act(-3) || {};
    return a.lineNumber;
}
print('running on line:', getCurrentLine());

gc()

Trigger a forced mark-and-sweep collection. If mark-and-sweep is disabled, this call is a no-op.

compact()

Minimize the memory allocated for a target object. Same as the C API call duk_compact() but accessible from Ecmascript code. If called with a non-object argument, this call is a no-op. The argument value is returned by the function, which allows code such as:

var obj = {
    foo: Duktape.compact({ bar:123 })
}

This call is useful when you know that an object is unlikely to gain new properties, but you don't want to seal or freeze the object in case it does.

errCreate() and errThrow()

These can be set by user code to process/replace errors when they are created (errCreate) or thrown (errThrow). Both values are initially non-existent.

See Error handlers (errCreate and errThrow) for details.

Duktape.Buffer (constructor)

The Buffer constructor is a function which returns a plain buffer when called as a normal function and a Buffer object when called as a constructor. Otherwise the behavior is the same:

• If the first argument is a plain buffer, the buffer is used as is (a new buffer is not created). The second argument is ignored. This form can be used to wrap a plain buffer value into a Buffer object.
• If the first argument is a Buffer object, the internal plain buffer value of the argument is used (a new buffer is not created). The second argument is again ignored. If called as a constructor, a new Buffer object is returned, but it will internally point to the same plain buffer value.
• If the first argument is a string, a new buffer is created and the bytes from the string's internal extended UTF-8 representation are copied to the buffer. The second argument (if present) indicates whether or not the new buffer should be dynamic (resizable); the default value is false.
• If the first argument is a number, a new buffer is created and filled with zero. The second argument (if present) indicates whether or not the new buffer should be dynamic. Zero filling the buffer is the default behavior, but this can be disabled with a feature option; if disabled, the contents will be unpredictable.
• When called as a constructor, the result is converted into a Buffer object whose internal value is the plain buffer. The internal prototype of the newly created Buffer will be the Duktape.Buffer.prototype object.

Duktape.Buffer.prototype

toString() and valueOf accept both plain buffers and Buffer objects as their this binding. This allows code such as:

var plain_buf = Duktape.Buffer('test');
print(plain_buf.toString());

Duktape.Pointer (constructor)

The Pointer constructor is a function which can be called both as an ordinary function and as a constructor:

• When called as a function, coerces the first argument to a pointer using the custom ToPointer coercion. The return value is a plain pointer (not a Pointer object).
• When called as a constructor, coerces the first argument to a pointer using the custom ToPointer coercion. Returns a Pointer object whose internal value is the pointer resulting from the coercion. The internal prototype of the newly created Pointer will be the Duktape.Pointer.prototype object.

Duktape.Pointer.prototype

toString() and valueOf accept both plain pointers and Pointer objects as their this binding. This allows code such as:

var plain_ptr = Duktape.Pointer({ test: 'object' });
print(plain_ptr.toString());

Duktape.Thread (constructor)

The Thread constructor is a function which can be called both as an ordinary function and as a constructor. The behavior is the same in both cases:

• The first argument is checked to be a function (if not, a TypeError is thrown). The return value is a new thread whose initial function is recorded to be the argument function (this function will start executing when the new thread is first resumed). The internal prototype of the newly created Thread will be the Duktape.Thread.prototype object.

Duktape.Thread.prototype

Duktape.Logger (constructor)

Called as a constructor, creates a new Logger object with a specified name (first argument). If the name is omitted, Logger will automatically assign a name based on the calling function's fileName. If called as a normal function, throws a TypeError.

Logger instances have the following properties:

• n: logger name; the property will be missing if (a) the given name is not a string, or (b) no name is given and the automatic assignment fails. The logger will then inherit a value from the Logger prototype. You can manually set this property later to whatever value is desired.
• l: log level, indicates the minimum log level to output. This property is not assigned by default and the logger inherits a default level from the Logger prototype. You can manually set this property to another value to control log level on a per-logger basis.

To write log entries:

var logger = new Duktape.Logger();
logger.info('three values:', val1, val2, val3);

For now, see the internal documentation on logging for more info.

Duktape.Logger.prototype