duktape/website/guide/intro.html

<h1 id="introduction">Introduction</h1>

<p>Version: <span class="duktape-version">XX.XX.XX</span> (<span class="current-date">XXXX-XX-XX</span>)</p>

<h2>Document scope</h2>

<p>This guide provides an introduction to using Duktape in your programs.
Once you're familiar with the basics, there is a concise
<a href="api.html">API reference</a> for looking up API details.</p>

<p>This document doesn't cover Duktape internals (see the
<a href="https://github.com/svaarala/duktape/tree/master/doc">Duktape repo</a>
if you wish to tinker with them).</p>

<h2>What is Duktape?</h2>

<p>Duktape is an embeddable Ecmascript E5/E5.1 interpreter with a focus
on portability and compact footprint.  By integrating Duktape into your
C/C++ program you can easily extend its functionality through scripting.
You can also build the main control flow of your program in Ecmascript
and use fast C code functions to do heavy lifting.</p>

<p>The terms Ecmascript and Javascript are often considered more or less
equivalent, although Javascript and its variants are technically just one
environment where the Ecmascript language is used.  The line between the
two is not very clear in practice: even non-browser Ecmascript environments
often provide some browser-specific built-ins.  Duktape is no exception,
and provides the commonly used <code>print()</code> and <code>alert()</code>
built-ins.  Even so, we use the term Ecmascript throughout to refer to the
language implemented by Duktape.</p>

<h2>Conformance</h2>

<p>Duktape conforms to the following Ecmascript specifications:</p>
<ul>
<li><a href="http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262%205th%20edition%20December%202009.pdf">Edition 5 (E5)</a></li>
<li><a href="http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf">Edition 5.1 (E5.1)</a>
    (as <a href="http://www.ecma-international.org/ecma-262/5.1/">HTML</a>)</li>
</ul>

<p>The upcoming Ecmascript Edition 6 standard is not yet final and Duktape has
no support for its features.</p>

<h2>Features</h2>

<p>Besides standard Ecmascript features, Duktape has the following additional
features (some are visible to applications, while others are internal):</p>
<ul>
<li>Additional built-ins: <code>print()</code> and <code>alert()</code> borrowed from
    browsers, Duktape specific built-ins in the <code>Duktape</code> global object</li>
<li>Extended types: custom "buffer" and "pointer" types, extended string type
    which supports arbitary binary strings and
    non-<a href="http://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane">BMP</a>
    strings (standard Ecmascript only supports 16-bit codepoints)</li>
<li>Combined reference counting and mark-and-sweep garbage collection,
    with finalizers and emergency garbage collection (you can also build
    with just reference counting or mark-and-sweep)</li>
<li>Coroutine support</li>
<li>Tail call support</li>
<li>Built-in regular expression engine with no platform dependencies</li>
<li>Built-in Unicode support with no platform dependencies</li>
<li>Built-in number parsing and formatting with no platform dependencies</li>
<li>Additional custom JSON formats (JSONX and JSONC)</li>
</ul>

<h2>Goals</h2>

<p><b>Compliance</b>.  Ecmascript E5/E5.1 and real world compliance.
Ecmascript compliance requires regular expression and Unicode support.</p>

<p><b>Portability</b>.  Minimal system dependencies are nice when porting,
so Duktape depends on very few system libraries.  For example, number
formatting and parsing, regular expressions, and Unicode are all implemented
internally by Duktape.  One of the few dependencies that cannot be fully
eliminated is system date/time integration.  This is confined to the
implementation of the <code>Date</code> built-in.</p>

<p><b>Easy C interface</b>.  The interface between Duktape and C programs
should be natural and error-tolerant.  As a particular issue, string
representation should be UTF-8 with automatic NUL terminators to match
common C use.</p>

<p><b>Small footprint</b>.  Code and data footprint should be as small as
possible, even for small programs.  This is more important than performance,
as there are already several very fast engines but fewer very compact,
portable engines.</p>

<p><b>Reasonable performance</b>.  Small footprint (and portability, to some
extent) probably eliminates the possibility of a competitive JIT-based engine,
so there is no practical way of competing with very advanced JIT-based engines
like SpiderMonkey (and its optimized variants) or Google V8.  Performance
should still be reasonable for typical embedded programs.
<a href="http://www.lua.org/">Lua</a> is a good benchmark in this respect.
(Adding optional, modular support for JITing or perhaps off-line compilation
would be nice.)</p>

<p><b>ASCII string performance</b>.  It's important that operations dealing
with plain ASCII strings be very fast: ASCII dominates most embedded use.
Operations dealing with non-ASCII strings need to perform reasonably but are
not critical.  This is a necessary trade-off: using C-compatible strings means
essentially using UTF-8 string representation which makes string indexing and
many other operations slower than with fixed size character representations.
It's still important to support common idioms like iterating strings sequentially
(in either direction) efficiently.</p>

<h2>Document organization</h2>

<p><a href="#gettingstarted">Getting started</a> guides you through downloading,
compiling, and integrating Duktape into your program.  It also provides concrete
examples of how you can integrate scripting capabilities into your program.</p>

<p><a href="#programming">Programming model</a> and <a href="#types">Stack types</a>
discuss core Duktape concepts such as <i>heap</i>, <i>context</i>, <i>value stacks</i>,
<i>Duktape API</i>, and <i>Duktape/C functions</i>.  Duktape types are discussed
in detail.</p>

<p>Duktape specific Ecmascript features are discussed in multiple sections:
<a href="#typealgorithms">Type algorithms</a> (for custom types),
<a href="#duktapebuiltins">Duktape built-ins</a> (additional built-ins), 
<a href="#custombehavior">Custom behavior</a> (behavior differing from standard),
<a href="#customjson">Custom JSON formats</a>,
<a href="#errorobjects">Error objects</a> (properties and traceback support),
<a href="#functionobjects">Function objects</a> (properties),
<a href="#finalization">Finalization</a>, and
<a href="#coroutines">Coroutines</a>.</p>

<p><a href="#compiling">Compiling</a> describes how to compile Duktape in detail,
covering in particular available feature defines.
<a href="#performance">Performance</a> provides a few Duktape-specific tips
for improving performance and avoiding performance pitfalls.
<a href="#portability">Portability</a> covers platform and compiler specific
issues and other portability issues.
<a href="#compatibility">Compatibility</a> discussed Duktape's compatibility
with Ecmascript dialects, extensions, and frameworks.
<a href="#limitations">Limitations</a> summarizes currently known limitations
and provides possible workarounds.</p>

<p><a href="#comparisontolua">Comparison to Lua</a> discusses some differences
between Lua and Duktape; it may be useful reading if you're already familiar with Lua.</p>