duktape/website/guide/duktapebuiltins.html

<h2 id="duktapebuiltins">Duktape built-ins</h2>

<p>This section describes Duktape-specific built-in objects, methods, and
values.</p>

<h3>Additional global object properties</h3>

<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 entries to <tt>stdout</tt>.</td></tr>
<tr><td class="propname">alert</td><td>Non-standard, browser-like function for writing entries to <tt>stderr</tt>.</td></tr>
</tbody>
</table>

<h3>The __duk__ object</h3>

<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: <tt>(major * 10000) + (minor * 100) + patch</tt>.</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.  First argument is format ("hex" or "base64"), second argument is value which is coerced to string before encoding.</td></tr>
<tr><td class="propname">dec</td><td>Decode a value.  First argument is format ("hex" or "base64"), second argument is value which is coerced to string before decoding.</td></tr>
<tr><td class="propname">addr</td><td>Get heap address of a value as a string, <tt>undefined</tt> if not appropriate (debug use).</td></tr>
<tr><td class="propname">refc</td><td>Get reference count of a value as a number, <tt>undefined</tt> 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>

<h4>version</h4>

<p>The <tt>version</tt> 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;= 700) {
    print('Duktape 0.7.0 or higher (but lower than 1.2.3)');
} else {
    print('Duktape lower than 0.7.0');
}
</pre>

<p>Remember to check for existence of <tt>__duk__</tt> 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>

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

<p>To encode a string into base64:</p>
<pre class="ecmascript-code">
__duk__.enc('base64', 'foo')  // returns 'Zm9v'
</pre>

<p>The input value is automatically coerced to a string and the internal byte
representation (CESU-8 for Ecmascript strings) is then base64 encoded.</p>

<p>Decoding is similar:</p>
<pre class="ecmascript-code">
__duk__.dec('base64', 'Zm9v')  // returns 'foo'
</pre>

<h3>__duk__.Buffer (constructor)</h3>

<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>

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

<h3>__duk__.Buffer.prototype</h3>

<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><tt>toString()</tt> and <tt>valueOf</tt> accept both plain buffers and
Buffer objects as their <tt>this</tt> binding.  This allows code such as:</p>
<pre class="ecmascript-code">
print(plain_buf.toString());
</pre>

<h3>__duk__.Pointer (constructor)</h3>

<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>

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

<h3>__duk__.Pointer.prototype</h3>

<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><tt>toString()</tt> and <tt>valueOf</tt> accept both plain pointers and
Pointer objects as their <tt>this</tt> binding.  This allows code such as:</p>
<pre class="ecmascript-code">
print(plain_ptr.toString());
</pre>

<h3>__duk__.Thread (constructor)</h3>

<table>
<thead>
<tr>
<th>Property</th><th>Description</th>
</tr>
</thead>
<tbody>
<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 <tt>TypeError</tt>
    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 <tt>__duk__.Thread.prototype</tt> object.</li>
</ul>

<h3>__duk__.Thread.prototype</h3>

<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>