duktape/website/api/defines.html

<h1 id="defines">Header definitions</h1>

<p>This section summarizes some commonly needed header definitions in
<code>duktape.h</code>.  It is not exhaustive and the excerpts have been
reorganized for readability.  Don't rely on the specific define values
shown below for e.g. flags fields.  When in doubt, consult the header
directly.</p>

<h2>Duktape version</h2>

<p>Duktape version is available through the <code>DUK_VERSION</code> define,
with the numeric value <code>(major * 10000 + minor * 100 + patch)</code>.
The same value is available to Ecmascript code through <code>Duktape.version</code>.
For example, version 1.2.3 would have <code>DUK_VERSION</code> and
<code>Duktape.version</code> set to 10203.  For pre-releases <code>DUK_VERSION</code>
is one less than the actual release, e.g. 1199 for a 0.12.0 pre-release and 10299
for a 1.3.0 pre-release.  See <a href="guide.html#versioning">Versioning</a>.</p>

<h2>Git information</h2>

<p>The following Git identifiers are available (all refer to the
<a href="https://github.com/svaarala/duktape">Duktape GitHub repo</a>):</p>

<table>
<tr>
<td><code>DUK_GIT_DESCRIBE</code></td>
<td>Git describe string for the Duktape build.  For official releases this
is just "v1.0.0" or similar, but for snapshot builds it provides useful
version information, e.g. "v1.0.0-155-g5b7ef1f-dirty".</td>
</tr>
<tr>
<td><code>DUK_GIT_COMMIT</code></td>
<td>Exact commit hash where distributable was built from.</td>
</tr>
<tr>
<td><code>DUK_GIT_BRANCH</code></td>
<td>Branch where the distributable was built from.  This is useful to
identify prototypes built from a development branch.</td>
</tr>
</table>

<p>There are no equivalent defines in the Ecmascript environment.</p>

<h2>Debug protocol version</h2>

<p>The version number of the debug protocol (a single integer) is available as
the define <code>DUK_DEBUG_PROTOCOL_VERSION</code>.</p>

<h2>Structs and typedefs</h2>
<pre class="c-code">
typedef struct duk_hthread duk_context;

typedef duk_ret_t (*duk_c_function)(duk_context *ctx);
typedef void *(*duk_alloc_function) (void *udata, duk_size_t size);
typedef void *(*duk_realloc_function) (void *udata, void *ptr, duk_size_t size);
typedef void (*duk_free_function) (void *udata, void *ptr);
typedef void (*duk_fatal_function) (void *udata, const char *msg);
typedef void (*duk_decode_char_function) (void *udata, duk_codepoint_t codepoint);
typedef duk_codepoint_t (*duk_map_char_function) (void *udata, duk_codepoint_t codepoint);
typedef duk_ret_t (*duk_safe_call_function) (duk_context *ctx, void *udata);
typedef duk_size_t (*duk_debug_read_function) (void *udata, char *buffer, duk_size_t length);
typedef duk_size_t (*duk_debug_write_function) (void *udata, const char *buffer, duk_size_t length);
typedef duk_size_t (*duk_debug_peek_function) (void *udata);
typedef void (*duk_debug_read_flush_function) (void *udata);
typedef void (*duk_debug_write_flush_function) (void *udata);
typedef void (*duk_debug_detached_function) (duk_context *ctx, void *udata);

struct duk_memory_functions {
        duk_alloc_function alloc_func;
        duk_realloc_function realloc_func;
        duk_free_function free_func;
        void *udata;
};
typedef struct duk_memory_functions duk_memory_functions;

struct duk_function_list_entry {
	const char *key;
	duk_c_function value;
	duk_int_t nargs;
};
typedef struct duk_function_list_entry duk_function_list_entry;

struct duk_number_list_entry {
	const char *key;
	duk_double_t value;
};
typedef struct duk_number_list_entry duk_number_list_entry;
</pre>

<h2>Error codes</h2>
<pre class="c-code">
#define DUK_ERR_NONE                 0    /* no error (e.g. from duk_get_error_code()) */
#define DUK_ERR_ERROR                1    /* Error */
#define DUK_ERR_EVAL_ERROR           2    /* EvalError */
#define DUK_ERR_RANGE_ERROR          3    /* RangeError */
#define DUK_ERR_REFERENCE_ERROR      4    /* ReferenceError */
#define DUK_ERR_SYNTAX_ERROR         5    /* SyntaxError */
#define DUK_ERR_TYPE_ERROR           6    /* TypeError */
#define DUK_ERR_URI_ERROR            7    /* URIError */
</pre>

<h2>Return codes from Duktape/C functions</h2>
<pre class="c-code">
/* Return codes for C functions */
#define DUK_RET_ERROR                (-DUK_ERR_ERROR)
#define DUK_RET_EVAL_ERROR           (-DUK_ERR_EVAL_ERROR)
#define DUK_RET_RANGE_ERROR          (-DUK_ERR_RANGE_ERROR)
#define DUK_RET_REFERENCE_ERROR      (-DUK_ERR_REFERENCE_ERROR)
#define DUK_RET_SYNTAX_ERROR         (-DUK_ERR_SYNTAX_ERROR)
#define DUK_RET_TYPE_ERROR           (-DUK_ERR_TYPE_ERROR)
#define DUK_RET_URI_ERROR            (-DUK_ERR_URI_ERROR)

