api docs for duk_push_string_file(), duk_compile_file(), and duk_eval_file(); other additions to concepts and defines docs

website/api/concepts.html

@@ -114,3 +114,54 @@ is really just a shorthand for <tt>obj["123"]</tt>.</p>
 accesses whenever possible, so it is preferable to use numeric array
 indices in both Ecmascript code and C code using the Duktape API.</p>
 
+<h3>Duktape/C function</h3>
+
+<p>A C function with a Duktape/C API signature can be associated with an
+Ecmascript function object, and gets called when the Ecmascript function
+object is called.  A Duktape/C API function looks as follows:</p>
+<pre class="c-code">
+int my_func(duk_context *ctx) {
+    duk_push_int(ctx, 123);
+    return 1;
+}
+</pre>
+
+<p>The function gets Ecmascript call argument in the value stack of
+<tt>ctx</tt>, with <tt>duk_get_top(ctx)</tt> indicating the number of
+arguments present on the value stack.  When creating an Ecmascript function
+object associated with a Duktape/C function, one can select the desired
+number of arguments.  Extra arguments are dropped and missing arguments
+are replaced with <tt>undefined</tt>.  A function can also be registered
+as a vararg function (by giving <tt>DUK_VARARGS</tt> as the argument count)
+in which case call arguments are not modified prior to C function entry.</p>
+
+<p>The function can return one of the following:</p>
+<ul>
+<li>Return value 1 indicates that the value on the stack top is to be
+    interpreted as a return value.</li>
+<li>Return value 0 indicates that there is no explicit return value on
+    the value stack; an <tt>undefined</tt> is returned to caller.</li>
+<li>A negative return value indicates that an error is to be automatically
+    thrown.  Error codes named <tt>DUK_RET_xxx</tt> map to specific kinds
+    of errors (do not confuse these with <tt>DUK_ERR_xxx</tt> which are
+    positive values).</li>
+</ul>
+
+<p>A return value higher than 1 is currently undefined, as Ecmascript
+doesn't support multiple return values in Edition 5.1.</p>
+
+<p>A negative error return value is intended to simplify common error
+handling, and is an alternative to constructing and throwing an error
+explicitly with Duktape API calls.  No error message can be given; a
+message is automatically constructed by Duktape.  For example:</p>
+
+<pre class="c-code">
+int my_func(duk_context *ctx) {
+    if (duk_get_top(ctx) == 0) {
+        /* throw TypeError if no arguments given */
+        return DUK_RET_TYPE_ERROR;
+    }
+    /* ... */
+}
+</pre>
+

website/api/defines.html

@@ -64,7 +64,14 @@ struct duk_memory_functions {
 #define  DUK_RET_URI_ERROR            (-DUK_ERR_URI_ERROR)
 </pre>
 
-<h3>Enumeration flags</h3>
+<h3>Compilation flags for duk_compile()</h3>
+<pre class="c-code">
+#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>
+
+<h3>Enumeration flags for duk_enum()</h3>
 <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 */

website/api/duk_compile.txt

@@ -137,6 +137,7 @@ compile
 
 =seealso
 duk_compile_string
+duk_compile_file
 
 =fixme
 Remove DUK_COMPILE_FUNCTION, one can simply just eval a function expression?

website/api/duk_compile_file.txt

@@ -0,0 +1,16 @@
+=proto
+void duk_compile_file(duk_context *ctx, int flags, const char *path);
+
+=stack
+[ ... ] -> [ ... function! ]
+
+=summary
+<p>Like
+<tt><a href="#duk_compile">duk_compile()</a></tt>, but the compile input
+is given as a filename.</p>
+
+=example
+duk_compile_file(ctx, 0, "test.js");
+
+=tags
+compile

website/api/duk_eval.txt

@@ -37,6 +37,7 @@ compile
 
 =seealso
 duk_eval_string
+duk_eval_file
 
 =fixme
 Remove?

website/api/duk_eval_file.txt

@@ -0,0 +1,20 @@
+=proto
+void duk_eval_file(duk_context *ctx, const char *path);
+
+=stack
+[ ... ] -> [ ... result! ]
+
+=summary
+<p>Like
+<tt><a href="#duk_eval">duk_eval()</a></tt>, but the eval input
+is given as a filename.</p>
+
+=example
+duk_eval_string(ctx, "test.js");
+printf("result is: '%s'\n", duk_get_string(ctx, -1));
+duk_pop(ctx);
+
+=tags
+compile
+
+=macro

website/api/duk_push_string_file.txt

@@ -0,0 +1,20 @@
+=proto
+const char *duk_push_string_file(duk_context *ctx, const char *path);
+
+=stack
+[ ... ] -> [ ... data! ]
+
+=summary
+<p>Push the contents of a file <tt>path</tt> into the stack as string data.
+The file should be CESU-8 formatted if Ecmascript string compatibility is
+necessary.  A pointer to the interned string data is returned.  If the
+operation fails, throws an error.</p>
+
+<p>If <tt>path</tt> is NULL, throws an error.</p>
+
+=example
+duk_push_string_file(ctx, "test.js");
+
+=tags
+stack
+string

website/api/notation.html

@@ -46,6 +46,12 @@ shown with a white background:</p>
 [ ... obj! ... key! value! ]
 </pre>
 
+<p>In some cases the index of an element may be emphasized with a number
+or symbolic value in parenthesis:</p>
+<pre class="stack">
+[ ... val(index)! val(index+1)! ... ]
+</pre>
+
 <p>Stack transformation is represented with an arrow and two stacks:</p>
 
 <pre class="stack">