<commit_before><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">Proxy</td><td>Proxy constructor borrowed from ES6 draft (not part of Ecmascript E5/E5.1).</td></tr>
<tr><td class="propname">require</td><td>Non-standard, CommonsJS module loading function.</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>require()</h3>

<p>CommonJS module loading function, see
<a href="#modules">Modules</a>.</p>

<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, JX, JC): <code>Duktape.enc('hex', 'foo')</code>.</td></tr>
<tr><td class="propname">dec</td><td>Decode a value (hex, base-64, JX, JC): <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">act</td><td>Get information about call stack entry.</td></tr>
<tr><td class="propname">gc</td><td>Trigger mark-and-sweep garbage collection.</td></tr>
<tr><td class="propname">compact</td><td>Compact the memory allocated for a value (object).</td></tr>
<tr><td class="propname">errCreate</td><td>Callback to modify/replace a created error.</td></tr>
<tr><td class="propname">errThrow</td><td>Callback to modify/replace an error about to be thrown.</td></tr>
<tr><td class="propname">modSearch</td><td>Module search function, must be provided by user code if using modules.</td></tr>
<tr><td class="propname">modLoaded</td><td>Internal tracking table for loaded modules, maps resolved identifier to exported symbols.</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>
<tr><td class="propname">Logger</td><td>Logger 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 &gt;= 10203) {
    print('Duktape 1.2.3 or higher');
} else if (Duktape.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>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.</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>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.0.0:</p>
<pre class="ecmascript-code">
ll u p2 a4 x64 linux gcc     // l|b|m integer endianness, l|b|m IEEE double endianness
                             // p|u packed/unpacked tval, p1|p2|p3 prop memory layout
                             // a1/a4/a8: align target
                             // x64 etc: architecture
                             // linux etc: operating system
                             // gcc etc: compiler
</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"><commit_msg>Improve Duktape.env example in guide<commit_after><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">Proxy</td><td>Proxy constructor borrowed from ES6 draft (not part of Ecmascript E5/E5.1).</td></tr>
<tr><td class="propname">require</td><td>Non-standard, CommonsJS module loading function.</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>require()</h3>

<p>CommonJS module loading function, see
<a href="#modules">Modules</a>.</p>

<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, JX, JC): <code>Duktape.enc('hex', 'foo')</code>.</td></tr>
<tr><td class="propname">dec</td><td>Decode a value (hex, base-64, JX, JC): <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">act</td><td>Get information about call stack entry.</td></tr>
<tr><td class="propname">gc</td><td>Trigger mark-and-sweep garbage collection.</td></tr>
<tr><td class="propname">compact</td><td>Compact the memory allocated for a value (object).</td></tr>
<tr><td class="propname">errCreate</td><td>Callback to modify/replace a created error.</td></tr>
<tr><td class="propname">errThrow</td><td>Callback to modify/replace an error about to be thrown.</td></tr>
<tr><td class="propname">modSearch</td><td>Module search function, must be provided by user code if using modules.</td></tr>
<tr><td class="propname">modLoaded</td><td>Internal tracking table for loaded modules, maps resolved identifier to exported symbols.</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>
<tr><td class="propname">Logger</td><td>Logger 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 &gt;= 10203) {
    print('Duktape 1.2.3 or higher');
} else if (Duktape.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>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.</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>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.0.0:</p>
<pre class="ecmascript-code">
ll u p2 a4 x64 linux gcc     // l|b|m integer endianness, l|b|m IEEE double endianness
                             // p|u packed/unpacked tval, 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>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">
{'fraction_non_alphanumeric': 0.1598120764017252, 'fraction_numerical': 0.015865680837954404, 'mean_word_length': 4.532594801874733, 'pattern_counts': {'":': 0, '<': 497, '<?xml version=': 0, '>': 497, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2868848', 'n_tokens_mistral': 4287, 'n_tokens_neox': 4175, 'n_words': 1322}