/* Return codes for protected calls (duk_safe_call(), duk_pcall()). */
#define DUK_EXEC_SUCCESS             0
#define DUK_EXEC_ERROR               1
</pre>

<h2>Compilation flags for duk_compile()</h2>
<pre class="c-code">
/* Compilation flags for duk_compile() and duk_eval() */
#define DUK_COMPILE_EVAL                  (1 &lt;&lt; 0)    /* compile eval code (instead of program) */
#define DUK_COMPILE_FUNCTION              (1 &lt;&lt; 1)    /* compile function code (instead of program) */
#define DUK_COMPILE_STRICT                (1 &lt;&lt; 2)    /* use strict (outer) context for program, eval, or function */
</pre>

<h2>Flags for duk_def_prop()</h2>
<pre class="c-code">
/* Flags for duk_def_prop() and its variants */
#define DUK_DEFPROP_WRITABLE              (1 &lt;&lt; 0)    /* set writable (effective if DUK_DEFPROP_HAVE_WRITABLE set) */
#define DUK_DEFPROP_ENUMERABLE            (1 &lt;&lt; 1)    /* set enumerable (effective if DUK_DEFPROP_HAVE_ENUMERABLE set) */
#define DUK_DEFPROP_CONFIGURABLE          (1 &lt;&lt; 2)    /* set configurable (effective if DUK_DEFPROP_HAVE_CONFIGURABLE set) */
#define DUK_DEFPROP_HAVE_WRITABLE         (1 &lt;&lt; 3)    /* set/clear writable */
#define DUK_DEFPROP_HAVE_ENUMERABLE       (1 &lt;&lt; 4)    /* set/clear enumerable */
#define DUK_DEFPROP_HAVE_CONFIGURABLE     (1 &lt;&lt; 5)    /* set/clear configurable */
#define DUK_DEFPROP_HAVE_VALUE            (1 &lt;&lt; 6)    /* set value (given on value stack) */
#define DUK_DEFPROP_HAVE_GETTER           (1 &lt;&lt; 7)    /* set getter (given on value stack) */
#define DUK_DEFPROP_HAVE_SETTER           (1 &lt;&lt; 8)    /* set setter (given on value stack) */
#define DUK_DEFPROP_FORCE                 (1 &lt;&lt; 9)    /* force change if possible, may still fail for e.g. virtual properties */
#define DUK_DEFPROP_SET_WRITABLE          (DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE)
#define DUK_DEFPROP_CLEAR_WRITABLE        DUK_DEFPROP_HAVE_WRITABLE
#define DUK_DEFPROP_SET_ENUMERABLE        (DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_ENUMERABLE)
#define DUK_DEFPROP_CLEAR_ENUMERABLE      DUK_DEFPROP_HAVE_ENUMERABLE
#define DUK_DEFPROP_SET_CONFIGURABLE      (DUK_DEFPROP_HAVE_CONFIGURABLE | DUK_DEFPROP_CONFIGURABLE)
#define DUK_DEFPROP_CLEAR_CONFIGURABLE    DUK_DEFPROP_HAVE_CONFIGURABLE
</pre>

<h2>Enumeration flags for duk_enum()</h2>
<pre class="c-code">
/* Enumeration flags for duk_enum() */
#define DUK_ENUM_INCLUDE_NONENUMERABLE    (1 &lt;&lt; 0)    /* enumerate non-numerable properties in addition to enumerable */
#define DUK_ENUM_INCLUDE_INTERNAL         (1 &lt;&lt; 1)    /* enumerate internal properties */
#define DUK_ENUM_OWN_PROPERTIES_ONLY      (1 &lt;&lt; 2)    /* don't walk prototype chain, only check own properties */
#define DUK_ENUM_ARRAY_INDICES_ONLY       (1 &lt;&lt; 3)    /* only enumerate array indices */
#define DUK_ENUM_SORT_ARRAY_INDICES       (1 &lt;&lt; 4)    /* sort array indices (applied to full enumeration result, including inherited array indices) */
#define DUK_ENUM_NO_PROXY_BEHAVIOR        (1 &lt;&lt; 5)    /* enumerate a proxy object itself without invoking proxy behavior */
</pre>

<h2>Garbage collection flags for duk_gc()</h2>
<pre class="c-code">
/* Flags for duk_gc() */
#define DUK_GC_COMPACT                    (1 &lt;&lt; 0)    /* compact heap objects */
</pre>

<h2>Coercion hints</h2>
<pre class="c-code">
/* Coercion hints */
#define DUK_HINT_NONE         0    /* prefer number, unless coercion input is a Date, in which case prefer string (E5 Section 8.12.8) */
#define DUK_HINT_STRING       1    /* prefer string */
#define DUK_HINT_NUMBER       2    /* prefer number */
</pre>

<h2>Flags for duk_push_thread_raw()</h2>
<pre class="c-code">
/* Flags for duk_push_thread_raw() */
#define DUK_THREAD_NEW_GLOBAL_ENV         (1 &lt;&lt; 0)    /* create a new global environment */
</pre>

<h2>Misc defines</h2>
<pre class="c-code">
#define DUK_INVALID_INDEX     DUK_IDX_MIN

#define DUK_VARARGS           ((duk_int_t) (-1))

#define DUK_API_ENTRY_STACK   64
</pre>