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.
580 lines
18 KiB
580 lines
18 KiB
<h1 id="duktapebuiltins">Duktape built-ins</h1>
|
|
|
|
<p>This section describes Duktape-specific built-in objects, methods, and
|
|
values.</p>
|
|
|
|
<h2>Additional global object properties</h2>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Property</th><th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td class="propname"><a href="#builtin-duktape">Duktape</a></td>
|
|
<td>The Duktape built-in object. Contains miscellaneous implementation specific stuff.</td></tr>
|
|
<tr><td class="propname"><a href="#virtualization-proxy-object">Proxy</a></td>
|
|
<td>Proxy constructor borrowed from ES6 (not part of Ecmascript E5/E5.1).</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h2 id="builtin-duktape">The Duktape object</h2>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Property</th><th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td class="propname"><a href="#builtin-duktape-version">version</a></td>
|
|
<td>Duktape version number: <code>(major * 10000) + (minor * 100) + patch</code>.</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-env">env</a></td>
|
|
<td>Cryptic, version dependent summary of most important effective options like endianness and architecture.</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-fin">fin</a></td>
|
|
<td>Set or get finalizer of an object.</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-enc">enc</a></td>
|
|
<td>Encode a value (hex, base-64, JX, JC): <code>Duktape.enc('hex', 'foo')</code>.</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-dec">dec</a></td>
|
|
<td>Decode a value (hex, base-64, JX, JC): <code>Duktape.dec('base64', 'Zm9v')</code>.</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-info">info</a></td>
|
|
<td>Get internal information (such as heap address and alloc size) of a value in a version specific format.</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-act">act</a></td>
|
|
<td>Get information about call stack entry.</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-gc">gc</a></td>
|
|
<td>Trigger mark-and-sweep garbage collection.</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-compact">compact</a></td>
|
|
<td>Compact the memory allocated for a value (object).</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-errcreate-errthrow">errCreate</a></td>
|
|
<td>Callback to modify/replace a created error.</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-errcreate-errthrow">errThrow</a></td>
|
|
<td>Callback to modify/replace an error about to be thrown.</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-pointer">Pointer</a></td>
|
|
<td>Pointer constructor (function).</td></tr>
|
|
<tr><td class="propname"><a href="#builtin-duktape-thread">Thread</a></td>
|
|
<td>Thread constructor (function).</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3 id="builtin-duktape-version">version</h3>
|
|
|
|
<p>The <code>version</code> 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:</p>
|
|
<pre class="ecmascript-code">
|
|
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');
|
|
}
|
|
</pre>
|
|
|
|
<p>The value of <code>version</code> for pre-releases is one less than the
|
|
actual release, e.g. 1199 for a 0.12.0 pre-release and 10299 for a 1.3.0
|
|
pre-release. See <a href="#versioning">Versioning</a>.</p>
|
|
|
|
<p>Remember to check for existence of <code>Duktape</code> 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:</p>
|
|
<pre class="ecmascript-code">
|
|
// 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');
|
|
}
|
|
</pre>
|
|
|
|
<h3 id="builtin-duktape-env">env</h3>
|
|
|
|
<p><code>env</code> 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 <code>duk_hthread_builtins.c</code> for the code which sets
|
|
the value).</p>
|
|
|
|
<p>Example from Duktape 1.1.0:</p>
|
|
<pre class="ecmascript-code">
|
|
ll u n p2 a4 x64 linux gcc // l|b|m integer endianness, l|b|m IEEE double endianness
|
|
// p|u packed/unpacked tval
|
|
// n|various, memory optimization options (n = none)
|
|
// p1|p2|p3 prop memory layout
|
|
// a1|a4|a8: align target
|
|
// x64|x86|arm|etc: architecture
|
|
// linux|windows|etc: operating system
|
|
// gcc|clang|msvc|etc: compiler
|
|
</pre>
|
|
|
|
<h3 id="builtin-duktape-fin">fin()</h3>
|
|
|
|
<p>When called with a single argument, gets the current finalizer of an object:</p>
|
|
<pre class="ecmascript-code">
|
|
var currFin = Duktape.fin(o);
|
|
</pre>
|
|
|
|
<p>When called with two arguments, sets the finalizer of an object (returns undefined):</p>
|
|
<pre class="ecmascript-code">
|
|
Duktape.fin(o, function(x) { print('finalizer called'); });
|
|
Duktape.fin(o, undefined); // disable
|
|
</pre>
|
|
|
|
<h3 id="builtin-duktape-enc">enc()</h3>
|
|
|
|
<p><code>enc()</code> 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.</p>
|
|
|
|
<p>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:</p>
|
|
<pre class="ecmascript-code">
|
|
var result = Duktape.enc('base64', 'foo');
|
|
print(result); // prints 'Zm9v'
|
|
</pre>
|
|
|
|
<p>For "jx" and "jc" the argument list following the format name is the
|
|
same as for <code>JSON.stringify()</code>: value, replacer (optional),
|
|
space (optional). For example:</p>
|
|
<pre class="ecmascript-code">
|
|
var result = Duktape.enc('jx', { foo: 123 }, null, 4);
|
|
print(result); // prints JX encoded {foo:123} with 4-space indent
|
|
</pre>
|
|
|
|
<h3 id="builtin-duktape-dec">dec()</h3>
|
|
|
|
<p><code>dec()</code> provides the reverse function of <code>enc()</code>.</p>
|
|
|
|
<p>For "hex" and "base64" the input value is first string coerced (it only
|
|
really makes sense to decode strings). The result is always a plain buffer.
|
|
For example:</p>
|
|
<pre class="ecmascript-code">
|
|
var result = Duktape.dec('base64', 'Zm9v');
|
|
print(typeof result, result); // prints 'object foo'
|
|
</pre>
|
|
|
|
<p>If you wish to get back a string value, you can coerce the plain buffer to
|
|
a string as follows:</p>
|
|
<pre class="ecmascript-code">
|
|
var result = String.fromBuffer(Duktape.dec('base64', 'Zm9v'));
|
|
print(typeof result, result); // prints 'string foo'
|
|
</pre>
|
|
|
|
<p>For "jx" and "jc" the argument list following the format name is the same
|
|
as for <code>JSON.parse()</code>: text, reviver (optional). For example:</p>
|
|
<pre class="ecmascript-code">
|
|
var result = Duktape.dec('jx', "{foo:123}");
|
|
print(result.foo); // prints 123
|
|
</pre>
|
|
|
|
<h3 id="builtin-duktape-info">info()</h3>
|
|
|
|
<p>When given an arbitrary input value, <code>Duktape.info()</code> 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.</p>
|
|
|
|
<p>The current result array format is described in the table below. Notes:</p>
|
|
<ul>
|
|
<li>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).</li>
|
|
<li>Reference counts are not adjusted in any way, and include references to
|
|
the value caused by the <code>info()</code> call.</li>
|
|
<li>"type tag" is a number matching <code>DUK_TYPE_xxx</code> from <code>duktape.h</code>.</li>
|
|
<li>Prop entry count: for objects, number of entries allocated for properties
|
|
outside the array part.</li>
|
|
<li>Prop entry next: for objects, index where the next new property will be
|
|
inserted within the entry part. When "prop entry count" equals "prop entry next",
|
|
insertion of a new property causes an object resize.
|
|
Note that this number does <i>not</i> indicate the number of properties actually
|
|
present in the object because some entries may have been deleted and not yet
|
|
"compacted".</li>
|
|
<li>Prop array count: for objects, number of entries currently allocated
|
|
for the array part (if any); there is no value to indicate the number
|
|
of actually used entries (indices present).</li>
|
|
<li>Prop hash count: for objects, size of entry part hash lookup table or
|
|
zero if not present. Typical small objects don't have a hash part.</li>
|
|
<li>Function data contains bytecode instructions, constants, etc. It is
|
|
shared between all instances (closures) of a certain function template.</li>
|
|
<li>Internal type tag values may change between versions and are also
|
|
dependent on the memory layout used for tagged values internally.</li>
|
|
</ul>
|
|
|
|
<div class="table-wrap">
|
|
<table>
|
|
<thead>
|
|
<tr><th>Type</th><th>0</th><th>1</th><th>2</th><th>3</th><th>4</th><th>5</th><th>6</th><th>7</th><th>8</th><th>9</th></tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>undefined</td>
|
|
<td>type tag</td>
|
|
<td>internal type tag</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>null</td>
|
|
<td>type tag</td>
|
|
<td>internal type tag</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>boolean</td>
|
|
<td>type tag</td>
|
|
<td>internal type tag</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>number</td>
|
|
<td>type tag</td>
|
|
<td>internal type tag</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>string</td>
|
|
<td>type tag</td>
|
|
<td>heap ptr</td>
|
|
<td>refcount</td>
|
|
<td>heap hdr size</td>
|
|
<td>internal type tag</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>object, Ecmascript function</td>
|
|
<td>type tag</td>
|
|
<td>heap ptr</td>
|
|
<td>refcount</td>
|
|
<td>heap hdr size</td>
|
|
<td>prop alloc size</td>
|
|
<td>prop entry count</td>
|
|
<td>prop entry next</td>
|
|
<td>prop array count</td>
|
|
<td>prop hash count</td>
|
|
<td>func data size</td>
|
|
</tr>
|
|
<tr>
|
|
<td>object, Duktape/C function</td>
|
|
<td>type tag</td>
|
|
<td>heap ptr</td>
|
|
<td>refcount</td>
|
|
<td>heap hdr size</td>
|
|
<td>prop alloc size</td>
|
|
<td>prop entry count</td>
|
|
<td>prop entry next</td>
|
|
<td>prop array count</td>
|
|
<td>prop hash count</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>object, thread</td>
|
|
<td>type tag</td>
|
|
<td>heap ptr</td>
|
|
<td>refcount</td>
|
|
<td>heap hdr size</td>
|
|
<td>prop alloc size</td>
|
|
<td>prop entry count</td>
|
|
<td>prop entry next</td>
|
|
<td>prop array count</td>
|
|
<td>prop hash count</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>object, other</td>
|
|
<td>type tag</td>
|
|
<td>heap ptr</td>
|
|
<td>refcount</td>
|
|
<td>heap hdr size</td>
|
|
<td>prop alloc size</td>
|
|
<td>prop entry count</td>
|
|
<td>prop entry next</td>
|
|
<td>prop array count</td>
|
|
<td>prop hash count</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>buffer, fixed</td>
|
|
<td>type tag</td>
|
|
<td>heap ptr</td>
|
|
<td>refcount</td>
|
|
<td>heap hdr size</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>buffer, dynamic</td>
|
|
<td>type tag</td>
|
|
<td>heap ptr</td>
|
|
<td>refcount</td>
|
|
<td>heap hdr size</td>
|
|
<td>curr buf size</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>buffer, external</td>
|
|
<td>type tag</td>
|
|
<td>heap ptr</td>
|
|
<td>refcount</td>
|
|
<td>heap hdr size</td>
|
|
<td>curr buf size</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>pointer</td>
|
|
<td>type tag</td>
|
|
<td>internal type tag</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
</tr>
|
|
<tr>
|
|
<td>lightfunc</td>
|
|
<td>type tag</td>
|
|
<td>internal type tag</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<h3 id="builtin-duktape-act">act()</h3>
|
|
|
|
<p>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 <code>undefined</code>
|
|
if the entry doesn't exist. Example:</p>
|
|
<pre class="ecmascript-code">
|
|
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();
|
|
</pre>
|
|
|
|
<p>The example, when executed with the command line tool, currently prints
|
|
something like:</p>
|
|
<pre>
|
|
-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}}
|
|
</pre>
|
|
|
|
<p>The interesting entries are <code>lineNumber</code> and <code>function</code>
|
|
which provides e.g. the function name.</p>
|
|
|
|
<p>You can also implement a helper to get the current line number using
|
|
<code>Duktape.act()</code>:</p>
|
|
<pre class="ecmascript-code">
|
|
function getCurrentLine() {
|
|
'use duk notail';
|
|
|
|
/* Tail calls are prevented to ensure calling activation exists.
|
|
* Call stack indices: -1 = Duktape.act, -2 = getCurrentLine, -3 = caller
|
|
*/
|
|
|
|
var a = Duktape.act(-3) || {};
|
|
return a.lineNumber;
|
|
}
|
|
print('running on line:', getCurrentLine());
|
|
</pre>
|
|
|
|
<div class="note">
|
|
The properties provided for call stack entries may change between versions.
|
|
</div>
|
|
|
|
<h3 id="builtin-duktape-gc">gc()</h3>
|
|
|
|
<p>Trigger a forced mark-and-sweep collection. If mark-and-sweep is disabled,
|
|
this call is a no-op.</p>
|
|
|
|
<!-- Return value is undocumented for now, which is probably good for now.
|
|
Not sure what the best return value would be. Arguments are undocumented.
|
|
-->
|
|
|
|
<h3 id="builtin-duktape-compact">compact()</h3>
|
|
|
|
<p>Minimize the memory allocated for a target object. Same as the C API call
|
|
<code>duk_compact()</code> 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:</p>
|
|
<pre class="ecmascript-code">
|
|
var obj = {
|
|
foo: Duktape.compact({ bar:123 })
|
|
}
|
|
</pre>
|
|
|
|
<p>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.</p>
|
|
|
|
<h3 id="builtin-duktape-errcreate-errthrow">errCreate() and errThrow()</h3>
|
|
|
|
<p>These can be set by user code to process/replace errors when they are created
|
|
(<code>errCreate</code>) or thrown (<code>errThrow</code>). Both values are
|
|
initially non-existent.</p>
|
|
|
|
<p>See
|
|
<a href="#error-handlers">Error handlers (errCreate and errThrow)</a> for
|
|
details.</p>
|
|
|
|
<h2 id="builtin-duktape-pointer">Duktape.Pointer (constructor)</h2>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Property</th><th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td class="propname">prototype</td><td>Prototype for Pointer objects.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>The Pointer constructor is a function which can be called both as an
|
|
ordinary function and as a constructor:</p>
|
|
<ul>
|
|
<li>When called as a function, coerces the first argument to a pointer using
|
|
the custom <code>ToPointer</code> coercion. The return value is a plain
|
|
pointer (not a Pointer object).</li>
|
|
<li>When called as a constructor, coerces the first argument to a pointer
|
|
using the custom <code>ToPointer</code> 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
|
|
<code>Duktape.Pointer.prototype</code> object.</li>
|
|
</ul>
|
|
|
|
<h2>Duktape.Pointer.prototype</h2>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Property</th><th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td class="propname">toString</td><td>Convert Pointer to a printable string.</td></tr>
|
|
<tr><td class="propname">valueOf</td><td>Return the primitive pointer value held by Pointer.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p><code>toString()</code> and <code>valueOf</code> accept both plain pointers and
|
|
Pointer objects as their <code>this</code> binding. This allows code such as:</p>
|
|
<pre class="ecmascript-code">
|
|
var plain_ptr = Duktape.Pointer({ test: 'object' });
|
|
print(plain_ptr.toString());
|
|
</pre>
|
|
|
|
<h2 id="builtin-duktape-thread">Duktape.Thread (constructor)</h2>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Property</th><th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td class="propname">prototype</td><td>Prototype for Thread objects.</td></tr>
|
|
<tr><td class="propname">resume</td><td>Resume target thread with a value or an error.
|
|
Arguments: target thread, value, flag indicating whether value is to be thrown (optional, default false).</td></tr>
|
|
<tr><td class="propname">yield</td><td>Yield a value or an error from current thread.
|
|
Arguments: value, flag indicating whether value is to be thrown (optional, default false).</td></tr>
|
|
<tr><td class="propname">current</td><td>Get currently running Thread object.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>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:</p>
|
|
<ul>
|
|
<li>The first argument is checked to be a function (if not, a <code>TypeError</code>
|
|
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 <code>Duktape.Thread.prototype</code> object.</li>
|
|
</ul>
|
|
|
|
<h2>Duktape.Thread.prototype</h2>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Property</th><th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td colspan="2">No properties at the moment.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|