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; 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) (duk_context *ctx, duk_errcode_t code, 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);
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) (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">
/* Internal error codes */
#define DUK_ERR_NONE                 0    /* no error (e.g. from duk_get_error_code()) */
#define DUK_ERR_UNIMPLEMENTED_ERROR  50   /* UnimplementedError */
#define DUK_ERR_UNSUPPORTED_ERROR    51   /* UnsupportedError */
#define DUK_ERR_INTERNAL_ERROR       52   /* InternalError */
#define DUK_ERR_ALLOC_ERROR          53   /* AllocError */
#define DUK_ERR_ASSERTION_ERROR      54   /* AssertionError */
#define DUK_ERR_API_ERROR            55   /* APIError */
#define DUK_ERR_UNCAUGHT_ERROR       56   /* UncaughtError */

/* Ecmascript E5 specification error codes */
#define DUK_ERR_ERROR                100  /* Error */
#define DUK_ERR_EVAL_ERROR           101  /* EvalError */
#define DUK_ERR_RANGE_ERROR          102  /* RangeError */
#define DUK_ERR_REFERENCE_ERROR      103  /* ReferenceError */
#define DUK_ERR_SYNTAX_ERROR         104  /* SyntaxError */
#define DUK_ERR_TYPE_ERROR           105  /* TypeError */
#define DUK_ERR_URI_ERROR            106  /* URIError */
</pre>

<h2>Return codes from Duktape/C functions</h2>
<pre class="c-code">
/* Return codes for C functions */
#define DUK_RET_UNIMPLEMENTED_ERROR  (-DUK_ERR_UNIMPLEMENTED_ERROR)
#define DUK_RET_UNSUPPORTED_ERROR    (-DUK_ERR_UNSUPPORTED_ERROR)
#define DUK_RET_INTERNAL_ERROR       (-DUK_ERR_INTERNAL_ERROR)
#define DUK_RET_ALLOC_ERROR          (-DUK_ERR_ALLOC_ERROR)
#define DUK_RET_ASSERTION_ERROR      (-DUK_ERR_ASSERTION_ERROR)
#define DUK_RET_API_ERROR            (-DUK_ERR_API_ERROR)
#define DUK_RET_UNCAUGHT_ERROR       (-DUK_ERR_UNCAUGHT_ERROR)
#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 */
</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 (regardless of enumerability) */
#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, use with DUK_ENUM_ARRAY_INDICES_ONLY */
#define DUK_ENUM_NO_PROXY_BEHAVIOR        (1 &lt;&lt; 5)    /* enumerate a proxy object itself without invoking proxy behavior */
</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>Log levels</h2>
<pre class="c-code">
/* Log levels */
#define  DUK_LOG_TRACE                    0
#define  DUK_LOG_DEBUG                    1
#define  DUK_LOG_INFO                     2
#define  DUK_LOG_WARN                     3
#define  DUK_LOG_ERROR                    4
#define  DUK_LOG_FATAL                    5
</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>