From 77b41f7f326b644cf79cb5137409759a584ce047 Mon Sep 17 00:00:00 2001 From: Sami Vaarala Date: Mon, 16 Sep 2013 04:08:09 +0300 Subject: [PATCH] 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 | 51 ++++++++++++++++++++++++++++ website/api/defines.html | 9 ++++- website/api/duk_compile.txt | 1 + website/api/duk_compile_file.txt | 16 +++++++++ website/api/duk_eval.txt | 1 + website/api/duk_eval_file.txt | 20 +++++++++++ website/api/duk_push_string_file.txt | 20 +++++++++++ website/api/notation.html | 6 ++++ 8 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 website/api/duk_compile_file.txt create mode 100644 website/api/duk_eval_file.txt create mode 100644 website/api/duk_push_string_file.txt diff --git a/website/api/concepts.html b/website/api/concepts.html index f3aa4c82..0ff7dddd 100644 --- a/website/api/concepts.html +++ b/website/api/concepts.html @@ -114,3 +114,54 @@ is really just a shorthand for obj["123"].

accesses whenever possible, so it is preferable to use numeric array indices in both Ecmascript code and C code using the Duktape API.

+

Duktape/C function

+ +

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:

+
+int my_func(duk_context *ctx) {
+    duk_push_int(ctx, 123);
+    return 1;
+}
+
+ +

The function gets Ecmascript call argument in the value stack of +ctx, with duk_get_top(ctx) 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 undefined. A function can also be registered +as a vararg function (by giving DUK_VARARGS as the argument count) +in which case call arguments are not modified prior to C function entry.

+ +

The function can return one of the following:

+ + +

A return value higher than 1 is currently undefined, as Ecmascript +doesn't support multiple return values in Edition 5.1.

+ +

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:

+ +
+int my_func(duk_context *ctx) {
+    if (duk_get_top(ctx) == 0) {
+        /* throw TypeError if no arguments given */
+        return DUK_RET_TYPE_ERROR;
+    }
+    /* ... */
+}
+
+ diff --git a/website/api/defines.html b/website/api/defines.html index 0ee2e77f..b15bf7a8 100644 --- a/website/api/defines.html +++ b/website/api/defines.html @@ -64,7 +64,14 @@ struct duk_memory_functions { #define DUK_RET_URI_ERROR (-DUK_ERR_URI_ERROR) -

Enumeration flags

+

Compilation flags for duk_compile()

+
+#define  DUK_COMPILE_EVAL                  (1 << 0)    /* compile eval code (instead of program) */
+#define  DUK_COMPILE_FUNCTION              (1 << 1)    /* compile function code (instead of program) */
+#define  DUK_COMPILE_STRICT                (1 << 2)    /* use strict (outer) context for program, eval, or function */
+
+ +

Enumeration flags for duk_enum()

 /* Enumeration flags for duk_enum() */
 #define  DUK_ENUM_INCLUDE_NONENUMERABLE    (1 << 0)    /* enumerate non-numerable properties in addition to enumerable */
diff --git a/website/api/duk_compile.txt b/website/api/duk_compile.txt
index e2ebe331..73117f2c 100644
--- a/website/api/duk_compile.txt
+++ b/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?
diff --git a/website/api/duk_compile_file.txt b/website/api/duk_compile_file.txt
new file mode 100644
index 00000000..558e9cce
--- /dev/null
+++ b/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
+
Like
+duk_compile(), but the compile input
+is given as a filename.

+
+=example
+duk_compile_file(ctx, 0, "test.js");
+
+=tags
+compile
diff --git a/website/api/duk_eval.txt b/website/api/duk_eval.txt
index 97352209..bf619cc7 100644
--- a/website/api/duk_eval.txt
+++ b/website/api/duk_eval.txt
@@ -37,6 +37,7 @@ compile
 
 =seealso
 duk_eval_string
+duk_eval_file
 
 =fixme
 Remove?
diff --git a/website/api/duk_eval_file.txt b/website/api/duk_eval_file.txt
new file mode 100644
index 00000000..c43bb8b9
--- /dev/null
+++ b/website/api/duk_eval_file.txt
@@ -0,0 +1,20 @@
+=proto
+void duk_eval_file(duk_context *ctx, const char *path);
+
+=stack
+[ ... ] -> [ ... result! ]
+
+=summary
+
Like
+duk_eval(), but the eval input
+is given as a filename.

+
+=example
+duk_eval_string(ctx, "test.js");
+printf("result is: '%s'\n", duk_get_string(ctx, -1));
+duk_pop(ctx);
+
+=tags
+compile
+
+=macro
diff --git a/website/api/duk_push_string_file.txt b/website/api/duk_push_string_file.txt
new file mode 100644
index 00000000..1b703f08
--- /dev/null
+++ b/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
+
Push the contents of a file path 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.

+
+
If path is NULL, throws an error.

+
+=example
+duk_push_string_file(ctx, "test.js");
+
+=tags
+stack
+string
diff --git a/website/api/notation.html b/website/api/notation.html
index e1dd4181..66e6db7b 100644
--- a/website/api/notation.html
+++ b/website/api/notation.html
@@ -46,6 +46,12 @@ shown with a white background:

 [ ... obj! ... key! value! ]
+

In some cases the index of an element may be emphasized with a number +or symbolic value in parenthesis:

+
+[ ... val(index)! val(index+1)! ... ]
+
+

Stack transformation is represented with an arrow and two stacks: