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.
503 lines
15 KiB
503 lines
15 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">Duktape</td><td>The Duktape built-in object. Contains miscellaneous implementation specific stuff.</td></tr>
|
|
<tr><td class="propname">print</td><td>Non-standard, browser-like function for writing to <code>stdout</code>.</td></tr>
|
|
<tr><td class="propname">alert</td><td>Non-standard, browser-like function for writing to <code>stderr</code>.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>print and alert</h3>
|
|
|
|
<p><code>print()</code> writes to <code>stdout</code> with an automatic
|
|
flush afterwards. The bytes written depend on the arguments:</p>
|
|
<ul>
|
|
<li>If given a single buffer argument, the contents of that buffer are
|
|
written to <code>stdout</code> as is. This allows raw byte streams
|
|
to be reliably written.</li>
|
|
<li>Otherwise arguments are string coerced, joined with a single space
|
|
character, a newline (0x0a) is appended, and the result is written
|
|
to <code>stdout</code>. For instance, <code>print('foo', 'bar')</code>
|
|
would write the bytes <code>66 6f 6f 20 62 61 72 0a</code>. 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.</li>
|
|
</ul>
|
|
|
|
<p><code>alert()</code> behaves the same way, but writes to
|
|
<code>stderr</code>. Unlike a browser <code>alert()</code>, the call
|
|
does not block.</p>
|
|
|
|
<h2>The Duktape object</h2>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Property</th><th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td class="propname">version</td><td>Duktape version number: <code>(major * 10000) + (minor * 100) + patch</code>.</td></tr>
|
|
<tr><td class="propname">env</td><td>Cryptic, version dependent summary of most important effective options like endianness and architecture.</td></tr>
|
|
<tr><td class="propname">fin</td><td>Set or get finalizer of an object.</td></tr>
|
|
<tr><td class="propname">enc</td><td>Encode a value (hex, base-64, JSONX, JSONC): <code>Duktape.enc('hex', 'foo')</code>.</td></tr>
|
|
<tr><td class="propname">dec</td><td>Decode a value (hex, base-64, JSONX, JSONC): <code>Duktape.dec('base64', 'Zm9v')</code>.</td></tr>
|
|
<tr><td class="propname">info</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">gc</td><td>Trigger mark-and-sweep garbage collection.</td></tr>
|
|
<tr><td class="propname">Buffer</td><td>Buffer constructor (function).</td></tr>
|
|
<tr><td class="propname">Pointer</td><td>Pointer constructor (function).</td></tr>
|
|
<tr><td class="propname">Thread</td><td>Thread constructor (function).</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>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>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>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 0.9.0:</p>
|
|
<pre class="ecmascript-code">
|
|
l u x64 // l|b|m endianness, p|u packed/unpacked tval, arch
|
|
</pre>
|
|
|
|
<h3>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>enc()</h3>
|
|
|
|
<p><code>enc()</code> encodes its argument value into chosen format.
|
|
The first argument is a format (currently supported are "hex", "base64",
|
|
"jsonx" and "jsonc"), 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 "jsonx" and "jsonc" 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('jsonx', { foo: 123 }, null, 4);
|
|
print(result); // prints JSONX encoded {foo:123} with 4-space indent
|
|
</pre>
|
|
|
|
<h3>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 buffer. For example:</p>
|
|
<pre class="ecmascript-code">
|
|
var result = Duktape.dec('base64', 'Zm9v');
|
|
print(typeof result, result); // prints 'buffer foo'
|
|
</pre>
|
|
|
|
<p>If you wish to get back a string value, you can simply:</p>
|
|
<pre class="ecmascript-code">
|
|
var result = String(Duktape.dec('base64', 'Zm9v'));
|
|
print(typeof result, result); // prints 'string foo'
|
|
</pre>
|
|
|
|
<p>For "jsonx" and "jsonc" 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('jsonx', "{foo:123}");
|
|
print(result.foo); // prints 123
|
|
</pre>
|
|
|
|
<h3>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>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.</li>
|
|
<li>Function data contains bytecode instructions, constants, etc. It is
|
|
shared between all instances (closures) of a certain function template.</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>-</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>-</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>-</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>-</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>-</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 used</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 used</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 used</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 used</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>pointer</td>
|
|
<td>type tag</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
<td>-</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<h2>Duktape.Buffer (constructor)</h2>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Property</th><th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td class="propname">prototype</td><td>Prototype for Buffer objects.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>The Buffer 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 buffer using
|
|
the custom <code>ToBuffer</code> coercion. The return value is a plain
|
|
buffer (not a Buffer object).</li>
|
|
<li>When called as a constructor, coerces the first argument to a buffer
|
|
using the custom <code>ToBuffer</code> coercion. Returns a Buffer object
|
|
whose internal value is the buffer resulting from the coercion. The
|
|
internal prototype of the newly created Buffer will be the
|
|
<code>Duktape.Buffer.prototype</code> object.</li>
|
|
</ul>
|
|
|
|
<h2>Duktape.Buffer.prototype</h2>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Property</th><th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td class="propname">toString</td><td>Convert Buffer to a printable string.</td></tr>
|
|
<tr><td class="propname">valueOf</td><td>Return the primitive buffer value held by Buffer.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p><code>toString()</code> and <code>valueOf</code> accept both plain buffers and
|
|
Buffer objects as their <code>this</code> binding. This allows code such as:</p>
|
|
<pre class="ecmascript-code">
|
|
var plain_buf = Duktape.Buffer('test');
|
|
print(plain_buf.toString());
|
|
</pre>
|
|
|
|
<h2>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>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>
|
|
|