duktape/website/guide/duktapebuiltins.html

<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">__duk__</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 __duk__ object</h2>

<table>
<thead>
<tr>
<th>Property</th><th>Description</th>
</tr>
</thead>
<tbody>
<tr><td class="propname">build</td><td>Opaque build information string.  Describes when and how the Duktape distributable sources were built.</td></tr>
<tr><td class="propname">version</td><td>Duktape version number: <code>(major * 10000) + (minor * 100) + patch</code>.</td></tr>
<tr><td class="propname">setFinalizer</td><td>Set finalizer of an object.</td></tr>
<tr><td class="propname">getFinalizer</td><td>Set finalizer of an object.</td></tr>
<tr><td class="propname">enc</td><td>Encode a value: <code>__duk__.enc('hex', 'foo')</code>.</td></tr>
<tr><td class="propname">dec</td><td>Decode a value: <code>__duk__.dec('base64', 'Zm9v')</code>.</td></tr>
<tr><td class="propname">jsonxEnc</td><td>Like <code>JSON.stringify()</code> but encodes to JSONX custom format.</td></tr>
<tr><td class="propname">jsonxDec</td><td>Like <code>JSON.parse()</code> but decodes from JSONX custom format.</td></tr>
<tr><td class="propname">jsoncEnc</td><td>Like <code>JSON.stringify()</code> but encodes to JSONC custom format.</td></tr>
<tr><td class="propname">jsoncDec</td><td>Like <code>JSON.parse()</code> but decodes from JSONC custom format.</td></tr>
<tr><td class="propname">addr</td><td>Get heap address of a value as a string, <code>undefined</code> if not appropriate (debug use).</td></tr>
<tr><td class="propname">refc</td><td>Get reference count of a value as a number, <code>undefined</code> if not appropriate (debug use).</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 __duk__ !== 'object') {
    print('not Duktape');
} else if (__duk__.version &gt;= 10203) {
    print('Duktape 1.2.3 or higher');
} else if (__duk__.version &gt;= 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>__duk__</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 (!__duk__) {
    print('not Duktape');
}

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

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

<h3>enc() and dec()</h3>

<p><code>enc()</code> encodes its argument value into chosen format.
The first argument is a format (currently supported are "hex" and "base64"),
second argument is the value to encode.  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.</p>

<p>For example, to encode a string into base64:</p>
<pre class="ecmascript-code">
var result = __duk__.enc('base64', 'foo');
print(result);  // prints 'Zm9v'
</pre>

<p><code>dec()</code> provides the reverse function.  The input value is
first string coerced (it only really makes sense to decode strings), and
the result is always a buffer.  For example:</p>
<pre class="ecmascript-code">
var result = __duk__.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(__duk__.dec('base64', 'Zm9v'));
print(typeof result, result);  // prints 'string foo'
</pre>

<h2>__duk__.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>__duk__.Buffer.prototype</code> object.</li>
</ul>

<h2>__duk__.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 = __duk__.Buffer('test');
print(plain_buf.toString());
</pre>

<h2>__duk__.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>__duk__.Pointer.prototype</code> object.</li>
</ul>

<h2>__duk__.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 = __duk__.Pointer({ test: 'object' });
print(plain_ptr.toString());
</pre>

<h2>__duk__.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>__duk__.Thread.prototype</code> object.</li>
</ul>

<h2>__duk__.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>