diff --git a/website/api/duk_alloc.txt b/website/api/duk_alloc.txt deleted file mode 100644 index 9e391386..00000000 --- a/website/api/duk_alloc.txt +++ /dev/null @@ -1,35 +0,0 @@ -=proto -void *duk_alloc(duk_context *ctx, duk_size_t size); - -=summary -

Like duk_alloc_raw() but may trigger -a garbage collection to satisfy the request. However, the allocated memory -itself is not automatically garbage collected. The allocation request may -fail even after garbage collection, in which case a NULL is returned. -The allocated memory is not automatically zeroed, and may contain arbitrary garbage.

- -

Memory allocated with duk_alloc() can be freed with either -duk_free() or -duk_free_raw().

- -=example -/* Although duk_alloc() triggers a GC if necessary, it can still fail to - * allocate the desired amount of memory. Caller must check for NULL - * (however, if allocation size is 0, a NULL may be returned even in - * a success case). - */ -void *buf = duk_alloc(ctx, 1024); -if (buf) { - printf("allocation successful: %p\n", buf); -} else { - printf("allocation failed\n"); -} - -=tags -memory - -=seealso -duk_alloc_raw - -=introduced -1.0.0 diff --git a/website/api/duk_alloc.yaml b/website/api/duk_alloc.yaml new file mode 100644 index 00000000..ba6b0710 --- /dev/null +++ b/website/api/duk_alloc.yaml @@ -0,0 +1,36 @@ +name: duk_alloc + +proto: | + void *duk_alloc(duk_context *ctx, duk_size_t size); + +summary: | +

Like duk_alloc_raw() but may trigger + a garbage collection to satisfy the request. However, the allocated memory + itself is not automatically garbage collected. The allocation request may + fail even after garbage collection, in which case a NULL is returned. + The allocated memory is not automatically zeroed, and may contain arbitrary garbage.

+ +

Memory allocated with duk_alloc() can be freed with either + duk_free() or + duk_free_raw().

+ +example: | + /* Although duk_alloc() triggers a GC if necessary, it can still fail to + * allocate the desired amount of memory. Caller must check for NULL + * (however, if allocation size is 0, a NULL may be returned even in + * a success case). + */ + void *buf = duk_alloc(ctx, 1024); + if (buf) { + printf("allocation successful: %p\n", buf); + } else { + printf("allocation failed\n"); + } + +tags: + - memory + +seealso: + - duk_alloc_raw + +introduced: 1.0.0 diff --git a/website/api/duk_alloc_raw.txt b/website/api/duk_alloc_raw.txt deleted file mode 100644 index cad81f76..00000000 --- a/website/api/duk_alloc_raw.txt +++ /dev/null @@ -1,32 +0,0 @@ -=proto -void *duk_alloc_raw(duk_context *ctx, duk_size_t size); - -=summary -

Allocate size bytes using the raw allocation function registered -to the context. If allocation fails, returns NULL. If size -is zero, the call may either return a NULL or some non-NULL -value which may be safely given to e.g. duk_free_raw(). The allocation -cannot trigger a garbage collection, and the allocated memory is not automatically -garbage collected. The allocated memory is not automatically zeroed, and may contain -arbitrary garbage.

- -

Memory allocated with duk_alloc_raw() can be freed with either -duk_free() or -duk_free_raw().

- -=example -void *buf = duk_alloc_raw(ctx, 1024); -if (buf) { - printf("allocation successful: %p\n", buf); -} else { - printf("allocation failed\n"); -} - -=tags -memory - -=seealso -duk_alloc - -=introduced -1.0.0 diff --git a/website/api/duk_alloc_raw.yaml b/website/api/duk_alloc_raw.yaml new file mode 100644 index 00000000..d56b7ec2 --- /dev/null +++ b/website/api/duk_alloc_raw.yaml @@ -0,0 +1,33 @@ +name: duk_alloc_raw + +proto: | + void *duk_alloc_raw(duk_context *ctx, duk_size_t size); + +summary: | +

Allocate size bytes using the raw allocation function registered + to the context. If allocation fails, returns NULL. If size + is zero, the call may either return a NULL or some non-NULL + value which may be safely given to e.g. duk_free_raw(). The allocation + cannot trigger a garbage collection, and the allocated memory is not automatically + garbage collected. The allocated memory is not automatically zeroed, and may contain + arbitrary garbage.

+ +

Memory allocated with duk_alloc_raw() can be freed with either + duk_free() or + duk_free_raw().

+ +example: | + void *buf = duk_alloc_raw(ctx, 1024); + if (buf) { + printf("allocation successful: %p\n", buf); + } else { + printf("allocation failed\n"); + } + +tags: + - memory + +seealso: + - duk_alloc + +introduced: 1.0.0 diff --git a/website/api/duk_base64_decode.txt b/website/api/duk_base64_decode.txt deleted file mode 100644 index c1f29780..00000000 --- a/website/api/duk_base64_decode.txt +++ /dev/null @@ -1,28 +0,0 @@ -=proto -void duk_base64_decode(duk_context *ctx, duk_idx_t index); - -=stack -[ ... base64_val! ... ] -> [ ... val! ... ] - -=summary -

Decodes a base-64 encoded value into a buffer as an in-place operation. -If the input is invalid, throws an error.

- -=example -duk_push_string(ctx, "Zm9v"); -duk_base64_decode(ctx, -1); /* buffer */ -printf("base-64 decoded: %s\n", duk_to_string(ctx, -1)); -duk_pop(ctx); - -/* Output: - * base-64 decoded: foo - */ - -=tags -codec - -=seealso -duk_base64_encode - -=introduced -1.0.0 diff --git a/website/api/duk_base64_decode.yaml b/website/api/duk_base64_decode.yaml new file mode 100644 index 00000000..15041c75 --- /dev/null +++ b/website/api/duk_base64_decode.yaml @@ -0,0 +1,29 @@ +name: duk_base64_decode + +proto: | + void duk_base64_decode(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... base64_val! ... ] -> [ ... val! ... ] + +summary: | +

Decodes a base-64 encoded value into a buffer as an in-place operation. + If the input is invalid, throws an error.

+ +example: | + duk_push_string(ctx, "Zm9v"); + duk_base64_decode(ctx, -1); /* buffer */ + printf("base-64 decoded: %s\n", duk_to_string(ctx, -1)); + duk_pop(ctx); + + /* Output: + * base-64 decoded: foo + */ + +tags: + - codec + +seealso: + - duk_base64_encode + +introduced: 1.0.0 diff --git a/website/api/duk_base64_encode.txt b/website/api/duk_base64_encode.txt deleted file mode 100644 index 837562ec..00000000 --- a/website/api/duk_base64_encode.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -const char *duk_base64_encode(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... base64_val! ... ] - -=summary -

Coerces an arbitrary value into a buffer and then encodes the result -into base-64 as an in-place operation. Returns a pointer to the resulting -string for convenience.

- -
-Coercing to a buffer first coerces a non-buffer value into a string, and -then coerces the string into a buffer. The resulting buffer contains the -string in CESU-8 encoding. -
- -=example -duk_push_string(ctx, "foo"); -printf("base-64 encoded: %s\n", duk_base64_encode(ctx, -1)); - -/* Output: - * base-64 encoded: Zm9v - */ - -=tags -codec - -=seealso -duk_base64_decode - -=introduced -1.0.0 diff --git a/website/api/duk_base64_encode.yaml b/website/api/duk_base64_encode.yaml new file mode 100644 index 00000000..b6a4fcce --- /dev/null +++ b/website/api/duk_base64_encode.yaml @@ -0,0 +1,34 @@ +name: duk_base64_encode + +proto: | + const char *duk_base64_encode(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... base64_val! ... ] + +summary: | +

Coerces an arbitrary value into a buffer and then encodes the result + into base-64 as an in-place operation. Returns a pointer to the resulting + string for convenience.

+ +
+ Coercing to a buffer first coerces a non-buffer value into a string, and + then coerces the string into a buffer. The resulting buffer contains the + string in CESU-8 encoding. +
+ +example: | + duk_push_string(ctx, "foo"); + printf("base-64 encoded: %s\n", duk_base64_encode(ctx, -1)); + + /* Output: + * base-64 encoded: Zm9v + */ + +tags: + - codec + +seealso: + - duk_base64_decode + +introduced: 1.0.0 diff --git a/website/api/duk_call.txt b/website/api/duk_call.txt deleted file mode 100644 index aab93d4c..00000000 --- a/website/api/duk_call.txt +++ /dev/null @@ -1,53 +0,0 @@ -=proto -void duk_call(duk_context *ctx, duk_idx_t nargs); - -=stack -[ ... func! arg1! ...! argN! ] -> [ ... retval! ] - -=summary -

Call target function func with nargs arguments -(not counting the function itself). The function and its arguments -are replaced by a single return value. An error thrown during the -function call is not automatically caught. -

- -

The target function this binding is initially set to -undefined. If the target function is not strict, the binding -is replaced by the global object before the function is invoked; see -Entering Function Code. -If you want to control the this binding, you can use -duk_call_method() or -duk_call_prop() instead.

- -

This API call is equivalent to:

-
-var retval = func(arg1, ..., argN);
-
- -

or:

-
-var retval = func.call(undefined, arg1, ..., argN);
-
- -=example -/* Assume target function is already on stack at func_idx; the target - * function adds arguments and returns the result. - */ -duk_idx_t func_idx = /* ... */; - -duk_dup(ctx, func_idx); -duk_push_int(ctx, 2); -duk_push_int(ctx, 3); -duk_call(ctx, 2); /* [ ... func 2 3 ] -> [ 5 ] */ -printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); -duk_pop(ctx); - -=tags -call - -=seealso -duk_call_method -duk_call_prop - -=introduced -1.0.0 diff --git a/website/api/duk_call.yaml b/website/api/duk_call.yaml new file mode 100644 index 00000000..99ab0ab9 --- /dev/null +++ b/website/api/duk_call.yaml @@ -0,0 +1,54 @@ +name: duk_call + +proto: | + void duk_call(duk_context *ctx, duk_idx_t nargs); + +stack: | + [ ... func! arg1! ...! argN! ] -> [ ... retval! ] + +summary: | +

Call target function func with nargs arguments + (not counting the function itself). The function and its arguments + are replaced by a single return value. An error thrown during the + function call is not automatically caught. +

+ +

The target function this binding is initially set to + undefined. If the target function is not strict, the binding + is replaced by the global object before the function is invoked; see + Entering Function Code. + If you want to control the this binding, you can use + duk_call_method() or + duk_call_prop() instead.

+ +

This API call is equivalent to:

+ 
+  var retval = func(arg1, ..., argN);
+
+ +

or:

+ 
+  var retval = func.call(undefined, arg1, ..., argN);
+
+ +example: | + /* Assume target function is already on stack at func_idx; the target + * function adds arguments and returns the result. + */ + duk_idx_t func_idx = /* ... */; + + duk_dup(ctx, func_idx); + duk_push_int(ctx, 2); + duk_push_int(ctx, 3); + duk_call(ctx, 2); /* [ ... func 2 3 ] -> [ 5 ] */ + printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); + duk_pop(ctx); + +tags: + - call + +seealso: + - duk_call_method + - duk_call_prop + +introduced: 1.0.0 diff --git a/website/api/duk_call_method.txt b/website/api/duk_call_method.txt deleted file mode 100644 index 84cb0c24..00000000 --- a/website/api/duk_call_method.txt +++ /dev/null @@ -1,48 +0,0 @@ -=proto -void duk_call_method(duk_context *ctx, duk_idx_t nargs); - -=stack -[ ... func! this! arg! ...! argN! ] -> [ ... retval! ] - -=summary -

Call target function func with an explicit this -binding and nargs arguments (not counting the function and -the this binding value). The function object, the this -binding value, and the function arguments are replaced by a single -return value. An error thrown during the function call is not -automatically caught.

- -

If the target function is not strict, the binding value seen by the -target function may be modified by processing specified in -Entering Function Code. -

- -

This API call is equivalent to:

-
-var retval = func.call(this_binding, arg1, ..., argN);
-
- -=example -/* The target function here prints: - * - * this: 123 - * 2 3 - * - * and returns 5. - */ - -duk_push_string(ctx, "function(x,y) { print('this:', this); " - "print(x,y); return x+y; }"); -duk_eval(ctx); /* -> [ ... func ] */ -duk_push_int(ctx, 123); -duk_push_int(ctx, 2); -duk_push_int(ctx, 3); -duk_call_method(ctx, 2); /* [ ... func 123 2 3 ] -> [ 5 ] */ -printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); /* prints 5 */ -duk_pop(ctx); - -=tags -call - -=introduced -1.0.0 diff --git a/website/api/duk_call_method.yaml b/website/api/duk_call_method.yaml new file mode 100644 index 00000000..43cd251c --- /dev/null +++ b/website/api/duk_call_method.yaml @@ -0,0 +1,49 @@ +name: duk_call_method + +proto: | + void duk_call_method(duk_context *ctx, duk_idx_t nargs); + +stack: | + [ ... func! this! arg! ...! argN! ] -> [ ... retval! ] + +summary: | +

Call target function func with an explicit this + binding and nargs arguments (not counting the function and + the this binding value). The function object, the this + binding value, and the function arguments are replaced by a single + return value. An error thrown during the function call is not + automatically caught.

+ +

If the target function is not strict, the binding value seen by the + target function may be modified by processing specified in + Entering Function Code. +

+ +

This API call is equivalent to:

+ 
+  var retval = func.call(this_binding, arg1, ..., argN);
+
+ +example: | + /* The target function here prints: + * + * this: 123 + * 2 3 + * + * and returns 5. + */ + + duk_push_string(ctx, "function(x,y) { print('this:', this); " + "print(x,y); return x+y; }"); + duk_eval(ctx); /* -> [ ... func ] */ + duk_push_int(ctx, 123); + duk_push_int(ctx, 2); + duk_push_int(ctx, 3); + duk_call_method(ctx, 2); /* [ ... func 123 2 3 ] -> [ 5 ] */ + printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); /* prints 5 */ + duk_pop(ctx); + +tags: + - call + +introduced: 1.0.0 diff --git a/website/api/duk_call_prop.txt b/website/api/duk_call_prop.txt deleted file mode 100644 index 61aebddc..00000000 --- a/website/api/duk_call_prop.txt +++ /dev/null @@ -1,47 +0,0 @@ -=proto -void duk_call_prop(duk_context *ctx, duk_idx_t obj_index, duk_idx_t nargs); - -=stack -[ ... obj! ... key! arg1! ...! argN! ] -> [ ... obj! ... retval! ] - -=summary -

Call obj.key with nargs arguments, with this -binding set to obj. The property name and the function arguments -are replaced by a single return value; the target object is not touched. -An error during the function call is not automatically caught.

- -

If the target function is not strict, the binding value seen by the -target function may be modified by processing specified in -Entering Function Code. -

- -

This API call is equivalent to:

-
-var retval = obj[key](arg1, ..., argN);
-
- -

or:

-
-var func = obj[key];
-var retval = func.call(obj, arg1, ..., argN);
-
- -
- -=example -/* obj.myAdderMethod(2,3) -> 5 */ -duk_idx_t obj_idx = /* ... */; - -duk_push_string(ctx, "myAdderMethod"); -duk_push_int(ctx, 2); -duk_push_int(ctx, 3); -duk_call_prop(ctx, obj_idx, 2); /* [ ... "myAdderMethod" 2 3 ] -> [ ... 5 ] */ -printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); -duk_pop(ctx); - -=tags -property -call - -=introduced -1.0.0 diff --git a/website/api/duk_call_prop.yaml b/website/api/duk_call_prop.yaml new file mode 100644 index 00000000..af37f56b --- /dev/null +++ b/website/api/duk_call_prop.yaml @@ -0,0 +1,48 @@ +name: duk_call_prop + +proto: | + void duk_call_prop(duk_context *ctx, duk_idx_t obj_index, duk_idx_t nargs); + +stack: | + [ ... obj! ... key! arg1! ...! argN! ] -> [ ... obj! ... retval! ] + +summary: | +

Call obj.key with nargs arguments, with this + binding set to obj. The property name and the function arguments + are replaced by a single return value; the target object is not touched. + An error during the function call is not automatically caught.

+ +

If the target function is not strict, the binding value seen by the + target function may be modified by processing specified in + Entering Function Code. +

+ +

This API call is equivalent to:

+ 
+  var retval = obj[key](arg1, ..., argN);
+
+ +

or:

+ 
+  var func = obj[key];
+  var retval = func.call(obj, arg1, ..., argN);
+
+ +
+ +example: | + /* obj.myAdderMethod(2,3) -> 5 */ + duk_idx_t obj_idx = /* ... */; + + duk_push_string(ctx, "myAdderMethod"); + duk_push_int(ctx, 2); + duk_push_int(ctx, 3); + duk_call_prop(ctx, obj_idx, 2); /* [ ... "myAdderMethod" 2 3 ] -> [ ... 5 ] */ + printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); + duk_pop(ctx); + +tags: + - property + - call + +introduced: 1.0.0 diff --git a/website/api/duk_char_code_at.txt b/website/api/duk_char_code_at.txt deleted file mode 100644 index 4f833f10..00000000 --- a/website/api/duk_char_code_at.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -duk_codepoint_t duk_char_code_at(duk_context *ctx, duk_idx_t index, duk_size_t char_offset); - -=stack -[ ... str! ... ] - -=summary -

Get the codepoint of a character at character offset char_offset -of a string at index. If the value at index is not -a string, an error is thrown. If char_offset is invalid (outside -the string) a zero is returned.

- -=example -printf("char code at char index 12: %ld\n", (long) duk_char_code_at(ctx, -3, 12)); - -=tags -string - -=introduced -1.0.0 diff --git a/website/api/duk_char_code_at.yaml b/website/api/duk_char_code_at.yaml new file mode 100644 index 00000000..826f3ffc --- /dev/null +++ b/website/api/duk_char_code_at.yaml @@ -0,0 +1,21 @@ +name: duk_char_code_at + +proto: | + duk_codepoint_t duk_char_code_at(duk_context *ctx, duk_idx_t index, duk_size_t char_offset); + +stack: | + [ ... str! ... ] + +summary: | +

Get the codepoint of a character at character offset char_offset + of a string at index. If the value at index is not + a string, an error is thrown. If char_offset is invalid (outside + the string) a zero is returned.

+ +example: | + printf("char code at char index 12: %ld\n", (long) duk_char_code_at(ctx, -3, 12)); + +tags: + - string + +introduced: 1.0.0 diff --git a/website/api/duk_check_stack.txt b/website/api/duk_check_stack.txt deleted file mode 100644 index 8d3f2f94..00000000 --- a/website/api/duk_check_stack.txt +++ /dev/null @@ -1,59 +0,0 @@ -=proto -duk_bool_t duk_check_stack(duk_context *ctx, duk_idx_t extra); - -=summary -

Ensure that the value stack has at least extra reserved -(allocated) elements for caller's use, relative to the current stack top. -Returns 1 if successful, 0 otherwise. If the call is successful, the caller -is guaranteed that extra elements can be pushed to the value -stack without a value stack related error (other errors like out-of-memory -can still occur). The caller MUST NOT rely on being able to push more than -extra values; although this is possible, such elements are -reserved for Duktape's internal use.

- -

Upon entry to a Duktape/C function and when outside any call -there is an automatic reserve (of DUK_API_ENTRY_STACK elements) -allocated for the caller in addition to call arguments on the value stack. -If more value stack space is needed, the caller must reserve more space -explicitly either in the beginning of the function (e.g. if the number of -elements required is known or can be computed based on arguments) or -dynamically (e.g. inside a loop). Note that an attempt to push a value -beyond the currently allocated value stack causes an error: it does not cause -the value stack to be automatically extended. This simplifies the internal -implementation.

- -

In addition to user reserved elements, Duktape keeps an automatic -internal value stack reserve to ensure all API calls have enough -value stack space to work without further allocations. The value stack -is also extended in somewhat large steps to minimize memory reallocation -activity. As a result the internal number of value stack elements -available beyond the caller specified extra varies considerably. -The caller does not need to take this into account and should never -rely on any additional elements being available.

- -

As a general rule -duk_require_stack() should be -used instead of this function to reserve more stack space. If value stack -cannot be extended, there is almost never a useful recovery strategy except -to throw an error and unwind.

- -=example -duk_idx_t nargs = duk_get_top(ctx); /* number or arguments */ - -/* reserve space for one temporary for each input argument */ -if (!duk_check_stack(ctx, nargs * 2)) { - /* return 'undefined' if cannot allocate space */ - printf("failed to reserve enough stack space\n"); - return 0; -} - -/* ... */ - -=tags -stack - -=seealso -duk_require_stack - -=introduced -1.0.0 diff --git a/website/api/duk_check_stack.yaml b/website/api/duk_check_stack.yaml new file mode 100644 index 00000000..5561931c --- /dev/null +++ b/website/api/duk_check_stack.yaml @@ -0,0 +1,60 @@ +name: duk_check_stack + +proto: | + duk_bool_t duk_check_stack(duk_context *ctx, duk_idx_t extra); + +summary: | +

Ensure that the value stack has at least extra reserved + (allocated) elements for caller's use, relative to the current stack top. + Returns 1 if successful, 0 otherwise. If the call is successful, the caller + is guaranteed that extra elements can be pushed to the value + stack without a value stack related error (other errors like out-of-memory + can still occur). The caller MUST NOT rely on being able to push more than + extra values; although this is possible, such elements are + reserved for Duktape's internal use.

+ +

Upon entry to a Duktape/C function and when outside any call + there is an automatic reserve (of DUK_API_ENTRY_STACK elements) + allocated for the caller in addition to call arguments on the value stack. + If more value stack space is needed, the caller must reserve more space + explicitly either in the beginning of the function (e.g. if the number of + elements required is known or can be computed based on arguments) or + dynamically (e.g. inside a loop). Note that an attempt to push a value + beyond the currently allocated value stack causes an error: it does not cause + the value stack to be automatically extended. This simplifies the internal + implementation.

+ +

In addition to user reserved elements, Duktape keeps an automatic + internal value stack reserve to ensure all API calls have enough + value stack space to work without further allocations. The value stack + is also extended in somewhat large steps to minimize memory reallocation + activity. As a result the internal number of value stack elements + available beyond the caller specified extra varies considerably. + The caller does not need to take this into account and should never + rely on any additional elements being available.

+ +

As a general rule + duk_require_stack() should be + used instead of this function to reserve more stack space. If value stack + cannot be extended, there is almost never a useful recovery strategy except + to throw an error and unwind.

+ +example: | + duk_idx_t nargs = duk_get_top(ctx); /* number or arguments */ + + /* reserve space for one temporary for each input argument */ + if (!duk_check_stack(ctx, nargs * 2)) { + /* return 'undefined' if cannot allocate space */ + printf("failed to reserve enough stack space\n"); + return 0; + } + + /* ... */ + +tags: + - stack + +seealso: + - duk_require_stack + +introduced: 1.0.0 diff --git a/website/api/duk_check_stack_top.txt b/website/api/duk_check_stack_top.txt deleted file mode 100644 index cbb3b1e7..00000000 --- a/website/api/duk_check_stack_top.txt +++ /dev/null @@ -1,37 +0,0 @@ -=proto -duk_bool_t duk_check_stack_top(duk_context *ctx, duk_idx_t top); - -=summary -

Like duk_check_stack(), -but ensures there is space up to top for caller's use. -This is sometimes more convenient than specifying the number of -additional elements (relative to current stack top) to reserve.

- -
-The caller specifies the maximum stack top ensured for caller's -use, not the highest value stack index reserved for the caller. -For instance, if top is 500, the highest value stack -index reserved for the caller is 499. -
- -

As a general rule -duk_require_stack_top() should be -used instead of this function to reserve more stack space. If value stack -cannot be extended, there is almost never a useful recovery strategy except -to throw an error and unwind.

- -=example -if (duk_check_stack_top(ctx, 100)) { - printf("value stack guaranteed up to index 99\n"); -} else { - printf("cannot get value stack space\n"); -} - -=tags -stack - -=seealso -duk_require_stack_top - -=introduced -1.0.0 diff --git a/website/api/duk_check_stack_top.yaml b/website/api/duk_check_stack_top.yaml new file mode 100644 index 00000000..c403ba4d --- /dev/null +++ b/website/api/duk_check_stack_top.yaml @@ -0,0 +1,38 @@ +name: duk_check_stack_top + +proto: | + duk_bool_t duk_check_stack_top(duk_context *ctx, duk_idx_t top); + +summary: | +

Like duk_check_stack(), + but ensures there is space up to top for caller's use. + This is sometimes more convenient than specifying the number of + additional elements (relative to current stack top) to reserve.

+ +
+ The caller specifies the maximum stack top ensured for caller's + use, not the highest value stack index reserved for the caller. + For instance, if top is 500, the highest value stack + index reserved for the caller is 499. +
+ +

As a general rule + duk_require_stack_top() should be + used instead of this function to reserve more stack space. If value stack + cannot be extended, there is almost never a useful recovery strategy except + to throw an error and unwind.

+ +example: | + if (duk_check_stack_top(ctx, 100)) { + printf("value stack guaranteed up to index 99\n"); + } else { + printf("cannot get value stack space\n"); + } + +tags: + - stack + +seealso: + - duk_require_stack_top + +introduced: 1.0.0 diff --git a/website/api/duk_check_type.txt b/website/api/duk_check_type.txt deleted file mode 100644 index 6e9883b1..00000000 --- a/website/api/duk_check_type.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -duk_bool_t duk_check_type(duk_context *ctx, duk_idx_t index, duk_int_t type); - -=stack -[ ... val! ... ] - -=summary -

Matches the type of the value at index against type. -Returns 1 if the type matches, zero otherwise.

- -=example -if (duk_check_type(ctx, -3, DUK_TYPE_NUMBER)) { - printf("value is a number\n"); -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_check_type.yaml b/website/api/duk_check_type.yaml new file mode 100644 index 00000000..1860471f --- /dev/null +++ b/website/api/duk_check_type.yaml @@ -0,0 +1,21 @@ +name: duk_check_type + +proto: | + duk_bool_t duk_check_type(duk_context *ctx, duk_idx_t index, duk_int_t type); + +stack: | + [ ... val! ... ] + +summary: | +

Matches the type of the value at index against type. + Returns 1 if the type matches, zero otherwise.

+ +example: | + if (duk_check_type(ctx, -3, DUK_TYPE_NUMBER)) { + printf("value is a number\n"); + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_check_type_mask.txt b/website/api/duk_check_type_mask.txt deleted file mode 100644 index 633e31a6..00000000 --- a/website/api/duk_check_type_mask.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_bool_t duk_check_type_mask(duk_context *ctx, duk_idx_t index, duk_uint_t mask); - -=stack -[ ... val! ... ] - -=summary -

Matches the type of the value at index against the type -mask bits given in mask. Returns 1 if the value type matches -one of the type mask bits and zero otherwise.

- -=example -if (duk_check_type_mask(ctx, -3, DUK_TYPE_MASK_STRING | - DUK_TYPE_MASK_NUMBER)) { - printf("value is a string or a number\n"); -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_check_type_mask.yaml b/website/api/duk_check_type_mask.yaml new file mode 100644 index 00000000..6da894a3 --- /dev/null +++ b/website/api/duk_check_type_mask.yaml @@ -0,0 +1,23 @@ +name: duk_check_type_mask + +proto: | + duk_bool_t duk_check_type_mask(duk_context *ctx, duk_idx_t index, duk_uint_t mask); + +stack: | + [ ... val! ... ] + +summary: | +

Matches the type of the value at index against the type + mask bits given in mask. Returns 1 if the value type matches + one of the type mask bits and zero otherwise.

+ +example: | + if (duk_check_type_mask(ctx, -3, DUK_TYPE_MASK_STRING | + DUK_TYPE_MASK_NUMBER)) { + printf("value is a string or a number\n"); + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_compact.txt b/website/api/duk_compact.txt deleted file mode 100644 index b8a08c3f..00000000 --- a/website/api/duk_compact.txt +++ /dev/null @@ -1,50 +0,0 @@ -=proto -void duk_compact(duk_context *ctx, duk_idx_t obj_index); - -=summary -

-Resizes an object's internal memory allocation to minimize memory usage. -If the value at obj_index is not an object, does nothing. -Although compaction is normally safe, it can fail due to an internal error -(such as out-of-memory error). Compaction only affects to an object's -"own properties", not its inherited properties. -

- -

-Compaction is not a final operation and has no impact on object semantics. -Adding new properties to the object is still possible (assuming the object -is extensible), but causes an object resize. Existing property values can be -changed (assuming the properties are writable) without affecting the object's -internal memory allocation. An object can be compacted multiple times: -for instance, if a new property is added to a previously compacted object, -the object can be compacted again to minimize memory footprint after the -property addition. -

- -

-Compacting an object saves a small amount of memory per object. It is -generally useful when (1) memory footprint is very important, (2) an object -is unlikely to gain new properties, (3) an object is relatively long-lived, -and (4) when compaction can be applied to enough many objects to make a -significant difference. -

- -

-If Object.seal(), Object.freeze(), or -Object.preventExtensions() is called, an object is automatically -compacted. -

- -=example -duk_push_object(ctx); /* [ ... obj ] */ -duk_push_int(ctx, 42); /* [ ... obj 42 ] */ -duk_put_prop_string(ctx, -2, "meaningOfLife"); /* [ ... obj ] */ -duk_compact(ctx, -1); /* [ ... obj ] */ - -=tags -object -property -memory - -=introduced -1.0.0 diff --git a/website/api/duk_compact.yaml b/website/api/duk_compact.yaml new file mode 100644 index 00000000..d9486317 --- /dev/null +++ b/website/api/duk_compact.yaml @@ -0,0 +1,51 @@ +name: duk_compact + +proto: | + void duk_compact(duk_context *ctx, duk_idx_t obj_index); + +summary: | +

+ Resizes an object's internal memory allocation to minimize memory usage. + If the value at obj_index is not an object, does nothing. + Although compaction is normally safe, it can fail due to an internal error + (such as out-of-memory error). Compaction only affects to an object's + "own properties", not its inherited properties. +

+ +

+ Compaction is not a final operation and has no impact on object semantics. + Adding new properties to the object is still possible (assuming the object + is extensible), but causes an object resize. Existing property values can be + changed (assuming the properties are writable) without affecting the object's + internal memory allocation. An object can be compacted multiple times: + for instance, if a new property is added to a previously compacted object, + the object can be compacted again to minimize memory footprint after the + property addition. +

+ +

+ Compacting an object saves a small amount of memory per object. It is + generally useful when (1) memory footprint is very important, (2) an object + is unlikely to gain new properties, (3) an object is relatively long-lived, + and (4) when compaction can be applied to enough many objects to make a + significant difference. +

+ +

+ If Object.seal(), Object.freeze(), or + Object.preventExtensions() is called, an object is automatically + compacted. +

+ +example: | + duk_push_object(ctx); /* [ ... obj ] */ + duk_push_int(ctx, 42); /* [ ... obj 42 ] */ + duk_put_prop_string(ctx, -2, "meaningOfLife"); /* [ ... obj ] */ + duk_compact(ctx, -1); /* [ ... obj ] */ + +tags: + - object + - property + - memory + +introduced: 1.0.0 diff --git a/website/api/duk_compile.txt b/website/api/duk_compile.txt deleted file mode 100644 index 3dd91c8f..00000000 --- a/website/api/duk_compile.txt +++ /dev/null @@ -1,148 +0,0 @@ -=proto -void duk_compile(duk_context *ctx, duk_uint_t flags); - -=stack -[ ... source! filename! ] -> [ ... function! ] - -=summary -

Compile Ecmascript source code and replace it with a compiled function -object (the code is not executed). The filename argument is stored -as the fileName property of the resulting function, and is the name -used in e.g. tracebacks to identify the function. May throw a SyntaxError -for any compile-time errors (in addition to the usual internal errors like out-of-memory, -internal limit errors, etc).

- -

The following flags may be given:

- - -

The source code being compiled may be:

- - - -

All of these have slightly different semantics in Ecmascript. See -Establishing an Execution Context -for a detailed discussion. -One major difference is that program and eval contexts have an implicit -return value: the last non-empty statement value is an automatic -return value for the program or eval code, whereas functions don't have -an automatic return value. -

- -

Program and eval code don't have an explicit function syntax. -For instance, the following can be compiled both as a program and as an -eval expression:

-
-print("Hello world!");
-123;  // implicit return value
-
- -

Function code follows the Ecmascript function syntax -(the function name is optional):

-
-function adder(x,y) {
-    return x+y;
-}
-
- -

Compiling a function is equivalent to compiling eval code which contains -a function expression. Note that the outermost parentheses are required, -otherwise the eval code will register a global function named "adder" instead -of returning a plain function value:

-
-(function adder(x,y) {
-    return x+y;
-})
-
- -

The bytecode generated for program and eval code is currently slower -than that generated for functions: a "slow path" is used for all variable -accesses in program and eval code, and the implicit return value handling -of program and eval code generates some unnecessary bytecode. From a -performance point of view (both memory and execution performance) it is -thus preferable to have as much code inside functions as possible.

- -

When compiling eval and program expressions, be careful to avoid the -usual Ecmascript gotchas, such as:

-
-/* Function at top level is a function declaration which registers a global
- * function, and is different from a function expression.  Use parentheses
- * around the top level expression.
- */
-
-eval("function adder(x,y) { return x+y; }");   /* registers 'adder' to global */
-eval("function (x,y) { return x+y; }");        /* not allowed */
-eval("(function (x,y) { return x+y; })");      /* function expression (anonymous) */
-eval("(function adder(x,y) { return x+y; })"); /* function expression (named) */
-
-/* Opening curly brace at top level is interpreted as start of a block
- * expression, not an object literal.  Use parentheses around the top
- * level expression.
- */
-
-eval("{ myfunc: 1 }");   /* block with -label- "myfunc" and statement "1" (!) */
-eval("({ myfunc: 1 })";  /* object literal { myfunc: 1 } */
-
- -=example -/* Program code. Note that the hello() function is a function - * declaration which gets registered into the global object when - * executed. Implicit return value is 123. - */ - -duk_push_string(ctx, "print('program');\n" - "function hello() { print('Hello world!'); }\n" - "123;"); -duk_push_string(ctx, "hello"); -duk_compile(ctx, 0); /* [ source filename ] -> [ func ] */ -duk_call(ctx, 0); /* [ func ] -> [ result ] */ -printf("program result: %lf\n", (double) duk_get_number(ctx, -1)); -duk_pop(ctx); - -/* Eval code */ - -duk_push_string(ctx, "2+3"); -duk_push_string(ctx, "eval"); -duk_compile(ctx, DUK_COMPILE_EVAL); -duk_call(ctx, 0); /* [ func ] -> [ result ] */ -printf("eval result: %lf\n", (double) duk_get_number(ctx, -1)); -duk_pop(ctx); - -/* Function code */ - -duk_push_string(ctx, "function (x,y) { return x+y; }"); -duk_push_string(ctx, "function"); -duk_compile(ctx, DUK_COMPILE_FUNCTION); -duk_push_int(ctx, 5); -duk_push_int(ctx, 6); -duk_call(ctx, 2); /* [ func 5 6 ] -> [ result ] */ -printf("function result: %lf\n", (double) duk_get_number(ctx, -1)); -duk_pop(ctx); - -=tags -compile - -=seealso -duk_pcompile -duk_compile_string -duk_compile_string_filename -duk_compile_lstring -duk_compile_lstring_filename -duk_compile_file - -=introduced -1.0.0 diff --git a/website/api/duk_compile.yaml b/website/api/duk_compile.yaml new file mode 100644 index 00000000..79c7da5f --- /dev/null +++ b/website/api/duk_compile.yaml @@ -0,0 +1,149 @@ +name: duk_compile + +proto: | + void duk_compile(duk_context *ctx, duk_uint_t flags); + +stack: | + [ ... source! filename! ] -> [ ... function! ] + +summary: | +

Compile Ecmascript source code and replace it with a compiled function + object (the code is not executed). The filename argument is stored + as the fileName property of the resulting function, and is the name + used in e.g. tracebacks to identify the function. May throw a SyntaxError + for any compile-time errors (in addition to the usual internal errors like out-of-memory, + internal limit errors, etc).

+ +

The following flags may be given:

+ + +

The source code being compiled may be:

+ + + +

All of these have slightly different semantics in Ecmascript. See + Establishing an Execution Context + for a detailed discussion. + One major difference is that program and eval contexts have an implicit + return value: the last non-empty statement value is an automatic + return value for the program or eval code, whereas functions don't have + an automatic return value. +

+ +

Program and eval code don't have an explicit function syntax. + For instance, the following can be compiled both as a program and as an + eval expression:

+ 
+  print("Hello world!");
+  123;  // implicit return value
+
+ +

Function code follows the Ecmascript function syntax + (the function name is optional):

+ 
+  function adder(x,y) {
+      return x+y;
+  }
+
+ +

Compiling a function is equivalent to compiling eval code which contains + a function expression. Note that the outermost parentheses are required, + otherwise the eval code will register a global function named "adder" instead + of returning a plain function value:

+ 
+  (function adder(x,y) {
+      return x+y;
+  })
+
+ +

The bytecode generated for program and eval code is currently slower + than that generated for functions: a "slow path" is used for all variable + accesses in program and eval code, and the implicit return value handling + of program and eval code generates some unnecessary bytecode. From a + performance point of view (both memory and execution performance) it is + thus preferable to have as much code inside functions as possible.

+ +

When compiling eval and program expressions, be careful to avoid the + usual Ecmascript gotchas, such as:

+ 
+  /* Function at top level is a function declaration which registers a global
+   * function, and is different from a function expression.  Use parentheses
+   * around the top level expression.
+   */
+
+  eval("function adder(x,y) { return x+y; }");   /* registers 'adder' to global */
+  eval("function (x,y) { return x+y; }");        /* not allowed */
+  eval("(function (x,y) { return x+y; })");      /* function expression (anonymous) */
+  eval("(function adder(x,y) { return x+y; })"); /* function expression (named) */
+
+  /* Opening curly brace at top level is interpreted as start of a block
+   * expression, not an object literal.  Use parentheses around the top
+   * level expression.
+   */
+
+  eval("{ myfunc: 1 }");   /* block with -label- "myfunc" and statement "1" (!) */
+  eval("({ myfunc: 1 })";  /* object literal { myfunc: 1 } */
+
+ +example: | + /* Program code. Note that the hello() function is a function + * declaration which gets registered into the global object when + * executed. Implicit return value is 123. + */ + + duk_push_string(ctx, "print('program');\n" + "function hello() { print('Hello world!'); }\n" + "123;"); + duk_push_string(ctx, "hello"); + duk_compile(ctx, 0); /* [ source filename ] -> [ func ] */ + duk_call(ctx, 0); /* [ func ] -> [ result ] */ + printf("program result: %lf\n", (double) duk_get_number(ctx, -1)); + duk_pop(ctx); + + /* Eval code */ + + duk_push_string(ctx, "2+3"); + duk_push_string(ctx, "eval"); + duk_compile(ctx, DUK_COMPILE_EVAL); + duk_call(ctx, 0); /* [ func ] -> [ result ] */ + printf("eval result: %lf\n", (double) duk_get_number(ctx, -1)); + duk_pop(ctx); + + /* Function code */ + + duk_push_string(ctx, "function (x,y) { return x+y; }"); + duk_push_string(ctx, "function"); + duk_compile(ctx, DUK_COMPILE_FUNCTION); + duk_push_int(ctx, 5); + duk_push_int(ctx, 6); + duk_call(ctx, 2); /* [ func 5 6 ] -> [ result ] */ + printf("function result: %lf\n", (double) duk_get_number(ctx, -1)); + duk_pop(ctx); + +tags: + - compile + +seealso: + - duk_pcompile + - duk_compile_string + - duk_compile_string_filename + - duk_compile_lstring + - duk_compile_lstring_filename + - duk_compile_file + +introduced: 1.0.0 diff --git a/website/api/duk_compile_file.txt b/website/api/duk_compile_file.txt deleted file mode 100644 index 70f39587..00000000 --- a/website/api/duk_compile_file.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -void duk_compile_file(duk_context *ctx, duk_uint_t flags, const char *path); - -=stack -[ ... ] -> [ ... function! ] - -=summary -

Like -duk_compile(), but the compile input -is given as a filename. The filename associated with the result function -is path as is.

- -
- -=example -duk_compile_file(ctx, 0, "test.js"); - -=tags -compile -nonportable - -=introduced -1.0.0 diff --git a/website/api/duk_compile_file.yaml b/website/api/duk_compile_file.yaml new file mode 100644 index 00000000..f3f030d6 --- /dev/null +++ b/website/api/duk_compile_file.yaml @@ -0,0 +1,24 @@ +name: duk_compile_file + +proto: | + void duk_compile_file(duk_context *ctx, duk_uint_t flags, const char *path); + +stack: | + [ ... ] -> [ ... function! ] + +summary: | +

Like + duk_compile(), but the compile input + is given as a filename. The filename associated with the result function + is path as is.

+ +
+ +example: | + duk_compile_file(ctx, 0, "test.js"); + +tags: + - compile + - nonportable + +introduced: 1.0.0 diff --git a/website/api/duk_compile_lstring.txt b/website/api/duk_compile_lstring.txt deleted file mode 100644 index 4b0575fa..00000000 --- a/website/api/duk_compile_lstring.txt +++ /dev/null @@ -1,26 +0,0 @@ -=proto -void duk_compile_lstring(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); - -=stack -[ ... ] -> [ ... function! ] - -=summary -

Like -duk_compile(), but the compile input -is given as a C string with explicit length. The filename associated with the -function is automatically provided from the __FILE__ preprocessor -define of the caller.

- -
- -=example -const char *src = /* ... */; -duk_size_t len = /* ... */; - -duk_compile_lstring(ctx, 0, src, len); - -=tags -compile - -=introduced -1.0.0 diff --git a/website/api/duk_compile_lstring.yaml b/website/api/duk_compile_lstring.yaml new file mode 100644 index 00000000..45955244 --- /dev/null +++ b/website/api/duk_compile_lstring.yaml @@ -0,0 +1,27 @@ +name: duk_compile_lstring + +proto: | + void duk_compile_lstring(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); + +stack: | + [ ... ] -> [ ... function! ] + +summary: | +

Like + duk_compile(), but the compile input + is given as a C string with explicit length. The filename associated with the + function is automatically provided from the __FILE__ preprocessor + define of the caller.

+ +
+ +example: | + const char *src = /* ... */; + duk_size_t len = /* ... */; + + duk_compile_lstring(ctx, 0, src, len); + +tags: + - compile + +introduced: 1.0.0 diff --git a/website/api/duk_compile_lstring_filename.txt b/website/api/duk_compile_lstring_filename.txt deleted file mode 100644 index 47107df5..00000000 --- a/website/api/duk_compile_lstring_filename.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -void duk_compile_lstring_filename(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); - -=stack -[ ... filename! ] -> [ ... function! ] - -=summary -

Like -duk_compile(), but the compile input -is given as a C string with explicit length.

- -
- -=example -const char *src = /* ... */; -duk_size_t len = /* ... */; - -duk_push_string(ctx, "myFile.js"); -duk_compile_lstring_filename(ctx, 0, src, len); - -=tags -compile - -=introduced -1.0.0 diff --git a/website/api/duk_compile_lstring_filename.yaml b/website/api/duk_compile_lstring_filename.yaml new file mode 100644 index 00000000..69d01dcf --- /dev/null +++ b/website/api/duk_compile_lstring_filename.yaml @@ -0,0 +1,26 @@ +name: duk_compile_lstring_filename + +proto: | + void duk_compile_lstring_filename(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); + +stack: | + [ ... filename! ] -> [ ... function! ] + +summary: | +

Like + duk_compile(), but the compile input + is given as a C string with explicit length.

+ +
+ +example: | + const char *src = /* ... */; + duk_size_t len = /* ... */; + + duk_push_string(ctx, "myFile.js"); + duk_compile_lstring_filename(ctx, 0, src, len); + +tags: + - compile + +introduced: 1.0.0 diff --git a/website/api/duk_compile_string.txt b/website/api/duk_compile_string.txt deleted file mode 100644 index 5675727e..00000000 --- a/website/api/duk_compile_string.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -void duk_compile_string(duk_context *ctx, duk_uint_t flags, const char *src); - -=stack -[ ... ] -> [ ... function! ] - -=summary -

Like -duk_compile(), but the compile input -is given as a C string. The filename associated with the function is -automatically provided from the __FILE__ preprocessor define of -the caller.

- -
- -=example -duk_compile_string(ctx, 0, "print('program code');"); - -=tags -compile - -=introduced -1.0.0 diff --git a/website/api/duk_compile_string.yaml b/website/api/duk_compile_string.yaml new file mode 100644 index 00000000..f4f7f666 --- /dev/null +++ b/website/api/duk_compile_string.yaml @@ -0,0 +1,24 @@ +name: duk_compile_string + +proto: | + void duk_compile_string(duk_context *ctx, duk_uint_t flags, const char *src); + +stack: | + [ ... ] -> [ ... function! ] + +summary: | +

Like + duk_compile(), but the compile input + is given as a C string. The filename associated with the function is + automatically provided from the __FILE__ preprocessor define of + the caller.

+ +
+ +example: | + duk_compile_string(ctx, 0, "print('program code');"); + +tags: + - compile + +introduced: 1.0.0 diff --git a/website/api/duk_compile_string_filename.txt b/website/api/duk_compile_string_filename.txt deleted file mode 100644 index 32b7bd71..00000000 --- a/website/api/duk_compile_string_filename.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -void duk_compile_string_filename(duk_context *ctx, duk_uint_t flags, const char *src); - -=stack -[ ... filename! ] -> [ ... function! ] - -=summary -

Like -duk_compile(), but the compile input -is given as a C string.

- -
- -=example -duk_push_string(ctx, "myFile.js"); -duk_compile_string_filename(ctx, 0, "print('program code');"); - -=tags -compile - -=introduced -1.0.0 diff --git a/website/api/duk_compile_string_filename.yaml b/website/api/duk_compile_string_filename.yaml new file mode 100644 index 00000000..58d3b79e --- /dev/null +++ b/website/api/duk_compile_string_filename.yaml @@ -0,0 +1,23 @@ +name: duk_compile_string_filename + +proto: | + void duk_compile_string_filename(duk_context *ctx, duk_uint_t flags, const char *src); + +stack: | + [ ... filename! ] -> [ ... function! ] + +summary: | +

Like + duk_compile(), but the compile input + is given as a C string.

+ +
+ +example: | + duk_push_string(ctx, "myFile.js"); + duk_compile_string_filename(ctx, 0, "print('program code');"); + +tags: + - compile + +introduced: 1.0.0 diff --git a/website/api/duk_concat.txt b/website/api/duk_concat.txt deleted file mode 100644 index ef9e8072..00000000 --- a/website/api/duk_concat.txt +++ /dev/null @@ -1,31 +0,0 @@ -=proto -void duk_concat(duk_context *ctx, duk_idx_t count); - -=stack -[ ... val1! ...! valN! ] -> [ ... result! ] - -=summary -

Concatenate zero or more values into a result string. The input values -are automatically coerced with -ToString().

- -

This primitive minimizes the number of intermediate string interning -operations and is better than concatenating strings manually.

- -=example -duk_push_string(ctx, "foo"); -duk_push_int(ctx, 123); -duk_push_true(ctx); -duk_concat(ctx, 3); - -printf("result: %s\n", duk_get_string(ctx, -1)); /* "foo123true" */ -duk_pop(ctx); - -=tags -string - -=seealso -duk_join - -=introduced -1.0.0 diff --git a/website/api/duk_concat.yaml b/website/api/duk_concat.yaml new file mode 100644 index 00000000..2325210c --- /dev/null +++ b/website/api/duk_concat.yaml @@ -0,0 +1,32 @@ +name: duk_concat + +proto: | + void duk_concat(duk_context *ctx, duk_idx_t count); + +stack: | + [ ... val1! ...! valN! ] -> [ ... result! ] + +summary: | +

Concatenate zero or more values into a result string. The input values + are automatically coerced with + ToString().

+ +

This primitive minimizes the number of intermediate string interning + operations and is better than concatenating strings manually.

+ +example: | + duk_push_string(ctx, "foo"); + duk_push_int(ctx, 123); + duk_push_true(ctx); + duk_concat(ctx, 3); + + printf("result: %s\n", duk_get_string(ctx, -1)); /* "foo123true" */ + duk_pop(ctx); + +tags: + - string + +seealso: + - duk_join + +introduced: 1.0.0 diff --git a/website/api/duk_copy.txt b/website/api/duk_copy.txt deleted file mode 100644 index 86f99a9c..00000000 --- a/website/api/duk_copy.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -void duk_copy(duk_context *ctx, duk_idx_t from_index, duk_idx_t to_index); - -=stack -[ ... old(to_index)! ... val(from_index)! ... ] -> [ ... val(to_index)! ... val(from_index)! ... ] - -=summary -

Copy a value from from_index to to_index, -overwriting the previous value. If either index is invalid, throws an -error.

- -

This is a shorthand for:

-
-/* to_index must be normalize in case it is negative and would change its
- * meaning after duk_dup().
- */
-to_index = duk_normalize_index(ctx, to_index);
-duk_dup(ctx, from_index);
-duk_replace(ctx, to_index);
-
- -=example -duk_copy(ctx, -3, 1); - -=tags -stack - -=seealso -duk_insert -duk_replace - -=introduced -1.0.0 diff --git a/website/api/duk_copy.yaml b/website/api/duk_copy.yaml new file mode 100644 index 00000000..0b91ef4a --- /dev/null +++ b/website/api/duk_copy.yaml @@ -0,0 +1,34 @@ +name: duk_copy + +proto: | + void duk_copy(duk_context *ctx, duk_idx_t from_index, duk_idx_t to_index); + +stack: | + [ ... old(to_index)! ... val(from_index)! ... ] -> [ ... val(to_index)! ... val(from_index)! ... ] + +summary: | +

Copy a value from from_index to to_index, + overwriting the previous value. If either index is invalid, throws an + error.

+ +

This is a shorthand for:

+ 
+  /* to_index must be normalize in case it is negative and would change its
+   * meaning after duk_dup().
+   */
+  to_index = duk_normalize_index(ctx, to_index);
+  duk_dup(ctx, from_index);
+  duk_replace(ctx, to_index);
+
+ +example: | + duk_copy(ctx, -3, 1); + +tags: + - stack + +seealso: + - duk_insert + - duk_replace + +introduced: 1.0.0 diff --git a/website/api/duk_create_heap.txt b/website/api/duk_create_heap.txt deleted file mode 100644 index 9483e5a0..00000000 --- a/website/api/duk_create_heap.txt +++ /dev/null @@ -1,73 +0,0 @@ -=proto -duk_context *duk_create_heap(duk_alloc_function alloc_func, - duk_realloc_function realloc_func, - duk_free_function free_func, - void *heap_udata, - duk_fatal_function fatal_handler); - -=summary -

Create a new Duktape heap and return an initial context (thread). -If heap initialization fails, a NULL is returned. There is -currently no way to obtain more detailed error information.

- -

The caller may provide custom memory management functions in -alloc_func, realloc_func, and free_func; -the pointers must either all be NULL or all be -non-NULL. If the pointers are NULL, default -memory management functions (ANSI C malloc(), realloc() -, and free()) are used. The memory management functions -share the same opaque userdata pointer, heap_udata. This -userdata pointer is also used for other Duktape features (like low memory -pointer compression macros).

- -

A fatal error handler is provided in fatal_handler. This -handler is called in unrecoverable error situations such as uncaught -errors, out-of-memory errors not resolved by garbage collection, etc. -A caller SHOULD implement a fatal error handler in most applications. -If not given, a default fatal error handler is used. The default -handler ultimately calls ANSI C abort(), which may not always -be the preferred action.

- -

To create a Duktape heap with default settings, use -duk_create_heap_default().

- -

New contexts linked to the same heap can be created with -duk_push_thread() and -duk_push_thread_new_globalenv().

- -=example -/* - * Simple case: use default allocation functions and fatal error handler - */ - -duk_context *ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL); -if (ctx) { - /* success */ -} else { - /* error */ -} - -/* - * Customized handlers - */ - -duk_context *ctx = duk_create_heap(my_alloc, my_realloc, my_free, - (void *) 0xdeadbeef, my_fatal); -if (ctx) { - /* success */ - - /* ... after heap is no longer needed: */ - duk_destroy_heap(ctx); -} else { - /* error */ -} - -=tags -heap - -=seealso -duk_create_heap_default -duk_destroy_heap - -=introduced -1.0.0 diff --git a/website/api/duk_create_heap.yaml b/website/api/duk_create_heap.yaml new file mode 100644 index 00000000..0a1bbc65 --- /dev/null +++ b/website/api/duk_create_heap.yaml @@ -0,0 +1,74 @@ +name: duk_create_heap + +proto: | + duk_context *duk_create_heap(duk_alloc_function alloc_func, + duk_realloc_function realloc_func, + duk_free_function free_func, + void *heap_udata, + duk_fatal_function fatal_handler); + +summary: | +

Create a new Duktape heap and return an initial context (thread). + If heap initialization fails, a NULL is returned. There is + currently no way to obtain more detailed error information.

+ +

The caller may provide custom memory management functions in + alloc_func, realloc_func, and free_func; + the pointers must either all be NULL or all be + non-NULL. If the pointers are NULL, default + memory management functions (ANSI C malloc(), realloc() + , and free()) are used. The memory management functions + share the same opaque userdata pointer, heap_udata. This + userdata pointer is also used for other Duktape features (like low memory + pointer compression macros).

+ +

A fatal error handler is provided in fatal_handler. This + handler is called in unrecoverable error situations such as uncaught + errors, out-of-memory errors not resolved by garbage collection, etc. + A caller SHOULD implement a fatal error handler in most applications. + If not given, a default fatal error handler is used. The default + handler ultimately calls ANSI C abort(), which may not always + be the preferred action.

+ +

To create a Duktape heap with default settings, use + duk_create_heap_default().

+ +

New contexts linked to the same heap can be created with + duk_push_thread() and + duk_push_thread_new_globalenv().

+ +example: | + /* + * Simple case: use default allocation functions and fatal error handler + */ + + duk_context *ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL); + if (ctx) { + /* success */ + } else { + /* error */ + } + + /* + * Customized handlers + */ + + duk_context *ctx = duk_create_heap(my_alloc, my_realloc, my_free, + (void *) 0xdeadbeef, my_fatal); + if (ctx) { + /* success */ + + /* ... after heap is no longer needed: */ + duk_destroy_heap(ctx); + } else { + /* error */ + } + +tags: + - heap + +seealso: + - duk_create_heap_default + - duk_destroy_heap + +introduced: 1.0.0 diff --git a/website/api/duk_create_heap_default.txt b/website/api/duk_create_heap_default.txt deleted file mode 100644 index 70c204a3..00000000 --- a/website/api/duk_create_heap_default.txt +++ /dev/null @@ -1,30 +0,0 @@ -=proto -duk_context *duk_create_heap_default(void); - -=summary -

Create a new Duktape heap and return an initial context (thread). -If heap initialization fails, a NULL is returned. There is -currently no way to obtain more detailed error information.

- -

The created heap will use default memory management and fatal error -handler functions. This API call is equivalent to:

-
-ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL);
-
- -=example -duk_context *ctx = duk_create_heap_default(); -if (ctx) { - /* success */ - - /* ... after heap is no longer needed: */ - duk_destroy_heap(ctx); -} else { - /* error */ -} - -=tags -heap - -=introduced -1.0.0 diff --git a/website/api/duk_create_heap_default.yaml b/website/api/duk_create_heap_default.yaml new file mode 100644 index 00000000..c5548fc0 --- /dev/null +++ b/website/api/duk_create_heap_default.yaml @@ -0,0 +1,31 @@ +name: duk_create_heap_default + +proto: | + duk_context *duk_create_heap_default(void); + +summary: | +

Create a new Duktape heap and return an initial context (thread). + If heap initialization fails, a NULL is returned. There is + currently no way to obtain more detailed error information.

+ +

The created heap will use default memory management and fatal error + handler functions. This API call is equivalent to:

+ 
+  ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL);
+
+ +example: | + duk_context *ctx = duk_create_heap_default(); + if (ctx) { + /* success */ + + /* ... after heap is no longer needed: */ + duk_destroy_heap(ctx); + } else { + /* error */ + } + +tags: + - heap + +introduced: 1.0.0 diff --git a/website/api/duk_debugger_attach.txt b/website/api/duk_debugger_attach.txt deleted file mode 100644 index c34c3ac2..00000000 --- a/website/api/duk_debugger_attach.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -void duk_debugger_attach(duk_context *ctx, duk_debug_read_function read_cb, duk_debug_write_function write_cb, duk_debug_peek_function peek_cb, duk_debug_read_flush_function read_flush_cb, duk_debug_write_flush_function write_flush_cb, duk_debug_detached_function detached_cb, void *udata); - -=summary -

Attach a debugger to the Duktape heap. If debugger support is not -compiled into Duktape, throws an error. See -debugger.rst -for more information.

- -

The read_cb and write_cb callbacks are mandatory. -The peek_cb is strongly recommended but optional. The -read_flush_cb and write_flush_cb callbacks are -optional. Unimplemented callbacks are indicated using a NULL.

- -=example -duk_debugger_attach(ctx, - my_read_cb, - my_write_cb, - my_peek_cb, - NULL, - NULL, - my_detached_cb, - my_udata); - -=tags -debug -experimental - -=seealso -duk_debugger_detach -duk_debugger_cooperate - -=introduced -1.2.0 diff --git a/website/api/duk_debugger_attach.yaml b/website/api/duk_debugger_attach.yaml new file mode 100644 index 00000000..0ff39f00 --- /dev/null +++ b/website/api/duk_debugger_attach.yaml @@ -0,0 +1,42 @@ +name: duk_debugger_attach + +proto: | + void duk_debugger_attach(duk_context *ctx, + duk_debug_read_function read_cb, + duk_debug_write_function write_cb, + duk_debug_peek_function peek_cb, + duk_debug_read_flush_function read_flush_cb, + duk_debug_write_flush_function write_flush_cb, + duk_debug_detached_function detached_cb, + void *udata); + +summary: | +

Attach a debugger to the Duktape heap. If debugger support is not + compiled into Duktape, throws an error. See + debugger.rst + for more information.

+ +

The read_cb and write_cb callbacks are mandatory. + The peek_cb is strongly recommended but optional. The + read_flush_cb and write_flush_cb callbacks are + optional. Unimplemented callbacks are indicated using a NULL.

+ +example: | + duk_debugger_attach(ctx, + my_read_cb, + my_write_cb, + my_peek_cb, + NULL, + NULL, + my_detached_cb, + my_udata); + +tags: + - debug + - experimental + +seealso: + - duk_debugger_detach + - duk_debugger_cooperate + +introduced: 1.2.0 diff --git a/website/api/duk_debugger_cooperate.txt b/website/api/duk_debugger_cooperate.txt deleted file mode 100644 index 05c931bf..00000000 --- a/website/api/duk_debugger_cooperate.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -void duk_debugger_cooperate(duk_context *ctx); - -=summary -

Check for and execute inbound debug commands without blocking. Debug -commands are executed in the context of the ctx argument. -May only be called when no calls into Duktape are in progress (from any -context). See -debugger.rst -for more information.

- -=example -duk_debugger_cooperate(ctx); - -=tags -debug -experimental - -=seealso -duk_debugger_attach -duk_debugger_detach - -=introduced -1.2.0 diff --git a/website/api/duk_debugger_cooperate.yaml b/website/api/duk_debugger_cooperate.yaml new file mode 100644 index 00000000..2e0aaf55 --- /dev/null +++ b/website/api/duk_debugger_cooperate.yaml @@ -0,0 +1,25 @@ +name: duk_debugger_cooperate + +proto: | + void duk_debugger_cooperate(duk_context *ctx); + +summary: | +

Check for and execute inbound debug commands without blocking. Debug + commands are executed in the context of the ctx argument. + May only be called when no calls into Duktape are in progress (from any + context). See + debugger.rst + for more information.

+ +example: | + duk_debugger_cooperate(ctx); + +tags: + - debug + - experimental + +seealso: + - duk_debugger_attach + - duk_debugger_detach + +introduced: 1.2.0 diff --git a/website/api/duk_debugger_detach.txt b/website/api/duk_debugger_detach.txt deleted file mode 100644 index 3758f42c..00000000 --- a/website/api/duk_debugger_detach.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -void duk_debugger_detach(duk_context *ctx); - -=summary -

Detach a debugger from the Duktape heap. If debugger support is not -compiled into Duktape, throws an error. See -debugger.rst -for more information.

- -=example -duk_debugger_detach(ctx); - -=tags -debug -experimental - -=seealso -duk_debugger_attach -duk_debugger_cooperate - -=introduced -1.2.0 diff --git a/website/api/duk_debugger_detach.yaml b/website/api/duk_debugger_detach.yaml new file mode 100644 index 00000000..d236d899 --- /dev/null +++ b/website/api/duk_debugger_detach.yaml @@ -0,0 +1,23 @@ +name: duk_debugger_detach + +proto: | + void duk_debugger_detach(duk_context *ctx); + +summary: | +

Detach a debugger from the Duktape heap. If debugger support is not + compiled into Duktape, throws an error. See + debugger.rst + for more information.

+ +example: | + duk_debugger_detach(ctx); + +tags: + - debug + - experimental + +seealso: + - duk_debugger_attach + - duk_debugger_cooperate + +introduced: 1.2.0 diff --git a/website/api/duk_decode_string.txt b/website/api/duk_decode_string.txt deleted file mode 100644 index 4e4c2f35..00000000 --- a/website/api/duk_decode_string.txt +++ /dev/null @@ -1,28 +0,0 @@ -=proto -void duk_decode_string(duk_context *ctx, duk_idx_t index, duk_decode_char_function callback, void *udata); - -=stack -[ ... val! ... ] - -=summary -

Process string at index, calling callback for each codepoint -of the string. The callback is given the udata argument and a codepoint. -The input string is not modified. If the value is not a string or the index is -invalid, throws an error.

- -=example -static void decode_char(void *udata, duk_codepoint_t codepoint) { - printf("codepoint: %ld\n", (long) codepoint); -} - -duk_push_string(ctx, "test_string"); -duk_decode_string(ctx, -1, decode_char, NULL); - -=tags -string - -=seealso -duk_map_string - -=introduced -1.0.0 diff --git a/website/api/duk_decode_string.yaml b/website/api/duk_decode_string.yaml new file mode 100644 index 00000000..b70f4dca --- /dev/null +++ b/website/api/duk_decode_string.yaml @@ -0,0 +1,29 @@ +name: duk_decode_string + +proto: | + void duk_decode_string(duk_context *ctx, duk_idx_t index, duk_decode_char_function callback, void *udata); + +stack: | + [ ... val! ... ] + +summary: | +

Process string at index, calling callback for each codepoint + of the string. The callback is given the udata argument and a codepoint. + The input string is not modified. If the value is not a string or the index is + invalid, throws an error.

+ +example: | + static void decode_char(void *udata, duk_codepoint_t codepoint) { + printf("codepoint: %ld\n", (long) codepoint); + } + + duk_push_string(ctx, "test_string"); + duk_decode_string(ctx, -1, decode_char, NULL); + +tags: + - string + +seealso: + - duk_map_string + +introduced: 1.0.0 diff --git a/website/api/duk_def_prop.txt b/website/api/duk_def_prop.txt deleted file mode 100644 index ebe3fc67..00000000 --- a/website/api/duk_def_prop.txt +++ /dev/null @@ -1,142 +0,0 @@ -=proto -void duk_def_prop(duk_context *ctx, duk_idx_t obj_index, duk_uint_t flags); - -=stack -[ ... obj! ... key! ] -> [ ... obj! ... ] (if have no value, setter, getter) -[ ... obj! ... key! value! ] -> [ ... obj! ... ] (if have value) -[ ... obj! ... key! getter! ] -> [ ... obj! ... ] (if have getter, but no setter) -[ ... obj! ... key! setter! ] -> [ ... obj! ... ] (if have setter, but no getter) -[ ... obj! ... key! getter! setter! ] -> [ ... obj! ... ] (if have both getter and setter) - -=summary -

Create or alter the attributes of property key of object at -obj_index, with semantics like -Object.defineProperty(). -When the requested change is not allowed (e.g. property is not configurable), a -TypeError is thrown. If the target is not an object (or the -index is invalid) an error is thrown.

- -

The flags field provides "have" flags to indicate what property attributes -are changed (this models the partial property descriptors allowed by -Object.defineProperty()). Values for the writable, configurable, -and enumerable attributes are given in the flags field, while property value, -getter, and setter are given as value stack arguments. When creating a new -property, missing attribute values cause -Ecmascript defaults -to be used (false for all boolean attributes, undefined for value, getter, setter); -when modifying an existing property missing attribute values mean that existing -attribute values are not touched.

- -

With the DUK_DEFPROP_FORCE flag property changes can be forced -even when an operation would normally fail due to a non-extensible target object -or a non-configurable property. This cannot be done from Ecmascript code with -Object.defineProperty() and is useful for e.g. sandboxing setup. -In some cases even a forced change is not possible and will cause an error to be -thrown. For instance, properties implemented internally as virtual properties -(such as string "length" and index properties) cannot be modified because they -don't have concrete internal storage and thus no way of recording changes.

- -

Some examples (see further examples below):

-
    -
  • To set the writable attribute, set flags to - DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE.
    • -
  • To clear the writable attribute, set flags to - DUK_DEFPROP_HAVE_WRITABLE.
    • -
  • To set value, clear writable, and set enumerable, set flags to - DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_ENUMERABLE - and provide the property value as a stack argument.
    • -
  • To forcibly set the value of a non-configurable property, set flags to - DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_FORCE and provide the - new property value as a stack argument.
    • -
- -

This API call is useful for various things:

-
    -
  • To create properties with non-default attributes directly from C code.
    • -
  • To create accessor (getter/setter) properties directly from C code.
    • -
  • To modify the property attributes of existing properties directly from C code.
    • -
- -

See API testcase -test-def-prop.c -for more examples.

- -=example -duk_idx_t obj_idx = /* ... */; - -/* Create an ordinary property which is writable and configurable, but - * not enumerable. - */ - -duk_push_string(ctx, "my_prop_1"); -duk_push_int(ctx, 123); /* prop value */ -duk_def_prop(ctx, - obj_idx, - DUK_DEFPROP_HAVE_VALUE | - DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE | - DUK_DEFPROP_HAVE_ENUMERABLE | 0 | - DUK_DEFPROP_HAVE_CONFIGURABLE | DUK_DEFPROP_CONFIGURABLE); - -/* Change the property value and make it non-writable. Don't touch other - * attributes. - */ - -duk_push_string(ctx, "my_prop_1"); -duk_push_int(ctx, 321); -duk_def_prop(ctx, - obj_idx, - DUK_DEFPROP_HAVE_VALUE | - DUK_DEFPROP_HAVE_WRITABLE | 0); - -/* Make the property non-configurable, don't touch value or other attributes. */ - -duk_push_string(ctx, "my_prop_1"); -duk_def_prop(ctx, - obj_idx, - DUK_DEFPROP_HAVE_CONFIGURABLE | 0); - -/* Create an accessor property which is non-configurable and non-enumerable. - * Attribute flags are not given so they default to Ecmascript defaults - * (false) automatically. - */ - -duk_push_string(ctx, "my_accessor_1"); -duk_push_c_function(ctx, my_getter, 0 /*nargs*/); -duk_push_c_function(ctx, my_setter, 1 /*nargs*/); -duk_def_prop(ctx, - obj_idx, - DUK_DEFPROP_HAVE_GETTER | - DUK_DEFPROP_HAVE_SETTER); - -/* Create an accessor property which is non-configurable but enumerable. - * Attribute flags are given explicitly which is easier to read without - * knowing about Ecmascript attribute default values. - */ - -duk_push_string(ctx, "my_accessor_2"); -duk_push_c_function(ctx, my_getter, 0 /*nargs*/); -duk_push_c_function(ctx, my_setter, 1 /*nargs*/); -duk_def_prop(ctx, - obj_idx, - DUK_DEFPROP_HAVE_GETTER | - DUK_DEFPROP_HAVE_SETTER | - DUK_DEFPROP_HAVE_CONFIGURABLE | /* clear */ - DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_ENUMERABLE); /* set */ - -/* Change the value of a non-configurable property by force. */ -duk_push_string(ctx, "my_nonconfigurable_prop"); -duk_push_value(ctx, 321); -duk_def_prop(ctx, - obj_idx, - DUK_DEFPROP_HAVE_VALUE | - DUK_DEFPROP_FORCE); - -=tags -property -sandbox -experimental - -=seealso - -=introduced -1.1.0 diff --git a/website/api/duk_def_prop.yaml b/website/api/duk_def_prop.yaml new file mode 100644 index 00000000..c11605ef --- /dev/null +++ b/website/api/duk_def_prop.yaml @@ -0,0 +1,141 @@ +name: duk_def_prop + +proto: | + void duk_def_prop(duk_context *ctx, duk_idx_t obj_index, duk_uint_t flags); + +stack: | + [ ... obj! ... key! ] -> [ ... obj! ... ] (if have no value, setter, getter) + [ ... obj! ... key! value! ] -> [ ... obj! ... ] (if have value) + [ ... obj! ... key! getter! ] -> [ ... obj! ... ] (if have getter, but no setter) + [ ... obj! ... key! setter! ] -> [ ... obj! ... ] (if have setter, but no getter) + [ ... obj! ... key! getter! setter! ] -> [ ... obj! ... ] (if have both getter and setter) + +summary: | +

Create or alter the attributes of property key of object at + obj_index, with semantics like + Object.defineProperty(). + When the requested change is not allowed (e.g. property is not configurable), a + TypeError is thrown. If the target is not an object (or the + index is invalid) an error is thrown.

+ +

The flags field provides "have" flags to indicate what property attributes + are changed (this models the partial property descriptors allowed by + Object.defineProperty()). Values for the writable, configurable, + and enumerable attributes are given in the flags field, while property value, + getter, and setter are given as value stack arguments. When creating a new + property, missing attribute values cause + Ecmascript defaults + to be used (false for all boolean attributes, undefined for value, getter, setter); + when modifying an existing property missing attribute values mean that existing + attribute values are not touched.

+ +

With the DUK_DEFPROP_FORCE flag property changes can be forced + even when an operation would normally fail due to a non-extensible target object + or a non-configurable property. This cannot be done from Ecmascript code with + Object.defineProperty() and is useful for e.g. sandboxing setup. + In some cases even a forced change is not possible and will cause an error to be + thrown. For instance, properties implemented internally as virtual properties + (such as string "length" and index properties) cannot be modified because they + don't have concrete internal storage and thus no way of recording changes.

+ +

Some examples (see further examples below):

+
    +
  • To set the writable attribute, set flags to + DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE.
    • +
  • To clear the writable attribute, set flags to + DUK_DEFPROP_HAVE_WRITABLE.
    • +
  • To set value, clear writable, and set enumerable, set flags to + DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_ENUMERABLE + and provide the property value as a stack argument.
    • +
  • To forcibly set the value of a non-configurable property, set flags to + DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_FORCE and provide the + new property value as a stack argument.
    • +
+ +

This API call is useful for various things:

+
    +
  • To create properties with non-default attributes directly from C code.
    • +
  • To create accessor (getter/setter) properties directly from C code.
    • +
  • To modify the property attributes of existing properties directly from C code.
    • +
+ +

See API testcase + test-def-prop.c + for more examples.

+ +example: | + duk_idx_t obj_idx = /* ... */; + + /* Create an ordinary property which is writable and configurable, but + * not enumerable. + */ + + duk_push_string(ctx, "my_prop_1"); + duk_push_int(ctx, 123); /* prop value */ + duk_def_prop(ctx, + obj_idx, + DUK_DEFPROP_HAVE_VALUE | + DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE | + DUK_DEFPROP_HAVE_ENUMERABLE | 0 | + DUK_DEFPROP_HAVE_CONFIGURABLE | DUK_DEFPROP_CONFIGURABLE); + + /* Change the property value and make it non-writable. Don't touch other + * attributes. + */ + + duk_push_string(ctx, "my_prop_1"); + duk_push_int(ctx, 321); + duk_def_prop(ctx, + obj_idx, + DUK_DEFPROP_HAVE_VALUE | + DUK_DEFPROP_HAVE_WRITABLE | 0); + + /* Make the property non-configurable, don't touch value or other attributes. */ + + duk_push_string(ctx, "my_prop_1"); + duk_def_prop(ctx, + obj_idx, + DUK_DEFPROP_HAVE_CONFIGURABLE | 0); + + /* Create an accessor property which is non-configurable and non-enumerable. + * Attribute flags are not given so they default to Ecmascript defaults + * (false) automatically. + */ + + duk_push_string(ctx, "my_accessor_1"); + duk_push_c_function(ctx, my_getter, 0 /*nargs*/); + duk_push_c_function(ctx, my_setter, 1 /*nargs*/); + duk_def_prop(ctx, + obj_idx, + DUK_DEFPROP_HAVE_GETTER | + DUK_DEFPROP_HAVE_SETTER); + + /* Create an accessor property which is non-configurable but enumerable. + * Attribute flags are given explicitly which is easier to read without + * knowing about Ecmascript attribute default values. + */ + + duk_push_string(ctx, "my_accessor_2"); + duk_push_c_function(ctx, my_getter, 0 /*nargs*/); + duk_push_c_function(ctx, my_setter, 1 /*nargs*/); + duk_def_prop(ctx, + obj_idx, + DUK_DEFPROP_HAVE_GETTER | + DUK_DEFPROP_HAVE_SETTER | + DUK_DEFPROP_HAVE_CONFIGURABLE | /* clear */ + DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_ENUMERABLE); /* set */ + + /* Change the value of a non-configurable property by force. */ + duk_push_string(ctx, "my_nonconfigurable_prop"); + duk_push_value(ctx, 321); + duk_def_prop(ctx, + obj_idx, + DUK_DEFPROP_HAVE_VALUE | + DUK_DEFPROP_FORCE); + +tags: + - property + - sandbox + - experimental + +introduced: 1.1.0 diff --git a/website/api/duk_del_prop.txt b/website/api/duk_del_prop.txt deleted file mode 100644 index 5904a9e1..00000000 --- a/website/api/duk_del_prop.txt +++ /dev/null @@ -1,71 +0,0 @@ -=proto -duk_bool_t duk_del_prop(duk_context *ctx, duk_idx_t obj_index); - -=stack -[ ... obj! ... key! ] -> [ ... obj! ... ] - -=summary -

Delete the property key of a value at obj_index. -key is removed from the stack. Return code and error throwing -behavior:

-
    -
  • If property exists and is configurable (deletable), deletes the - property and returns 1.
    • -
  • If property exists but is not configurable, throws an error - (strict mode semantics).
    • -
  • If property does not exist, returns 1 (not 0).
    • -
  • If the value at obj_index is not - object coercible, - throws an error.
    • -
  • If obj_index is invalid, throws an error.
    • -
- -

The property deletion is equivalent to the Ecmascript expression:

-
-delete obj[key]
-
- -

For semantics, see -Property Accessors, -The delete operator -and [[Delete]] (P, Throw). -The return value and error throwing behavior mirrors the Ecmascript -delete operator behavior. -Both the target value and the key are coerced:

-
    -
  • The target value is automatically coerced to an object. However, this - object is a temporary one, so deleting its properties is not very useful.
    • -
  • The key argument is internally coerced to a string. There is - an internal fast path for arrays and numeric indices which avoids an - explicit string coercion, so use a numeric key when applicable.

    -
- -
-This API call returns 1 when the target property does not exist. -This is not very intuitive, but follows Ecmascript semantics: -delete obj.nonexistent also evaluates to true. -
- -

If the key is a fixed string you can avoid one API call and use the -duk_del_prop_string() variant. -Similarly, if the key is an array index, you can use the -duk_del_prop_index() variant.

- -
- -=example -duk_bool_t rc; - -duk_push_string(ctx, "myProperty"); -rc = duk_del_prop(ctx, -3); -printf("delete obj.myProperty -> rc=%d\n", (int) rc); - -=tags -property - -=seealso -duk_del_prop_string -duk_del_prop_index - -=introduced -1.0.0 diff --git a/website/api/duk_del_prop.yaml b/website/api/duk_del_prop.yaml new file mode 100644 index 00000000..b952901f --- /dev/null +++ b/website/api/duk_del_prop.yaml @@ -0,0 +1,72 @@ +name: duk_del_prop + +proto: | + duk_bool_t duk_del_prop(duk_context *ctx, duk_idx_t obj_index); + +stack: | + [ ... obj! ... key! ] -> [ ... obj! ... ] + +summary: | +

Delete the property key of a value at obj_index. + key is removed from the stack. Return code and error throwing + behavior:

+
    +
  • If property exists and is configurable (deletable), deletes the + property and returns 1.
    • +
  • If property exists but is not configurable, throws an error + (strict mode semantics).
    • +
  • If property does not exist, returns 1 (not 0).
    • +
  • If the value at obj_index is not + object coercible, + throws an error.
    • +
  • If obj_index is invalid, throws an error.
    • +
+ +

The property deletion is equivalent to the Ecmascript expression:

+ 
+  delete obj[key]
+
+ +

For semantics, see + Property Accessors, + The delete operator + and [[Delete]] (P, Throw). + The return value and error throwing behavior mirrors the Ecmascript + delete operator behavior. + Both the target value and the key are coerced:

+
    +
  • The target value is automatically coerced to an object. However, this + object is a temporary one, so deleting its properties is not very useful.
    • +
  • The key argument is internally coerced to a string. There is + an internal fast path for arrays and numeric indices which avoids an + explicit string coercion, so use a numeric key when applicable.

    +
+ +
+ This API call returns 1 when the target property does not exist. + This is not very intuitive, but follows Ecmascript semantics: + delete obj.nonexistent also evaluates to true. +
+ +

If the key is a fixed string you can avoid one API call and use the + duk_del_prop_string() variant. + Similarly, if the key is an array index, you can use the + duk_del_prop_index() variant.

+ +
+ +example: | + duk_bool_t rc; + + duk_push_string(ctx, "myProperty"); + rc = duk_del_prop(ctx, -3); + printf("delete obj.myProperty -> rc=%d\n", (int) rc); + +tags: + - property + +seealso: + - duk_del_prop_string + - duk_del_prop_index + +introduced: 1.0.0 diff --git a/website/api/duk_del_prop_index.txt b/website/api/duk_del_prop_index.txt deleted file mode 100644 index efb25411..00000000 --- a/website/api/duk_del_prop_index.txt +++ /dev/null @@ -1,28 +0,0 @@ -=proto -duk_bool_t duk_del_prop_index(duk_context *ctx, duk_idx_t obj_index, duk_uarridx_t arr_index); - -=stack -[ ... obj! ... ] -> [ ... obj! ... ] - -=summary -

Like duk_del_prop(), -but the property name is given as an unsigned integer -arr_index. This is especially useful for deleting -array elements (but is not limited to that).

- -

Conceptually the number is coerced to a string for the -property deletion, e.g. 123 would be equivalent to a property -name "123". Duktape avoids an explicit coercion whenever -possible.

- -=example -duk_bool_t rc; - -rc = duk_del_prop_index(ctx, -3, 123); -printf("delete obj[123] -> rc=%d\n", (int) rc); - -=tags -property - -=introduced -1.0.0 diff --git a/website/api/duk_del_prop_index.yaml b/website/api/duk_del_prop_index.yaml new file mode 100644 index 00000000..a501e42f --- /dev/null +++ b/website/api/duk_del_prop_index.yaml @@ -0,0 +1,29 @@ +name: duk_del_prop_index + +proto: | + duk_bool_t duk_del_prop_index(duk_context *ctx, duk_idx_t obj_index, duk_uarridx_t arr_index); + +stack: | + [ ... obj! ... ] -> [ ... obj! ... ] + +summary: | +

Like duk_del_prop(), + but the property name is given as an unsigned integer + arr_index. This is especially useful for deleting + array elements (but is not limited to that).

+ +

Conceptually the number is coerced to a string for the + property deletion, e.g. 123 would be equivalent to a property + name "123". Duktape avoids an explicit coercion whenever + possible.

+ +example: | + duk_bool_t rc; + + rc = duk_del_prop_index(ctx, -3, 123); + printf("delete obj[123] -> rc=%d\n", (int) rc); + +tags: + - property + +introduced: 1.0.0 diff --git a/website/api/duk_del_prop_string.txt b/website/api/duk_del_prop_string.txt deleted file mode 100644 index 8b002b36..00000000 --- a/website/api/duk_del_prop_string.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_bool_t duk_del_prop_string(duk_context *ctx, duk_idx_t obj_index, const char *key); - -=stack -[ ... obj! ... ] -> [ ... obj! ... ] - -=summary -

Like duk_del_prop(), -but the property name is given as a NUL-terminated C string -key.

- -=example -duk_bool_t rc; - -rc = duk_del_prop_string(ctx, -3, "propertyName"); -printf("delete obj.propertyName -> rc=%d\n", (int) rc); - -=tags -property - -=introduced -1.0.0 diff --git a/website/api/duk_del_prop_string.yaml b/website/api/duk_del_prop_string.yaml new file mode 100644 index 00000000..8c6782c7 --- /dev/null +++ b/website/api/duk_del_prop_string.yaml @@ -0,0 +1,23 @@ +name: duk_del_prop_string + +proto: | + duk_bool_t duk_del_prop_string(duk_context *ctx, duk_idx_t obj_index, const char *key); + +stack: | + [ ... obj! ... ] -> [ ... obj! ... ] + +summary: | +

Like duk_del_prop(), + but the property name is given as a NUL-terminated C string + key.

+ +example: | + duk_bool_t rc; + + rc = duk_del_prop_string(ctx, -3, "propertyName"); + printf("delete obj.propertyName -> rc=%d\n", (int) rc); + +tags: + - property + +introduced: 1.0.0 diff --git a/website/api/duk_del_var.txt b/website/api/duk_del_var.txt deleted file mode 100644 index d533bba8..00000000 --- a/website/api/duk_del_var.txt +++ /dev/null @@ -1,29 +0,0 @@ -=proto -duk_bool_t duk_del_var(duk_context *ctx); - -=stack -[ ... varname! ] -> [ ... ] - -=summary -XXX - -

The identifier deletion is equivalent to the Ecmascript expression:

-
-delete varname
-
- -
-Attempt to delete an identifier is compile time SyntaxError in strict mode -code. Because Duktape/C functions run in strict mode, the semantics for this -call are currently not very useful when called from inside a Duktape/C function. -
- -=example -XXX - -=tags -variable -omit - -=introduced -1.0.0 diff --git a/website/api/duk_del_var.yaml b/website/api/duk_del_var.yaml new file mode 100644 index 00000000..e568f17e --- /dev/null +++ b/website/api/duk_del_var.yaml @@ -0,0 +1,30 @@ +name: duk_del_var + +proto: | + duk_bool_t duk_del_var(duk_context *ctx); + +stack: | + [ ... varname! ] -> [ ... ] + +summary: | + XXX + +

The identifier deletion is equivalent to the Ecmascript expression:

+ 
+  delete varname
+
+ +
+ Attempt to delete an identifier is compile time SyntaxError in strict mode + code. Because Duktape/C functions run in strict mode, the semantics for this + call are currently not very useful when called from inside a Duktape/C function. +
+ +example: | + XXX + +tags: + - variable + - omit + +introduced: 1.0.0 diff --git a/website/api/duk_destroy_heap.txt b/website/api/duk_destroy_heap.txt deleted file mode 100644 index 9e36142e..00000000 --- a/website/api/duk_destroy_heap.txt +++ /dev/null @@ -1,19 +0,0 @@ -=proto -void duk_destroy_heap(duk_context *ctx); - -=summary -

Destroy a Duktape heap. The argument context can be any context linked -to the heap. All resources related to the heap are freed and must not be -referenced after the call completes. These resources include all contexts -linked to the heap, and also all string and buffer pointers within the heap.

- -

If ctx is NULL, the call is a no-op.

- -=example -duk_destroy_heap(ctx); - -=tags -heap - -=introduced -1.0.0 diff --git a/website/api/duk_destroy_heap.yaml b/website/api/duk_destroy_heap.yaml new file mode 100644 index 00000000..9cfe7834 --- /dev/null +++ b/website/api/duk_destroy_heap.yaml @@ -0,0 +1,20 @@ +name: duk_destroy_heap + +proto: | + void duk_destroy_heap(duk_context *ctx); + +summary: | +

Destroy a Duktape heap. The argument context can be any context linked + to the heap. All resources related to the heap are freed and must not be + referenced after the call completes. These resources include all contexts + linked to the heap, and also all string and buffer pointers within the heap.

+ +

If ctx is NULL, the call is a no-op.

+ +example: | + duk_destroy_heap(ctx); + +tags: + - heap + +introduced: 1.0.0 diff --git a/website/api/duk_dump_context_stderr.txt b/website/api/duk_dump_context_stderr.txt deleted file mode 100644 index 55791c79..00000000 --- a/website/api/duk_dump_context_stderr.txt +++ /dev/null @@ -1,27 +0,0 @@ -=proto -void duk_dump_context_stderr(duk_context *ctx); - -=stack -[ ... ] -> [ ... ] - -=summary -

Like duk_push_context_dump() but -the context dump is written to stderr and nothing is left on -the value stack.

- -

If file I/O has been disabled, this call is a NOP.

- -
- -=example -duk_push_int(ctx, 123); -duk_push_string(ctx, "foo"); -duk_dump_context_stderr(ctx); - -=tags -stack -debug -nonportable - -=introduced -1.0.0 diff --git a/website/api/duk_dump_context_stderr.yaml b/website/api/duk_dump_context_stderr.yaml new file mode 100644 index 00000000..80a438ab --- /dev/null +++ b/website/api/duk_dump_context_stderr.yaml @@ -0,0 +1,28 @@ +name: duk_dump_context_stderr + +proto: | + void duk_dump_context_stderr(duk_context *ctx); + +stack: | + [ ... ] -> [ ... ] + +summary: | +

Like duk_push_context_dump() but + the context dump is written to stderr and nothing is left on + the value stack.

+ +

If file I/O has been disabled, this call is a NOP.

+ +
+ +example: | + duk_push_int(ctx, 123); + duk_push_string(ctx, "foo"); + duk_dump_context_stderr(ctx); + +tags: + - stack + - debug + - nonportable + +introduced: 1.0.0 diff --git a/website/api/duk_dump_context_stdout.txt b/website/api/duk_dump_context_stdout.txt deleted file mode 100644 index 845f6a4e..00000000 --- a/website/api/duk_dump_context_stdout.txt +++ /dev/null @@ -1,27 +0,0 @@ -=proto -void duk_dump_context_stdout(duk_context *ctx); - -=stack -[ ... ] -> [ ... ] - -=summary -

Like duk_push_context_dump() but -the context dump is written to stdout and nothing is left on -the value stack.

- -

If file I/O has been disabled, this call is a NOP.

- -
- -=example -duk_push_int(ctx, 123); -duk_push_string(ctx, "foo"); -duk_dump_context_stdout(ctx); - -=tags -stack -debug -nonportable - -=introduced -1.0.0 diff --git a/website/api/duk_dump_context_stdout.yaml b/website/api/duk_dump_context_stdout.yaml new file mode 100644 index 00000000..74c72af3 --- /dev/null +++ b/website/api/duk_dump_context_stdout.yaml @@ -0,0 +1,28 @@ +name: duk_dump_context_stdout + +proto: | + void duk_dump_context_stdout(duk_context *ctx); + +stack: | + [ ... ] -> [ ... ] + +summary: | +

Like duk_push_context_dump() but + the context dump is written to stdout and nothing is left on + the value stack.

+ +

If file I/O has been disabled, this call is a NOP.

+ +
+ +example: | + duk_push_int(ctx, 123); + duk_push_string(ctx, "foo"); + duk_dump_context_stdout(ctx); + +tags: + - stack + - debug + - nonportable + +introduced: 1.0.0 diff --git a/website/api/duk_dup.txt b/website/api/duk_dup.txt deleted file mode 100644 index 220673d2..00000000 --- a/website/api/duk_dup.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -void duk_dup(duk_context *ctx, duk_idx_t from_index); - -=stack -[ ... val! ... ] -> [ ... val! ... val! ] - -=summary -

Push a duplicate of value at from_index to the stack. -If from_index is invalid, throws an error.

- -=example -duk_push_int(ctx, 123); /* -> [ ... 123 ] */ -duk_push_int(ctx, 234); /* -> [ ... 123 234 ] */ -duk_dup(ctx, -2); /* -> [ ... 123 234 123 ] */ - -=tags -stack - -=seealso -duk_dup_top - -=introduced -1.0.0 diff --git a/website/api/duk_dup.yaml b/website/api/duk_dup.yaml new file mode 100644 index 00000000..15b2969b --- /dev/null +++ b/website/api/duk_dup.yaml @@ -0,0 +1,24 @@ +name: duk_dup + +proto: | + void duk_dup(duk_context *ctx, duk_idx_t from_index); + +stack: | + [ ... val! ... ] -> [ ... val! ... val! ] + +summary: | +

Push a duplicate of value at from_index to the stack. + If from_index is invalid, throws an error.

+ +example: | + duk_push_int(ctx, 123); /* -> [ ... 123 ] */ + duk_push_int(ctx, 234); /* -> [ ... 123 234 ] */ + duk_dup(ctx, -2); /* -> [ ... 123 234 123 ] */ + +tags: + - stack + +seealso: + - duk_dup_top + +introduced: 1.0.0 diff --git a/website/api/duk_dup_top.txt b/website/api/duk_dup_top.txt deleted file mode 100644 index 04fe93ef..00000000 --- a/website/api/duk_dup_top.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -void duk_dup_top(duk_context *ctx); - -=stack -[ ... val! ] -> [ ... val! val! ] - -=summary -

Push a duplicate of the value at stack top to the stack. -If the value stack is empty, throws an error.

- -

Equivalent to calling -duk_dup(ctx, -1).

- -=example -duk_push_int(ctx, 123); /* -> [ ... 123 ] */ -duk_push_int(ctx, 234); /* -> [ ... 123 234 ] */ -duk_dup_top(ctx); /* -> [ ... 123 234 234 ] */ - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_dup_top.yaml b/website/api/duk_dup_top.yaml new file mode 100644 index 00000000..417a682f --- /dev/null +++ b/website/api/duk_dup_top.yaml @@ -0,0 +1,24 @@ +name: duk_dup_top + +proto: | + void duk_dup_top(duk_context *ctx); + +stack: | + [ ... val! ] -> [ ... val! val! ] + +summary: | +

Push a duplicate of the value at stack top to the stack. + If the value stack is empty, throws an error.

+ +

Equivalent to calling + duk_dup(ctx, -1).

+ +example: | + duk_push_int(ctx, 123); /* -> [ ... 123 ] */ + duk_push_int(ctx, 234); /* -> [ ... 123 234 ] */ + duk_dup_top(ctx); /* -> [ ... 123 234 234 ] */ + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_enum.txt b/website/api/duk_enum.txt deleted file mode 100644 index 23480f51..00000000 --- a/website/api/duk_enum.txt +++ /dev/null @@ -1,70 +0,0 @@ -=proto -void duk_enum(duk_context *ctx, duk_idx_t obj_index, duk_uint_t enum_flags); - -=stack -[ ... obj! ... ] -> [ ... obj! ... enum! ] - -=summary -

Create an enumerator for object at obj_index. Enumeration -details can be controlled with enum_flags. If the target value -is not an object, throws an error.

- -

Enumeration flags:

-
    -
  • DUK_ENUM_INCLUDE_NONENUMERABLE: enumerate also non-enumerable - properties (by default only enumerable properties are enumerated)
    • -
  • DUK_ENUM_INCLUDE_INTERNAL: enumerate also internal properties - (by default internal properties are not enumerated)
    • -
  • DUK_ENUM_OWN_PROPERTIES_ONLY: enumerate only an object's "own" - properties (by default also inherited properties are enumerated)
    • -
  • DUK_ENUM_ARRAY_INDICES_ONLY: enumerate only array indices, - i.e. property names of the form "0", "1", "2", etc.
    • -
  • DUK_ENUM_SORT_ARRAY_INDICES: guarantee that array indices are - sorted by their numeric value, only use with DUK_ENUM_ARRAY_INDICES_ONLY; - this is quite slow
    • -
- -

Without any flags, enumeration follows the Ecmascript default enumeration -semantics, as in the expression:

-
-for (key in obj) {
-    print(key, obj[i]);
-}
-
- -

Once the enumerator has been created, use -duk_next() to extract keys (or key/value -pairs) from the enumerator.

- -
-Array indices are usually enumerated in a sorted order even without the -DUK_ENUM_SORT_ARRAY_INDICES flag. This is not the case -for "sparse arrays" which contain a lot of gaps (unused indices). -Duktape represents such arrays internally using a key-value representation -instead of a plain array, which affects key enumeration order. -The criteria for switching from a dense to a sparse array are internal details -and potentially version dependent. With the DUK_ENUM_SORT_ARRAY_INDICES -flag the array indices will be sorted even for sparse arrays, at the -cost of an explicit key sorting pass. -
- -=example -duk_enum(ctx, -3, DUK_ENUM_INCLUDE_NONENUMERABLE); - -while (duk_next(ctx, -1 /*enum_index*/, 0 /*get_value*/)) { - /* [ ... enum key ] */ - printf("-> key %s\n", duk_get_string(ctx, -1)); - duk_pop(ctx); /* pop_key */ -} - -duk_pop(ctx); /* pop enum object */ - -=tags -object -property - -=seealso -duk_next - -=introduced -1.0.0 diff --git a/website/api/duk_enum.yaml b/website/api/duk_enum.yaml new file mode 100644 index 00000000..7b35390c --- /dev/null +++ b/website/api/duk_enum.yaml @@ -0,0 +1,71 @@ +name: duk_enum + +proto: | + void duk_enum(duk_context *ctx, duk_idx_t obj_index, duk_uint_t enum_flags); + +stack: | + [ ... obj! ... ] -> [ ... obj! ... enum! ] + +summary: | +

Create an enumerator for object at obj_index. Enumeration + details can be controlled with enum_flags. If the target value + is not an object, throws an error.

+ +

Enumeration flags:

+
    +
  • DUK_ENUM_INCLUDE_NONENUMERABLE: enumerate also non-enumerable + properties (by default only enumerable properties are enumerated)
    • +
  • DUK_ENUM_INCLUDE_INTERNAL: enumerate also internal properties + (by default internal properties are not enumerated)
    • +
  • DUK_ENUM_OWN_PROPERTIES_ONLY: enumerate only an object's "own" + properties (by default also inherited properties are enumerated)
    • +
  • DUK_ENUM_ARRAY_INDICES_ONLY: enumerate only array indices, + i.e. property names of the form "0", "1", "2", etc.
    • +
  • DUK_ENUM_SORT_ARRAY_INDICES: guarantee that array indices are + sorted by their numeric value, only use with DUK_ENUM_ARRAY_INDICES_ONLY; + this is quite slow
    • +
+ +

Without any flags, enumeration follows the Ecmascript default enumeration + semantics, as in the expression:

+ 
+  for (key in obj) {
+      print(key, obj[i]);
+  }
+
+ +

Once the enumerator has been created, use + duk_next() to extract keys (or key/value + pairs) from the enumerator.

+ +
+ Array indices are usually enumerated in a sorted order even without the + DUK_ENUM_SORT_ARRAY_INDICES flag. This is not the case + for "sparse arrays" which contain a lot of gaps (unused indices). + Duktape represents such arrays internally using a key-value representation + instead of a plain array, which affects key enumeration order. + The criteria for switching from a dense to a sparse array are internal details + and potentially version dependent. With the DUK_ENUM_SORT_ARRAY_INDICES + flag the array indices will be sorted even for sparse arrays, at the + cost of an explicit key sorting pass. +
+ +example: | + duk_enum(ctx, -3, DUK_ENUM_INCLUDE_NONENUMERABLE); + + while (duk_next(ctx, -1 /*enum_index*/, 0 /*get_value*/)) { + /* [ ... enum key ] */ + printf("-> key %s\n", duk_get_string(ctx, -1)); + duk_pop(ctx); /* pop_key */ + } + + duk_pop(ctx); /* pop enum object */ + +tags: + - object + - property + +seealso: + - duk_next + +introduced: 1.0.0 diff --git a/website/api/duk_equals.txt b/website/api/duk_equals.txt deleted file mode 100644 index 2b328364..00000000 --- a/website/api/duk_equals.txt +++ /dev/null @@ -1,36 +0,0 @@ -=proto -duk_bool_t duk_equals(duk_context *ctx, duk_idx_t index1, duk_idx_t index2); - -=stack -[ ... val1! ... val2! ... ] - -=summary -

Compare values at index1 and index2 for equality. -Returns 1 if values are considered equal using Ecmascript -Equals -operator (==) semantics, otherwise returns 0. Also returns 0 if either -index is invalid.

- -

Because -The Abstract Equality Comparison Algorithm -used by the Equals operator performs value coercion (ToNumber() and ToPrimitive()), -the comparison may have side effects and may throw an error. The strict equality comparison, -available through duk_strict_equals(), has no -side effects.

- -

Comparison algorithm for Duktape custom types is described in -Equality (non-strict).

- -=example -if (duk_equals(ctx, -3, -7)) { - printf("values at indices -3 and -7 are equal\n"); -} - -=tags -compare - -=seealso -duk_strict_equals - -=introduced -1.0.0 diff --git a/website/api/duk_equals.yaml b/website/api/duk_equals.yaml new file mode 100644 index 00000000..c7da0c10 --- /dev/null +++ b/website/api/duk_equals.yaml @@ -0,0 +1,37 @@ +name: duk_equals + +proto: | + duk_bool_t duk_equals(duk_context *ctx, duk_idx_t index1, duk_idx_t index2); + +stack: | + [ ... val1! ... val2! ... ] + +summary: | +

Compare values at index1 and index2 for equality. + Returns 1 if values are considered equal using Ecmascript + Equals + operator (==) semantics, otherwise returns 0. Also returns 0 if either + index is invalid.

+ +

Because + The Abstract Equality Comparison Algorithm + used by the Equals operator performs value coercion (ToNumber() and ToPrimitive()), + the comparison may have side effects and may throw an error. The strict equality comparison, + available through duk_strict_equals(), has no + side effects.

+ +

Comparison algorithm for Duktape custom types is described in + Equality (non-strict).

+ +example: | + if (duk_equals(ctx, -3, -7)) { + printf("values at indices -3 and -7 are equal\n"); + } + +tags: + - compare + +seealso: + - duk_strict_equals + +introduced: 1.0.0 diff --git a/website/api/duk_error.txt b/website/api/duk_error.txt deleted file mode 100644 index 27e8c0a1..00000000 --- a/website/api/duk_error.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -void duk_error(duk_context *ctx, duk_errcode_t err_code, const char *fmt, ...); - -=stack -[ ... ] -> [ ... err! ] - -=summary -

Push a new Error object to the stack and throw it. -This call never returns.

- -

The message property of the error object will be set to a sprintf-formatted -string using fmt and the remaining arguments. The internal prototype for the created -error object is chosen based on err_code. For instance, DUK_ERR_RANGE_ERROR -causes the built-in RangeError prototype to be used. The valid range for user error codes -is [1,16777215].

- -

To push an Error object to the stack without throwing it, use -duk_push_error_object(). -

- -=example -duk_error(ctx, DUK_ERR_RANGE_ERROR, "argument out of range: %d", (int) argval); - -=tags -error - -=seealso -duk_error_va -duk_throw -duk_push_error_object - -=introduced -1.0.0 diff --git a/website/api/duk_error.yaml b/website/api/duk_error.yaml new file mode 100644 index 00000000..bef2abbe --- /dev/null +++ b/website/api/duk_error.yaml @@ -0,0 +1,34 @@ +name: duk_error + +proto: | + void duk_error(duk_context *ctx, duk_errcode_t err_code, const char *fmt, ...); + +stack: | + [ ... ] -> [ ... err! ] + +summary: | +

Push a new Error object to the stack and throw it. + This call never returns.

+ +

The message property of the error object will be set to a sprintf-formatted + string using fmt and the remaining arguments. The internal prototype for the created + error object is chosen based on err_code. For instance, DUK_ERR_RANGE_ERROR + causes the built-in RangeError prototype to be used. The valid range for user error codes + is [1,16777215].

+ +

To push an Error object to the stack without throwing it, use + duk_push_error_object(). +

+ +example: | + duk_error(ctx, DUK_ERR_RANGE_ERROR, "argument out of range: %d", (int) argval); + +tags: + - error + +seealso: + - duk_error_va + - duk_throw + - duk_push_error_object + +introduced: 1.0.0 diff --git a/website/api/duk_error_va.txt b/website/api/duk_error_va.txt deleted file mode 100644 index b5a3aad9..00000000 --- a/website/api/duk_error_va.txt +++ /dev/null @@ -1,30 +0,0 @@ -=proto -void duk_error_va(duk_context *ctx, duk_errcode_t err_code, const char *fmt, va_list ap); - -=stack -[ ... ] -> [ ... err! ] - -=summary -

Vararg variant of -duk_error().

- -=example -void my_range_error(duk_context *ctx, const char *fmt, ...) { - va_list ap; - - va_start(ap, fmt); - duk_error_va(ctx, DUK_ERR_RANGE_ERROR, fmt, ap); - va_end(ap); -} - -=tags -error -vararg - -=seealso -duk_error -duk_throw -duk_push_error_object - -=introduced -1.1.0 diff --git a/website/api/duk_error_va.yaml b/website/api/duk_error_va.yaml new file mode 100644 index 00000000..2bc51566 --- /dev/null +++ b/website/api/duk_error_va.yaml @@ -0,0 +1,31 @@ +name: duk_error_va + +proto: | + void duk_error_va(duk_context *ctx, duk_errcode_t err_code, const char *fmt, va_list ap); + +stack: | + [ ... ] -> [ ... err! ] + +summary: | +

Vararg variant of + duk_error().

+ +example: | + void my_range_error(duk_context *ctx, const char *fmt, ...) { + va_list ap; + + va_start(ap, fmt); + duk_error_va(ctx, DUK_ERR_RANGE_ERROR, fmt, ap); + va_end(ap); + } + +tags: + - error + - vararg + +seealso: + - duk_error + - duk_throw + - duk_push_error_object + +introduced: 1.1.0 diff --git a/website/api/duk_eval.txt b/website/api/duk_eval.txt deleted file mode 100644 index 613b8922..00000000 --- a/website/api/duk_eval.txt +++ /dev/null @@ -1,55 +0,0 @@ -=proto -void duk_eval(duk_context *ctx); - -=stack -[ ... source! ] -> [ ... result! ] - -=summary -

Evaluate the Ecmascript source code at the top of the stack, and leave a single -return value on top of the stack. May throw an error, errors are not caught -automatically. The filename associated with the temporary eval function is -automatically provided from the __FILE__ preprocessor define -of the caller.

- -

This is essentially a shortcut for:

-
-duk_push_string(ctx, __FILE__);
-duk_compile(ctx, DUK_COMPILE_EVAL);  /* [ ... source filename ] -> [ function ] */
-duk_call(ctx, 0);
-
- -

The source code is evaluated in non-strict mode unless it contains an -explicit "use strict" directive. In particular, strictness -of the current context is not transferred into the eval code. This avoids -confusing behavior where eval strictness would depend on whether eval is -used inside a Duktape/C function call (strict mode) or outside of one -(non-strict mode).

- -

If the eval input is a fixed string, you can also use -duk_eval_string().

- -=example -/* Eval result in Ecmascript is the last non-empty statement; here, the - * result of the eval is the number 123. - */ - -duk_push_string(ctx, "print('Hello world!'); 123;"); -duk_eval(ctx); -printf("return value is: %lf\n", (double) duk_get_number(ctx, -1)); -duk_pop(ctx); - -=tags -compile - -=seealso -duk_peval -duk_eval_noresult -duk_eval_string -duk_eval_string_noresult -duk_eval_lstring -duk_eval_lstring_noresult -duk_eval_file -duk_eval_file_noresult - -=introduced -1.0.0 diff --git a/website/api/duk_eval.yaml b/website/api/duk_eval.yaml new file mode 100644 index 00000000..97c05fbb --- /dev/null +++ b/website/api/duk_eval.yaml @@ -0,0 +1,56 @@ +name: duk_eval + +proto: | + void duk_eval(duk_context *ctx); + +stack: | + [ ... source! ] -> [ ... result! ] + +summary: | +

Evaluate the Ecmascript source code at the top of the stack, and leave a single + return value on top of the stack. May throw an error, errors are not caught + automatically. The filename associated with the temporary eval function is + automatically provided from the __FILE__ preprocessor define + of the caller.

+ +

This is essentially a shortcut for:

+ 
+  duk_push_string(ctx, __FILE__);
+  duk_compile(ctx, DUK_COMPILE_EVAL);  /* [ ... source filename ] -> [ function ] */
+  duk_call(ctx, 0);
+
+ +

The source code is evaluated in non-strict mode unless it contains an + explicit "use strict" directive. In particular, strictness + of the current context is not transferred into the eval code. This avoids + confusing behavior where eval strictness would depend on whether eval is + used inside a Duktape/C function call (strict mode) or outside of one + (non-strict mode).

+ +

If the eval input is a fixed string, you can also use + duk_eval_string().

+ +example: | + /* Eval result in Ecmascript is the last non-empty statement; here, the + * result of the eval is the number 123. + */ + + duk_push_string(ctx, "print('Hello world!'); 123;"); + duk_eval(ctx); + printf("return value is: %lf\n", (double) duk_get_number(ctx, -1)); + duk_pop(ctx); + +tags: + - compile + +seealso: + - duk_peval + - duk_eval_noresult + - duk_eval_string + - duk_eval_string_noresult + - duk_eval_lstring + - duk_eval_lstring_noresult + - duk_eval_file + - duk_eval_file_noresult + +introduced: 1.0.0 diff --git a/website/api/duk_eval_file.txt b/website/api/duk_eval_file.txt deleted file mode 100644 index be9d7b37..00000000 --- a/website/api/duk_eval_file.txt +++ /dev/null @@ -1,28 +0,0 @@ -=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. The filename associated with the temporary -function created for the eval code is path as is.

- -
- -=example -duk_eval_file(ctx, "test.js"); -printf("result is: %s\n", duk_safe_to_string(ctx, -1)); -duk_pop(ctx); - -=tags -compile -nonportable - -=seealso -duk_eval_file_noresult - -=introduced -1.0.0 diff --git a/website/api/duk_eval_file.yaml b/website/api/duk_eval_file.yaml new file mode 100644 index 00000000..3f56e100 --- /dev/null +++ b/website/api/duk_eval_file.yaml @@ -0,0 +1,29 @@ +name: duk_eval_file + +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. The filename associated with the temporary + function created for the eval code is path as is.

+ +
+ +example: | + duk_eval_file(ctx, "test.js"); + printf("result is: %s\n", duk_safe_to_string(ctx, -1)); + duk_pop(ctx); + +tags: + - compile + - nonportable + +seealso: + - duk_eval_file_noresult + +introduced: 1.0.0 diff --git a/website/api/duk_eval_file_noresult.txt b/website/api/duk_eval_file_noresult.txt deleted file mode 100644 index 96fdd037..00000000 --- a/website/api/duk_eval_file_noresult.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -void duk_eval_file_noresult(duk_context *ctx, const char *path); - -=stack -[ ... ] -> [ ... ] - -=summary -

Like -duk_eval_file(), but leaves no -result on the value stack.

- -
- -=example -duk_eval_file_noresult(ctx, "test.js"); - -=tags -compile -nonportable - -=introduced -1.0.0 diff --git a/website/api/duk_eval_file_noresult.yaml b/website/api/duk_eval_file_noresult.yaml new file mode 100644 index 00000000..83210c23 --- /dev/null +++ b/website/api/duk_eval_file_noresult.yaml @@ -0,0 +1,23 @@ +name: duk_eval_file_noresult + +proto: | + void duk_eval_file_noresult(duk_context *ctx, const char *path); + +stack: | + [ ... ] -> [ ... ] + +summary: | +

Like + duk_eval_file(), but leaves no + result on the value stack.

+ +
+ +example: | + duk_eval_file_noresult(ctx, "test.js"); + +tags: + - compile + - nonportable + +introduced: 1.0.0 diff --git a/website/api/duk_eval_lstring.txt b/website/api/duk_eval_lstring.txt deleted file mode 100644 index 79ef18e6..00000000 --- a/website/api/duk_eval_lstring.txt +++ /dev/null @@ -1,31 +0,0 @@ -=proto -void duk_eval_lstring(duk_context *ctx, const char *src, duk_size_t len); - -=stack -[ ... ] -> [ ... result! ] - -=summary -

Like -duk_eval(), but the eval input -is given as a C string with explicit length. The filename associated with the -temporary is automatically provided from the __FILE__ preprocessor -define of the caller.

- -
- -=example -const char *src = /* ... */; -duk_size_t len = /* ... */; - -duk_eval_lstring(ctx, src, len); -printf("result is: %s\n", duk_get_string(ctx, -1)); -duk_pop(ctx); - -=tags -compile - -=seealso -duk_eval_lstring_noresult - -=introduced -1.0.0 diff --git a/website/api/duk_eval_lstring.yaml b/website/api/duk_eval_lstring.yaml new file mode 100644 index 00000000..fdeb6e70 --- /dev/null +++ b/website/api/duk_eval_lstring.yaml @@ -0,0 +1,32 @@ +name: duk_eval_lstring + +proto: | + void duk_eval_lstring(duk_context *ctx, const char *src, duk_size_t len); + +stack: | + [ ... ] -> [ ... result! ] + +summary: | +

Like + duk_eval(), but the eval input + is given as a C string with explicit length. The filename associated with the + temporary is automatically provided from the __FILE__ preprocessor + define of the caller.

+ +
+ +example: | + const char *src = /* ... */; + duk_size_t len = /* ... */; + + duk_eval_lstring(ctx, src, len); + printf("result is: %s\n", duk_get_string(ctx, -1)); + duk_pop(ctx); + +tags: + - compile + +seealso: + - duk_eval_lstring_noresult + +introduced: 1.0.0 diff --git a/website/api/duk_eval_lstring_noresult.txt b/website/api/duk_eval_lstring_noresult.txt deleted file mode 100644 index 522f3e44..00000000 --- a/website/api/duk_eval_lstring_noresult.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -void duk_eval_lstring_noresult(duk_context *ctx, const char *src, duk_size_t len); - -=stack -[ ... ] -> [ ... ] - -=summary -

Like -duk_eval_lstring(), but leaves no -result on the value stack.

- -
- -=example -const char *src = /* ... */; -duk_size_t len = /* ... */; - -duk_eval_lstring_noresult(ctx, src, len); - -=tags -compile - -=introduced -1.0.0 diff --git a/website/api/duk_eval_lstring_noresult.yaml b/website/api/duk_eval_lstring_noresult.yaml new file mode 100644 index 00000000..b5df21be --- /dev/null +++ b/website/api/duk_eval_lstring_noresult.yaml @@ -0,0 +1,25 @@ +name: duk_eval_lstring_noresult + +proto: | + void duk_eval_lstring_noresult(duk_context *ctx, const char *src, duk_size_t len); + +stack: | + [ ... ] -> [ ... ] + +summary: | +

Like + duk_eval_lstring(), but leaves no + result on the value stack.

+ +
+ +example: | + const char *src = /* ... */; + duk_size_t len = /* ... */; + + duk_eval_lstring_noresult(ctx, src, len); + +tags: + - compile + +introduced: 1.0.0 diff --git a/website/api/duk_eval_noresult.txt b/website/api/duk_eval_noresult.txt deleted file mode 100644 index 4547179a..00000000 --- a/website/api/duk_eval_noresult.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -void duk_eval_noresult(duk_context *ctx); - -=stack -[ ... source! ] -> [ ... ] - -=summary -

Like -duk_eval(), but leaves no result on -the value stack.

- -=example -duk_push_string(ctx, "print('Hello world!');"); -duk_eval_noresult(ctx); - -=tags -compile - -=seealso -duk_eval_string_noresult -duk_eval_lstring_noresult -duk_eval_file_noresult - -=introduced -1.0.0 diff --git a/website/api/duk_eval_noresult.yaml b/website/api/duk_eval_noresult.yaml new file mode 100644 index 00000000..6dbd5f8c --- /dev/null +++ b/website/api/duk_eval_noresult.yaml @@ -0,0 +1,26 @@ +name: duk_eval_noresult + +proto: | + void duk_eval_noresult(duk_context *ctx); + +stack: | + [ ... source! ] -> [ ... ] + +summary: | +

Like + duk_eval(), but leaves no result on + the value stack.

+ +example: | + duk_push_string(ctx, "print('Hello world!');"); + duk_eval_noresult(ctx); + +tags: + - compile + +seealso: + - duk_eval_string_noresult + - duk_eval_lstring_noresult + - duk_eval_file_noresult + +introduced: 1.0.0 diff --git a/website/api/duk_eval_string.txt b/website/api/duk_eval_string.txt deleted file mode 100644 index 52bbfedc..00000000 --- a/website/api/duk_eval_string.txt +++ /dev/null @@ -1,28 +0,0 @@ -=proto -void duk_eval_string(duk_context *ctx, const char *src); - -=stack -[ ... ] -> [ ... result! ] - -=summary -

Like -duk_eval(), but the eval input -is given as a C string. The filename associated with the temporary -is automatically provided from the __FILE__ preprocessor define -of the caller.

- -
- -=example -duk_eval_string(ctx, "'testString'.toUpperCase()"); -printf("result is: %s\n", duk_get_string(ctx, -1)); -duk_pop(ctx); - -=tags -compile - -=seealso -duk_eval_string_noresult - -=introduced -1.0.0 diff --git a/website/api/duk_eval_string.yaml b/website/api/duk_eval_string.yaml new file mode 100644 index 00000000..ecc2af9c --- /dev/null +++ b/website/api/duk_eval_string.yaml @@ -0,0 +1,29 @@ +name: duk_eval_string + +proto: | + void duk_eval_string(duk_context *ctx, const char *src); + +stack: | + [ ... ] -> [ ... result! ] + +summary: | +

Like + duk_eval(), but the eval input + is given as a C string. The filename associated with the temporary + is automatically provided from the __FILE__ preprocessor define + of the caller.

+ +
+ +example: | + duk_eval_string(ctx, "'testString'.toUpperCase()"); + printf("result is: %s\n", duk_get_string(ctx, -1)); + duk_pop(ctx); + +tags: + - compile + +seealso: + - duk_eval_string_noresult + +introduced: 1.0.0 diff --git a/website/api/duk_eval_string_noresult.txt b/website/api/duk_eval_string_noresult.txt deleted file mode 100644 index d45ce959..00000000 --- a/website/api/duk_eval_string_noresult.txt +++ /dev/null @@ -1,21 +0,0 @@ -=proto -void duk_eval_string_noresult(duk_context *ctx, const char *src); - -=stack -[ ... ] -> [ ... ] - -=summary -

Like -duk_eval_string(), but leaves no -result on the value stack.

- -
- -=example -duk_eval_string_noresult(ctx, "print('testString'.toUpperCase())"); - -=tags -compile - -=introduced -1.0.0 diff --git a/website/api/duk_eval_string_noresult.yaml b/website/api/duk_eval_string_noresult.yaml new file mode 100644 index 00000000..b399fe6f --- /dev/null +++ b/website/api/duk_eval_string_noresult.yaml @@ -0,0 +1,22 @@ +name: duk_eval_string_noresult + +proto: | + void duk_eval_string_noresult(duk_context *ctx, const char *src); + +stack: | + [ ... ] -> [ ... ] + +summary: | +

Like + duk_eval_string(), but leaves no + result on the value stack.

+ +
+ +example: | + duk_eval_string_noresult(ctx, "print('testString'.toUpperCase())"); + +tags: + - compile + +introduced: 1.0.0 diff --git a/website/api/duk_fatal.txt b/website/api/duk_fatal.txt deleted file mode 100644 index b0d6e870..00000000 --- a/website/api/duk_fatal.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -void duk_fatal(duk_context *ctx, duk_errcode_t err_code, const char *err_msg); - -=summary -

Call fatal error handler with a specified error code and an optional -message (err_msg may be NULL). The valid range -for user error codes is [1,16777215].

- -

A fatal error handler never returns and may e.g. exit the current -process. Error catching points (like try-catch statements -and error catching API calls) are bypassed, and finalizers are not executed. -You should only call this function when a truly fatal, unrecoverable error -has occurred.

- -=example -duk_fatal(ctx, DUK_ERR_INTERNAL_ERROR, "assumption failed"); - -=tags -error - -=introduced -1.0.0 diff --git a/website/api/duk_fatal.yaml b/website/api/duk_fatal.yaml new file mode 100644 index 00000000..44f0a0f3 --- /dev/null +++ b/website/api/duk_fatal.yaml @@ -0,0 +1,23 @@ +name: duk_fatal + +proto: | + void duk_fatal(duk_context *ctx, duk_errcode_t err_code, const char *err_msg); + +summary: | +

Call fatal error handler with a specified error code and an optional + message (err_msg may be NULL). The valid range + for user error codes is [1,16777215].

+ +

A fatal error handler never returns and may e.g. exit the current + process. Error catching points (like try-catch statements + and error catching API calls) are bypassed, and finalizers are not executed. + You should only call this function when a truly fatal, unrecoverable error + has occurred.

+ +example: | + duk_fatal(ctx, DUK_ERR_INTERNAL_ERROR, "assumption failed"); + +tags: + - error + +introduced: 1.0.0 diff --git a/website/api/duk_free.txt b/website/api/duk_free.txt deleted file mode 100644 index 56872df8..00000000 --- a/website/api/duk_free.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -void duk_free(duk_context *ctx, void *ptr); - -=summary -

Like duk_free_raw() but may involve -garbage collection steps. The garbage collection interaction cannot cause -the operation to fail.

- -

duk_free() can be used to free memory allocated with either -duk_alloc() or -duk_alloc_raw() -and their reallocation variants.

- -
-Currently a duk_free() cannot cause a garbage collection -pass but does update internal GC trigger counters. -
- -=example -void *buf = duk_alloc(ctx, 1024); -/* ... */ - -duk_free(ctx, buf); /* safe even if 'buf' is NULL */ - -=tags -memory - -=seealso -duk_free_raw - - -=introduced -1.0.0 diff --git a/website/api/duk_free.yaml b/website/api/duk_free.yaml new file mode 100644 index 00000000..cda8a388 --- /dev/null +++ b/website/api/duk_free.yaml @@ -0,0 +1,33 @@ +name: duk_free + +proto: | + void duk_free(duk_context *ctx, void *ptr); + +summary: | +

Like duk_free_raw() but may involve + garbage collection steps. The garbage collection interaction cannot cause + the operation to fail.

+ +

duk_free() can be used to free memory allocated with either + duk_alloc() or + duk_alloc_raw() + and their reallocation variants.

+ +
+ Currently a duk_free() cannot cause a garbage collection + pass but does update internal GC trigger counters. +
+ +example: | + void *buf = duk_alloc(ctx, 1024); + /* ... */ + + duk_free(ctx, buf); /* safe even if 'buf' is NULL */ + +tags: + - memory + +seealso: + - duk_free_raw + +introduced: 1.0.0 diff --git a/website/api/duk_free_raw.txt b/website/api/duk_free_raw.txt deleted file mode 100644 index 19e95328..00000000 --- a/website/api/duk_free_raw.txt +++ /dev/null @@ -1,27 +0,0 @@ -=proto -void duk_free_raw(duk_context *ctx, void *ptr); - -=summary -

Free memory allocated with the allocation function registered to the -context. The operation cannot fail. If ptr is NULL, -the call is a no-op.

- -

duk_free_raw() can be used to free memory allocated with either -duk_alloc() or -duk_alloc_raw() -and their reallocation variants.

- -=example -void *buf = duk_alloc_raw(ctx, 1024); -/* ... */ - -duk_free_raw(ctx, buf); /* safe even if 'buf' is NULL */ - -=tags -memory - -=seealso -duk_free - -=introduced -1.0.0 diff --git a/website/api/duk_free_raw.yaml b/website/api/duk_free_raw.yaml new file mode 100644 index 00000000..e2392579 --- /dev/null +++ b/website/api/duk_free_raw.yaml @@ -0,0 +1,28 @@ +name: duk_free_raw + +proto: | + void duk_free_raw(duk_context *ctx, void *ptr); + +summary: | +

Free memory allocated with the allocation function registered to the + context. The operation cannot fail. If ptr is NULL, + the call is a no-op.

+ +

duk_free_raw() can be used to free memory allocated with either + duk_alloc() or + duk_alloc_raw() + and their reallocation variants.

+ +example: | + void *buf = duk_alloc_raw(ctx, 1024); + /* ... */ + + duk_free_raw(ctx, buf); /* safe even if 'buf' is NULL */ + +tags: + - memory + +seealso: + - duk_free + +introduced: 1.0.0 diff --git a/website/api/duk_gc.txt b/website/api/duk_gc.txt deleted file mode 100644 index d846184f..00000000 --- a/website/api/duk_gc.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -void duk_gc(duk_context *ctx, duk_uint_t flags); - -=summary -

Force a mark-and-sweep garbage collection round. If mark-and-sweep is -disabled in the Duktape build, the call is a no-op. The flags field is a -placeholder; no flags are defined at the moment.

- -

You may want to call this function twice to ensure even objects with -finalizers are collected. Currently it takes two mark-and-sweep rounds -to collect such objects. First round marks the object as finalizable and -runs the finalizer. Second round ensures the object is still -unreachable after finalization and then frees the object.

- -=example -duk_gc(ctx, 0); - -=tags -memory -heap - -=introduced -1.0.0 diff --git a/website/api/duk_gc.yaml b/website/api/duk_gc.yaml new file mode 100644 index 00000000..24f49188 --- /dev/null +++ b/website/api/duk_gc.yaml @@ -0,0 +1,24 @@ +name: duk_gc + +proto: | + void duk_gc(duk_context *ctx, duk_uint_t flags); + +summary: | +

Force a mark-and-sweep garbage collection round. If mark-and-sweep is + disabled in the Duktape build, the call is a no-op. The flags field is a + placeholder; no flags are defined at the moment.

+ +

You may want to call this function twice to ensure even objects with + finalizers are collected. Currently it takes two mark-and-sweep rounds + to collect such objects. First round marks the object as finalizable and + runs the finalizer. Second round ensures the object is still + unreachable after finalization and then frees the object.

+ +example: | + duk_gc(ctx, 0); + +tags: + - memory + - heap + +introduced: 1.0.0 diff --git a/website/api/duk_get_boolean.txt b/website/api/duk_get_boolean.txt deleted file mode 100644 index 34146906..00000000 --- a/website/api/duk_get_boolean.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -duk_bool_t duk_get_boolean(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Get the boolean value at index without modifying or coercing -the value. Returns 1 if the value is true, 0 if the value is -false, not a boolean, or the index is invalid.

- -

Note that the value is not coerced, so even a "truthy" Ecmascript value -(like a non-empty string) will be treated as false. If you want to coerce -the value, use duk_to_boolean().

- -=example -if (duk_get_boolean(ctx, -3)) { - printf("value is true\n"); -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_get_boolean.yaml b/website/api/duk_get_boolean.yaml new file mode 100644 index 00000000..1df650ec --- /dev/null +++ b/website/api/duk_get_boolean.yaml @@ -0,0 +1,26 @@ +name: duk_get_boolean + +proto: | + duk_bool_t duk_get_boolean(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Get the boolean value at index without modifying or coercing + the value. Returns 1 if the value is true, 0 if the value is + false, not a boolean, or the index is invalid.

+ +

Note that the value is not coerced, so even a "truthy" Ecmascript value + (like a non-empty string) will be treated as false. If you want to coerce + the value, use duk_to_boolean().

+ +example: | + if (duk_get_boolean(ctx, -3)) { + printf("value is true\n"); + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_get_buffer.txt b/website/api/duk_get_buffer.txt deleted file mode 100644 index b336e35c..00000000 --- a/website/api/duk_get_buffer.txt +++ /dev/null @@ -1,35 +0,0 @@ -=proto -void *duk_get_buffer(duk_context *ctx, duk_idx_t index, duk_size_t *out_size); - -=stack -[ ... val! ... ] - -=summary -

Get the data pointer for a buffer value at index without modifying -or coercing the value. Returns a non-NULL pointer if the value is a -valid buffer (fixed or dynamic) with a non-zero size. For a zero-size buffer, -may return a NULL or a non-NULL pointer. Returns NULL -if the value is not a buffer or the index is invalid. If out_size is -non-NULL, the size of the buffer is written to *out_size; 0 -is written if the return value is NULL.

- -
-There is no reliable way to distinguish a zero-size buffer from a non-buffer -based on the return values. A NULL with zero size is returned for -a non-buffer. The same values may be returned for a zero-size buffer (although -it is also possible that a non-NULL pointer is returned). -
- -=example -void *ptr; -duk_size_t sz; - -ptr = duk_get_buffer(ctx, -3, &sz); -printf("buf=%p, size=%lu\n", ptr, (unsigned long) sz); - -=tags -stack -buffer - -=introduced -1.0.0 diff --git a/website/api/duk_get_buffer.yaml b/website/api/duk_get_buffer.yaml new file mode 100644 index 00000000..f2d6c6e2 --- /dev/null +++ b/website/api/duk_get_buffer.yaml @@ -0,0 +1,36 @@ +name: duk_get_buffer + +proto: | + void *duk_get_buffer(duk_context *ctx, duk_idx_t index, duk_size_t *out_size); + +stack: | + [ ... val! ... ] + +summary: | +

Get the data pointer for a buffer value at index without modifying + or coercing the value. Returns a non-NULL pointer if the value is a + valid buffer (fixed or dynamic) with a non-zero size. For a zero-size buffer, + may return a NULL or a non-NULL pointer. Returns NULL + if the value is not a buffer or the index is invalid. If out_size is + non-NULL, the size of the buffer is written to *out_size; 0 + is written if the return value is NULL.

+ +
+ There is no reliable way to distinguish a zero-size buffer from a non-buffer + based on the return values. A NULL with zero size is returned for + a non-buffer. The same values may be returned for a zero-size buffer (although + it is also possible that a non-NULL pointer is returned). +
+ +example: | + void *ptr; + duk_size_t sz; + + ptr = duk_get_buffer(ctx, -3, &sz); + printf("buf=%p, size=%lu\n", ptr, (unsigned long) sz); + +tags: + - stack + - buffer + +introduced: 1.0.0 diff --git a/website/api/duk_get_c_function.txt b/website/api/duk_get_c_function.txt deleted file mode 100644 index 7acb2acd..00000000 --- a/website/api/duk_get_c_function.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -duk_c_function duk_get_c_function(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Get the Duktape/C function pointer (a duk_c_function) from an -Ecmascript function object associated with a Duktape/C function. If the -value is not such a function or index is invalid, returns NULL.

- -

If you prefer an error to be thrown for an invalid value or index, use -duk_require_c_function().

- -=example -duk_c_function funcptr; - -funcptr = duk_get_c_function(ctx, -3); - -=tags -stack -function - -=introduced -1.0.0 diff --git a/website/api/duk_get_c_function.yaml b/website/api/duk_get_c_function.yaml new file mode 100644 index 00000000..c9e898f0 --- /dev/null +++ b/website/api/duk_get_c_function.yaml @@ -0,0 +1,26 @@ +name: duk_get_c_function + +proto: | + duk_c_function duk_get_c_function(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Get the Duktape/C function pointer (a duk_c_function) from an + Ecmascript function object associated with a Duktape/C function. If the + value is not such a function or index is invalid, returns NULL.

+ +

If you prefer an error to be thrown for an invalid value or index, use + duk_require_c_function().

+ +example: | + duk_c_function funcptr; + + funcptr = duk_get_c_function(ctx, -3); + +tags: + - stack + - function + +introduced: 1.0.0 diff --git a/website/api/duk_get_context.txt b/website/api/duk_get_context.txt deleted file mode 100644 index 65d8b8fa..00000000 --- a/website/api/duk_get_context.txt +++ /dev/null @@ -1,46 +0,0 @@ -=proto -duk_context *duk_get_context(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Get a context pointer for a Duktape thread at index. If the -value at index is not a Duktape thread or the index is invalid, -returns NULL.

- -

The returned context pointer is only valid while the Duktape thread -is reachable from a garbage collection point of view.

- -

If you prefer an error to be thrown for an invalid value or index, -use duk_require_context().

- -=example -duk_context *new_ctx; - -/* Create a new thread and get a context pointer. */ - -(void) duk_push_thread(ctx); -new_ctx = duk_get_context(ctx, -1); - -/* You can use new_ctx as long as the related thread is reachable - * from a garbage collection point of view. - */ - -duk_push_string(new_ctx, "foo"); - -/* This duk_pop() makes the new thread unreachable (assuming there - * is no other reference to it), so new_ctx is no longer valid - * afterwards. - */ - -duk_pop(ctx); - -/* Using new_ctx here may cause a crash. */ - -=tags -stack -borrowed - -=introduced -1.0.0 diff --git a/website/api/duk_get_context.yaml b/website/api/duk_get_context.yaml new file mode 100644 index 00000000..4b752d93 --- /dev/null +++ b/website/api/duk_get_context.yaml @@ -0,0 +1,47 @@ +name: duk_get_context + +proto: | + duk_context *duk_get_context(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Get a context pointer for a Duktape thread at index. If the + value at index is not a Duktape thread or the index is invalid, + returns NULL.

+ +

The returned context pointer is only valid while the Duktape thread + is reachable from a garbage collection point of view.

+ +

If you prefer an error to be thrown for an invalid value or index, + use duk_require_context().

+ +example: | + duk_context *new_ctx; + + /* Create a new thread and get a context pointer. */ + + (void) duk_push_thread(ctx); + new_ctx = duk_get_context(ctx, -1); + + /* You can use new_ctx as long as the related thread is reachable + * from a garbage collection point of view. + */ + + duk_push_string(new_ctx, "foo"); + + /* This duk_pop() makes the new thread unreachable (assuming there + * is no other reference to it), so new_ctx is no longer valid + * afterwards. + */ + + duk_pop(ctx); + + /* Using new_ctx here may cause a crash. */ + +tags: + - stack + - borrowed + +introduced: 1.0.0 diff --git a/website/api/duk_get_current_magic.txt b/website/api/duk_get_current_magic.txt deleted file mode 100644 index 417e959d..00000000 --- a/website/api/duk_get_current_magic.txt +++ /dev/null @@ -1,35 +0,0 @@ -=proto -duk_int_t duk_get_current_magic(duk_context *ctx); - -=summary -

Get the 16-bit signed "magic" value associated with the running -Duktape/C function. If there is no current activation, zero is returned.

- -

The magic function allows the same Duktape/C function to be used with slightly -different behavior; behavior flags or other parameters can be passed in the -magic field. This is less expensive than having behavior related flags or -properties in the function object as normal properties.

- -

If you need an unsigned 16-bit value, simply AND the result:

-
-unsigned int my_flags = ((unsigned int) duk_get_current_magic(ctx)) & 0xffffU;
-
- -=example -duk_int_t my_flags = duk_get_current_magic(ctx); -if (my_flags & 0x01) { - printf("flag set\n"); -} else { - printf("flag not set\n"); -} - -=tags -function -magic - -=seealso -duk_get_magic -duk_set_magic - -=introduced -1.0.0 diff --git a/website/api/duk_get_current_magic.yaml b/website/api/duk_get_current_magic.yaml new file mode 100644 index 00000000..45d9b0d9 --- /dev/null +++ b/website/api/duk_get_current_magic.yaml @@ -0,0 +1,36 @@ +name: duk_get_current_magic + +proto: | + duk_int_t duk_get_current_magic(duk_context *ctx); + +summary: | +

Get the 16-bit signed "magic" value associated with the running + Duktape/C function. If there is no current activation, zero is returned.

+ +

The magic function allows the same Duktape/C function to be used with slightly + different behavior; behavior flags or other parameters can be passed in the + magic field. This is less expensive than having behavior related flags or + properties in the function object as normal properties.

+ +

If you need an unsigned 16-bit value, simply AND the result:

+ 
+  unsigned int my_flags = ((unsigned int) duk_get_current_magic(ctx)) & 0xffffU;
+
+ +example: | + duk_int_t my_flags = duk_get_current_magic(ctx); + if (my_flags & 0x01) { + printf("flag set\n"); + } else { + printf("flag not set\n"); + } + +tags: + - function + - magic + +seealso: + - duk_get_magic + - duk_set_magic + +introduced: 1.0.0 diff --git a/website/api/duk_get_error_code.txt b/website/api/duk_get_error_code.txt deleted file mode 100644 index 6fb3da4e..00000000 --- a/website/api/duk_get_error_code.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -duk_errcode_t duk_get_error_code(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Map the value at index to the error codes DUK_ERR_xxx -based on which Error subclass the value inherits from. For example, -if the value at the stack top is an user-defined error which inherits from -ReferenceError, the return value will be DUK_ERR_REFERENCE_ERROR. -If the value is not an object, does not inherit from Error, or index -is invalid, returns 0 (= DUK_ERR_NONE).

- -=example -if (duk_get_error_code(ctx, -3) == DUK_ERR_URI_ERROR) { - printf("Invalid URI\n"); -} - -=tags -stack -error - -=introduced -1.1.0 diff --git a/website/api/duk_get_error_code.yaml b/website/api/duk_get_error_code.yaml new file mode 100644 index 00000000..bf822bed --- /dev/null +++ b/website/api/duk_get_error_code.yaml @@ -0,0 +1,26 @@ +name: duk_get_error_code + +proto: | + duk_errcode_t duk_get_error_code(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Map the value at index to the error codes DUK_ERR_xxx + based on which Error subclass the value inherits from. For example, + if the value at the stack top is an user-defined error which inherits from + ReferenceError, the return value will be DUK_ERR_REFERENCE_ERROR. + If the value is not an object, does not inherit from Error, or index + is invalid, returns 0 (= DUK_ERR_NONE).

+ +example: | + if (duk_get_error_code(ctx, -3) == DUK_ERR_URI_ERROR) { + printf("Invalid URI\n"); + } + +tags: + - stack + - error + +introduced: 1.1.0 diff --git a/website/api/duk_get_finalizer.txt b/website/api/duk_get_finalizer.txt deleted file mode 100644 index 87361b27..00000000 --- a/website/api/duk_get_finalizer.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -void duk_get_finalizer(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... val! ... finalizer! ] - -=summary -

Get the finalizer associated with a value at index. If the -value is not an object or it is an object without a finalizer, -undefined is pushed to the stack instead.

- -=example -/* Get the finalizer of an object at index -3. */ -duk_get_finalizer(ctx, -3); - -=tags -object -finalizer - -=seealso -duk_set_finalizer - -=introduced -1.0.0 diff --git a/website/api/duk_get_finalizer.yaml b/website/api/duk_get_finalizer.yaml new file mode 100644 index 00000000..118d77fc --- /dev/null +++ b/website/api/duk_get_finalizer.yaml @@ -0,0 +1,25 @@ +name: duk_get_finalizer + +proto: | + void duk_get_finalizer(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... val! ... finalizer! ] + +summary: | +

Get the finalizer associated with a value at index. If the + value is not an object or it is an object without a finalizer, + undefined is pushed to the stack instead.

+ +example: | + /* Get the finalizer of an object at index -3. */ + duk_get_finalizer(ctx, -3); + +tags: + - object + - finalizer + +seealso: + - duk_set_finalizer + +introduced: 1.0.0 diff --git a/website/api/duk_get_global_string.txt b/website/api/duk_get_global_string.txt deleted file mode 100644 index 7c42871f..00000000 --- a/website/api/duk_get_global_string.txt +++ /dev/null @@ -1,35 +0,0 @@ -=proto -duk_bool_t duk_get_global_string(duk_context *ctx, const char *key); - -=stack -[ ... ] -> [ ... val! ] (if key exists) -[ ... ] -> [ ... undefined! ] (if key doesn't exist) - -=summary -

Get property named key from the global object. -Returns non-zero if the property exists and zero otherwise. -This is a convenience function which does the equivalent of:

-
-duk_bool_t ret;
-
-duk_push_global_object(ctx);
-ret = duk_get_prop_string(ctx, -1, key);
-duk_remove(ctx, -2);
-/* 'ret' would be the return value from duk_get_global_string() */
-
- -=example -(void) duk_get_global_string(ctx, "encodeURIComponent"); -duk_push_string(ctx, "foo bar"); -duk_call(ctx, 1); /* [ ... encodeURIComponent "foo bar" ] -> [ "foo%20bar" ] */ -printf("encoded: %s\n", duk_to_string(ctx, -1)); -duk_pop(ctx); - -=tags -property - -=seealso -duk_put_global_string - -=introduced -1.0.0 diff --git a/website/api/duk_get_global_string.yaml b/website/api/duk_get_global_string.yaml new file mode 100644 index 00000000..fd3916e7 --- /dev/null +++ b/website/api/duk_get_global_string.yaml @@ -0,0 +1,36 @@ +name: duk_get_global_string + +proto: | + duk_bool_t duk_get_global_string(duk_context *ctx, const char *key); + +stack: | + [ ... ] -> [ ... val! ] (if key exists) + [ ... ] -> [ ... undefined! ] (if key doesn't exist) + +summary: | +

Get property named key from the global object. + Returns non-zero if the property exists and zero otherwise. + This is a convenience function which does the equivalent of:

+ 
+  duk_bool_t ret;
+
+  duk_push_global_object(ctx);
+  ret = duk_get_prop_string(ctx, -1, key);
+  duk_remove(ctx, -2);
+  /* 'ret' would be the return value from duk_get_global_string() */
+
+ +example: | + (void) duk_get_global_string(ctx, "encodeURIComponent"); + duk_push_string(ctx, "foo bar"); + duk_call(ctx, 1); /* [ ... encodeURIComponent "foo bar" ] -> [ "foo%20bar" ] */ + printf("encoded: %s\n", duk_to_string(ctx, -1)); + duk_pop(ctx); + +tags: + - property + +seealso: + - duk_put_global_string + +introduced: 1.0.0 diff --git a/website/api/duk_get_heapptr.txt b/website/api/duk_get_heapptr.txt deleted file mode 100644 index efe846ca..00000000 --- a/website/api/duk_get_heapptr.txt +++ /dev/null @@ -1,50 +0,0 @@ -=proto -void *duk_get_heapptr(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Get a borrowed void * reference to a Duktape heap allocated -value (object, buffer, string) at index. Return NULL -if the index is invalid or the target value is not heap allocated. -The returned pointer must not be interpreted or dereferenced, but -duk_push_heapptr() can be used -to push the original value into the value stack later.

- -

The returned void pointer is only valid while the original value is -reachable from a garbage collection point of view. If this is not the case, -it is memory unsafe to use -duk_push_heapptr().

- -=example -duk_context *new_ctx; -void *ptr; - -duk_eval_string(ctx, "({ foo: 'bar' })"); -ptr = duk_get_heapptr(ctx, -1); - -/* The original value must remain reachable for Duktape up to a future - * duk_push_heapptr(). Here we just write it to the global object, but - * it could also be a value stack somewhere, a stash object, etc. - */ -duk_put_global_string(ctx, "ref"); - -/* Later, assuming the original value has been reachable all the way - * to here: - */ - -duk_push_heapptr(ctx, ptr); -duk_get_prop_string(ctx, -1, "foo"); -printf("obj.foo: %s\n", duk_safe_to_string(ctx, -1)); /* prints 'bar' */ - -=tags -stack -borrowed - -=seealso -duk_require_heapptr -duk_push_heapptr - -=introduced -1.1.0 diff --git a/website/api/duk_get_heapptr.yaml b/website/api/duk_get_heapptr.yaml new file mode 100644 index 00000000..3bb059a7 --- /dev/null +++ b/website/api/duk_get_heapptr.yaml @@ -0,0 +1,51 @@ +name: duk_get_heapptr + +proto: | + void *duk_get_heapptr(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Get a borrowed void * reference to a Duktape heap allocated + value (object, buffer, string) at index. Return NULL + if the index is invalid or the target value is not heap allocated. + The returned pointer must not be interpreted or dereferenced, but + duk_push_heapptr() can be used + to push the original value into the value stack later.

+ +

The returned void pointer is only valid while the original value is + reachable from a garbage collection point of view. If this is not the case, + it is memory unsafe to use + duk_push_heapptr().

+ +example: | + duk_context *new_ctx; + void *ptr; + + duk_eval_string(ctx, "({ foo: 'bar' })"); + ptr = duk_get_heapptr(ctx, -1); + + /* The original value must remain reachable for Duktape up to a future + * duk_push_heapptr(). Here we just write it to the global object, but + * it could also be a value stack somewhere, a stash object, etc. + */ + duk_put_global_string(ctx, "ref"); + + /* Later, assuming the original value has been reachable all the way + * to here: + */ + + duk_push_heapptr(ctx, ptr); + duk_get_prop_string(ctx, -1, "foo"); + printf("obj.foo: %s\n", duk_safe_to_string(ctx, -1)); /* prints 'bar' */ + +tags: + - stack + - borrowed + +seealso: + - duk_require_heapptr + - duk_push_heapptr + +introduced: 1.1.0 diff --git a/website/api/duk_get_int.txt b/website/api/duk_get_int.txt deleted file mode 100644 index 952932c9..00000000 --- a/website/api/duk_get_int.txt +++ /dev/null @@ -1,42 +0,0 @@ -=proto -duk_int_t duk_get_int(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Get the number at index and convert it to a C duk_int_t -by first clamping the value between [DUK_INT_MIN, DUK_INT_MAX] and then -truncating towards zero. The value on the stack is not modified. -If the value is a NaN, is not a number, or the index is invalid, -returns 0.

- -

Conversion examples:

- - - - - - - - - - -
InputOutput
-InfinityDUK_INT_MIN
DUK_INT_MIN - 1DUK_INT_MIN
-3.9-3
3.93
DUK_INT_MAX + 1DUK_INT_MAX
+InfinityDUK_INT_MAX
NaN0
"123"0 (non-number)
- -
-The coercion is different from a basic C cast from double to -integer, which may have counterintuitive (and non-portable) behavior like coercing -NaN to DUK_INT_MIN. The coercion is also different from Ecmascript -ToInt32() coercion because the full range of the native -duk_int_t is allowed (which may be more than 32 bits). -
- -=example -printf("int value: %ld\n", (long) duk_get_int(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_get_int.yaml b/website/api/duk_get_int.yaml new file mode 100644 index 00000000..b69a13c4 --- /dev/null +++ b/website/api/duk_get_int.yaml @@ -0,0 +1,43 @@ +name: duk_get_int + +proto: | + duk_int_t duk_get_int(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Get the number at index and convert it to a C duk_int_t + by first clamping the value between [DUK_INT_MIN, DUK_INT_MAX] and then + truncating towards zero. The value on the stack is not modified. + If the value is a NaN, is not a number, or the index is invalid, + returns 0.

+ +

Conversion examples:

+ + + + + + + + + + +
InputOutput
-InfinityDUK_INT_MIN
DUK_INT_MIN - 1DUK_INT_MIN
-3.9-3
3.93
DUK_INT_MAX + 1DUK_INT_MAX
+InfinityDUK_INT_MAX
NaN0
"123"0 (non-number)
+ +
+ The coercion is different from a basic C cast from double to + integer, which may have counterintuitive (and non-portable) behavior like coercing + NaN to DUK_INT_MIN. The coercion is also different from Ecmascript + ToInt32() coercion because the full range of the native + duk_int_t is allowed (which may be more than 32 bits). +
+ +example: | + printf("int value: %ld\n", (long) duk_get_int(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_get_length.txt b/website/api/duk_get_length.txt deleted file mode 100644 index 9bff4263..00000000 --- a/website/api/duk_get_length.txt +++ /dev/null @@ -1,30 +0,0 @@ -=proto -duk_size_t duk_get_length(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Get a type-specific "length" for value at index:

-
    -
  • String: character length of string (not byte length)
    • -
  • Object: Math.floor(ToNumber(obj.length)) if result within - 32-bit unsigned range; otherwise 0
    • -
  • Buffer: byte length of buffer
    • -
  • Other type or invalid stack index: 0
    • -
- -

To get the byte length of a string, use -duk_get_lstring(). -

- -=example -if (duk_is_string(ctx, -3)) { - printf("string char len is %lu\n", (unsigned long) duk_get_length(ctx, -3)); -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_get_length.yaml b/website/api/duk_get_length.yaml new file mode 100644 index 00000000..03f33835 --- /dev/null +++ b/website/api/duk_get_length.yaml @@ -0,0 +1,31 @@ +name: duk_get_length + +proto: | + duk_size_t duk_get_length(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Get a type-specific "length" for value at index:

+
    +
  • String: character length of string (not byte length)
    • +
  • Object: Math.floor(ToNumber(obj.length)) if result within + 32-bit unsigned range; otherwise 0
    • +
  • Buffer: byte length of buffer
    • +
  • Other type or invalid stack index: 0
    • +
+ +

To get the byte length of a string, use + duk_get_lstring(). +

+ +example: | + if (duk_is_string(ctx, -3)) { + printf("string char len is %lu\n", (unsigned long) duk_get_length(ctx, -3)); + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_get_lstring.txt b/website/api/duk_get_lstring.txt deleted file mode 100644 index 8c07b57a..00000000 --- a/website/api/duk_get_lstring.txt +++ /dev/null @@ -1,37 +0,0 @@ -=proto -const char *duk_get_lstring(duk_context *ctx, duk_idx_t index, duk_size_t *out_len); - -=stack -[ ... val! ... ] - -=summary -

Get character data pointer and length for a string at index -without modifying or coercing the value. Returns a non-NULL -pointer to the read-only, NUL-terminated string data, and writes the -string byte length to *out_len (if out_len is -non-NULL). Returns NULL and writes zero to *out_len -(if out_len is non-NULL) if the value is not a string or -the index is invalid.

- -

To get the string character length (instead of byte length), use -duk_get_length().

- -
-A non-NULL return value is guaranteed even for zero length strings; -this differs from how buffer data pointers are handled (for technical reasons). -
- -=example -const char *buf; -duk_size_t len; - -buf = duk_get_lstring(ctx, -3, &len); -if (buf) { - printf("value is a string, %lu bytes\n", (unsigned long) len); -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_get_lstring.yaml b/website/api/duk_get_lstring.yaml new file mode 100644 index 00000000..43c35b88 --- /dev/null +++ b/website/api/duk_get_lstring.yaml @@ -0,0 +1,38 @@ +name: duk_get_lstring + +proto: | + const char *duk_get_lstring(duk_context *ctx, duk_idx_t index, duk_size_t *out_len); + +stack: | + [ ... val! ... ] + +summary: | +

Get character data pointer and length for a string at index + without modifying or coercing the value. Returns a non-NULL + pointer to the read-only, NUL-terminated string data, and writes the + string byte length to *out_len (if out_len is + non-NULL). Returns NULL and writes zero to *out_len + (if out_len is non-NULL) if the value is not a string or + the index is invalid.

+ +

To get the string character length (instead of byte length), use + duk_get_length().

+ +
+ A non-NULL return value is guaranteed even for zero length strings; + this differs from how buffer data pointers are handled (for technical reasons). +
+ +example: | + const char *buf; + duk_size_t len; + + buf = duk_get_lstring(ctx, -3, &len); + if (buf) { + printf("value is a string, %lu bytes\n", (unsigned long) len); + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_get_magic.txt b/website/api/duk_get_magic.txt deleted file mode 100644 index 5c4acd71..00000000 --- a/website/api/duk_get_magic.txt +++ /dev/null @@ -1,29 +0,0 @@ -=proto -duk_int_t duk_get_magic(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Get the 16-bit signed "magic" value associated with the Duktape/C function -at index. If the value is not a Duktape/C function, an error is -thrown.

- -
-Lightweight functions have space for only 8 magic value bits which is -interpreted as a signed integer (-128 to 127). -
- -=example -duk_int_t my_flags = duk_get_magic(ctx, -3); - -=tags -function -magic - -=seealso -duk_get_current_magic -duk_set_magic - -=introduced -1.0.0 diff --git a/website/api/duk_get_magic.yaml b/website/api/duk_get_magic.yaml new file mode 100644 index 00000000..cc900d18 --- /dev/null +++ b/website/api/duk_get_magic.yaml @@ -0,0 +1,30 @@ +name: duk_get_magic + +proto: | + duk_int_t duk_get_magic(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Get the 16-bit signed "magic" value associated with the Duktape/C function + at index. If the value is not a Duktape/C function, an error is + thrown.

+ +
+ Lightweight functions have space for only 8 magic value bits which is + interpreted as a signed integer (-128 to 127). +
+ +example: | + duk_int_t my_flags = duk_get_magic(ctx, -3); + +tags: + - function + - magic + +seealso: + - duk_get_current_magic + - duk_set_magic + +introduced: 1.0.0 diff --git a/website/api/duk_get_memory_functions.txt b/website/api/duk_get_memory_functions.txt deleted file mode 100644 index b245a56c..00000000 --- a/website/api/duk_get_memory_functions.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -void duk_get_memory_functions(duk_context *ctx, duk_memory_functions *out_funcs); - -=summary -

Get the memory management functions used by the context.

- -

Normally there is no reason to call this function: you can use the -memory management primitives through wrapped memory management functions -such as -duk_alloc(), -duk_realloc(), and -duk_free().

- -=example -duk_memory_functions funcs; - -duk_get_memory_functions(ctx, &funcs); - -=tags -memory -heap - -=introduced -1.0.0 diff --git a/website/api/duk_get_memory_functions.yaml b/website/api/duk_get_memory_functions.yaml new file mode 100644 index 00000000..8b33c56f --- /dev/null +++ b/website/api/duk_get_memory_functions.yaml @@ -0,0 +1,25 @@ +name: duk_get_memory_functions + +proto: | + void duk_get_memory_functions(duk_context *ctx, duk_memory_functions *out_funcs); + +summary: | +

Get the memory management functions used by the context.

+ +

Normally there is no reason to call this function: you can use the + memory management primitives through wrapped memory management functions + such as + duk_alloc(), + duk_realloc(), and + duk_free().

+ +example: | + duk_memory_functions funcs; + + duk_get_memory_functions(ctx, &funcs); + +tags: + - memory + - heap + +introduced: 1.0.0 diff --git a/website/api/duk_get_number.txt b/website/api/duk_get_number.txt deleted file mode 100644 index bb7dcee3..00000000 --- a/website/api/duk_get_number.txt +++ /dev/null @@ -1,16 +0,0 @@ -=proto -duk_double_t duk_get_number(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Get the number value at index without modifying or coercing -the value. Returns NaN if the value is not a number or the -index is invalid.

- -=example -printf("value: %lf\n", (double) duk_get_number(ctx, -3)); - -=introduced -1.0.0 diff --git a/website/api/duk_get_number.yaml b/website/api/duk_get_number.yaml new file mode 100644 index 00000000..942a4fe1 --- /dev/null +++ b/website/api/duk_get_number.yaml @@ -0,0 +1,17 @@ +name: duk_get_number + +proto: | + duk_double_t duk_get_number(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Get the number value at index without modifying or coercing + the value. Returns NaN if the value is not a number or the + index is invalid.

+ +example: | + printf("value: %lf\n", (double) duk_get_number(ctx, -3)); + +introduced: 1.0.0 diff --git a/website/api/duk_get_pointer.txt b/website/api/duk_get_pointer.txt deleted file mode 100644 index 41bfdcee..00000000 --- a/website/api/duk_get_pointer.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -void *duk_get_pointer(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Get the pointer value at index as void * without -modifying or coercing the value. Returns NULL if the value is -not a pointer or the index is invalid.

- -=example -void *ptr; - -ptr = duk_get_pointer(ctx, -3); -printf("my pointer is: %p\n", ptr); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_get_pointer.yaml b/website/api/duk_get_pointer.yaml new file mode 100644 index 00000000..1fd1835e --- /dev/null +++ b/website/api/duk_get_pointer.yaml @@ -0,0 +1,23 @@ +name: duk_get_pointer + +proto: | + void *duk_get_pointer(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Get the pointer value at index as void * without + modifying or coercing the value. Returns NULL if the value is + not a pointer or the index is invalid.

+ +example: | + void *ptr; + + ptr = duk_get_pointer(ctx, -3); + printf("my pointer is: %p\n", ptr); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_get_prop.txt b/website/api/duk_get_prop.txt deleted file mode 100644 index 83528301..00000000 --- a/website/api/duk_get_prop.txt +++ /dev/null @@ -1,80 +0,0 @@ -=proto -duk_bool_t duk_get_prop(duk_context *ctx, duk_idx_t obj_index); - -=stack -[ ... obj! ... key! ] -> [ ... obj! ... val! ] (if key exists) -[ ... obj! ... key! ] -> [ ... obj! ... undefined! ] (if key doesn't exist) - -=summary -

Get the property key of a value at obj_index. -Return code and error throwing behavior:

-
    -
  • If the property exists, 1 is returned and key - is replaced by the property value on the value stack. However, - if the property is an accessor, the "getter" function may throw - an error.
    • -
  • If the property does not exist, 0 is returned and key - is replaced by undefined on the value stack.
    • -
  • If the value at obj_index is not - object coercible, - throws an error.
    • -
  • If obj_index is invalid, throws an error.
    • -
- -

The property read is equivalent to the Ecmascript expression:

-
-obj[key]
-
- -

For semantics, see -Property Accessors, -GetValue (V), -and [[Get]] (P). -Both the target value and the key are coerced:

-
    -
  • The target value is automatically coerced to an object. For instance, - a string is converted to a String and you can access its - "length" property.
    • -
  • The key argument is internally coerced to a string. There is - an internal fast path for arrays and numeric indices which avoids an - explicit string coercion, so use a numeric key when applicable.

    -
- -

If the key is a fixed string you can avoid one API call and use the -duk_get_prop_string() variant. -Similarly, if the key is an array index, you can use the -duk_get_prop_index() variant.

- -
- -=example -/* reading [global object].Math.PI */ -duk_push_global_object(ctx); /* -> [ global ] */ -duk_push_string(ctx, "Math"); /* -> [ global "Math" ] */ -duk_get_prop(ctx, -2); /* -> [ global Math ] */ -duk_push_string(ctx, "PI"); /* -> [ global Math "PI" ] */ -duk_get_prop(ctx, -2); /* -> [ global Math PI ] */ -printf("Math.PI is %lf\n", (double) duk_get_number(ctx, -1)); -duk_pop_n(ctx, 3); - -/* reading a configuration value, cfg_idx is normalized - * index of a configuration object. - */ -duk_push_string(ctx, "mySetting"); -if (duk_get_prop(ctx, cfg_idx)) { - const char *str_value = duk_to_string(ctx, -1); - printf("configuration setting present, value: %s\n", str_value); -} else { - printf("configuration setting missing\n"); -} -duk_pop(ctx); /* remember to pop, regardless of whether or not present */ - -=tags -property - -=seealso -duk_get_prop_string -duk_get_prop_index - -=introduced -1.0.0 diff --git a/website/api/duk_get_prop.yaml b/website/api/duk_get_prop.yaml new file mode 100644 index 00000000..e8cdc1ef --- /dev/null +++ b/website/api/duk_get_prop.yaml @@ -0,0 +1,81 @@ +name: duk_get_prop + +proto: | + duk_bool_t duk_get_prop(duk_context *ctx, duk_idx_t obj_index); + +stack: | + [ ... obj! ... key! ] -> [ ... obj! ... val! ] (if key exists) + [ ... obj! ... key! ] -> [ ... obj! ... undefined! ] (if key doesn't exist) + +summary: | +

Get the property key of a value at obj_index. + Return code and error throwing behavior:

+
    +
  • If the property exists, 1 is returned and key + is replaced by the property value on the value stack. However, + if the property is an accessor, the "getter" function may throw + an error.
    • +
  • If the property does not exist, 0 is returned and key + is replaced by undefined on the value stack.
    • +
  • If the value at obj_index is not + object coercible, + throws an error.
    • +
  • If obj_index is invalid, throws an error.
    • +
+ +

The property read is equivalent to the Ecmascript expression:

+ 
+  obj[key]
+
+ +

For semantics, see + Property Accessors, + GetValue (V), + and [[Get]] (P). + Both the target value and the key are coerced:

+
    +
  • The target value is automatically coerced to an object. For instance, + a string is converted to a String and you can access its + "length" property.
    • +
  • The key argument is internally coerced to a string. There is + an internal fast path for arrays and numeric indices which avoids an + explicit string coercion, so use a numeric key when applicable.

    +
+ +

If the key is a fixed string you can avoid one API call and use the + duk_get_prop_string() variant. + Similarly, if the key is an array index, you can use the + duk_get_prop_index() variant.

+ +
+ +example: | + /* reading [global object].Math.PI */ + duk_push_global_object(ctx); /* -> [ global ] */ + duk_push_string(ctx, "Math"); /* -> [ global "Math" ] */ + duk_get_prop(ctx, -2); /* -> [ global Math ] */ + duk_push_string(ctx, "PI"); /* -> [ global Math "PI" ] */ + duk_get_prop(ctx, -2); /* -> [ global Math PI ] */ + printf("Math.PI is %lf\n", (double) duk_get_number(ctx, -1)); + duk_pop_n(ctx, 3); + + /* reading a configuration value, cfg_idx is normalized + * index of a configuration object. + */ + duk_push_string(ctx, "mySetting"); + if (duk_get_prop(ctx, cfg_idx)) { + const char *str_value = duk_to_string(ctx, -1); + printf("configuration setting present, value: %s\n", str_value); + } else { + printf("configuration setting missing\n"); + } + duk_pop(ctx); /* remember to pop, regardless of whether or not present */ + +tags: + - property + +seealso: + - duk_get_prop_string + - duk_get_prop_index + +introduced: 1.0.0 diff --git a/website/api/duk_get_prop_index.txt b/website/api/duk_get_prop_index.txt deleted file mode 100644 index d04a8fdf..00000000 --- a/website/api/duk_get_prop_index.txt +++ /dev/null @@ -1,28 +0,0 @@ -=proto -duk_bool_t duk_get_prop_index(duk_context *ctx, duk_idx_t obj_index, duk_uarridx_t arr_index); - -=stack -[ ... obj! ... ] -> [ ... obj! ... val! ] (if key exists) -[ ... obj! ... ] -> [ ... obj! ... undefined! ] (if key doesn't exist) - -=summary -

Like duk_get_prop(), -but the property name is given as an unsigned integer -arr_index. This is especially useful for accessing -array elements (but is not limited to that).

- -

Conceptually the number is coerced to a string for the property -read, e.g. 123 would be equivalent to a property name -"123". Duktape avoids an explicit coercion whenever -possible.

- -=example -duk_get_prop_index(ctx, -3, 123); -printf("obj[123] = %s\n", duk_to_string(ctx, -1)); -duk_pop(ctx); - -=tags -property - -=introduced -1.0.0 diff --git a/website/api/duk_get_prop_index.yaml b/website/api/duk_get_prop_index.yaml new file mode 100644 index 00000000..f27046f8 --- /dev/null +++ b/website/api/duk_get_prop_index.yaml @@ -0,0 +1,29 @@ +name: duk_get_prop_index + +proto: | + duk_bool_t duk_get_prop_index(duk_context *ctx, duk_idx_t obj_index, duk_uarridx_t arr_index); + +stack: | + [ ... obj! ... ] -> [ ... obj! ... val! ] (if key exists) + [ ... obj! ... ] -> [ ... obj! ... undefined! ] (if key doesn't exist) + +summary: | +

Like duk_get_prop(), + but the property name is given as an unsigned integer + arr_index. This is especially useful for accessing + array elements (but is not limited to that).

+ +

Conceptually the number is coerced to a string for the property + read, e.g. 123 would be equivalent to a property name + "123". Duktape avoids an explicit coercion whenever + possible.

+ +example: | + duk_get_prop_index(ctx, -3, 123); + printf("obj[123] = %s\n", duk_to_string(ctx, -1)); + duk_pop(ctx); + +tags: + - property + +introduced: 1.0.0 diff --git a/website/api/duk_get_prop_string.txt b/website/api/duk_get_prop_string.txt deleted file mode 100644 index 3faace8d..00000000 --- a/website/api/duk_get_prop_string.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_bool_t duk_get_prop_string(duk_context *ctx, duk_idx_t obj_index, const char *key); - -=stack -[ ... obj! ... ] -> [ ... obj! ... val! ] (if key exists) -[ ... obj! ... ] -> [ ... obj! ... undefined! ] (if key doesn't exist) - -=summary -

Like duk_get_prop(), -but the property name is given as a NUL-terminated C string -key.

- -=example -duk_get_prop_string(ctx, -3, "propertyName"); -printf("obj.propertyName = %s\n", duk_to_string(ctx, -1)); -duk_pop(ctx); - -=tags -property - -=introduced -1.0.0 diff --git a/website/api/duk_get_prop_string.yaml b/website/api/duk_get_prop_string.yaml new file mode 100644 index 00000000..afd7fe03 --- /dev/null +++ b/website/api/duk_get_prop_string.yaml @@ -0,0 +1,23 @@ +name: duk_get_prop_string + +proto: | + duk_bool_t duk_get_prop_string(duk_context *ctx, duk_idx_t obj_index, const char *key); + +stack: | + [ ... obj! ... ] -> [ ... obj! ... val! ] (if key exists) + [ ... obj! ... ] -> [ ... obj! ... undefined! ] (if key doesn't exist) + +summary: | +

Like duk_get_prop(), + but the property name is given as a NUL-terminated C string + key.

+ +example: | + duk_get_prop_string(ctx, -3, "propertyName"); + printf("obj.propertyName = %s\n", duk_to_string(ctx, -1)); + duk_pop(ctx); + +tags: + - property + +introduced: 1.0.0 diff --git a/website/api/duk_get_prototype.txt b/website/api/duk_get_prototype.txt deleted file mode 100644 index bc3168b4..00000000 --- a/website/api/duk_get_prototype.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -void duk_get_prototype(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... val! ... proto! ] - -=summary -

Get the internal prototype of the value at index. If the -value is not an object, an error is thrown. If the object has no prototype -(which is possible for "naked objects") undefined is pushed to -the stack instead.

- -=example -/* Get the internal prototype of an object at index -3. */ -duk_get_prototype(ctx, -3); - -=tags -object -prototype - -=seealso -duk_set_prototype - -=introduced -1.0.0 diff --git a/website/api/duk_get_prototype.yaml b/website/api/duk_get_prototype.yaml new file mode 100644 index 00000000..581849a7 --- /dev/null +++ b/website/api/duk_get_prototype.yaml @@ -0,0 +1,26 @@ +name: duk_get_prototype + +proto: | + void duk_get_prototype(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... val! ... proto! ] + +summary: | +

Get the internal prototype of the value at index. If the + value is not an object, an error is thrown. If the object has no prototype + (which is possible for "naked objects") undefined is pushed to + the stack instead.

+ +example: | + /* Get the internal prototype of an object at index -3. */ + duk_get_prototype(ctx, -3); + +tags: + - object + - prototype + +seealso: + - duk_set_prototype + +introduced: 1.0.0 diff --git a/website/api/duk_get_string.txt b/website/api/duk_get_string.txt deleted file mode 100644 index 8c098a6d..00000000 --- a/website/api/duk_get_string.txt +++ /dev/null @@ -1,35 +0,0 @@ -=proto -const char *duk_get_string(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Get character data pointer for a string at index without -modifying or coercing the value. Returns a non-NULL pointer to -the read-only, NUL-terminated string data. Returns NULL if the -value is not a string or the index is invalid.

- -

To get the string byte length explicitly (which is useful if the string -contains embedded NUL characters), use -duk_get_lstring().

- -
-A non-NULL return value is guaranteed even for zero length strings; -this differs from how buffer data pointers are handled (for technical reasons). -
- -=example -const char *buf; - -buf = duk_get_string(ctx, -3); -if (buf) { - printf("value is a string: %s\n", buf); -} - -=tags -stack -string - -=introduced -1.0.0 diff --git a/website/api/duk_get_string.yaml b/website/api/duk_get_string.yaml new file mode 100644 index 00000000..b7f17327 --- /dev/null +++ b/website/api/duk_get_string.yaml @@ -0,0 +1,36 @@ +name: duk_get_string + +proto: | + const char *duk_get_string(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Get character data pointer for a string at index without + modifying or coercing the value. Returns a non-NULL pointer to + the read-only, NUL-terminated string data. Returns NULL if the + value is not a string or the index is invalid.

+ +

To get the string byte length explicitly (which is useful if the string + contains embedded NUL characters), use + duk_get_lstring().

+ +
+ A non-NULL return value is guaranteed even for zero length strings; + this differs from how buffer data pointers are handled (for technical reasons). +
+ +example: | + const char *buf; + + buf = duk_get_string(ctx, -3); + if (buf) { + printf("value is a string: %s\n", buf); + } + +tags: + - stack + - string + +introduced: 1.0.0 diff --git a/website/api/duk_get_top.txt b/website/api/duk_get_top.txt deleted file mode 100644 index 9bc10679..00000000 --- a/website/api/duk_get_top.txt +++ /dev/null @@ -1,15 +0,0 @@ -=proto -duk_idx_t duk_get_top(duk_context *ctx); - -=summary -

Get current stack top (>= 0), indicating the number of values currently on -the value stack (of the current activation).

- -=example -printf("stack top is %ld\n", (long) duk_get_top(ctx)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_get_top.yaml b/website/api/duk_get_top.yaml new file mode 100644 index 00000000..6d6886fb --- /dev/null +++ b/website/api/duk_get_top.yaml @@ -0,0 +1,16 @@ +name: duk_get_top + +proto: | + duk_idx_t duk_get_top(duk_context *ctx); + +summary: | +

Get current stack top (>= 0), indicating the number of values currently on + the value stack (of the current activation).

+ +example: | + printf("stack top is %ld\n", (long) duk_get_top(ctx)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_get_top_index.txt b/website/api/duk_get_top_index.txt deleted file mode 100644 index d59a4f84..00000000 --- a/website/api/duk_get_top_index.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -duk_idx_t duk_get_top_index(duk_context *ctx); - -=summary -

Get the absolute index (>= 0) of the topmost value on the stack. -If the stack is empty, returns DUK_INVALID_INDEX.

- -=example -duk_idx_t idx_top; - -idx_top = duk_get_top_index(ctx); -if (idx_top == DUK_INVALID_INDEX) { - printf("stack is empty\n"); -} else { - printf("index of top element: %ld\n", (long) idx_top); -} - -=tags -stack - -=seealso -duk_require_top_index - -=introduced -1.0.0 diff --git a/website/api/duk_get_top_index.yaml b/website/api/duk_get_top_index.yaml new file mode 100644 index 00000000..b800c480 --- /dev/null +++ b/website/api/duk_get_top_index.yaml @@ -0,0 +1,26 @@ +name: duk_get_top_index + +proto: | + duk_idx_t duk_get_top_index(duk_context *ctx); + +summary: | +

Get the absolute index (>= 0) of the topmost value on the stack. + If the stack is empty, returns DUK_INVALID_INDEX.

+ +example: | + duk_idx_t idx_top; + + idx_top = duk_get_top_index(ctx); + if (idx_top == DUK_INVALID_INDEX) { + printf("stack is empty\n"); + } else { + printf("index of top element: %ld\n", (long) idx_top); + } + +tags: + - stack + +seealso: + - duk_require_top_index + +introduced: 1.0.0 diff --git a/website/api/duk_get_type.txt b/website/api/duk_get_type.txt deleted file mode 100644 index 032c26dd..00000000 --- a/website/api/duk_get_type.txt +++ /dev/null @@ -1,26 +0,0 @@ -=proto -duk_int_t duk_get_type(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns type of value at index. The return value is one of -DUK_TYPE_xxx or DUK_TYPE_NONE if index is -invalid.

- -=example -if (duk_get_type(ctx, -3) == DUK_TYPE_NUMBER) { - printf("value is a number\n"); -} - -=tags -stack - -=seealso -duk_check_type -duk_get_type_mask -duk_check_type_mask - -=introduced -1.0.0 diff --git a/website/api/duk_get_type.yaml b/website/api/duk_get_type.yaml new file mode 100644 index 00000000..f619a874 --- /dev/null +++ b/website/api/duk_get_type.yaml @@ -0,0 +1,27 @@ +name: duk_get_type + +proto: | + duk_int_t duk_get_type(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns type of value at index. The return value is one of + DUK_TYPE_xxx or DUK_TYPE_NONE if index is + invalid.

+ +example: | + if (duk_get_type(ctx, -3) == DUK_TYPE_NUMBER) { + printf("value is a number\n"); + } + +tags: + - stack + +seealso: + - duk_check_type + - duk_get_type_mask + - duk_check_type_mask + +introduced: 1.0.0 diff --git a/website/api/duk_get_type_mask.txt b/website/api/duk_get_type_mask.txt deleted file mode 100644 index d105c796..00000000 --- a/website/api/duk_get_type_mask.txt +++ /dev/null @@ -1,30 +0,0 @@ -=proto -duk_uint_t duk_get_type_mask(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns type mask of value at index. The return value is one of -DUK_TYPE_MASK_xxx or DUK_TYPE_MASK_NONE if index -is invalid.

- -

Type masks allow e.g. for a convenient comparison for multiple types at once -(the duk_check_type_mask() call is -even more convenient for this purpose).

- -=example -if (duk_get_type_mask(ctx, -3) & (DUK_TYPE_MASK_STRING | - DUK_TYPE_MASK_NUMBER)) { - printf("value is a string or a number\n"); -} - -=tags -stack - -=seealso -duk_get_type -duk_check_type_mask - -=introduced -1.0.0 diff --git a/website/api/duk_get_type_mask.yaml b/website/api/duk_get_type_mask.yaml new file mode 100644 index 00000000..8380a11c --- /dev/null +++ b/website/api/duk_get_type_mask.yaml @@ -0,0 +1,31 @@ +name: duk_get_type_mask + +proto: | + duk_uint_t duk_get_type_mask(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns type mask of value at index. The return value is one of + DUK_TYPE_MASK_xxx or DUK_TYPE_MASK_NONE if index + is invalid.

+ +

Type masks allow e.g. for a convenient comparison for multiple types at once + (the duk_check_type_mask() call is + even more convenient for this purpose).

+ +example: | + if (duk_get_type_mask(ctx, -3) & (DUK_TYPE_MASK_STRING | + DUK_TYPE_MASK_NUMBER)) { + printf("value is a string or a number\n"); + } + +tags: + - stack + +seealso: + - duk_get_type + - duk_check_type_mask + +introduced: 1.0.0 diff --git a/website/api/duk_get_uint.txt b/website/api/duk_get_uint.txt deleted file mode 100644 index e64d6776..00000000 --- a/website/api/duk_get_uint.txt +++ /dev/null @@ -1,42 +0,0 @@ -=proto -duk_uint_t duk_get_uint(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Get the number at index and convert it to a C duk_uint_t -by first clamping the value between [0, DUK_UINT_MAX] and then -truncating towards zero. The value on the stack is not modified. -If the value is a NaN, is not a number, or the index is invalid, -returns 0.

- -

Conversion examples:

- - - - - - - - - - -
InputOutput
-Infinity0
-10
-3.90
3.93
DUK_UINT_MAX + 1DUK_UINT_MAX
+InfinityDUK_UINT_MAX
NaN0
"123"0 (non-number)
- -
-The coercion is different from a basic C cast from double to -unsigned integer, which may have counterintuitive (and non-portable) behavior -for e.g. NaN values. The coercion is also different from Ecmascript -ToUint32() coercion because the full range of the native -duk_uint_t is allowed (which may be more than 32 bits). -
- -=example -printf("unsigned int value: %lu\n", (unsigned long) duk_get_uint(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_get_uint.yaml b/website/api/duk_get_uint.yaml new file mode 100644 index 00000000..1cc9605b --- /dev/null +++ b/website/api/duk_get_uint.yaml @@ -0,0 +1,43 @@ +name: duk_get_uint + +proto: | + duk_uint_t duk_get_uint(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Get the number at index and convert it to a C duk_uint_t + by first clamping the value between [0, DUK_UINT_MAX] and then + truncating towards zero. The value on the stack is not modified. + If the value is a NaN, is not a number, or the index is invalid, + returns 0.

+ +

Conversion examples:

+ + + + + + + + + + +
InputOutput
-Infinity0
-10
-3.90
3.93
DUK_UINT_MAX + 1DUK_UINT_MAX
+InfinityDUK_UINT_MAX
NaN0
"123"0 (non-number)
+ +
+ The coercion is different from a basic C cast from double to + unsigned integer, which may have counterintuitive (and non-portable) behavior + for e.g. NaN values. The coercion is also different from Ecmascript + ToUint32() coercion because the full range of the native + duk_uint_t is allowed (which may be more than 32 bits). +
+ +example: | + printf("unsigned int value: %lu\n", (unsigned long) duk_get_uint(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_get_var.txt b/website/api/duk_get_var.txt deleted file mode 100644 index ade7b758..00000000 --- a/website/api/duk_get_var.txt +++ /dev/null @@ -1,49 +0,0 @@ -=proto -void duk_get_var(duk_context *ctx); - -=stack -[ ... varname! ] -> [ ... val! ] - -=summary -

Look up identifier varname. Possible outcomes:

-
    -
  • If identifier is found, replaces varname with its value on the - value stack and returns.
    • -
  • If identifier is not found, throws a ReferenceError (this applies - to both strict and non-strict code).
    • -
  • If the input stack is empty (or some other internal error occurs), - throws an error.
    • -
- -

The identifier lookup is equivalent to the Ecmascript expression:

-
-varname
-
- -

For semantics, see -Identifier Resolution, -GetIdentifierReference (lex, name, strict), -Identifier Reference, -GetValue (V). -Ecmascript semantics require that a ReferenceError be thrown if the identifier -cannot be resolved (this is the case even in non-strict mode). -

- -
-Because Duktape/C functions cannot currently be nested functions, their -outer lexical environment is always the global environment. -
- -=example -duk_push_string(ctx, "Math"); -duk_get_var(ctx); /* [ ... "Math" ] -> [ ... Math ] */ -duk_get_prop_string(ctx, -1, "PI"); /* -> [ ... Math PI ] */ -printf("Math.PI=%lf\n", (double) duk_get_number(ctx, -1)); -duk_pop_2(ctx); - -=tags -variable -omit - -=introduced -1.0.0 diff --git a/website/api/duk_get_var.yaml b/website/api/duk_get_var.yaml new file mode 100644 index 00000000..69b43b83 --- /dev/null +++ b/website/api/duk_get_var.yaml @@ -0,0 +1,50 @@ +name: duk_get_var + +proto: | + void duk_get_var(duk_context *ctx); + +stack: | + [ ... varname! ] -> [ ... val! ] + +summary: | +

Look up identifier varname. Possible outcomes:

+
    +
  • If identifier is found, replaces varname with its value on the + value stack and returns.
    • +
  • If identifier is not found, throws a ReferenceError (this applies + to both strict and non-strict code).
    • +
  • If the input stack is empty (or some other internal error occurs), + throws an error.
    • +
+ +

The identifier lookup is equivalent to the Ecmascript expression:

+ 
+  varname
+
+ +

For semantics, see + Identifier Resolution, + GetIdentifierReference (lex, name, strict), + Identifier Reference, + GetValue (V). + Ecmascript semantics require that a ReferenceError be thrown if the identifier + cannot be resolved (this is the case even in non-strict mode). +

+ +
+ Because Duktape/C functions cannot currently be nested functions, their + outer lexical environment is always the global environment. +
+ +example: | + duk_push_string(ctx, "Math"); + duk_get_var(ctx); /* [ ... "Math" ] -> [ ... Math ] */ + duk_get_prop_string(ctx, -1, "PI"); /* -> [ ... Math PI ] */ + printf("Math.PI=%lf\n", (double) duk_get_number(ctx, -1)); + duk_pop_2(ctx); + +tags: + - variable + - omit + +introduced: 1.0.0 diff --git a/website/api/duk_has_prop.txt b/website/api/duk_has_prop.txt deleted file mode 100644 index 0e236549..00000000 --- a/website/api/duk_has_prop.txt +++ /dev/null @@ -1,68 +0,0 @@ -=proto -duk_bool_t duk_has_prop(duk_context *ctx, duk_idx_t obj_index); - -=stack -[ ... obj! ... key! ] -> [ ... obj! ... ] - -=summary -

Check whether value at obj_index has a property key. -key is removed from the stack. Return code and error throwing -behavior:

-
    -
  • If the property exists, 1 is returned.
    • -
  • If the property doesn't exist, 0 is returned.
    • -
  • If the value at obj_index is not an object, throws an error.
    • -
  • If obj_index is invalid, throws an error.
    • -
- -

The property existence check is equivalent to the Ecmascript expression:

-
-key in obj
-
- -

For semantics, see -Property Accessors, -The in operator, -and [[HasProperty]] (P). -Both the target value and the key are coerced:

-
    -
  • The target value is automatically coerced to an object. For instance, - a string is converted to a String and you can check for its - "length" property.
    • -
  • The key argument is internally coerced to a string. There is - an internal fast path for arrays and numeric indices which avoids an - explicit string coercion, so use a numeric key when applicable.

    -
- -
-Instead of accepting any -object coercible -value (like most property related API calls) this call accepts only an object -as its target value. This is intentional as it follows Ecmascript operator semantics. -
- -

If the key is a fixed string you can avoid one API call and use the -duk_has_prop_string() variant. -Similarly, if the key is an array index, you can use the -duk_has_prop_index() variant.

- -
- -=example -duk_push_string(ctx, "myProperty"); -if (duk_has_prop(ctx, -3)) { - printf("obj has 'myProperty'\n"); -} else { - printf("obj does not have 'myProperty'\n"); -} - -=tags -property -stack - -=seealso -duk_has_prop_string -duk_has_prop_index - -=introduced -1.0.0 diff --git a/website/api/duk_has_prop.yaml b/website/api/duk_has_prop.yaml new file mode 100644 index 00000000..41f789e8 --- /dev/null +++ b/website/api/duk_has_prop.yaml @@ -0,0 +1,69 @@ +name: duk_has_prop + +proto: | + duk_bool_t duk_has_prop(duk_context *ctx, duk_idx_t obj_index); + +stack: | + [ ... obj! ... key! ] -> [ ... obj! ... ] + +summary: | +

Check whether value at obj_index has a property key. + key is removed from the stack. Return code and error throwing + behavior:

+
    +
  • If the property exists, 1 is returned.
    • +
  • If the property doesn't exist, 0 is returned.
    • +
  • If the value at obj_index is not an object, throws an error.
    • +
  • If obj_index is invalid, throws an error.
    • +
+ +

The property existence check is equivalent to the Ecmascript expression:

+ 
+  key in obj
+
+ +

For semantics, see + Property Accessors, + The in operator, + and [[HasProperty]] (P). + Both the target value and the key are coerced:

+
    +
  • The target value is automatically coerced to an object. For instance, + a string is converted to a String and you can check for its + "length" property.
    • +
  • The key argument is internally coerced to a string. There is + an internal fast path for arrays and numeric indices which avoids an + explicit string coercion, so use a numeric key when applicable.

    +
+ +
+ Instead of accepting any + object coercible + value (like most property related API calls) this call accepts only an object + as its target value. This is intentional as it follows Ecmascript operator semantics. +
+ +

If the key is a fixed string you can avoid one API call and use the + duk_has_prop_string() variant. + Similarly, if the key is an array index, you can use the + duk_has_prop_index() variant.

+ +
+ +example: | + duk_push_string(ctx, "myProperty"); + if (duk_has_prop(ctx, -3)) { + printf("obj has 'myProperty'\n"); + } else { + printf("obj does not have 'myProperty'\n"); + } + +tags: + - property + - stack + +seealso: + - duk_has_prop_string + - duk_has_prop_index + +introduced: 1.0.0 diff --git a/website/api/duk_has_prop_index.txt b/website/api/duk_has_prop_index.txt deleted file mode 100644 index a7177a75..00000000 --- a/website/api/duk_has_prop_index.txt +++ /dev/null @@ -1,30 +0,0 @@ -=proto -duk_bool_t duk_has_prop_index(duk_context *ctx, duk_idx_t obj_index, duk_uarridx_t arr_index); - -=stack -[ ... obj! ... ] -> [ ... obj! ... ] - -=summary -

Like duk_has_prop(), -but the property name is given as an unsigned integer -arr_index. This is especially useful for checking -existence of array elements (but is not limited to that).

- -

Conceptually the number is coerced to a string for property -existence check, e.g. 123 would be equivalent to a property -name "123". Duktape avoids an explicit coercion whenever -possible.

- -=example -if (duk_has_prop_index(ctx, -3, 123)) { - printf("obj has index 123\n"); -} else { - printf("obj does not have index 123\n"); -} - -=tags -property -stack - -=introduced -1.0.0 diff --git a/website/api/duk_has_prop_index.yaml b/website/api/duk_has_prop_index.yaml new file mode 100644 index 00000000..aa2b2a69 --- /dev/null +++ b/website/api/duk_has_prop_index.yaml @@ -0,0 +1,31 @@ +name: duk_has_prop_index + +proto: | + duk_bool_t duk_has_prop_index(duk_context *ctx, duk_idx_t obj_index, duk_uarridx_t arr_index); + +stack: | + [ ... obj! ... ] -> [ ... obj! ... ] + +summary: | +

Like duk_has_prop(), + but the property name is given as an unsigned integer + arr_index. This is especially useful for checking + existence of array elements (but is not limited to that).

+ +

Conceptually the number is coerced to a string for property + existence check, e.g. 123 would be equivalent to a property + name "123". Duktape avoids an explicit coercion whenever + possible.

+ +example: | + if (duk_has_prop_index(ctx, -3, 123)) { + printf("obj has index 123\n"); + } else { + printf("obj does not have index 123\n"); + } + +tags: + - property + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_has_prop_string.txt b/website/api/duk_has_prop_string.txt deleted file mode 100644 index c3c492e0..00000000 --- a/website/api/duk_has_prop_string.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -duk_bool_t duk_has_prop_string(duk_context *ctx, duk_idx_t obj_index, const char *key); - -=stack -[ ... obj! ... ] -> [ ... obj! ... ] - -=summary -

Like duk_has_prop(), -but the property name is given as a NUL-terminated C string -key.

- -=example -if (duk_has_prop(ctx, -3, "myProperty")) { - printf("obj has 'myProperty'\n"); -} else { - printf("obj does not have 'myProperty'\n"); -} - -=tags -property -stack - -=introduced -1.0.0 diff --git a/website/api/duk_has_prop_string.yaml b/website/api/duk_has_prop_string.yaml new file mode 100644 index 00000000..cb693f6e --- /dev/null +++ b/website/api/duk_has_prop_string.yaml @@ -0,0 +1,25 @@ +name: duk_has_prop_string + +proto: | + duk_bool_t duk_has_prop_string(duk_context *ctx, duk_idx_t obj_index, const char *key); + +stack: | + [ ... obj! ... ] -> [ ... obj! ... ] + +summary: | +

Like duk_has_prop(), + but the property name is given as a NUL-terminated C string + key.

+ +example: | + if (duk_has_prop(ctx, -3, "myProperty")) { + printf("obj has 'myProperty'\n"); + } else { + printf("obj does not have 'myProperty'\n"); + } + +tags: + - property + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_has_var.txt b/website/api/duk_has_var.txt deleted file mode 100644 index f320c02a..00000000 --- a/website/api/duk_has_var.txt +++ /dev/null @@ -1,29 +0,0 @@ -=proto -duk_bool_t duk_has_var(duk_context *ctx); - -=stack -[ ... varname! ] -> [ ... ] - -=summary -XXX - -

The identifier existence check does not have a direct Ecmascript equivalent. -The closest equivalent is:

-
-typeof varname !== 'undefined'
-
- -

However, if the identifier is defined but has the value undefined, -the above check gives a different result than this API call. Note that the -value of the identifier is not looked up and there can thus be no side effects -from e.g. getter calls.

- -=tags -variable -omit - -=example -XXX - -=introduced -1.0.0 diff --git a/website/api/duk_has_var.yaml b/website/api/duk_has_var.yaml new file mode 100644 index 00000000..d977dd2d --- /dev/null +++ b/website/api/duk_has_var.yaml @@ -0,0 +1,30 @@ +name: duk_has_var + +proto: | + duk_bool_t duk_has_var(duk_context *ctx); + +stack: | + [ ... varname! ] -> [ ... ] + +summary: | + XXX + +

The identifier existence check does not have a direct Ecmascript equivalent. + The closest equivalent is:

+ 
+  typeof varname !== 'undefined'
+
+ +

However, if the identifier is defined but has the value undefined, + the above check gives a different result than this API call. Note that the + value of the identifier is not looked up and there can thus be no side effects + from e.g. getter calls.

+ +example: | + XXX + +tags: + - variable + - omit + +introduced: 1.0.0 diff --git a/website/api/duk_hex_decode.txt b/website/api/duk_hex_decode.txt deleted file mode 100644 index 4dfe0488..00000000 --- a/website/api/duk_hex_decode.txt +++ /dev/null @@ -1,28 +0,0 @@ -=proto -void duk_hex_decode(duk_context *ctx, duk_idx_t index); - -=stack -[ ... hex_val! ... ] -> [ ... val! ... ] - -=summary -

Decodes a hex encoded value into a buffer as an in-place operation. -If the input is invalid, throws an error.

- -=example -duk_push_string(ctx, "7465737420737472696e67"); -duk_hex_decode(ctx, -1); /* buffer */ -printf("hex decoded: %s\n", duk_to_string(ctx, -1)); -duk_pop(ctx); - -/* Output: - * hex decoded: test string - */ - -=tags -codec - -=seealso -duk_hex_encode - -=introduced -1.0.0 diff --git a/website/api/duk_hex_decode.yaml b/website/api/duk_hex_decode.yaml new file mode 100644 index 00000000..b940da59 --- /dev/null +++ b/website/api/duk_hex_decode.yaml @@ -0,0 +1,29 @@ +name: duk_hex_decode + +proto: | + void duk_hex_decode(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... hex_val! ... ] -> [ ... val! ... ] + +summary: | +

Decodes a hex encoded value into a buffer as an in-place operation. + If the input is invalid, throws an error.

+ +example: | + duk_push_string(ctx, "7465737420737472696e67"); + duk_hex_decode(ctx, -1); /* buffer */ + printf("hex decoded: %s\n", duk_to_string(ctx, -1)); + duk_pop(ctx); + + /* Output: + * hex decoded: test string + */ + +tags: + - codec + +seealso: + - duk_hex_encode + +introduced: 1.0.0 diff --git a/website/api/duk_hex_encode.txt b/website/api/duk_hex_encode.txt deleted file mode 100644 index 0512363e..00000000 --- a/website/api/duk_hex_encode.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -const char *duk_hex_encode(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... hex_val! ... ] - -=summary -

Coerces an arbitrary value into a buffer and then encodes the result -into hex as an in-place operation. Returns pointer to the resulting -string for convenience.

- -
-Coercing to a buffer first coerces a non-buffer value into a string, and -then coerces the string into a buffer. The resulting buffer contains the -string in CESU-8 encoding. -
- -=example -duk_push_string(ctx, "foo"); -printf("hex encoded: %s\n", duk_hex_encode(ctx, -1)); - -/* Output: - * hex encoded: 666f6f - */ - -=tags -codec - -=seealso -duk_hex_decode - -=introduced -1.0.0 diff --git a/website/api/duk_hex_encode.yaml b/website/api/duk_hex_encode.yaml new file mode 100644 index 00000000..93db27f5 --- /dev/null +++ b/website/api/duk_hex_encode.yaml @@ -0,0 +1,34 @@ +name: duk_hex_encode + +proto: | + const char *duk_hex_encode(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... hex_val! ... ] + +summary: | +

Coerces an arbitrary value into a buffer and then encodes the result + into hex as an in-place operation. Returns pointer to the resulting + string for convenience.

+ +
+ Coercing to a buffer first coerces a non-buffer value into a string, and + then coerces the string into a buffer. The resulting buffer contains the + string in CESU-8 encoding. +
+ +example: | + duk_push_string(ctx, "foo"); + printf("hex encoded: %s\n", duk_hex_encode(ctx, -1)); + + /* Output: + * hex encoded: 666f6f + */ + +tags: + - codec + +seealso: + - duk_hex_decode + +introduced: 1.0.0 diff --git a/website/api/duk_insert.txt b/website/api/duk_insert.txt deleted file mode 100644 index aae8817a..00000000 --- a/website/api/duk_insert.txt +++ /dev/null @@ -1,32 +0,0 @@ -=proto -void duk_insert(duk_context *ctx, duk_idx_t to_index); - -=stack -[ ... old(to_index)! ... val! ] -> [ ... val(to_index)! old! ... ] - -=summary -

Insert a value at to_index with a value popped from the -stack top. The previous value at to_index and any values -above it are moved up the stack by a step. If to_index is -an invalid index, throws an error.

- -
-Negative indices are evaluated prior to popping the value at the stack -top. This is also illustrated by the example. -
- -=example -duk_push_int(ctx, 123); -duk_push_int(ctx, 234); -duk_push_int(ctx, 345); /* -> [ 123 234 345 ] */ -duk_push_string(ctx, "foo"); /* -> [ 123 234 345 "foo" ] */ -duk_insert(ctx, -3); /* -> [ 123 "foo" 234 345 ] */ - -=tags -stack - -=seealso -duk_replace - -=introduced -1.0.0 diff --git a/website/api/duk_insert.yaml b/website/api/duk_insert.yaml new file mode 100644 index 00000000..086e3e0f --- /dev/null +++ b/website/api/duk_insert.yaml @@ -0,0 +1,33 @@ +name: duk_insert + +proto: | + void duk_insert(duk_context *ctx, duk_idx_t to_index); + +stack: | + [ ... old(to_index)! ... val! ] -> [ ... val(to_index)! old! ... ] + +summary: | +

Insert a value at to_index with a value popped from the + stack top. The previous value at to_index and any values + above it are moved up the stack by a step. If to_index is + an invalid index, throws an error.

+ +
+ Negative indices are evaluated prior to popping the value at the stack + top. This is also illustrated by the example. +
+ +example: | + duk_push_int(ctx, 123); + duk_push_int(ctx, 234); + duk_push_int(ctx, 345); /* -> [ 123 234 345 ] */ + duk_push_string(ctx, "foo"); /* -> [ 123 234 345 "foo" ] */ + duk_insert(ctx, -3); /* -> [ 123 "foo" 234 345 ] */ + +tags: + - stack + +seealso: + - duk_replace + +introduced: 1.0.0 diff --git a/website/api/duk_is_array.txt b/website/api/duk_is_array.txt deleted file mode 100644 index d7f63b4c..00000000 --- a/website/api/duk_is_array.txt +++ /dev/null @@ -1,26 +0,0 @@ -=proto -duk_bool_t duk_is_array(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is an object and is an Ecmascript array -(has the internal class Array), otherwise returns 0. If index -is invalid, also returns 0.

- -

This function returns 1 when the following Ecmascript expression is true:

-
-Object.prototype.toString.call(val) === '[object Array]'
-
- -=example -if (duk_is_array(ctx, -3)) { - /* ... */ -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_is_array.yaml b/website/api/duk_is_array.yaml new file mode 100644 index 00000000..55ea058e --- /dev/null +++ b/website/api/duk_is_array.yaml @@ -0,0 +1,27 @@ +name: duk_is_array + +proto: | + duk_bool_t duk_is_array(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is an object and is an Ecmascript array + (has the internal class Array), otherwise returns 0. If index + is invalid, also returns 0.

+ +

This function returns 1 when the following Ecmascript expression is true:

+ 
+  Object.prototype.toString.call(val) === '[object Array]'
+
+ +example: | + if (duk_is_array(ctx, -3)) { + /* ... */ + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_is_boolean.txt b/website/api/duk_is_boolean.txt deleted file mode 100644 index f6ce196a..00000000 --- a/website/api/duk_is_boolean.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -duk_bool_t duk_is_boolean(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a boolean, otherwise -returns 0. If index is invalid, also returns 0.

- -=example -if (duk_is_boolean(ctx, -3)) { - /* ... */ -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_is_boolean.yaml b/website/api/duk_is_boolean.yaml new file mode 100644 index 00000000..76c170a3 --- /dev/null +++ b/website/api/duk_is_boolean.yaml @@ -0,0 +1,21 @@ +name: duk_is_boolean + +proto: | + duk_bool_t duk_is_boolean(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a boolean, otherwise + returns 0. If index is invalid, also returns 0.

+ +example: | + if (duk_is_boolean(ctx, -3)) { + /* ... */ + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_is_bound_function.txt b/website/api/duk_is_bound_function.txt deleted file mode 100644 index e6102c49..00000000 --- a/website/api/duk_is_bound_function.txt +++ /dev/null @@ -1,28 +0,0 @@ -=proto -duk_bool_t duk_is_bound_function(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a Function object which has -been created with Ecmascript Function.prototype.bind(), -otherwise returns 0. If index is invalid, also returns 0.

- -

Bound functions are an Ecmascript concept: they point to a target -function and supply a this binding and zero or more argument -bindings. See -Function.prototype.bind (thisArg [, arg1 [, arg2, ...]]). -

- -=example -if (duk_is_bound_function(ctx, -3)) { - /* ... */ -} - -=tags -stack -function - -=introduced -1.0.0 diff --git a/website/api/duk_is_bound_function.yaml b/website/api/duk_is_bound_function.yaml new file mode 100644 index 00000000..e9398166 --- /dev/null +++ b/website/api/duk_is_bound_function.yaml @@ -0,0 +1,29 @@ +name: duk_is_bound_function + +proto: | + duk_bool_t duk_is_bound_function(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a Function object which has + been created with Ecmascript Function.prototype.bind(), + otherwise returns 0. If index is invalid, also returns 0.

+ +

Bound functions are an Ecmascript concept: they point to a target + function and supply a this binding and zero or more argument + bindings. See + Function.prototype.bind (thisArg [, arg1 [, arg2, ...]]). +

+ +example: | + if (duk_is_bound_function(ctx, -3)) { + /* ... */ + } + +tags: + - stack + - function + +introduced: 1.0.0 diff --git a/website/api/duk_is_buffer.txt b/website/api/duk_is_buffer.txt deleted file mode 100644 index f1340b43..00000000 --- a/website/api/duk_is_buffer.txt +++ /dev/null @@ -1,21 +0,0 @@ -=proto -duk_bool_t duk_is_buffer(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a buffer, otherwise -returns 0. If index is invalid, also returns 0.

- -=example -if (duk_is_buffer(ctx, -3)) { - /* ... */ -} - -=tags -stack -buffer - -=introduced -1.0.0 diff --git a/website/api/duk_is_buffer.yaml b/website/api/duk_is_buffer.yaml new file mode 100644 index 00000000..2a920546 --- /dev/null +++ b/website/api/duk_is_buffer.yaml @@ -0,0 +1,22 @@ +name: duk_is_buffer + +proto: | + duk_bool_t duk_is_buffer(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a buffer, otherwise + returns 0. If index is invalid, also returns 0.

+ +example: | + if (duk_is_buffer(ctx, -3)) { + /* ... */ + } + +tags: + - stack + - buffer + +introduced: 1.0.0 diff --git a/website/api/duk_is_c_function.txt b/website/api/duk_is_c_function.txt deleted file mode 100644 index 7d7ae3df..00000000 --- a/website/api/duk_is_c_function.txt +++ /dev/null @@ -1,30 +0,0 @@ -=proto -duk_bool_t duk_is_c_function(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a Function object and is -assocated with a C function, otherwise returns 0. -If index is invalid, also returns 0.

- -

An example of an underlying C function observing the Duktape/C API -calling convention:

-
-int my_func(duk_context *ctx) {
-    /* ... */
-}
-
- -=example -if (duk_is_c_function(ctx, -3)) { - /* ... */ -} - -=tags -stack -function - -=introduced -1.0.0 diff --git a/website/api/duk_is_c_function.yaml b/website/api/duk_is_c_function.yaml new file mode 100644 index 00000000..3f15dcd5 --- /dev/null +++ b/website/api/duk_is_c_function.yaml @@ -0,0 +1,31 @@ +name: duk_is_c_function + +proto: | + duk_bool_t duk_is_c_function(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a Function object and is + assocated with a C function, otherwise returns 0. + If index is invalid, also returns 0.

+ +

An example of an underlying C function observing the Duktape/C API + calling convention:

+ 
+  int my_func(duk_context *ctx) {
+      /* ... */
+  }
+
+ +example: | + if (duk_is_c_function(ctx, -3)) { + /* ... */ + } + +tags: + - stack + - function + +introduced: 1.0.0 diff --git a/website/api/duk_is_callable.txt b/website/api/duk_is_callable.txt deleted file mode 100644 index 7bbc3f3c..00000000 --- a/website/api/duk_is_callable.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -duk_bool_t duk_is_callable(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Return 1 if value at index is callable, otherwise returns 0. -Also returns 0 if index is invalid.

- -

Currently this is the same as -duk_is_function().

- -=example -if (duk_is_callable(ctx, -3)) { - /* ... */ -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_is_callable.yaml b/website/api/duk_is_callable.yaml new file mode 100644 index 00000000..2061c95c --- /dev/null +++ b/website/api/duk_is_callable.yaml @@ -0,0 +1,24 @@ +name: duk_is_callable + +proto: | + duk_bool_t duk_is_callable(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Return 1 if value at index is callable, otherwise returns 0. + Also returns 0 if index is invalid.

+ +

Currently this is the same as + duk_is_function().

+ +example: | + if (duk_is_callable(ctx, -3)) { + /* ... */ + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_is_constructor_call.txt b/website/api/duk_is_constructor_call.txt deleted file mode 100644 index 051154ba..00000000 --- a/website/api/duk_is_constructor_call.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_bool_t duk_is_constructor_call(duk_context *ctx); - -=summary -

Return non-zero if current function was called as a constructor -(new Foo() instead of Foo()); otherwise returns 0.

- -

This call allows a C function to have different behavior for normal -and constructor calls (as is the case for many built-in functions).

- -=example -if (duk_is_constructor_call(ctx)) { - printf("called as a constructor\n"); -} else { - printf("called as a normal function\n"); -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_is_constructor_call.yaml b/website/api/duk_is_constructor_call.yaml new file mode 100644 index 00000000..eba874de --- /dev/null +++ b/website/api/duk_is_constructor_call.yaml @@ -0,0 +1,23 @@ +name: duk_is_constructor_call + +proto: | + duk_bool_t duk_is_constructor_call(duk_context *ctx); + +summary: | +

Return non-zero if current function was called as a constructor + (new Foo() instead of Foo()); otherwise returns 0.

+ +

This call allows a C function to have different behavior for normal + and constructor calls (as is the case for many built-in functions).

+ +example: | + if (duk_is_constructor_call(ctx)) { + printf("called as a constructor\n"); + } else { + printf("called as a normal function\n"); + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_is_dynamic_buffer.txt b/website/api/duk_is_dynamic_buffer.txt deleted file mode 100644 index 25c40009..00000000 --- a/website/api/duk_is_dynamic_buffer.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_bool_t duk_is_dynamic_buffer(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a dynamic buffer, -otherwise returns 0. If index is invalid, also -returns 0.

- -=example -if (duk_is_dynamic_buffer(ctx, -3)) { - /* ... */ -} - -=tags -stack -buffer - -=introduced -1.0.0 diff --git a/website/api/duk_is_dynamic_buffer.yaml b/website/api/duk_is_dynamic_buffer.yaml new file mode 100644 index 00000000..b587f4f2 --- /dev/null +++ b/website/api/duk_is_dynamic_buffer.yaml @@ -0,0 +1,23 @@ +name: duk_is_dynamic_buffer + +proto: | + duk_bool_t duk_is_dynamic_buffer(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a dynamic buffer, + otherwise returns 0. If index is invalid, also + returns 0.

+ +example: | + if (duk_is_dynamic_buffer(ctx, -3)) { + /* ... */ + } + +tags: + - stack + - buffer + +introduced: 1.0.0 diff --git a/website/api/duk_is_ecmascript_function.txt b/website/api/duk_is_ecmascript_function.txt deleted file mode 100644 index 4c99649f..00000000 --- a/website/api/duk_is_ecmascript_function.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -duk_bool_t duk_is_ecmascript_function(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a Function object which has -been compiled from Ecmascript source code, otherwise returns 0. -If index is invalid, also returns 0.

- -

Internally Ecmascript functions are compiled into bytecode and executed -with the Ecmascript bytecode interpreter.

- -=example -if (duk_is_ecmascript_function(ctx, -3)) { - /* ... */ -} - -=tags -stack -function - -=introduced -1.0.0 diff --git a/website/api/duk_is_ecmascript_function.yaml b/website/api/duk_is_ecmascript_function.yaml new file mode 100644 index 00000000..dc979276 --- /dev/null +++ b/website/api/duk_is_ecmascript_function.yaml @@ -0,0 +1,26 @@ +name: duk_is_ecmascript_function + +proto: | + duk_bool_t duk_is_ecmascript_function(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a Function object which has + been compiled from Ecmascript source code, otherwise returns 0. + If index is invalid, also returns 0.

+ +

Internally Ecmascript functions are compiled into bytecode and executed + with the Ecmascript bytecode interpreter.

+ +example: | + if (duk_is_ecmascript_function(ctx, -3)) { + /* ... */ + } + +tags: + - stack + - function + +introduced: 1.0.0 diff --git a/website/api/duk_is_error.txt b/website/api/duk_is_error.txt deleted file mode 100644 index 54e143f6..00000000 --- a/website/api/duk_is_error.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -duk_bool_t duk_is_error(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index inherits from Error, -otherwise returns 0. If index is invalid, also returns 0.

- -=example -if (duk_is_error(ctx, -3)) { - /* Inherits from Error, attempt to print stack trace */ - duk_get_prop_string(ctx, -3, "stack"); - printf("%s\n", duk_safe_to_string(ctx, -1)); - duk_pop(ctx); -} - -=tags -stack -error - -=introduced -1.1.0 diff --git a/website/api/duk_is_error.yaml b/website/api/duk_is_error.yaml new file mode 100644 index 00000000..a854f6af --- /dev/null +++ b/website/api/duk_is_error.yaml @@ -0,0 +1,25 @@ +name: duk_is_error + +proto: | + duk_bool_t duk_is_error(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index inherits from Error, + otherwise returns 0. If index is invalid, also returns 0.

+ +example: | + if (duk_is_error(ctx, -3)) { + /* Inherits from Error, attempt to print stack trace */ + duk_get_prop_string(ctx, -3, "stack"); + printf("%s\n", duk_safe_to_string(ctx, -1)); + duk_pop(ctx); + } + +tags: + - stack + - error + +introduced: 1.1.0 diff --git a/website/api/duk_is_fixed_buffer.txt b/website/api/duk_is_fixed_buffer.txt deleted file mode 100644 index 319d04fe..00000000 --- a/website/api/duk_is_fixed_buffer.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_bool_t duk_is_fixed_buffer(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a fixed buffer, -otherwise returns 0. If index is invalid, also -returns 0.

- -=example -if (duk_is_fixed_buffer(ctx, -3)) { - /* ... */ -} - -=tags -stack -buffer - -=introduced -1.0.0 diff --git a/website/api/duk_is_fixed_buffer.yaml b/website/api/duk_is_fixed_buffer.yaml new file mode 100644 index 00000000..9d9ca6a8 --- /dev/null +++ b/website/api/duk_is_fixed_buffer.yaml @@ -0,0 +1,23 @@ +name: duk_is_fixed_buffer + +proto: | + duk_bool_t duk_is_fixed_buffer(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a fixed buffer, + otherwise returns 0. If index is invalid, also + returns 0.

+ +example: | + if (duk_is_fixed_buffer(ctx, -3)) { + /* ... */ + } + +tags: + - stack + - buffer + +introduced: 1.0.0 diff --git a/website/api/duk_is_function.txt b/website/api/duk_is_function.txt deleted file mode 100644 index a7561c21..00000000 --- a/website/api/duk_is_function.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -duk_bool_t duk_is_function(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is an object and is a function (has the -internal class Function), otherwise returns 0. If index is -invalid, also returns 0.

- -

This function returns 1 when the following Ecmascript expression is true:

-
-Object.prototype.toString.call(val) === '[object Function]'
-
- -

To determine the specific type of the function, use:

- - -=example -if (duk_is_function(ctx, -3)) { - /* ... */ -} - -=tags -stack -function - -=introduced -1.0.0 diff --git a/website/api/duk_is_function.yaml b/website/api/duk_is_function.yaml new file mode 100644 index 00000000..da102f51 --- /dev/null +++ b/website/api/duk_is_function.yaml @@ -0,0 +1,35 @@ +name: duk_is_function + +proto: | + duk_bool_t duk_is_function(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is an object and is a function (has the + internal class Function), otherwise returns 0. If index is + invalid, also returns 0.

+ +

This function returns 1 when the following Ecmascript expression is true:

+ 
+  Object.prototype.toString.call(val) === '[object Function]'
+
+ +

To determine the specific type of the function, use:

+ + +example: | + if (duk_is_function(ctx, -3)) { + /* ... */ + } + +tags: + - stack + - function + +introduced: 1.0.0 diff --git a/website/api/duk_is_lightfunc.txt b/website/api/duk_is_lightfunc.txt deleted file mode 100644 index c4429fd3..00000000 --- a/website/api/duk_is_lightfunc.txt +++ /dev/null @@ -1,17 +0,0 @@ -=proto -duk_bool_t duk_is_lightfunc(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a lightfunc, otherwise -returns 0. If index is invalid, also returns 0.

- -=example -if (duk_is_lightfunc(ctx, -3)) { - /* ... */ -} - -=tags -stack diff --git a/website/api/duk_is_lightfunc.yaml b/website/api/duk_is_lightfunc.yaml new file mode 100644 index 00000000..243825f2 --- /dev/null +++ b/website/api/duk_is_lightfunc.yaml @@ -0,0 +1,19 @@ +name: duk_is_lightfunc + +proto: | + duk_bool_t duk_is_lightfunc(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a lightfunc, otherwise + returns 0. If index is invalid, also returns 0.

+ +example: | + if (duk_is_lightfunc(ctx, -3)) { + /* ... */ + } + +tags: + - stack diff --git a/website/api/duk_is_nan.txt b/website/api/duk_is_nan.txt deleted file mode 100644 index bca06270..00000000 --- a/website/api/duk_is_nan.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -duk_bool_t duk_is_nan(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a NaN (a special -number value), otherwise returns 0. If index is invalid, -also returns 0.

- -

IEEE has a large number of different NaN values. Duktape -normalizes NaN values internally. This function returns 1 -for any kind of a NaN.

- -=example -if (duk_is_nan(ctx, -3)) { - /* ... */ -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_is_nan.yaml b/website/api/duk_is_nan.yaml new file mode 100644 index 00000000..c5ba6090 --- /dev/null +++ b/website/api/duk_is_nan.yaml @@ -0,0 +1,26 @@ +name: duk_is_nan + +proto: | + duk_bool_t duk_is_nan(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a NaN (a special + number value), otherwise returns 0. If index is invalid, + also returns 0.

+ +

IEEE has a large number of different NaN values. Duktape + normalizes NaN values internally. This function returns 1 + for any kind of a NaN.

+ +example: | + if (duk_is_nan(ctx, -3)) { + /* ... */ + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_is_null.txt b/website/api/duk_is_null.txt deleted file mode 100644 index 09042674..00000000 --- a/website/api/duk_is_null.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -duk_bool_t duk_is_null(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is either null, otherwise -returns 0. If index is invalid, also returns 0.

- -=example -if (duk_is_null(ctx, -3)) { - /* ... */ -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_is_null.yaml b/website/api/duk_is_null.yaml new file mode 100644 index 00000000..be73f09d --- /dev/null +++ b/website/api/duk_is_null.yaml @@ -0,0 +1,21 @@ +name: duk_is_null + +proto: | + duk_bool_t duk_is_null(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is either null, otherwise + returns 0. If index is invalid, also returns 0.

+ +example: | + if (duk_is_null(ctx, -3)) { + /* ... */ + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_is_null_or_undefined.txt b/website/api/duk_is_null_or_undefined.txt deleted file mode 100644 index a28f0cc3..00000000 --- a/website/api/duk_is_null_or_undefined.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -duk_bool_t duk_is_null_or_undefined(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is either null or undefined, -otherwise returns 0. If index is invalid, also returns 0.

- -

This API call is similar to a (x == null) comparison in Ecmascript, which -is true for both null and undefined.

- -=example -if (duk_is_null_or_undefined(ctx, -3)) { - /* ... */ -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_is_null_or_undefined.yaml b/website/api/duk_is_null_or_undefined.yaml new file mode 100644 index 00000000..a618d519 --- /dev/null +++ b/website/api/duk_is_null_or_undefined.yaml @@ -0,0 +1,24 @@ +name: duk_is_null_or_undefined + +proto: | + duk_bool_t duk_is_null_or_undefined(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is either null or undefined, + otherwise returns 0. If index is invalid, also returns 0.

+ +

This API call is similar to a (x == null) comparison in Ecmascript, which + is true for both null and undefined.

+ +example: | + if (duk_is_null_or_undefined(ctx, -3)) { + /* ... */ + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_is_number.txt b/website/api/duk_is_number.txt deleted file mode 100644 index 952f479f..00000000 --- a/website/api/duk_is_number.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -duk_bool_t duk_is_number(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a number, otherwise -returns 0. If index is invalid, also returns 0.

- -=example -if (duk_is_number(ctx, -3)) { - /* ... */ -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_is_number.yaml b/website/api/duk_is_number.yaml new file mode 100644 index 00000000..a6ecbbcd --- /dev/null +++ b/website/api/duk_is_number.yaml @@ -0,0 +1,21 @@ +name: duk_is_number + +proto: | + duk_bool_t duk_is_number(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a number, otherwise + returns 0. If index is invalid, also returns 0.

+ +example: | + if (duk_is_number(ctx, -3)) { + /* ... */ + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_is_object.txt b/website/api/duk_is_object.txt deleted file mode 100644 index 90992b75..00000000 --- a/website/api/duk_is_object.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -duk_bool_t duk_is_object(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is an object, otherwise -returns 0. If index is invalid, also returns 0.

- -

Note that many values are considered to be an object, e.g.:

- -
    -
  • Ecmascript object
    • -
  • Ecmascript array
    • -
  • Ecmascript function
    • -
  • Duktape thread (coroutine)
    • -
  • Duktape internal objects
    • -
- -

Specific object types can be checked with separate API calls, -e.g. duk_is_array().

- -=example -if (duk_is_object(ctx, -3)) { - /* ... */ -} - -=tags -stack -object - -=introduced -1.0.0 diff --git a/website/api/duk_is_object.yaml b/website/api/duk_is_object.yaml new file mode 100644 index 00000000..7174e088 --- /dev/null +++ b/website/api/duk_is_object.yaml @@ -0,0 +1,35 @@ +name: duk_is_object + +proto: | + duk_bool_t duk_is_object(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is an object, otherwise + returns 0. If index is invalid, also returns 0.

+ +

Note that many values are considered to be an object, e.g.:

+ +
    +
  • Ecmascript object
    • +
  • Ecmascript array
    • +
  • Ecmascript function
    • +
  • Duktape thread (coroutine)
    • +
  • Duktape internal objects
    • +
+ +

Specific object types can be checked with separate API calls, + e.g. duk_is_array().

+ +example: | + if (duk_is_object(ctx, -3)) { + /* ... */ + } + +tags: + - stack + - object + +introduced: 1.0.0 diff --git a/website/api/duk_is_object_coercible.txt b/website/api/duk_is_object_coercible.txt deleted file mode 100644 index 92caa8e9..00000000 --- a/website/api/duk_is_object_coercible.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -duk_bool_t duk_is_object_coercible(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is object coercible, as defined in -CheckObjectCoercible, -otherwise returns 0. If index is invalid, also returns 0.

- -

All Ecmascript types are object coercible except undefined and -null. The custom buffer and pointer types are object coercible.

- -=example -if (duk_is_object_coercible(ctx, -3)) { - /* ... */ -} - -=tags -stack -object - -=introduced -1.0.0 diff --git a/website/api/duk_is_object_coercible.yaml b/website/api/duk_is_object_coercible.yaml new file mode 100644 index 00000000..b300ce84 --- /dev/null +++ b/website/api/duk_is_object_coercible.yaml @@ -0,0 +1,26 @@ +name: duk_is_object_coercible + +proto: | + duk_bool_t duk_is_object_coercible(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is object coercible, as defined in + CheckObjectCoercible, + otherwise returns 0. If index is invalid, also returns 0.

+ +

All Ecmascript types are object coercible except undefined and + null. The custom buffer and pointer types are object coercible.

+ +example: | + if (duk_is_object_coercible(ctx, -3)) { + /* ... */ + } + +tags: + - stack + - object + +introduced: 1.0.0 diff --git a/website/api/duk_is_pointer.txt b/website/api/duk_is_pointer.txt deleted file mode 100644 index 39fdf0e2..00000000 --- a/website/api/duk_is_pointer.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -duk_bool_t duk_is_pointer(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a pointer, otherwise -returns 0. If index is invalid, also returns 0.

- -=example -if (duk_is_pointer(ctx, -3)) { - /* ... */ -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_is_pointer.yaml b/website/api/duk_is_pointer.yaml new file mode 100644 index 00000000..2d9bc65b --- /dev/null +++ b/website/api/duk_is_pointer.yaml @@ -0,0 +1,21 @@ +name: duk_is_pointer + +proto: | + duk_bool_t duk_is_pointer(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a pointer, otherwise + returns 0. If index is invalid, also returns 0.

+ +example: | + if (duk_is_pointer(ctx, -3)) { + /* ... */ + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_is_primitive.txt b/website/api/duk_is_primitive.txt deleted file mode 100644 index e1b7a127..00000000 --- a/website/api/duk_is_primitive.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -duk_bool_t duk_is_primitive(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a primitive type, as defined in -ToPrimitive, -otherwise returns 0. If index is invalid, also returns 0.

- -

Anything other than an object is a primitive type at the moment, including -custom buffer and pointer types.

- -=example -if (duk_is_primitive(ctx, -3)) { - /* ... */ -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_is_primitive.yaml b/website/api/duk_is_primitive.yaml new file mode 100644 index 00000000..eb6d84f0 --- /dev/null +++ b/website/api/duk_is_primitive.yaml @@ -0,0 +1,25 @@ +name: duk_is_primitive + +proto: | + duk_bool_t duk_is_primitive(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a primitive type, as defined in + ToPrimitive, + otherwise returns 0. If index is invalid, also returns 0.

+ +

Anything other than an object is a primitive type at the moment, including + custom buffer and pointer types.

+ +example: | + if (duk_is_primitive(ctx, -3)) { + /* ... */ + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_is_strict_call.txt b/website/api/duk_is_strict_call.txt deleted file mode 100644 index b4cb344e..00000000 --- a/website/api/duk_is_strict_call.txt +++ /dev/null @@ -1,21 +0,0 @@ -=proto -duk_bool_t duk_is_strict_call(duk_context *ctx); - -=summary -

Check whether the current (Duktape/C) function call is strict or not. -Returns 1 if the current function call is strict, 0 otherwise. As of -Duktape 0.12.0, this function always returns 1 when called from user code -(even if the call stack is empty).

- -=example -if (duk_is_strict_call(ctx)) { - printf("strict call\n"); -} else { - printf("non-strict call\n"); -} - -=tags -function - -=introduced -1.0.0 diff --git a/website/api/duk_is_strict_call.yaml b/website/api/duk_is_strict_call.yaml new file mode 100644 index 00000000..79a89d07 --- /dev/null +++ b/website/api/duk_is_strict_call.yaml @@ -0,0 +1,22 @@ +name: duk_is_strict_call + +proto: | + duk_bool_t duk_is_strict_call(duk_context *ctx); + +summary: | +

Check whether the current (Duktape/C) function call is strict or not. + Returns 1 if the current function call is strict, 0 otherwise. As of + Duktape 0.12.0, this function always returns 1 when called from user code + (even if the call stack is empty).

+ +example: | + if (duk_is_strict_call(ctx)) { + printf("strict call\n"); + } else { + printf("non-strict call\n"); + } + +tags: + - function + +introduced: 1.0.0 diff --git a/website/api/duk_is_string.txt b/website/api/duk_is_string.txt deleted file mode 100644 index 0f2325c2..00000000 --- a/website/api/duk_is_string.txt +++ /dev/null @@ -1,21 +0,0 @@ -=proto -duk_bool_t duk_is_string(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is a string, otherwise -returns 0. If index is invalid, also returns 0.

- -=example -if (duk_is_string(ctx, -3)) { - /* ... */ -} - -=tags -stack -string - -=introduced -1.0.0 diff --git a/website/api/duk_is_string.yaml b/website/api/duk_is_string.yaml new file mode 100644 index 00000000..ca9da95c --- /dev/null +++ b/website/api/duk_is_string.yaml @@ -0,0 +1,22 @@ +name: duk_is_string + +proto: | + duk_bool_t duk_is_string(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is a string, otherwise + returns 0. If index is invalid, also returns 0.

+ +example: | + if (duk_is_string(ctx, -3)) { + /* ... */ + } + +tags: + - stack + - string + +introduced: 1.0.0 diff --git a/website/api/duk_is_thread.txt b/website/api/duk_is_thread.txt deleted file mode 100644 index 4cb1e0c2..00000000 --- a/website/api/duk_is_thread.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_bool_t duk_is_thread(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is an object and is a Duktape -thread (coroutine), otherwise returns 0. If index is invalid, -also returns 0.

- -=example -if (duk_is_thread(ctx, -3)) { - /* ... */ -} - -=tags -stack -thread - -=introduced -1.0.0 diff --git a/website/api/duk_is_thread.yaml b/website/api/duk_is_thread.yaml new file mode 100644 index 00000000..d5cad085 --- /dev/null +++ b/website/api/duk_is_thread.yaml @@ -0,0 +1,23 @@ +name: duk_is_thread + +proto: | + duk_bool_t duk_is_thread(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is an object and is a Duktape + thread (coroutine), otherwise returns 0. If index is invalid, + also returns 0.

+ +example: | + if (duk_is_thread(ctx, -3)) { + /* ... */ + } + +tags: + - stack + - thread + +introduced: 1.0.0 diff --git a/website/api/duk_is_undefined.txt b/website/api/duk_is_undefined.txt deleted file mode 100644 index 6399d2ba..00000000 --- a/website/api/duk_is_undefined.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -duk_bool_t duk_is_undefined(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Returns 1 if value at index is either undefined, otherwise -returns 0. If index is invalid, also returns 0.

- -=example -if (duk_is_undefined(ctx, -3)) { - /* ... */ -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_is_undefined.yaml b/website/api/duk_is_undefined.yaml new file mode 100644 index 00000000..870b9ba5 --- /dev/null +++ b/website/api/duk_is_undefined.yaml @@ -0,0 +1,21 @@ +name: duk_is_undefined + +proto: | + duk_bool_t duk_is_undefined(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Returns 1 if value at index is either undefined, otherwise + returns 0. If index is invalid, also returns 0.

+ +example: | + if (duk_is_undefined(ctx, -3)) { + /* ... */ + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_is_valid_index.txt b/website/api/duk_is_valid_index.txt deleted file mode 100644 index 6fd1b0a0..00000000 --- a/website/api/duk_is_valid_index.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -duk_bool_t duk_is_valid_index(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Validate argument index, return 1 if index is valid, 0 otherwise.

- -=example -if (duk_is_valid_index(ctx, -3)) { - printf("index -3 is valid\n"); -} else { - printf("index -3 is not valid\n"); -} - -=tags -stack - -=seealso -duk_require_valid_index - -=introduced -1.0.0 diff --git a/website/api/duk_is_valid_index.yaml b/website/api/duk_is_valid_index.yaml new file mode 100644 index 00000000..a0598420 --- /dev/null +++ b/website/api/duk_is_valid_index.yaml @@ -0,0 +1,25 @@ +name: duk_is_valid_index + +proto: | + duk_bool_t duk_is_valid_index(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Validate argument index, return 1 if index is valid, 0 otherwise.

+ +example: | + if (duk_is_valid_index(ctx, -3)) { + printf("index -3 is valid\n"); + } else { + printf("index -3 is not valid\n"); + } + +tags: + - stack + +seealso: + - duk_require_valid_index + +introduced: 1.0.0 diff --git a/website/api/duk_join.txt b/website/api/duk_join.txt deleted file mode 100644 index d0ecf7b2..00000000 --- a/website/api/duk_join.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -void duk_join(duk_context *ctx, duk_idx_t count); - -=stack -[ ... sep! val1! ...! valN! ] -> [ ... result! ] - -=summary -

Join zero or more values into a result string with a separator between -each value. The separator and the input values are automatically coerced -with -ToString().

- -

This primitive minimizes the number of intermediate string interning -operations and is better than joining strings manually.

- -=example -duk_push_string(ctx, "; "); -duk_push_string(ctx, "foo"); -duk_push_int(ctx, 123); -duk_push_true(ctx); -duk_join(ctx, 3); - -printf("result: %s\n", duk_get_string(ctx, -1)); /* "foo; 123; true" */ -duk_pop(ctx); - -=tags -string - -=seealso -duk_concat - -=introduced -1.0.0 diff --git a/website/api/duk_join.yaml b/website/api/duk_join.yaml new file mode 100644 index 00000000..58183d7a --- /dev/null +++ b/website/api/duk_join.yaml @@ -0,0 +1,34 @@ +name: duk_join + +proto: | + void duk_join(duk_context *ctx, duk_idx_t count); + +stack: | + [ ... sep! val1! ...! valN! ] -> [ ... result! ] + +summary: | +

Join zero or more values into a result string with a separator between + each value. The separator and the input values are automatically coerced + with + ToString().

+ +

This primitive minimizes the number of intermediate string interning + operations and is better than joining strings manually.

+ +example: | + duk_push_string(ctx, "; "); + duk_push_string(ctx, "foo"); + duk_push_int(ctx, 123); + duk_push_true(ctx); + duk_join(ctx, 3); + + printf("result: %s\n", duk_get_string(ctx, -1)); /* "foo; 123; true" */ + duk_pop(ctx); + +tags: + - string + +seealso: + - duk_concat + +introduced: 1.0.0 diff --git a/website/api/duk_json_decode.txt b/website/api/duk_json_decode.txt deleted file mode 100644 index 0db9eb02..00000000 --- a/website/api/duk_json_decode.txt +++ /dev/null @@ -1,29 +0,0 @@ -=proto -void duk_json_decode(duk_context *ctx, duk_idx_t index); - -=stack -[ ... json_val! ... ] -> [ ... val! ... ] - -=summary -

Decodes an arbitrary JSON value as an in-place operation. -If the input is invalid, throws an error.

- -=example -duk_push_string(ctx, "{\"meaningOfLife\":42}"); -duk_json_decode(ctx, -1); -duk_get_prop_string(ctx, -1, "meaningOfLife"); -printf("JSON decoded meaningOfLife is: %s\n", duk_to_string(ctx, -1)); -duk_pop_2(ctx); - -/* Output: - * JSON decoded meaningOfLife is: 42 - */ - -=tags -codec - -=seealso -duk_json_encode - -=introduced -1.0.0 diff --git a/website/api/duk_json_decode.yaml b/website/api/duk_json_decode.yaml new file mode 100644 index 00000000..3c791ed3 --- /dev/null +++ b/website/api/duk_json_decode.yaml @@ -0,0 +1,30 @@ +name: duk_json_decode + +proto: | + void duk_json_decode(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... json_val! ... ] -> [ ... val! ... ] + +summary: | +

Decodes an arbitrary JSON value as an in-place operation. + If the input is invalid, throws an error.

+ +example: | + duk_push_string(ctx, "{\"meaningOfLife\":42}"); + duk_json_decode(ctx, -1); + duk_get_prop_string(ctx, -1, "meaningOfLife"); + printf("JSON decoded meaningOfLife is: %s\n", duk_to_string(ctx, -1)); + duk_pop_2(ctx); + + /* Output: + * JSON decoded meaningOfLife is: 42 + */ + +tags: + - codec + +seealso: + - duk_json_encode + +introduced: 1.0.0 diff --git a/website/api/duk_json_encode.txt b/website/api/duk_json_encode.txt deleted file mode 100644 index d4d7ad94..00000000 --- a/website/api/duk_json_encode.txt +++ /dev/null @@ -1,29 +0,0 @@ -=proto -const char *duk_json_encode(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... json_val! ... ] - -=summary -

Encodes an arbitrary value into its JSON representation as an in-place -operation. Returns pointer to the resulting string for convenience.

- -=example -duk_push_object(ctx); -duk_push_int(ctx, 42); -duk_put_prop_string(ctx, -2, "meaningOfLife"); -printf("JSON encoded: %s\n", duk_json_encode(ctx, -1)); -duk_pop(ctx); - -/* Output: - * JSON encoded: {"meaningOfLife":42} - */ - -=tags -codec - -=seealso -duk_json_decode - -=introduced -1.0.0 diff --git a/website/api/duk_json_encode.yaml b/website/api/duk_json_encode.yaml new file mode 100644 index 00000000..eff7bf05 --- /dev/null +++ b/website/api/duk_json_encode.yaml @@ -0,0 +1,30 @@ +name: duk_json_encode + +proto: | + const char *duk_json_encode(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... json_val! ... ] + +summary: | +

Encodes an arbitrary value into its JSON representation as an in-place + operation. Returns pointer to the resulting string for convenience.

+ +example: | + duk_push_object(ctx); + duk_push_int(ctx, 42); + duk_put_prop_string(ctx, -2, "meaningOfLife"); + printf("JSON encoded: %s\n", duk_json_encode(ctx, -1)); + duk_pop(ctx); + + /* Output: + * JSON encoded: {"meaningOfLife":42} + */ + +tags: + - codec + +seealso: + - duk_json_decode + +introduced: 1.0.0 diff --git a/website/api/duk_log.txt b/website/api/duk_log.txt deleted file mode 100644 index 5272ef22..00000000 --- a/website/api/duk_log.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -void duk_log(duk_context *ctx, duk_int_t level, const char *fmt, ...); - -=summary -

Write a formatted log entry with the specified log level (one of -DUK_LOG_xxx). The log write goes through the Duktape -built-in logging facility, see -Logging for details.

- -=example -duk_log(ctx, DUK_LOG_INFO, "received message, type: %d", (int) msg_type); - -=seealso -duk_log_va - -=tags -log - -=introduced -1.0.0 diff --git a/website/api/duk_log.yaml b/website/api/duk_log.yaml new file mode 100644 index 00000000..26b258a1 --- /dev/null +++ b/website/api/duk_log.yaml @@ -0,0 +1,21 @@ +name: duk_log + +proto: | + void duk_log(duk_context *ctx, duk_int_t level, const char *fmt, ...); + +summary: | +

Write a formatted log entry with the specified log level (one of + DUK_LOG_xxx). The log write goes through the Duktape + built-in logging facility, see + Logging for details.

+ +example: | + duk_log(ctx, DUK_LOG_INFO, "received message, type: %d", (int) msg_type); + +tags: + - log + +seealso: + - duk_log_va + +introduced: 1.0.0 diff --git a/website/api/duk_log_va.txt b/website/api/duk_log_va.txt deleted file mode 100644 index 9cc0e60b..00000000 --- a/website/api/duk_log_va.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -void duk_log_va(duk_context *ctx, duk_int_t level, const char *fmt, va_list ap); - -=summary -

Vararg variant of -duk_log().

- -=example -void my_log_info(duk_context *ctx, const char *fmt, ...) { - va_list ap; - - va_start(ap, fmt); - duk_log_va(ctx, DUK_LOG_INFO, fmt, ap); - va_end(ap); -} - -=tags -log -vararg - -=seealso -duk_log - -=introduced -1.1.0 diff --git a/website/api/duk_log_va.yaml b/website/api/duk_log_va.yaml new file mode 100644 index 00000000..daca3e5c --- /dev/null +++ b/website/api/duk_log_va.yaml @@ -0,0 +1,26 @@ +name: duk_log_va + +proto: | + void duk_log_va(duk_context *ctx, duk_int_t level, const char *fmt, va_list ap); + +summary: | +

Vararg variant of + duk_log().

+ +example: | + void my_log_info(duk_context *ctx, const char *fmt, ...) { + va_list ap; + + va_start(ap, fmt); + duk_log_va(ctx, DUK_LOG_INFO, fmt, ap); + va_end(ap); + } + +tags: + - log + - vararg + +seealso: + - duk_log + +introduced: 1.1.0 diff --git a/website/api/duk_map_string.txt b/website/api/duk_map_string.txt deleted file mode 100644 index bb4ee59d..00000000 --- a/website/api/duk_map_string.txt +++ /dev/null @@ -1,35 +0,0 @@ -=proto -void duk_map_string(duk_context *ctx, duk_idx_t index, duk_map_char_function callback, void *udata); - -=stack -[ ... val! ... ] -> [ ... val! ... ] - -=summary -

Process string at index, calling callback for each codepoint -of the string. The callback is given the udata argument and a codepoint -and returns a replacement codepoint. If successful, a new string consisting of -the replacement codepoints replaces the original. If the value is not a string or -the index is invalid, throws an error.

- -=example -static duk_codepoint_t map_char(void *udata, duk_codepoint_t codepoint) { - /* Convert ASCII to uppercase. */ - if (codepoint >= (duk_codepoint_t) 'a' && codepoint <= (duk_codepoint_t) 'z') { - return codepoint - (duk_codepoint_t) 'a' + (duk_codepoint_t) 'A'; - } - return codepoint; -} - -duk_push_string(ctx, "test_string"); -duk_map_string(ctx, -1, map_char, NULL); -printf("result: %s\n", duk_to_string(ctx, -1)); -duk_pop(ctx); - -=tags -string - -=seealso -duk_decode_string - -=introduced -1.0.0 diff --git a/website/api/duk_map_string.yaml b/website/api/duk_map_string.yaml new file mode 100644 index 00000000..9219260f --- /dev/null +++ b/website/api/duk_map_string.yaml @@ -0,0 +1,36 @@ +name: duk_map_string + +proto: | + void duk_map_string(duk_context *ctx, duk_idx_t index, duk_map_char_function callback, void *udata); + +stack: | + [ ... val! ... ] -> [ ... val! ... ] + +summary: | +

Process string at index, calling callback for each codepoint + of the string. The callback is given the udata argument and a codepoint + and returns a replacement codepoint. If successful, a new string consisting of + the replacement codepoints replaces the original. If the value is not a string or + the index is invalid, throws an error.

+ +example: | + static duk_codepoint_t map_char(void *udata, duk_codepoint_t codepoint) { + /* Convert ASCII to uppercase. */ + if (codepoint >= (duk_codepoint_t) 'a' && codepoint <= (duk_codepoint_t) 'z') { + return codepoint - (duk_codepoint_t) 'a' + (duk_codepoint_t) 'A'; + } + return codepoint; + } + + duk_push_string(ctx, "test_string"); + duk_map_string(ctx, -1, map_char, NULL); + printf("result: %s\n", duk_to_string(ctx, -1)); + duk_pop(ctx); + +tags: + - string + +seealso: + - duk_decode_string + +introduced: 1.0.0 diff --git a/website/api/duk_new.txt b/website/api/duk_new.txt deleted file mode 100644 index cb5bbee5..00000000 --- a/website/api/duk_new.txt +++ /dev/null @@ -1,43 +0,0 @@ -=proto -void duk_new(duk_context *ctx, duk_idx_t nargs); - -=stack -[ ... constructor! arg1! ...! argN! ] -> [ ... retval! ] - -=summary -

Call a constructor function with nargs arguments -(not counting the function itself). The function and its arguments -are replaced by a single return value. An error thrown during the -constructor call is not automatically caught.

- -

The target function this binding is set to a freshly -created empty object. If constructor.prototype is an -object, the internal prototype of the new object is set to that -value; otherwise the standard built-in Object prototype -is used as the internal prototype. The return value of the target -function determines what the result of the constructor call is. -If the constructor returns an object, it replaces the fresh empty object; -otherwise the fresh empty object (possibly modified by the constructor) -is returned. -See [[Construct]]. -

- -=example -/* Assume target function is already on stack at func_idx. - * Equivalent to Ecmascript 'new func("foo", 123)'. - */ -duk_idx_t func_idx = /* ... */; - -duk_dup(ctx, func_idx); -duk_push_string(ctx, "foo"); -duk_push_int(ctx, 123); -duk_new(ctx, 2); /* [ ... func "foo" 123 ] -> [ ... res ] */ -printf("result is object: %d\n", (int) duk_is_object(ctx, -1)); -duk_pop(ctx); - -=tags -object -call - -=introduced -1.0.0 diff --git a/website/api/duk_new.yaml b/website/api/duk_new.yaml new file mode 100644 index 00000000..9fc23f89 --- /dev/null +++ b/website/api/duk_new.yaml @@ -0,0 +1,44 @@ +name: duk_new + +proto: | + void duk_new(duk_context *ctx, duk_idx_t nargs); + +stack: | + [ ... constructor! arg1! ...! argN! ] -> [ ... retval! ] + +summary: | +

Call a constructor function with nargs arguments + (not counting the function itself). The function and its arguments + are replaced by a single return value. An error thrown during the + constructor call is not automatically caught.

+ +

The target function this binding is set to a freshly + created empty object. If constructor.prototype is an + object, the internal prototype of the new object is set to that + value; otherwise the standard built-in Object prototype + is used as the internal prototype. The return value of the target + function determines what the result of the constructor call is. + If the constructor returns an object, it replaces the fresh empty object; + otherwise the fresh empty object (possibly modified by the constructor) + is returned. + See [[Construct]]. +

+ +example: | + /* Assume target function is already on stack at func_idx. + * Equivalent to Ecmascript 'new func("foo", 123)'. + */ + duk_idx_t func_idx = /* ... */; + + duk_dup(ctx, func_idx); + duk_push_string(ctx, "foo"); + duk_push_int(ctx, 123); + duk_new(ctx, 2); /* [ ... func "foo" 123 ] -> [ ... res ] */ + printf("result is object: %d\n", (int) duk_is_object(ctx, -1)); + duk_pop(ctx); + +tags: + - object + - call + +introduced: 1.0.0 diff --git a/website/api/duk_next.txt b/website/api/duk_next.txt deleted file mode 100644 index 3c4f5672..00000000 --- a/website/api/duk_next.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -duk_bool_t duk_next(duk_context *ctx, duk_idx_t enum_index, duk_bool_t get_value); - -=stack -[ ... enum! ... ] -> [ ... enum! ... ] (if enum empty; function returns zero) -[ ... enum! ... ] -> [ ... enum! ... key! ] (if enum not empty and get_value == 0; function returns non-zero) -[ ... enum! ... ] -> [ ... enum! ... key! value! ] (if enum not empty and get_value != 0; function returns non-zero) - -=summary -

Get the next key (and optionally value) from an enumerator created with -duk_enum(). If the enumeration has been -exhausted, nothing is pushed to the stack and the function returns zero. -Otherwise the key is pushed to the stack, followed by the value if -get_value is non-zero, and the function returns non-zero. -

- -

Note that getting the value may invoke a getter which may have arbitrary -side effects (and may throw an error).

- -=example -while (duk_next(ctx, enum_idx, 1)) { - printf("key=%s, value=%s\n", duk_to_string(ctx, -2), duk_to_string(ctx, -1)); - duk_pop_2(ctx); -} - -=tags -object -property - -=seealso -duk_enum - -=introduced -1.0.0 diff --git a/website/api/duk_next.yaml b/website/api/duk_next.yaml new file mode 100644 index 00000000..b5dea449 --- /dev/null +++ b/website/api/duk_next.yaml @@ -0,0 +1,35 @@ +name: duk_next + +proto: | + duk_bool_t duk_next(duk_context *ctx, duk_idx_t enum_index, duk_bool_t get_value); + +stack: | + [ ... enum! ... ] -> [ ... enum! ... ] (if enum empty; function returns zero) + [ ... enum! ... ] -> [ ... enum! ... key! ] (if enum not empty and get_value == 0; function returns non-zero) + [ ... enum! ... ] -> [ ... enum! ... key! value! ] (if enum not empty and get_value != 0; function returns non-zero) + +summary: | +

Get the next key (and optionally value) from an enumerator created with + duk_enum(). If the enumeration has been + exhausted, nothing is pushed to the stack and the function returns zero. + Otherwise the key is pushed to the stack, followed by the value if + get_value is non-zero, and the function returns non-zero. +

+ +

Note that getting the value may invoke a getter which may have arbitrary + side effects (and may throw an error).

+ +example: | + while (duk_next(ctx, enum_idx, 1)) { + printf("key=%s, value=%s\n", duk_to_string(ctx, -2), duk_to_string(ctx, -1)); + duk_pop_2(ctx); + } + +tags: + - object + - property + +seealso: + - duk_enum + +introduced: 1.0.0 diff --git a/website/api/duk_normalize_index.txt b/website/api/duk_normalize_index.txt deleted file mode 100644 index a93bd6c7..00000000 --- a/website/api/duk_normalize_index.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -duk_idx_t duk_normalize_index(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Normalize argument index relative to the bottom of the current frame. -The resulting index will be 0 or greater and will be independent of -later stack modifications. If the input index is invalid, returns -DUK_INVALID_INDEX. If you prefer that an error be thrown for -an invalid index, use -duk_require_normalize_index().

- -=example -duk_idx_t idx = duk_normalize_index(-3); - -=tags -stack - -=seealso -duk_require_normalize_index - -=introduced -1.0.0 diff --git a/website/api/duk_normalize_index.yaml b/website/api/duk_normalize_index.yaml new file mode 100644 index 00000000..d9328296 --- /dev/null +++ b/website/api/duk_normalize_index.yaml @@ -0,0 +1,26 @@ +name: duk_normalize_index + +proto: | + duk_idx_t duk_normalize_index(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Normalize argument index relative to the bottom of the current frame. + The resulting index will be 0 or greater and will be independent of + later stack modifications. If the input index is invalid, returns + DUK_INVALID_INDEX. If you prefer that an error be thrown for + an invalid index, use + duk_require_normalize_index().

+ +example: | + duk_idx_t idx = duk_normalize_index(-3); + +tags: + - stack + +seealso: + - duk_require_normalize_index + +introduced: 1.0.0 diff --git a/website/api/duk_pcall.txt b/website/api/duk_pcall.txt deleted file mode 100644 index 21845598..00000000 --- a/website/api/duk_pcall.txt +++ /dev/null @@ -1,66 +0,0 @@ -=proto -duk_int_t duk_pcall(duk_context *ctx, duk_idx_t nargs); - -=stack -[ ... func! arg1! ...! argN! ] -> [ ... retval! ] (if success, return value == 0) -[ ... func! arg1! ...! argN! ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Call target function func with nargs arguments -(not counting the function itself). The function and its arguments -are replaced by a single return value or a single error value. -An error thrown during the function call is caught.

- -

The return value is:

-
    -
  • DUK_EXEC_SUCCESS (0): call succeeded, nargs arguments are replaced - with a single return value. (This return code constant is guaranteed to be zero, so - that one can check for success with a "zero or non-zero" check.)
    • -
  • DUK_EXEC_ERROR: call failed, nargs arguments are replaced with a - single error value. (In exceptional cases, e.g. when there are too few - arguments on the value stack, the call returns non-zero but may leave the stack - in an inconsistent state.)
    • -
- -
-Unlike most Duktape API calls, this call returns zero on success. This allows -multiple error codes to be defined later. -
- -

The target function this binding is initially set to -undefined. If the target function is not strict, the binding -is replaced by the global object before the function is invoked; see -Entering Function Code. -If you want to control the this binding, you can use -duk_pcall_method() or -duk_pcall_prop() instead.

- -=example -/* Assume target function is already on stack at func_idx; the target - * function adds arguments and returns the result. - */ - -duk_idx_t func_idx; -duk_int_t rc; - -duk_dup(ctx, func_idx); -duk_push_int(ctx, 2); -duk_push_int(ctx, 3); -rc = duk_pcall(ctx, 2); /* [ ... func 2 3 ] -> [ 5 ] */ -if (rc == DUK_EXEC_SUCCESS) { - printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); -} else { - printf("error: %s\n", duk_to_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -call -protected - -=seealso -duk_pcall_method -duk_pcall_prop - -=introduced -1.0.0 diff --git a/website/api/duk_pcall.yaml b/website/api/duk_pcall.yaml new file mode 100644 index 00000000..e263e375 --- /dev/null +++ b/website/api/duk_pcall.yaml @@ -0,0 +1,67 @@ +name: duk_pcall + +proto: | + duk_int_t duk_pcall(duk_context *ctx, duk_idx_t nargs); + +stack: | + [ ... func! arg1! ...! argN! ] -> [ ... retval! ] (if success, return value == 0) + [ ... func! arg1! ...! argN! ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Call target function func with nargs arguments + (not counting the function itself). The function and its arguments + are replaced by a single return value or a single error value. + An error thrown during the function call is caught.

+ +

The return value is:

+
    +
  • DUK_EXEC_SUCCESS (0): call succeeded, nargs arguments are replaced + with a single return value. (This return code constant is guaranteed to be zero, so + that one can check for success with a "zero or non-zero" check.)
    • +
  • DUK_EXEC_ERROR: call failed, nargs arguments are replaced with a + single error value. (In exceptional cases, e.g. when there are too few + arguments on the value stack, the call returns non-zero but may leave the stack + in an inconsistent state.)
    • +
+ +
+ Unlike most Duktape API calls, this call returns zero on success. This allows + multiple error codes to be defined later. +
+ +

The target function this binding is initially set to + undefined. If the target function is not strict, the binding + is replaced by the global object before the function is invoked; see + Entering Function Code. + If you want to control the this binding, you can use + duk_pcall_method() or + duk_pcall_prop() instead.

+ +example: | + /* Assume target function is already on stack at func_idx; the target + * function adds arguments and returns the result. + */ + + duk_idx_t func_idx; + duk_int_t rc; + + duk_dup(ctx, func_idx); + duk_push_int(ctx, 2); + duk_push_int(ctx, 3); + rc = duk_pcall(ctx, 2); /* [ ... func 2 3 ] -> [ 5 ] */ + if (rc == DUK_EXEC_SUCCESS) { + printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); + } else { + printf("error: %s\n", duk_to_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - call + - protected + +seealso: + - duk_pcall_method + - duk_pcall_prop + +introduced: 1.0.0 diff --git a/website/api/duk_pcall_method.txt b/website/api/duk_pcall_method.txt deleted file mode 100644 index a3950a94..00000000 --- a/website/api/duk_pcall_method.txt +++ /dev/null @@ -1,43 +0,0 @@ -=proto -duk_int_t duk_pcall_method(duk_context *ctx, duk_idx_t nargs); - -=stack -[ ... func! this! arg! ...! argN! ] -> [ ... retval! ] (if success, return value == 0) -[ ... func! this! arg! ...! argN! ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Like duk_pcall(), but the target function -func is called with an explicit this binding given on the value -stack.

- -=example -/* The target function here prints: - * - * this: 123 - * 2 3 - * - * and returns 5. - */ - -duk_int_t rc; - -duk_push_string(ctx, "function(x,y) { print('this:', this); " - "print(x,y); return x+y; }"); -duk_eval(ctx); /* -> [ ... func ] */ -duk_push_int(ctx, 123); -duk_push_int(ctx, 2); -duk_push_int(ctx, 3); -rc = duk_pcall_method(ctx, 2); /* [ ... func 123 2 3 ] -> [ 5 ] */ -if (rc == DUK_EXEC_SUCCESS) { - printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); /* prints 5 */ -} else { - printf("error: %s\n", duk_to_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -call -protected - -=introduced -1.0.0 diff --git a/website/api/duk_pcall_method.yaml b/website/api/duk_pcall_method.yaml new file mode 100644 index 00000000..dc2ed10b --- /dev/null +++ b/website/api/duk_pcall_method.yaml @@ -0,0 +1,44 @@ +name: duk_pcall_method + +proto: | + duk_int_t duk_pcall_method(duk_context *ctx, duk_idx_t nargs); + +stack: | + [ ... func! this! arg! ...! argN! ] -> [ ... retval! ] (if success, return value == 0) + [ ... func! this! arg! ...! argN! ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Like duk_pcall(), but the target function + func is called with an explicit this binding given on the value + stack.

+ +example: | + /* The target function here prints: + * + * this: 123 + * 2 3 + * + * and returns 5. + */ + + duk_int_t rc; + + duk_push_string(ctx, "function(x,y) { print('this:', this); " + "print(x,y); return x+y; }"); + duk_eval(ctx); /* -> [ ... func ] */ + duk_push_int(ctx, 123); + duk_push_int(ctx, 2); + duk_push_int(ctx, 3); + rc = duk_pcall_method(ctx, 2); /* [ ... func 123 2 3 ] -> [ 5 ] */ + if (rc == DUK_EXEC_SUCCESS) { + printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); /* prints 5 */ + } else { + printf("error: %s\n", duk_to_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - call + - protected + +introduced: 1.0.0 diff --git a/website/api/duk_pcall_prop.txt b/website/api/duk_pcall_prop.txt deleted file mode 100644 index df9e94cd..00000000 --- a/website/api/duk_pcall_prop.txt +++ /dev/null @@ -1,35 +0,0 @@ -=proto -duk_int_t duk_pcall_prop(duk_context *ctx, duk_idx_t obj_index, duk_idx_t nargs); - -=stack -[ ... obj! ... key! arg1! ...! argN! ] -> [ ... obj! ... retval! ] (if success, return value == 0) -[ ... obj! ... key! arg1! ...! argN! ] -> [ ... obj! ... err! ] (if failure, return value != 0) - -=summary -

Like duk_pcall(), but the target function -is looked up from obj.key and obj is used as the function's -this binding.

- -=example -/* obj.myAdderMethod(2,3) -> 5 */ -duk_idx_t obj_idx; -duk_int_t rc; - -duk_push_string(ctx, "myAdderMethod"); -duk_push_int(ctx, 2); -duk_push_int(ctx, 3); -rc = duk_pcall_prop(ctx, obj_idx, 2); /* [ ... "myAdderMethod" 2 3 ] -> [ ... 5 ] */ -if (rc == DUK_EXEC_SUCCESS) { - printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); -} else { - printf("error: %s\n", duk_to_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -property -call -protected - -=introduced -1.0.0 diff --git a/website/api/duk_pcall_prop.yaml b/website/api/duk_pcall_prop.yaml new file mode 100644 index 00000000..240306fd --- /dev/null +++ b/website/api/duk_pcall_prop.yaml @@ -0,0 +1,36 @@ +name: duk_pcall_prop + +proto: | + duk_int_t duk_pcall_prop(duk_context *ctx, duk_idx_t obj_index, duk_idx_t nargs); + +stack: | + [ ... obj! ... key! arg1! ...! argN! ] -> [ ... obj! ... retval! ] (if success, return value == 0) + [ ... obj! ... key! arg1! ...! argN! ] -> [ ... obj! ... err! ] (if failure, return value != 0) + +summary: | +

Like duk_pcall(), but the target function + is looked up from obj.key and obj is used as the function's + this binding.

+ +example: | + /* obj.myAdderMethod(2,3) -> 5 */ + duk_idx_t obj_idx; + duk_int_t rc; + + duk_push_string(ctx, "myAdderMethod"); + duk_push_int(ctx, 2); + duk_push_int(ctx, 3); + rc = duk_pcall_prop(ctx, obj_idx, 2); /* [ ... "myAdderMethod" 2 3 ] -> [ ... 5 ] */ + if (rc == DUK_EXEC_SUCCESS) { + printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); + } else { + printf("error: %s\n", duk_to_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - property + - call + - protected + +introduced: 1.0.0 diff --git a/website/api/duk_pcompile.txt b/website/api/duk_pcompile.txt deleted file mode 100644 index 209213a9..00000000 --- a/website/api/duk_pcompile.txt +++ /dev/null @@ -1,38 +0,0 @@ -=proto -duk_int_t duk_pcompile(duk_context *ctx, duk_uint_t flags); - -=stack -[ ... source! filename! ] -> [ ... function! ] (if success, return value == 0) -[ ... source! filename! ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Like duk_compile() but catches errors -related to compilation (such as syntax errors in the source). A zero return -value indicates success and the compiled function is left on the stack top. -A non-zero return value indicates an error, and the error is left on the stack top.

- -=example -duk_push_string(ctx, "print('program'); syntax error here="); -duk_push_string(ctx, "hello-with-syntax-error"); -if (duk_pcompile(ctx, 0) != 0) { - printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); -} else { - duk_call(ctx, 0); /* [ func ] -> [ result ] */ - printf("program result: %s\n", duk_safe_to_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -compile -protected - -=seealso -duk_compile -duk_pcompile_string -duk_pcompile_string_filename -duk_pcompile_lstring -duk_pcompile_lstring_filename -duk_pcompile_file - -=introduced -1.0.0 diff --git a/website/api/duk_pcompile.yaml b/website/api/duk_pcompile.yaml new file mode 100644 index 00000000..fb6c62f6 --- /dev/null +++ b/website/api/duk_pcompile.yaml @@ -0,0 +1,39 @@ +name: duk_pcompile + +proto: | + duk_int_t duk_pcompile(duk_context *ctx, duk_uint_t flags); + +stack: | + [ ... source! filename! ] -> [ ... function! ] (if success, return value == 0) + [ ... source! filename! ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Like duk_compile() but catches errors + related to compilation (such as syntax errors in the source). A zero return + value indicates success and the compiled function is left on the stack top. + A non-zero return value indicates an error, and the error is left on the stack top.

+ +example: | + duk_push_string(ctx, "print('program'); syntax error here="); + duk_push_string(ctx, "hello-with-syntax-error"); + if (duk_pcompile(ctx, 0) != 0) { + printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); + } else { + duk_call(ctx, 0); /* [ func ] -> [ result ] */ + printf("program result: %s\n", duk_safe_to_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - compile + - protected + +seealso: + - duk_compile + - duk_pcompile_string + - duk_pcompile_string_filename + - duk_pcompile_lstring + - duk_pcompile_lstring_filename + - duk_pcompile_file + +introduced: 1.0.0 diff --git a/website/api/duk_pcompile_file.txt b/website/api/duk_pcompile_file.txt deleted file mode 100644 index 0739cd5e..00000000 --- a/website/api/duk_pcompile_file.txt +++ /dev/null @@ -1,31 +0,0 @@ -=proto -duk_int_t duk_pcompile_file(duk_context *ctx, duk_uint_t flags, const char *path); - -=stack -[ ... ] -> [ ... function! ] (if success, return value == 0) -[ ... ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Like -duk_pcompile(), but the compile input -is given as a filename. The filename associated with the result function -is path as is.

- -
- -=example -if (duk_pcompile_file(ctx, 0, "test.js") != 0) { - printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); -} else { - duk_call(ctx, 0); /* [ func ] -> [ result ] */ - printf("program result: %s\n", duk_safe_to_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -compile -nonportable -protected - -=introduced -1.0.0 diff --git a/website/api/duk_pcompile_file.yaml b/website/api/duk_pcompile_file.yaml new file mode 100644 index 00000000..91fd24b0 --- /dev/null +++ b/website/api/duk_pcompile_file.yaml @@ -0,0 +1,32 @@ +name: duk_pcompile_file + +proto: | + duk_int_t duk_pcompile_file(duk_context *ctx, duk_uint_t flags, const char *path); + +stack: | + [ ... ] -> [ ... function! ] (if success, return value == 0) + [ ... ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Like + duk_pcompile(), but the compile input + is given as a filename. The filename associated with the result function + is path as is.

+ +
+ +example: | + if (duk_pcompile_file(ctx, 0, "test.js") != 0) { + printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); + } else { + duk_call(ctx, 0); /* [ func ] -> [ result ] */ + printf("program result: %s\n", duk_safe_to_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - compile + - nonportable + - protected + +introduced: 1.0.0 diff --git a/website/api/duk_pcompile_lstring.txt b/website/api/duk_pcompile_lstring.txt deleted file mode 100644 index 02d3079a..00000000 --- a/website/api/duk_pcompile_lstring.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -duk_int_t duk_pcompile_lstring(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); - -=stack -[ ... ] -> [ ... function! ] (if success, return value == 0) -[ ... ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Like -duk_pcompile(), but the compile input -is given as a C string with explicit length. The filename associated with the -function is automatically provided from the __FILE__ preprocessor -define of the caller.

- -
- -=example -const char *src = /* ... */; -duk_size_t len = /* ... */; - -if (duk_pcompile_lstring(ctx, 0, src, len) != 0) { - printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); -} else { - duk_call(ctx, 0); /* [ func ] -> [ result ] */ - printf("program result: %s\n", duk_safe_to_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -compile -protected - -=introduced -1.0.0 diff --git a/website/api/duk_pcompile_lstring.yaml b/website/api/duk_pcompile_lstring.yaml new file mode 100644 index 00000000..a85038d6 --- /dev/null +++ b/website/api/duk_pcompile_lstring.yaml @@ -0,0 +1,35 @@ +name: duk_pcompile_lstring + +proto: | + duk_int_t duk_pcompile_lstring(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); + +stack: | + [ ... ] -> [ ... function! ] (if success, return value == 0) + [ ... ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Like + duk_pcompile(), but the compile input + is given as a C string with explicit length. The filename associated with the + function is automatically provided from the __FILE__ preprocessor + define of the caller.

+ +
+ +example: | + const char *src = /* ... */; + duk_size_t len = /* ... */; + + if (duk_pcompile_lstring(ctx, 0, src, len) != 0) { + printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); + } else { + duk_call(ctx, 0); /* [ func ] -> [ result ] */ + printf("program result: %s\n", duk_safe_to_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - compile + - protected + +introduced: 1.0.0 diff --git a/website/api/duk_pcompile_lstring_filename.txt b/website/api/duk_pcompile_lstring_filename.txt deleted file mode 100644 index 39a13b86..00000000 --- a/website/api/duk_pcompile_lstring_filename.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -duk_int_t duk_pcompile_lstring_filename(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); - -=stack -[ ... filename! ] -> [ ... function! ] (if success, return value == 0) -[ ... filename! ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Like -duk_pcompile(), but the compile input -is given as a C string with explicit length.

- -
- -=example -const char *src = /* ... */; -duk_size_t len = /* ... */; - -duk_push_string(ctx, "myFile.js"); -if (duk_pcompile_lstring_filename(ctx, 0, src, len) != 0) { - printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); -} else { - duk_call(ctx, 0); /* [ func ] -> [ result ] */ - printf("program result: %s\n", duk_safe_to_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -compile -protected - -=introduced -1.0.0 diff --git a/website/api/duk_pcompile_lstring_filename.yaml b/website/api/duk_pcompile_lstring_filename.yaml new file mode 100644 index 00000000..2935343f --- /dev/null +++ b/website/api/duk_pcompile_lstring_filename.yaml @@ -0,0 +1,34 @@ +name: duk_pcompile_lstring_filename + +proto: | + duk_int_t duk_pcompile_lstring_filename(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); + +stack: | + [ ... filename! ] -> [ ... function! ] (if success, return value == 0) + [ ... filename! ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Like + duk_pcompile(), but the compile input + is given as a C string with explicit length.

+ +
+ +example: | + const char *src = /* ... */; + duk_size_t len = /* ... */; + + duk_push_string(ctx, "myFile.js"); + if (duk_pcompile_lstring_filename(ctx, 0, src, len) != 0) { + printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); + } else { + duk_call(ctx, 0); /* [ func ] -> [ result ] */ + printf("program result: %s\n", duk_safe_to_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - compile + - protected + +introduced: 1.0.0 diff --git a/website/api/duk_pcompile_string.txt b/website/api/duk_pcompile_string.txt deleted file mode 100644 index cc8fe298..00000000 --- a/website/api/duk_pcompile_string.txt +++ /dev/null @@ -1,31 +0,0 @@ -=proto -duk_int_t duk_pcompile_string(duk_context *ctx, duk_uint_t flags, const char *src); - -=stack -[ ... ] -> [ ... function! ] (if success, return value == 0) -[ ... ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Like -duk_pcompile(), but the compile input -is given as a C string. The filename associated with the function is -automatically provided from the __FILE__ preprocessor define -of the caller.

- -
- -=example -if (duk_pcompile_string(ctx, 0, "print('program code'); syntax error here=") != 0) { - printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); -} else { - duk_call(ctx, 0); /* [ func ] -> [ result ] */ - printf("program result: %s\n", duk_safe_to_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -compile -protected - -=introduced -1.0.0 diff --git a/website/api/duk_pcompile_string.yaml b/website/api/duk_pcompile_string.yaml new file mode 100644 index 00000000..4c168d2f --- /dev/null +++ b/website/api/duk_pcompile_string.yaml @@ -0,0 +1,32 @@ +name: duk_pcompile_string + +proto: | + duk_int_t duk_pcompile_string(duk_context *ctx, duk_uint_t flags, const char *src); + +stack: | + [ ... ] -> [ ... function! ] (if success, return value == 0) + [ ... ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Like + duk_pcompile(), but the compile input + is given as a C string. The filename associated with the function is + automatically provided from the __FILE__ preprocessor define + of the caller.

+ +
+ +example: | + if (duk_pcompile_string(ctx, 0, "print('program code'); syntax error here=") != 0) { + printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); + } else { + duk_call(ctx, 0); /* [ func ] -> [ result ] */ + printf("program result: %s\n", duk_safe_to_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - compile + - protected + +introduced: 1.0.0 diff --git a/website/api/duk_pcompile_string_filename.txt b/website/api/duk_pcompile_string_filename.txt deleted file mode 100644 index 3eccdaf4..00000000 --- a/website/api/duk_pcompile_string_filename.txt +++ /dev/null @@ -1,30 +0,0 @@ -=proto -duk_int_t duk_pcompile_string_filename(duk_context *ctx, duk_uint_t flags, const char *src); - -=stack -[ ... filename! ] -> [ ... function! ] (if success, return value == 0) -[ ... filename! ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Like -duk_pcompile(), but the compile input -is given as a C string.

- -
- -=example -duk_push_string(ctx, "myFile.js"); -if (duk_pcompile_string_filename(ctx, 0, "print('program code'); syntax error here=") != 0) { - printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); -} else { - duk_call(ctx, 0); /* [ func ] -> [ result ] */ - printf("program result: %s\n", duk_safe_to_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -compile -protected - -=introduced -1.0.0 diff --git a/website/api/duk_pcompile_string_filename.yaml b/website/api/duk_pcompile_string_filename.yaml new file mode 100644 index 00000000..33d0a1a1 --- /dev/null +++ b/website/api/duk_pcompile_string_filename.yaml @@ -0,0 +1,31 @@ +name: duk_pcompile_string_filename + +proto: | + duk_int_t duk_pcompile_string_filename(duk_context *ctx, duk_uint_t flags, const char *src); + +stack: | + [ ... filename! ] -> [ ... function! ] (if success, return value == 0) + [ ... filename! ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Like + duk_pcompile(), but the compile input + is given as a C string.

+ +
+ +example: | + duk_push_string(ctx, "myFile.js"); + if (duk_pcompile_string_filename(ctx, 0, "print('program code'); syntax error here=") != 0) { + printf("compile failed: %s\n", duk_safe_to_string(ctx, -1)); + } else { + duk_call(ctx, 0); /* [ func ] -> [ result ] */ + printf("program result: %s\n", duk_safe_to_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - compile + - protected + +introduced: 1.0.0 diff --git a/website/api/duk_peval.txt b/website/api/duk_peval.txt deleted file mode 100644 index feaccbf2..00000000 --- a/website/api/duk_peval.txt +++ /dev/null @@ -1,38 +0,0 @@ -=proto -duk_int_t duk_peval(duk_context *ctx); - -=stack -[ ... source! ] -> [ ... result! ] (if success, return value == 0) -[ ... source! ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Like duk_eval() but catches errors -related to compilation (such as syntax errors in the source). A zero return -value indicates success and the eval result is left on the stack top. -A non-zero return value indicates an error, and the error is left on the stack top.

- -=example -duk_push_string(ctx, "print('Hello world!'); syntax error here="); -if (duk_peval(ctx) != 0) { - printf("eval failed: %s\n", duk_safe_to_string(ctx, -1)); -} else { - printf("result is: %s\n", duk_safe_to_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -compile -protected - -=seealso -duk_eval -duk_peval_noresult -duk_peval_string -duk_peval_string_noresult -duk_peval_lstring -duk_peval_lstring_noresult -duk_peval_file -duk_peval_file_noresult - -=introduced -1.0.0 diff --git a/website/api/duk_peval.yaml b/website/api/duk_peval.yaml new file mode 100644 index 00000000..3d506cfc --- /dev/null +++ b/website/api/duk_peval.yaml @@ -0,0 +1,39 @@ +name: duk_peval + +proto: | + duk_int_t duk_peval(duk_context *ctx); + +stack: | + [ ... source! ] -> [ ... result! ] (if success, return value == 0) + [ ... source! ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Like duk_eval() but catches errors + related to compilation (such as syntax errors in the source). A zero return + value indicates success and the eval result is left on the stack top. + A non-zero return value indicates an error, and the error is left on the stack top.

+ +example: | + duk_push_string(ctx, "print('Hello world!'); syntax error here="); + if (duk_peval(ctx) != 0) { + printf("eval failed: %s\n", duk_safe_to_string(ctx, -1)); + } else { + printf("result is: %s\n", duk_safe_to_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - compile + - protected + +seealso: + - duk_eval + - duk_peval_noresult + - duk_peval_string + - duk_peval_string_noresult + - duk_peval_lstring + - duk_peval_lstring_noresult + - duk_peval_file + - duk_peval_file_noresult + +introduced: 1.0.0 diff --git a/website/api/duk_peval_file.txt b/website/api/duk_peval_file.txt deleted file mode 100644 index 8e38d838..00000000 --- a/website/api/duk_peval_file.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -duk_int_t duk_peval_file(duk_context *ctx, const char *path); - -=stack -[ ... ] -> [ ... result! ] (if success, return value == 0) -[ ... ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Like -duk_peval(), but the eval input -is given as a filename. The filename associated with the temporary -function created for the eval code is path as is.

- -
- -=example -if (duk_peval_file(ctx, "test.js") != 0) { - printf("eval failed: %s\n", duk_safe_to_string(ctx, -1)); -} else { - printf("result is: %s\n", duk_safe_to_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -compile -protected -nonportable - -=seealso -duk_peval_file_noresult - -=introduced -1.0.0 diff --git a/website/api/duk_peval_file.yaml b/website/api/duk_peval_file.yaml new file mode 100644 index 00000000..459f7fa8 --- /dev/null +++ b/website/api/duk_peval_file.yaml @@ -0,0 +1,34 @@ +name: duk_peval_file + +proto: | + duk_int_t duk_peval_file(duk_context *ctx, const char *path); + +stack: | + [ ... ] -> [ ... result! ] (if success, return value == 0) + [ ... ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Like + duk_peval(), but the eval input + is given as a filename. The filename associated with the temporary + function created for the eval code is path as is.

+ +
+ +example: | + if (duk_peval_file(ctx, "test.js") != 0) { + printf("eval failed: %s\n", duk_safe_to_string(ctx, -1)); + } else { + printf("result is: %s\n", duk_safe_to_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - compile + - protected + - nonportable + +seealso: + - duk_peval_file_noresult + +introduced: 1.0.0 diff --git a/website/api/duk_peval_file_noresult.txt b/website/api/duk_peval_file_noresult.txt deleted file mode 100644 index a2dc9e15..00000000 --- a/website/api/duk_peval_file_noresult.txt +++ /dev/null @@ -1,27 +0,0 @@ -=proto -duk_int_t duk_peval_file_noresult(duk_context *ctx, const char *path); - -=stack -[ ... ] -> [ ... ] - -=summary -

Like -duk_peval_file(), but leaves no -result on the value stack.

- -
- -=example -if (duk_peval_file_noresult(ctx, "test.js") != 0) { - printf("eval failed\n"); -} else { - printf("eval successful\n"); -} - -=tags -compile -nonportable -protected - -=introduced -1.0.0 diff --git a/website/api/duk_peval_file_noresult.yaml b/website/api/duk_peval_file_noresult.yaml new file mode 100644 index 00000000..fa5733ee --- /dev/null +++ b/website/api/duk_peval_file_noresult.yaml @@ -0,0 +1,28 @@ +name: duk_peval_file_noresult + +proto: | + duk_int_t duk_peval_file_noresult(duk_context *ctx, const char *path); + +stack: | + [ ... ] -> [ ... ] + +summary: | +

Like + duk_peval_file(), but leaves no + result on the value stack.

+ +
+ +example: | + if (duk_peval_file_noresult(ctx, "test.js") != 0) { + printf("eval failed\n"); + } else { + printf("eval successful\n"); + } + +tags: + - compile + - nonportable + - protected + +introduced: 1.0.0 diff --git a/website/api/duk_peval_lstring.txt b/website/api/duk_peval_lstring.txt deleted file mode 100644 index bc61e70a..00000000 --- a/website/api/duk_peval_lstring.txt +++ /dev/null @@ -1,36 +0,0 @@ -=proto -duk_int_t duk_peval_lstring(duk_context *ctx, const char *src, duk_size_t len); - -=stack -[ ... ] -> [ ... result! ] (if success, return value == 0) -[ ... ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Like -duk_peval(), but the eval input -is given as a C string with explicit length. The filename associated with the -temporary is automatically provided from the __FILE__ preprocessor -define of the caller.

- -
- -=example -const char *src = /* ... */; -duk_size_t len = /* ... */; - -if (duk_peval_lstring(ctx, src, len) != 0) { - printf("eval failed: %s\n", duk_safe_to_string(ctx, -1)); -} else { - printf("result is: %s\n", duk_get_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -compile -protected - -=seealso -duk_peval_lstring_noresult - -=introduced -1.0.0 diff --git a/website/api/duk_peval_lstring.yaml b/website/api/duk_peval_lstring.yaml new file mode 100644 index 00000000..19f7b350 --- /dev/null +++ b/website/api/duk_peval_lstring.yaml @@ -0,0 +1,37 @@ +name: duk_peval_lstring + +proto: | + duk_int_t duk_peval_lstring(duk_context *ctx, const char *src, duk_size_t len); + +stack: | + [ ... ] -> [ ... result! ] (if success, return value == 0) + [ ... ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Like + duk_peval(), but the eval input + is given as a C string with explicit length. The filename associated with the + temporary is automatically provided from the __FILE__ preprocessor + define of the caller.

+ +
+ +example: | + const char *src = /* ... */; + duk_size_t len = /* ... */; + + if (duk_peval_lstring(ctx, src, len) != 0) { + printf("eval failed: %s\n", duk_safe_to_string(ctx, -1)); + } else { + printf("result is: %s\n", duk_get_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - compile + - protected + +seealso: + - duk_peval_lstring_noresult + +introduced: 1.0.0 diff --git a/website/api/duk_peval_lstring_noresult.txt b/website/api/duk_peval_lstring_noresult.txt deleted file mode 100644 index 136c448a..00000000 --- a/website/api/duk_peval_lstring_noresult.txt +++ /dev/null @@ -1,29 +0,0 @@ -=proto -duk_int_t duk_peval_lstring_noresult(duk_context *ctx, const char *src, duk_size_t len); - -=stack -[ ... ] -> [ ... ] - -=summary -

Like -duk_peval_lstring(), but leaves -no result on the value stack.

- -
- -=example -const char *src = /* ... */; -duk_size_t len = /* ... */; - -if (duk_peval_lstring_noresult(ctx, src, len) != 0) { - printf("eval failed\n"); -} else { - printf("eval successful\n"); -} - -=tags -compile -protected - -=introduced -1.0.0 diff --git a/website/api/duk_peval_lstring_noresult.yaml b/website/api/duk_peval_lstring_noresult.yaml new file mode 100644 index 00000000..a03f77f1 --- /dev/null +++ b/website/api/duk_peval_lstring_noresult.yaml @@ -0,0 +1,30 @@ +name: duk_peval_lstring_noresult + +proto: | + duk_int_t duk_peval_lstring_noresult(duk_context *ctx, const char *src, duk_size_t len); + +stack: | + [ ... ] -> [ ... ] + +summary: | +

Like + duk_peval_lstring(), but leaves + no result on the value stack.

+ +
+ +example: | + const char *src = /* ... */; + duk_size_t len = /* ... */; + + if (duk_peval_lstring_noresult(ctx, src, len) != 0) { + printf("eval failed\n"); + } else { + printf("eval successful\n"); + } + +tags: + - compile + - protected + +introduced: 1.0.0 diff --git a/website/api/duk_peval_noresult.txt b/website/api/duk_peval_noresult.txt deleted file mode 100644 index 700659ff..00000000 --- a/website/api/duk_peval_noresult.txt +++ /dev/null @@ -1,29 +0,0 @@ -=proto -duk_int_t duk_peval_noresult(duk_context *ctx); - -=stack -[ ... source! ] -> [ ... ] - -=summary -

Like duk_peval() but leaves no result -on the value stack.

- -=example -duk_push_string(ctx, "print('Hello world!'); syntax error here="); -if (duk_peval_noresult(ctx) != 0) { - printf("eval failed\n"); -} else { - printf("eval successful\n"); -} - -=tags -compile -protected - -=seealso -duk_peval_string_noresult -duk_peval_lstring_noresult -duk_peval_file_noresult - -=introduced -1.0.0 diff --git a/website/api/duk_peval_noresult.yaml b/website/api/duk_peval_noresult.yaml new file mode 100644 index 00000000..b6277dca --- /dev/null +++ b/website/api/duk_peval_noresult.yaml @@ -0,0 +1,30 @@ +name: duk_peval_noresult + +proto: | + duk_int_t duk_peval_noresult(duk_context *ctx); + +stack: | + [ ... source! ] -> [ ... ] + +summary: | +

Like duk_peval() but leaves no result + on the value stack.

+ +example: | + duk_push_string(ctx, "print('Hello world!'); syntax error here="); + if (duk_peval_noresult(ctx) != 0) { + printf("eval failed\n"); + } else { + printf("eval successful\n"); + } + +tags: + - compile + - protected + +seealso: + - duk_peval_string_noresult + - duk_peval_lstring_noresult + - duk_peval_file_noresult + +introduced: 1.0.0 diff --git a/website/api/duk_peval_string.txt b/website/api/duk_peval_string.txt deleted file mode 100644 index 151b65f5..00000000 --- a/website/api/duk_peval_string.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -duk_int_t duk_peval_string(duk_context *ctx, const char *src); - -=stack -[ ... ] -> [ ... result! ] (if success, return value == 0) -[ ... ] -> [ ... err! ] (if failure, return value != 0) - -=summary -

Like -duk_peval(), but the eval input -is given as a C string. The filename associated with the temporary -is automatically provided from the __FILE__ preprocessor define -of the caller.

- -
- -=example -if (duk_peval_string(ctx, "'testString'.toUpperCase()") != 0) { - printf("eval failed: %s\n", duk_safe_to_string(ctx, -1)); -} else { - printf("result is: %s\n", duk_get_string(ctx, -1)); -} -duk_pop(ctx); - -=tags -compile -protected - -=seealso -duk_peval_string_noresult - -=introduced -1.0.0 diff --git a/website/api/duk_peval_string.yaml b/website/api/duk_peval_string.yaml new file mode 100644 index 00000000..430c950f --- /dev/null +++ b/website/api/duk_peval_string.yaml @@ -0,0 +1,34 @@ +name: duk_peval_string + +proto: | + duk_int_t duk_peval_string(duk_context *ctx, const char *src); + +stack: | + [ ... ] -> [ ... result! ] (if success, return value == 0) + [ ... ] -> [ ... err! ] (if failure, return value != 0) + +summary: | +

Like + duk_peval(), but the eval input + is given as a C string. The filename associated with the temporary + is automatically provided from the __FILE__ preprocessor define + of the caller.

+ +
+ +example: | + if (duk_peval_string(ctx, "'testString'.toUpperCase()") != 0) { + printf("eval failed: %s\n", duk_safe_to_string(ctx, -1)); + } else { + printf("result is: %s\n", duk_get_string(ctx, -1)); + } + duk_pop(ctx); + +tags: + - compile + - protected + +seealso: + - duk_peval_string_noresult + +introduced: 1.0.0 diff --git a/website/api/duk_peval_string_noresult.txt b/website/api/duk_peval_string_noresult.txt deleted file mode 100644 index 9be4af55..00000000 --- a/website/api/duk_peval_string_noresult.txt +++ /dev/null @@ -1,26 +0,0 @@ -=proto -duk_int_t duk_peval_string_noresult(duk_context *ctx, const char *src); - -=stack -[ ... ] -> [ ... ] - -=summary -

Like -duk_peval_string(), but leaves -no result on the value stack.

- -
- -=example -if (duk_peval_string_noresult(ctx, "print('testString'.toUpperCase());") != 0) { - printf("eval failed\n"); -} else { - printf("eval successful\n"); -} - -=tags -compile -protected - -=introduced -1.0.0 diff --git a/website/api/duk_peval_string_noresult.yaml b/website/api/duk_peval_string_noresult.yaml new file mode 100644 index 00000000..56af6566 --- /dev/null +++ b/website/api/duk_peval_string_noresult.yaml @@ -0,0 +1,27 @@ +name: duk_peval_string_noresult + +proto: | + duk_int_t duk_peval_string_noresult(duk_context *ctx, const char *src); + +stack: | + [ ... ] -> [ ... ] + +summary: | +

Like + duk_peval_string(), but leaves + no result on the value stack.

+ +
+ +example: | + if (duk_peval_string_noresult(ctx, "print('testString'.toUpperCase());") != 0) { + printf("eval failed\n"); + } else { + printf("eval successful\n"); + } + +tags: + - compile + - protected + +introduced: 1.0.0 diff --git a/website/api/duk_pop.txt b/website/api/duk_pop.txt deleted file mode 100644 index 97bd5f08..00000000 --- a/website/api/duk_pop.txt +++ /dev/null @@ -1,27 +0,0 @@ -=proto -void duk_pop(duk_context *ctx); - -=stack -[ ... val! ] -> [ ... ] - -=summary -

Pop one element off the stack. If the stack is empty, throws an error.

- -

To pop multiple elements, use -duk_pop_n() or the shortcuts for common cases: -duk_pop_2() and -duk_pop_3().

- -=example -duk_pop(ctx); - -=tags -stack - -=seealso -duk_pop_2 -duk_pop_3 -duk_pop_n - -=introduced -1.0.0 diff --git a/website/api/duk_pop.yaml b/website/api/duk_pop.yaml new file mode 100644 index 00000000..94cfc40f --- /dev/null +++ b/website/api/duk_pop.yaml @@ -0,0 +1,28 @@ +name: duk_pop + +proto: | + void duk_pop(duk_context *ctx); + +stack: | + [ ... val! ] -> [ ... ] + +summary: | +

Pop one element off the stack. If the stack is empty, throws an error.

+ +

To pop multiple elements, use + duk_pop_n() or the shortcuts for common cases: + duk_pop_2() and + duk_pop_3().

+ +example: | + duk_pop(ctx); + +tags: + - stack + +seealso: + - duk_pop_2 + - duk_pop_3 + - duk_pop_n + +introduced: 1.0.0 diff --git a/website/api/duk_pop_2.txt b/website/api/duk_pop_2.txt deleted file mode 100644 index 24a6269e..00000000 --- a/website/api/duk_pop_2.txt +++ /dev/null @@ -1,18 +0,0 @@ -=proto -void duk_pop_2(duk_context *ctx); - -=stack -[ ... val1! val2! ] -> [ ... ] - -=summary -

Pop two elements off the stack. If the stack has fewer than two elements, -throws an error.

- -=example -duk_pop_2(ctx); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_pop_2.yaml b/website/api/duk_pop_2.yaml new file mode 100644 index 00000000..c7ce1300 --- /dev/null +++ b/website/api/duk_pop_2.yaml @@ -0,0 +1,19 @@ +name: duk_pop_2 + +proto: | + void duk_pop_2(duk_context *ctx); + +stack: | + [ ... val1! val2! ] -> [ ... ] + +summary: | +

Pop two elements off the stack. If the stack has fewer than two elements, + throws an error.

+ +example: | + duk_pop_2(ctx); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_pop_3.txt b/website/api/duk_pop_3.txt deleted file mode 100644 index 6e08a77b..00000000 --- a/website/api/duk_pop_3.txt +++ /dev/null @@ -1,18 +0,0 @@ -=proto -void duk_pop_3(duk_context *ctx); - -=stack -[ ... val1! val2! val3! ] -> [ ... ] - -=summary -

Pop three elements off the stack. If the stack has fewer than three elements, -throws an error.

- -=example -duk_pop_3(ctx); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_pop_3.yaml b/website/api/duk_pop_3.yaml new file mode 100644 index 00000000..3ee13553 --- /dev/null +++ b/website/api/duk_pop_3.yaml @@ -0,0 +1,19 @@ +name: duk_pop_3 + +proto: | + void duk_pop_3(duk_context *ctx); + +stack: | + [ ... val1! val2! val3! ] -> [ ... ] + +summary: | +

Pop three elements off the stack. If the stack has fewer than three elements, + throws an error.

+ +example: | + duk_pop_3(ctx); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_pop_n.txt b/website/api/duk_pop_n.txt deleted file mode 100644 index 35014d33..00000000 --- a/website/api/duk_pop_n.txt +++ /dev/null @@ -1,19 +0,0 @@ -=proto -void duk_pop_n(duk_context *ctx, duk_idx_t count); - -=stack -[ ... val1! ...! valN! ] -> [ ... ] - -=summary -

Pop count elements off the stack. If the stack has fewer than -count elements, throws an error. If count is zero, the -call is a no-op. Negative counts cause an error to be thrown.

- -=example -duk_pop_n(ctx, 10); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_pop_n.yaml b/website/api/duk_pop_n.yaml new file mode 100644 index 00000000..e5287ff3 --- /dev/null +++ b/website/api/duk_pop_n.yaml @@ -0,0 +1,20 @@ +name: duk_pop_n + +proto: | + void duk_pop_n(duk_context *ctx, duk_idx_t count); + +stack: | + [ ... val1! ...! valN! ] -> [ ... ] + +summary: | +

Pop count elements off the stack. If the stack has fewer than + count elements, throws an error. If count is zero, the + call is a no-op. Negative counts cause an error to be thrown.

+ +example: | + duk_pop_n(ctx, 10); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_push_array.txt b/website/api/duk_push_array.txt deleted file mode 100644 index a490ca86..00000000 --- a/website/api/duk_push_array.txt +++ /dev/null @@ -1,31 +0,0 @@ -=proto -duk_idx_t duk_push_array(duk_context *ctx); - -=stack -[ ... ] -> [ ... arr! ] - -=summary -

Push an empty array to the stack. Returns non-negative index (relative to stack bottom) -of the pushed array.

- -=example -duk_idx_t arr_idx; - -arr_idx = duk_push_array(ctx); -duk_push_string(ctx, "foo"); -duk_put_prop_index(ctx, arr_idx, 0); -duk_push_string(ctx, "bar"); -duk_put_prop_index(ctx, arr_idx, 1); - -/* array is now: [ "foo", "bar" ], and array.length is 2 (automatically - * updated for Ecmascript arrays). - */ - -duk_pop(ctx); /* pop array */ - -=tags -stack -object - -=introduced -1.0.0 diff --git a/website/api/duk_push_array.yaml b/website/api/duk_push_array.yaml new file mode 100644 index 00000000..5dfa2f84 --- /dev/null +++ b/website/api/duk_push_array.yaml @@ -0,0 +1,32 @@ +name: duk_push_array + +proto: | + duk_idx_t duk_push_array(duk_context *ctx); + +stack: | + [ ... ] -> [ ... arr! ] + +summary: | +

Push an empty array to the stack. Returns non-negative index (relative to stack bottom) + of the pushed array.

+ +example: | + duk_idx_t arr_idx; + + arr_idx = duk_push_array(ctx); + duk_push_string(ctx, "foo"); + duk_put_prop_index(ctx, arr_idx, 0); + duk_push_string(ctx, "bar"); + duk_put_prop_index(ctx, arr_idx, 1); + + /* array is now: [ "foo", "bar" ], and array.length is 2 (automatically + * updated for Ecmascript arrays). + */ + + duk_pop(ctx); /* pop array */ + +tags: + - stack + - object + +introduced: 1.0.0 diff --git a/website/api/duk_push_boolean.txt b/website/api/duk_push_boolean.txt deleted file mode 100644 index ec5f44bd..00000000 --- a/website/api/duk_push_boolean.txt +++ /dev/null @@ -1,21 +0,0 @@ -=proto -void duk_push_boolean(duk_context *ctx, duk_bool_t val); - -=stack -[ ... ] -> [ ... true! ] (if val != 0) -[ ... ] -> [ ... false! ] (if val == 0) - -=summary -

Push true (if val != 0) or false (if val == 0) to the stack.

- -=example -duk_push_boolean(ctx, 0); /* -> [ ... false ] */ -duk_push_boolean(ctx, 1); /* -> [ ... false true ] */ -duk_push_boolean(ctx, -3); /* -> [ ... false true true ] */ - -=tags -stack - - -=introduced -1.0.0 diff --git a/website/api/duk_push_boolean.yaml b/website/api/duk_push_boolean.yaml new file mode 100644 index 00000000..b6d4c91e --- /dev/null +++ b/website/api/duk_push_boolean.yaml @@ -0,0 +1,21 @@ +name: duk_push_boolean + +proto: | + void duk_push_boolean(duk_context *ctx, duk_bool_t val); + +stack: | + [ ... ] -> [ ... true! ] (if val != 0) + [ ... ] -> [ ... false! ] (if val == 0) + +summary: | +

Push true (if val != 0) or false (if val == 0) to the stack.

+ +example: | + duk_push_boolean(ctx, 0); /* -> [ ... false ] */ + duk_push_boolean(ctx, 1); /* -> [ ... false true ] */ + duk_push_boolean(ctx, -3); /* -> [ ... false true true ] */ + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_push_buffer.txt b/website/api/duk_push_buffer.txt deleted file mode 100644 index e4226d88..00000000 --- a/website/api/duk_push_buffer.txt +++ /dev/null @@ -1,54 +0,0 @@ -=proto -void *duk_push_buffer(duk_context *ctx, duk_size_t size, duk_bool_t dynamic); - -=stack -[ ... ] -> [ ... buf! ] - -=summary -

Allocate a new buffer of size bytes and push it to the value stack. -Returns a non-NULL pointer to the buffer data area; for a zero-size buffer, -may return either NULL or non-NULL. The buffer data area is -automatically zeroed. If dynamic is non-zero, the buffer will be resizable, -otherwise the buffer will have a fixed size. Throws an error if allocation fails.

- -

There are also shortcut variants -duk_push_fixed_buffer() and -duk_push_dynamic_buffer().

- -
-A dynamic buffer requires two memory allocations internally: one for the buffer -header and another for the currently allocated data area. A fixed buffer only -requires a single allocation: the data area follows the buffer header. -
- -
-Be careful when requesting a zero length dynamic buffer: a NULL -data pointer is not an error and should not confuse calling code. -
- -
-Duktape can be compiled with a feature option which disables automatic zeroing -of allocated buffer data. If this is the case, you need to zero the buffer -manually if necessary. -
- -=example -/* Allocate a fixed buffer of 1024 bytes. There is no need to check for - * the return value: an error is thrown if allocation fails. - */ - -void *p; - -p = duk_push_buffer(ctx, 1024, 0); -printf("allocated buffer, data area: %p\n", p); - -=tags -stack -buffer - -=seealso -duk_push_fixed_buffer -duk_push_dynamic_buffer - -=introduced -1.0.0 diff --git a/website/api/duk_push_buffer.yaml b/website/api/duk_push_buffer.yaml new file mode 100644 index 00000000..e997cc79 --- /dev/null +++ b/website/api/duk_push_buffer.yaml @@ -0,0 +1,55 @@ +name: duk_push_buffer + +proto: | + void *duk_push_buffer(duk_context *ctx, duk_size_t size, duk_bool_t dynamic); + +stack: | + [ ... ] -> [ ... buf! ] + +summary: | +

Allocate a new buffer of size bytes and push it to the value stack. + Returns a non-NULL pointer to the buffer data area; for a zero-size buffer, + may return either NULL or non-NULL. The buffer data area is + automatically zeroed. If dynamic is non-zero, the buffer will be resizable, + otherwise the buffer will have a fixed size. Throws an error if allocation fails.

+ +

There are also shortcut variants + duk_push_fixed_buffer() and + duk_push_dynamic_buffer().

+ +
+ A dynamic buffer requires two memory allocations internally: one for the buffer + header and another for the currently allocated data area. A fixed buffer only + requires a single allocation: the data area follows the buffer header. +
+ +
+ Be careful when requesting a zero length dynamic buffer: a NULL + data pointer is not an error and should not confuse calling code. +
+ +
+ Duktape can be compiled with a feature option which disables automatic zeroing + of allocated buffer data. If this is the case, you need to zero the buffer + manually if necessary. +
+ +example: | + /* Allocate a fixed buffer of 1024 bytes. There is no need to check for + * the return value: an error is thrown if allocation fails. + */ + + void *p; + + p = duk_push_buffer(ctx, 1024, 0); + printf("allocated buffer, data area: %p\n", p); + +tags: + - stack + - buffer + +seealso: + - duk_push_fixed_buffer + - duk_push_dynamic_buffer + +introduced: 1.0.0 diff --git a/website/api/duk_push_c_function.txt b/website/api/duk_push_c_function.txt deleted file mode 100644 index e8d702e5..00000000 --- a/website/api/duk_push_c_function.txt +++ /dev/null @@ -1,74 +0,0 @@ -=proto -duk_idx_t duk_push_c_function(duk_context *ctx, duk_c_function func, duk_idx_t nargs); - -=stack -[ ... ] -> [ ... func! ] - -=summary -

Push a new function object, associated with a C function, to the stack. -The function object is an Ecmascript function object; when called, func -will be called using the Duktape/C function interface. Returns non-negative index -(relative to stack bottom) of the pushed function.

- -

The nargs argument controls how the value stack looks like when -func is entered:

- -
    -
  • If nargs is >= 0, it indicates the exact number of arguments the - function expects to see; extra arguments are discarded and missing arguments - are filled in with undefined values. Upon entry to the function, value - stack top will always match nargs.
    • -
  • If nargs is set to DUK_VARARGS, the value stack will contain - actual (variable) call arguments and the function needs to check actual argument - count with duk_get_top().
    • -
- -

The function created will be callable both as a normal function (func()) -and as a constructor (new func()). You can differentiate between the two -call styles using duk_is_constructor_call(). -Although the function can be used as a constructor, it doesn't have an automatic -prototype property like Ecmascript functions.

- -
-If you intend to use the pushed function as a constructor, you should usually -create a prototype object and set the prototype property of the -function manually. -
- -=example -duk_ret_t my_addtwo(duk_context *ctx) { - double a, b; - - /* Here one can expect that duk_get_top(ctx) == 2, because nargs - * for duk_push_c_function() is 2. - */ - - a = duk_get_number(ctx, 0); - b = duk_get_number(ctx, 1); - duk_push_number(ctx, a + b); - return 1; /* 1 = return value at top - * 0 = return 'undefined' - * <0 = throw error (use DUK_RET_xxx constants) - */ -} - -void test(void) { - duk_idx_t func_idx; - - func_idx = duk_push_c_function(ctx, my_addtwo, 2); - duk_push_int(ctx, 2); - duk_push_int(ctx, 3); /* -> [ ... func 2 3 ] */ - duk_call(ctx, 2); /* -> [ ... res ] */ - printf("2+3 is %ld\n", (long) duk_get_int(ctx, -1)); - duk_pop(ctx); -} - -=seealso -duk_push_c_lightfunc - -=tags -stack -function - -=introduced -1.0.0 diff --git a/website/api/duk_push_c_function.yaml b/website/api/duk_push_c_function.yaml new file mode 100644 index 00000000..505a9d29 --- /dev/null +++ b/website/api/duk_push_c_function.yaml @@ -0,0 +1,75 @@ +name: duk_push_c_function + +proto: | + duk_idx_t duk_push_c_function(duk_context *ctx, duk_c_function func, duk_idx_t nargs); + +stack: | + [ ... ] -> [ ... func! ] + +summary: | +

Push a new function object, associated with a C function, to the stack. + The function object is an Ecmascript function object; when called, func + will be called using the Duktape/C function interface. Returns non-negative index + (relative to stack bottom) of the pushed function.

+ +

The nargs argument controls how the value stack looks like when + func is entered:

+ +
    +
  • If nargs is >= 0, it indicates the exact number of arguments the + function expects to see; extra arguments are discarded and missing arguments + are filled in with undefined values. Upon entry to the function, value + stack top will always match nargs.
    • +
  • If nargs is set to DUK_VARARGS, the value stack will contain + actual (variable) call arguments and the function needs to check actual argument + count with duk_get_top().
    • +
+ +

The function created will be callable both as a normal function (func()) + and as a constructor (new func()). You can differentiate between the two + call styles using duk_is_constructor_call(). + Although the function can be used as a constructor, it doesn't have an automatic + prototype property like Ecmascript functions.

+ +
+ If you intend to use the pushed function as a constructor, you should usually + create a prototype object and set the prototype property of the + function manually. +
+ +example: | + duk_ret_t my_addtwo(duk_context *ctx) { + double a, b; + + /* Here one can expect that duk_get_top(ctx) == 2, because nargs + * for duk_push_c_function() is 2. + */ + + a = duk_get_number(ctx, 0); + b = duk_get_number(ctx, 1); + duk_push_number(ctx, a + b); + return 1; /* 1 = return value at top + * 0 = return 'undefined' + * <0 = throw error (use DUK_RET_xxx constants) + */ + } + + void test(void) { + duk_idx_t func_idx; + + func_idx = duk_push_c_function(ctx, my_addtwo, 2); + duk_push_int(ctx, 2); + duk_push_int(ctx, 3); /* -> [ ... func 2 3 ] */ + duk_call(ctx, 2); /* -> [ ... res ] */ + printf("2+3 is %ld\n", (long) duk_get_int(ctx, -1)); + duk_pop(ctx); + } + +tags: + - stack + - function + +seealso: + - duk_push_c_lightfunc + +introduced: 1.0.0 diff --git a/website/api/duk_push_c_lightfunc.txt b/website/api/duk_push_c_lightfunc.txt deleted file mode 100644 index a212b32c..00000000 --- a/website/api/duk_push_c_lightfunc.txt +++ /dev/null @@ -1,58 +0,0 @@ -=proto -duk_idx_t duk_push_c_lightfunc(duk_context *ctx, duk_c_function func, duk_idx_t nargs, duk_idx_t length, duk_int_t magic); - -=stack -[ ... ] -> [ ... func! ] - -=summary -

Push a new lightfunc value, associated with a C function, to the stack. -Returns non-negative index (relative to stack bottom) of the -pushed lightfunc.

- -

A lightfunc is a tagged value which contains a Duktape/C function -pointer and a small set of internal control flags with no related heap -allocations. The internal control flags encode the nargs, -length, and magic values, which therefore have -significant restrictions:

-
    -
  • nargs must be [0,14] or DUK_VARARGS.
    • -
  • length must be [0,15] and maps to the virtual length - property of the lightfunc.
    • -
  • magic must be [-128,127].
    • -
- -

A lightfunc cannot hold any own properties, it only has virtual -name and length properties, and inherits -further properties from Function.prototype.

- -

The nargs argument controls how the value stack looks like when -func is entered, and behaves like for ordinary Duktape/C functions, see -duk_push_c_function().

- -

The function created will be callable both as a normal function (func()) -and as a constructor (new func()). You can differentiate between the two -call styles using duk_is_constructor_call(). -Although the function can be used as a constructor, it cannot have a prototype -property like normal Function objects.

- -
-If you intend to use the pushed lightfunc as a constructor, and want to use -a custom prototype object (instead of Object.prototype), the -lightfunc must return an object value. The object will then replace the default -instance (bound to this) automatically created for the constructor, -and will be the value of a new MyLightFunc() expression. -
- -=example -duk_idx_t func_idx; - -func_idx = duk_push_c_lightfunc(ctx, my_addtwo, 2 /*nargs*/, 2 /*length*/, 0 /*magic*/); - -=seealso -duk_push_c_function - -=tags -stack -function -lightfunc -experimental diff --git a/website/api/duk_push_c_lightfunc.yaml b/website/api/duk_push_c_lightfunc.yaml new file mode 100644 index 00000000..8d2f59d3 --- /dev/null +++ b/website/api/duk_push_c_lightfunc.yaml @@ -0,0 +1,60 @@ +name: duk_push_c_lightfunc + +proto: | + duk_idx_t duk_push_c_lightfunc(duk_context *ctx, duk_c_function func, duk_idx_t nargs, duk_idx_t length, duk_int_t magic); + +stack: | + [ ... ] -> [ ... func! ] + +summary: | +

Push a new lightfunc value, associated with a C function, to the stack. + Returns non-negative index (relative to stack bottom) of the + pushed lightfunc.

+ +

A lightfunc is a tagged value which contains a Duktape/C function + pointer and a small set of internal control flags with no related heap + allocations. The internal control flags encode the nargs, + length, and magic values, which therefore have + significant restrictions:

+
    +
  • nargs must be [0,14] or DUK_VARARGS.
    • +
  • length must be [0,15] and maps to the virtual length + property of the lightfunc.
    • +
  • magic must be [-128,127].
    • +
+ +

A lightfunc cannot hold any own properties, it only has virtual + name and length properties, and inherits + further properties from Function.prototype.

+ +

The nargs argument controls how the value stack looks like when + func is entered, and behaves like for ordinary Duktape/C functions, see + duk_push_c_function().

+ +

The function created will be callable both as a normal function (func()) + and as a constructor (new func()). You can differentiate between the two + call styles using duk_is_constructor_call(). + Although the function can be used as a constructor, it cannot have a prototype + property like normal Function objects.

+ +
+ If you intend to use the pushed lightfunc as a constructor, and want to use + a custom prototype object (instead of Object.prototype), the + lightfunc must return an object value. The object will then replace the default + instance (bound to this) automatically created for the constructor, + and will be the value of a new MyLightFunc() expression. +
+ +example: | + duk_idx_t func_idx; + + func_idx = duk_push_c_lightfunc(ctx, my_addtwo, 2 /*nargs*/, 2 /*length*/, 0 /*magic*/); + +tags: + - stack + - function + - lightfunc + - experimental + +seealso: + - duk_push_c_function diff --git a/website/api/duk_push_context_dump.txt b/website/api/duk_push_context_dump.txt deleted file mode 100644 index c8946df9..00000000 --- a/website/api/duk_push_context_dump.txt +++ /dev/null @@ -1,38 +0,0 @@ -=proto -void duk_push_context_dump(duk_context *ctx); - -=stack -[ ... ] -> [ ... str! ] - -=summary -

Push a one-line string summarizing the state of the current activation of -context ctx. This is useful for debugging Duktape/C code and is -not intended for production use.

- -

The exact dump contents are version specific. The current format includes -the stack top (i.e. number of elements on the stack) and prints out the current -elements as an array of JX-formatted (Duktape's custom extended JSON format) -values. The example below would print something like:

-
-ctx: top=2, stack=[123,"foo"]
-
- -
- -=example -duk_push_int(ctx, 123); -duk_push_string(ctx, "foo"); -duk_push_context_dump(ctx); -printf("%s\n", duk_to_string(ctx, -1)); -duk_pop(ctx); - -=tags -stack -debug - -=seealso -duk_dump_context_stdout -duk_dump_context_stderr - -=introduced -1.0.0 diff --git a/website/api/duk_push_context_dump.yaml b/website/api/duk_push_context_dump.yaml new file mode 100644 index 00000000..94372e17 --- /dev/null +++ b/website/api/duk_push_context_dump.yaml @@ -0,0 +1,39 @@ +name: duk_push_context_dump + +proto: | + void duk_push_context_dump(duk_context *ctx); + +stack: | + [ ... ] -> [ ... str! ] + +summary: | +

Push a one-line string summarizing the state of the current activation of + context ctx. This is useful for debugging Duktape/C code and is + not intended for production use.

+ +

The exact dump contents are version specific. The current format includes + the stack top (i.e. number of elements on the stack) and prints out the current + elements as an array of JX-formatted (Duktape's custom extended JSON format) + values. The example below would print something like:

+ 
+  ctx: top=2, stack=[123,"foo"]
+
+ +
+ +example: | + duk_push_int(ctx, 123); + duk_push_string(ctx, "foo"); + duk_push_context_dump(ctx); + printf("%s\n", duk_to_string(ctx, -1)); + duk_pop(ctx); + +tags: + - stack + - debug + +seealso: + - duk_dump_context_stdout + - duk_dump_context_stderr + +introduced: 1.0.0 diff --git a/website/api/duk_push_current_function.txt b/website/api/duk_push_current_function.txt deleted file mode 100644 index 8b5f2736..00000000 --- a/website/api/duk_push_current_function.txt +++ /dev/null @@ -1,26 +0,0 @@ -=proto -void duk_push_current_function(duk_context *ctx); - -=stack -[ ... ] -> [ ... func! ] (if current function exists) -[ ... ] -> [ ... undefined! ] (if no current function) - -=summary -

Push the currently running function to the stack. The value pushed is -an Ecmascript Function object. If there is no current function, -undefined is pushed instead.

- -

This function allows a C function to gain access to its function object. -Since multiple function objects can internally point to the same C function, -a function object is a convenient place for function parameterization and -can also act as an internal state stash.

- -=example -duk_push_current_function(ctx); - -=tags -stack -function - -=introduced -1.0.0 diff --git a/website/api/duk_push_current_function.yaml b/website/api/duk_push_current_function.yaml new file mode 100644 index 00000000..25e8b2d9 --- /dev/null +++ b/website/api/duk_push_current_function.yaml @@ -0,0 +1,27 @@ +name: duk_push_current_function + +proto: | + void duk_push_current_function(duk_context *ctx); + +stack: | + [ ... ] -> [ ... func! ] (if current function exists) + [ ... ] -> [ ... undefined! ] (if no current function) + +summary: | +

Push the currently running function to the stack. The value pushed is + an Ecmascript Function object. If there is no current function, + undefined is pushed instead.

+ +

This function allows a C function to gain access to its function object. + Since multiple function objects can internally point to the same C function, + a function object is a convenient place for function parameterization and + can also act as an internal state stash.

+ +example: | + duk_push_current_function(ctx); + +tags: + - stack + - function + +introduced: 1.0.0 diff --git a/website/api/duk_push_current_thread.txt b/website/api/duk_push_current_thread.txt deleted file mode 100644 index 1d9a5c6a..00000000 --- a/website/api/duk_push_current_thread.txt +++ /dev/null @@ -1,29 +0,0 @@ -=proto -void duk_push_current_thread(duk_context *ctx); - -=stack -[ ... ] -> [ ... thread! ] (if current thread exists) -[ ... ] -> [ ... undefined! ] (if no current thread) - -=summary -

Push the currently running Duktape thread to the stack. The value pushed -is a thread object which is also an Ecmascript object. If there is no current -thread, undefined is pushed instead.

- -

The current thread is (almost always) the thread represented by the -ctx pointer.

- -

To get the duk_context * associated with the thread, use -duk_get_context().

- -=example -duk_push_thread(ctx); - -=tags -stack -function -thread -borrowed - -=introduced -1.0.0 diff --git a/website/api/duk_push_current_thread.yaml b/website/api/duk_push_current_thread.yaml new file mode 100644 index 00000000..18d1f3a2 --- /dev/null +++ b/website/api/duk_push_current_thread.yaml @@ -0,0 +1,30 @@ +name: duk_push_current_thread + +proto: | + void duk_push_current_thread(duk_context *ctx); + +stack: | + [ ... ] -> [ ... thread! ] (if current thread exists) + [ ... ] -> [ ... undefined! ] (if no current thread) + +summary: | +

Push the currently running Duktape thread to the stack. The value pushed + is a thread object which is also an Ecmascript object. If there is no current + thread, undefined is pushed instead.

+ +

The current thread is (almost always) the thread represented by the + ctx pointer.

+ +

To get the duk_context * associated with the thread, use + duk_get_context().

+ +example: | + duk_push_thread(ctx); + +tags: + - stack + - function + - thread + - borrowed + +introduced: 1.0.0 diff --git a/website/api/duk_push_dynamic_buffer.txt b/website/api/duk_push_dynamic_buffer.txt deleted file mode 100644 index 815636f9..00000000 --- a/website/api/duk_push_dynamic_buffer.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -void *duk_push_dynamic_buffer(duk_context *ctx, duk_size_t size); - -=stack -[ ... ] -> [ ... buf! ] - -=summary -

Allocate a dynamic (resizable) buffer and push it to the value stack. -Shortcut for duk_push_buffer() -with dynamic = 1.

- -=example -void *p; - -p = duk_push_dynamic_buffer(ctx, 1024); -printf("allocated buffer, data area: %p\n", p); - -=tags -stack -buffer - -=introduced -1.0.0 diff --git a/website/api/duk_push_dynamic_buffer.yaml b/website/api/duk_push_dynamic_buffer.yaml new file mode 100644 index 00000000..2ec7399e --- /dev/null +++ b/website/api/duk_push_dynamic_buffer.yaml @@ -0,0 +1,24 @@ +name: duk_push_dynamic_buffer + +proto: | + void *duk_push_dynamic_buffer(duk_context *ctx, duk_size_t size); + +stack: | + [ ... ] -> [ ... buf! ] + +summary: | +

Allocate a dynamic (resizable) buffer and push it to the value stack. + Shortcut for duk_push_buffer() + with dynamic = 1.

+ +example: | + void *p; + + p = duk_push_dynamic_buffer(ctx, 1024); + printf("allocated buffer, data area: %p\n", p); + +tags: + - stack + - buffer + +introduced: 1.0.0 diff --git a/website/api/duk_push_error_object.txt b/website/api/duk_push_error_object.txt deleted file mode 100644 index fab406c9..00000000 --- a/website/api/duk_push_error_object.txt +++ /dev/null @@ -1,31 +0,0 @@ -=proto -duk_idx_t duk_push_error_object(duk_context *ctx, duk_errcode_t err_code, const char *fmt, ...); - -=stack -[ ... ] -> [ ... err! ] - -=summary -

Create a new error object and push it to the value stack (the error is not thrown). -Returns non-negative index (relative to stack bottom) of the pushed error object.

- -

The message property of the error object will be set to a sprintf-formatted -string using fmt and the remaining arguments. The internal prototype for the created -error object is chosen based on err_code. For instance, DUK_ERR_RANGE_ERROR -causes the built-in RangeError prototype to be used. The valid range for user error -codes is [1,16777215].

- -=example -duk_idx_t err_idx; - -err_idx = duk_push_error_object(ctx, DUK_ERR_TYPE_ERROR, "invalid argument value: %d", arg_value); - -=tags -stack -object -error - -=seealso -duk_push_error_object_va - -=introduced -1.0.0 diff --git a/website/api/duk_push_error_object.yaml b/website/api/duk_push_error_object.yaml new file mode 100644 index 00000000..dddde54a --- /dev/null +++ b/website/api/duk_push_error_object.yaml @@ -0,0 +1,32 @@ +name: duk_push_error_object + +proto: | + duk_idx_t duk_push_error_object(duk_context *ctx, duk_errcode_t err_code, const char *fmt, ...); + +stack: | + [ ... ] -> [ ... err! ] + +summary: | +

Create a new error object and push it to the value stack (the error is not thrown). + Returns non-negative index (relative to stack bottom) of the pushed error object.

+ +

The message property of the error object will be set to a sprintf-formatted + string using fmt and the remaining arguments. The internal prototype for the created + error object is chosen based on err_code. For instance, DUK_ERR_RANGE_ERROR + causes the built-in RangeError prototype to be used. The valid range for user error + codes is [1,16777215].

+ +example: | + duk_idx_t err_idx; + + err_idx = duk_push_error_object(ctx, DUK_ERR_TYPE_ERROR, "invalid argument value: %d", arg_value); + +tags: + - stack + - object + - error + +seealso: + - duk_push_error_object_va + +introduced: 1.0.0 diff --git a/website/api/duk_push_error_object_va.txt b/website/api/duk_push_error_object_va.txt deleted file mode 100644 index 901c5897..00000000 --- a/website/api/duk_push_error_object_va.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -duk_idx_t duk_push_error_object_va(duk_context *ctx, duk_errcode_t err_code, const char *fmt, va_list ap); - -=stack -[ ... ] -> [ ... err! ] - -=summary -

Vararg variant of -duk_push_error_object().

- -=example -duk_idx_t my_type_error(duk_context *ctx, const char *fmt, ...) { - va_list ap; - duk_idx_t err_idx; - - va_start(ap, fmt); - err_idx = duk_push_error_object_va(ctx, fmt, ap); - va_end(ap); - - return err_idx; -} - -=tags -stack -object -error -vararg - -=seealso -duk_push_error_object - -=introduced -1.1.0 diff --git a/website/api/duk_push_error_object_va.yaml b/website/api/duk_push_error_object_va.yaml new file mode 100644 index 00000000..c56b5d2e --- /dev/null +++ b/website/api/duk_push_error_object_va.yaml @@ -0,0 +1,34 @@ +name: duk_push_error_object_va + +proto: | + duk_idx_t duk_push_error_object_va(duk_context *ctx, duk_errcode_t err_code, const char *fmt, va_list ap); + +stack: | + [ ... ] -> [ ... err! ] + +summary: | +

Vararg variant of + duk_push_error_object().

+ +example: | + duk_idx_t my_type_error(duk_context *ctx, const char *fmt, ...) { + va_list ap; + duk_idx_t err_idx; + + va_start(ap, fmt); + err_idx = duk_push_error_object_va(ctx, fmt, ap); + va_end(ap); + + return err_idx; + } + +tags: + - stack + - object + - error + - vararg + +seealso: + - duk_push_error_object + +introduced: 1.1.0 diff --git a/website/api/duk_push_false.txt b/website/api/duk_push_false.txt deleted file mode 100644 index ad27e19d..00000000 --- a/website/api/duk_push_false.txt +++ /dev/null @@ -1,18 +0,0 @@ -=proto -void duk_push_false(duk_context *ctx); - -=stack -[ ... ] -> [ ... false! ] - -=summary -

Push false to stack. Equivalent to calling -duk_push_boolean(ctx, 0).

- -=example -duk_push_false(ctx); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_push_false.yaml b/website/api/duk_push_false.yaml new file mode 100644 index 00000000..f0c90a54 --- /dev/null +++ b/website/api/duk_push_false.yaml @@ -0,0 +1,19 @@ +name: duk_push_false + +proto: | + void duk_push_false(duk_context *ctx); + +stack: | + [ ... ] -> [ ... false! ] + +summary: | +

Push false to stack. Equivalent to calling + duk_push_boolean(ctx, 0).

+ +example: | + duk_push_false(ctx); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_push_fixed_buffer.txt b/website/api/duk_push_fixed_buffer.txt deleted file mode 100644 index 4e06e945..00000000 --- a/website/api/duk_push_fixed_buffer.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -void *duk_push_fixed_buffer(duk_context *ctx, duk_size_t size); - -=stack -[ ... ] -> [ ... buf! ] - -=summary -

Allocate a fixed size buffer and push it to the value stack. -Shortcut for duk_push_buffer() -with dynamic = 0.

- -=example -void *p; - -p = duk_push_fixed_buffer(ctx, 1024); -printf("allocated buffer, data area: %p\n", p); - -=tags -stack -buffer - -=introduced -1.0.0 diff --git a/website/api/duk_push_fixed_buffer.yaml b/website/api/duk_push_fixed_buffer.yaml new file mode 100644 index 00000000..4f276da1 --- /dev/null +++ b/website/api/duk_push_fixed_buffer.yaml @@ -0,0 +1,24 @@ +name: duk_push_fixed_buffer + +proto: | + void *duk_push_fixed_buffer(duk_context *ctx, duk_size_t size); + +stack: | + [ ... ] -> [ ... buf! ] + +summary: | +

Allocate a fixed size buffer and push it to the value stack. + Shortcut for duk_push_buffer() + with dynamic = 0.

+ +example: | + void *p; + + p = duk_push_fixed_buffer(ctx, 1024); + printf("allocated buffer, data area: %p\n", p); + +tags: + - stack + - buffer + +introduced: 1.0.0 diff --git a/website/api/duk_push_global_object.txt b/website/api/duk_push_global_object.txt deleted file mode 100644 index 75101505..00000000 --- a/website/api/duk_push_global_object.txt +++ /dev/null @@ -1,18 +0,0 @@ -=proto -void duk_push_global_object(duk_context *ctx); - -=stack -[ ... ] -> [ ... global! ] - -=summary -

Push the global object to the stack.

- -=example -duk_push_global_object(ctx); - -=tags -stack -object - -=introduced -1.0.0 diff --git a/website/api/duk_push_global_object.yaml b/website/api/duk_push_global_object.yaml new file mode 100644 index 00000000..706bf306 --- /dev/null +++ b/website/api/duk_push_global_object.yaml @@ -0,0 +1,19 @@ +name: duk_push_global_object + +proto: | + void duk_push_global_object(duk_context *ctx); + +stack: | + [ ... ] -> [ ... global! ] + +summary: | +

Push the global object to the stack.

+ +example: | + duk_push_global_object(ctx); + +tags: + - stack + - object + +introduced: 1.0.0 diff --git a/website/api/duk_push_global_stash.txt b/website/api/duk_push_global_stash.txt deleted file mode 100644 index 08bbe88d..00000000 --- a/website/api/duk_push_global_stash.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -void duk_push_global_stash(duk_context *ctx); - -=stack -[ ... ] -> [ ... stash! ] - -=summary -

Push the global stash object to the stack. The global stash is an internal -object which can be used to store key/value pairs from C code so that they are -reachable for garbage collection, but are not accessible from Ecmascript code. -The stash is only accessible from C code with a ctx argument -associated with the same global object.

- -=example -duk_ret_t set_timer_callback(duk_context *ctx) { - duk_push_global_stash(ctx); - duk_dup(ctx, 0); /* timer callback */ - duk_put_prop_string(ctx, -2, "timerCallback"); - return 0; -} - -=tags -stack -stash -object -module -sandbox - -=seealso -duk_push_heap_stash -duk_push_thread_stash - -=introduced -1.0.0 diff --git a/website/api/duk_push_global_stash.yaml b/website/api/duk_push_global_stash.yaml new file mode 100644 index 00000000..4f00915a --- /dev/null +++ b/website/api/duk_push_global_stash.yaml @@ -0,0 +1,35 @@ +name: duk_push_global_stash + +proto: | + void duk_push_global_stash(duk_context *ctx); + +stack: | + [ ... ] -> [ ... stash! ] + +summary: | +

Push the global stash object to the stack. The global stash is an internal + object which can be used to store key/value pairs from C code so that they are + reachable for garbage collection, but are not accessible from Ecmascript code. + The stash is only accessible from C code with a ctx argument + associated with the same global object.

+ +example: | + duk_ret_t set_timer_callback(duk_context *ctx) { + duk_push_global_stash(ctx); + duk_dup(ctx, 0); /* timer callback */ + duk_put_prop_string(ctx, -2, "timerCallback"); + return 0; + } + +tags: + - stack + - stash + - object + - module + - sandbox + +seealso: + - duk_push_heap_stash + - duk_push_thread_stash + +introduced: 1.0.0 diff --git a/website/api/duk_push_heap_stash.txt b/website/api/duk_push_heap_stash.txt deleted file mode 100644 index eac44394..00000000 --- a/website/api/duk_push_heap_stash.txt +++ /dev/null @@ -1,30 +0,0 @@ -=proto -void duk_push_heap_stash(duk_context *ctx); - -=stack -[ ... ] -> [ ... stash! ] - -=summary -

Push the heap stash object to the stack. The heap stash is an internal -object which can be used to store key/value pairs from C code so that they are -reachable for garbage collection, but are not accessible from Ecmascript code. -The stash is only accessible from C code; the same stash object is used by all -code sharing the same Duktape heap (even if they don't share the same global -object).

- -=example -duk_push_heap_stash(ctx); - -=tags -stack -stash -object -module -sandbox - -=seealso -duk_push_global_stash -duk_push_thread_stash - -=introduced -1.0.0 diff --git a/website/api/duk_push_heap_stash.yaml b/website/api/duk_push_heap_stash.yaml new file mode 100644 index 00000000..f7aaa699 --- /dev/null +++ b/website/api/duk_push_heap_stash.yaml @@ -0,0 +1,31 @@ +name: duk_push_heap_stash + +proto: | + void duk_push_heap_stash(duk_context *ctx); + +stack: | + [ ... ] -> [ ... stash! ] + +summary: | +

Push the heap stash object to the stack. The heap stash is an internal + object which can be used to store key/value pairs from C code so that they are + reachable for garbage collection, but are not accessible from Ecmascript code. + The stash is only accessible from C code; the same stash object is used by all + code sharing the same Duktape heap (even if they don't share the same global + object).

+ +example: | + duk_push_heap_stash(ctx); + +tags: + - stack + - stash + - object + - module + - sandbox + +seealso: + - duk_push_global_stash + - duk_push_thread_stash + +introduced: 1.0.0 diff --git a/website/api/duk_push_heapptr.txt b/website/api/duk_push_heapptr.txt deleted file mode 100644 index e26ded2e..00000000 --- a/website/api/duk_push_heapptr.txt +++ /dev/null @@ -1,35 +0,0 @@ -=proto -duk_idx_t duk_push_heapptr(duk_context *ctx, void *ptr); - -=stack -[ ... ] -> [ ... obj! ] - -=summary -

Push a Duktape heap allocated object into the value stack based on a borrowed -void pointer reference. -The argument ptr must be obtained using -duk_get_heapptr() (or its variants) -and must have been reachable for Duktape garbage collection up to this call. -If ptr is NULL, undefined is pushed.

- -=example -void *ptr; -duk_idx_t idx; - -/* 'ptr' originally obtained using duk_get_heapptr() earlier, with the original - * value reachable by Duktape GC all the way to here: - */ - -idx = duk_push_heapptr(ctx, ptr); - -=tags -stack -object -borrowed - -=seealso -duk_get_heapptr -duk_require_heapptr - -=introduced -1.1.0 diff --git a/website/api/duk_push_heapptr.yaml b/website/api/duk_push_heapptr.yaml new file mode 100644 index 00000000..82d3a5bd --- /dev/null +++ b/website/api/duk_push_heapptr.yaml @@ -0,0 +1,36 @@ +name: duk_push_heapptr + +proto: | + duk_idx_t duk_push_heapptr(duk_context *ctx, void *ptr); + +stack: | + [ ... ] -> [ ... obj! ] + +summary: | +

Push a Duktape heap allocated object into the value stack based on a borrowed + void pointer reference. + The argument ptr must be obtained using + duk_get_heapptr() (or its variants) + and must have been reachable for Duktape garbage collection up to this call. + If ptr is NULL, undefined is pushed.

+ +example: | + void *ptr; + duk_idx_t idx; + + /* 'ptr' originally obtained using duk_get_heapptr() earlier, with the original + * value reachable by Duktape GC all the way to here: + */ + + idx = duk_push_heapptr(ctx, ptr); + +tags: + - stack + - object + - borrowed + +seealso: + - duk_get_heapptr + - duk_require_heapptr + +introduced: 1.1.0 diff --git a/website/api/duk_push_int.txt b/website/api/duk_push_int.txt deleted file mode 100644 index 598d5fb8..00000000 --- a/website/api/duk_push_int.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -void duk_push_int(duk_context *ctx, duk_int_t val); - -=stack -[ ... ] -> [ ... val! ] - -=summary -

Convert val to an IEEE double and push it to the stack.

- -

This is a shorthand for calling -duk_push_number(ctx, (duk_double_t) val).

- -=example -duk_push_int(ctx, 123); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_push_int.yaml b/website/api/duk_push_int.yaml new file mode 100644 index 00000000..244a45cc --- /dev/null +++ b/website/api/duk_push_int.yaml @@ -0,0 +1,21 @@ +name: duk_push_int + +proto: | + void duk_push_int(duk_context *ctx, duk_int_t val); + +stack: | + [ ... ] -> [ ... val! ] + +summary: | +

Convert val to an IEEE double and push it to the stack.

+ +

This is a shorthand for calling + duk_push_number(ctx, (duk_double_t) val).

+ +example: | + duk_push_int(ctx, 123); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_push_lstring.txt b/website/api/duk_push_lstring.txt deleted file mode 100644 index f507c42a..00000000 --- a/website/api/duk_push_lstring.txt +++ /dev/null @@ -1,35 +0,0 @@ -=proto -const char *duk_push_lstring(duk_context *ctx, const char *str, duk_size_t len); - -=stack -[ ... ] -> [ ... str! ] - -=summary -

Push a string of explicit length to the stack. The string may contain -arbitrary data, including internal NUL characters. A pointer to the interned -string data is returned. If the operation fails, throws an error.

- -

If str is NULL, an empty string is pushed to the stack -(regardless of what len is) and a non-NULL pointer to an -empty string is returned. The returned pointer can be dereferenced and -a NUL terminator character is guaranteed. This behavior differs from -duk_push_string on purpose.

- -

C code should normally only push valid CESU-8 strings to the stack.

- -=example -const char tmp1[5] = { 'f', '\0', '\0', 'x', 'y' }; -const char tmp2[1] = { '\0' }; - -duk_push_lstring(ctx, tmp1, 5); /* push the string "f\x00\x00xy" */ -duk_push_lstring(ctx, tmp2, 1); /* push the string "\x00" */ -duk_push_lstring(ctx, tmp2, 0); /* push empty string */ -duk_push_lstring(ctx, NULL, 0); /* push empty string */ -duk_push_lstring(ctx, NULL, 10); /* push empty string */ - -=tags -stack -string - -=introduced -1.0.0 diff --git a/website/api/duk_push_lstring.yaml b/website/api/duk_push_lstring.yaml new file mode 100644 index 00000000..9324269e --- /dev/null +++ b/website/api/duk_push_lstring.yaml @@ -0,0 +1,36 @@ +name: duk_push_lstring + +proto: | + const char *duk_push_lstring(duk_context *ctx, const char *str, duk_size_t len); + +stack: | + [ ... ] -> [ ... str! ] + +summary: | +

Push a string of explicit length to the stack. The string may contain + arbitrary data, including internal NUL characters. A pointer to the interned + string data is returned. If the operation fails, throws an error.

+ +

If str is NULL, an empty string is pushed to the stack + (regardless of what len is) and a non-NULL pointer to an + empty string is returned. The returned pointer can be dereferenced and + a NUL terminator character is guaranteed. This behavior differs from + duk_push_string on purpose.

+ +

C code should normally only push valid CESU-8 strings to the stack.

+ +example: | + const char tmp1[5] = { 'f', '\0', '\0', 'x', 'y' }; + const char tmp2[1] = { '\0' }; + + duk_push_lstring(ctx, tmp1, 5); /* push the string "f\x00\x00xy" */ + duk_push_lstring(ctx, tmp2, 1); /* push the string "\x00" */ + duk_push_lstring(ctx, tmp2, 0); /* push empty string */ + duk_push_lstring(ctx, NULL, 0); /* push empty string */ + duk_push_lstring(ctx, NULL, 10); /* push empty string */ + +tags: + - stack + - string + +introduced: 1.0.0 diff --git a/website/api/duk_push_nan.txt b/website/api/duk_push_nan.txt deleted file mode 100644 index 98fbd0b8..00000000 --- a/website/api/duk_push_nan.txt +++ /dev/null @@ -1,19 +0,0 @@ -=proto -void duk_push_nan(duk_context *ctx); - -=stack -[ ... ] -> [ ... NaN! ] - -=summary -Pushes a NaN (not-a-number) to the stack. - -=example -duk_push_nan(ctx); - -printf("NaN is number: %d\n", (int) duk_is_number(ctx, -1)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_push_nan.yaml b/website/api/duk_push_nan.yaml new file mode 100644 index 00000000..15246f14 --- /dev/null +++ b/website/api/duk_push_nan.yaml @@ -0,0 +1,20 @@ +name: duk_push_nan + +proto: | + void duk_push_nan(duk_context *ctx); + +stack: | + [ ... ] -> [ ... NaN! ] + +summary: | + Pushes a NaN (not-a-number) to the stack. + +example: | + duk_push_nan(ctx); + + printf("NaN is number: %d\n", (int) duk_is_number(ctx, -1)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_push_null.txt b/website/api/duk_push_null.txt deleted file mode 100644 index 90443600..00000000 --- a/website/api/duk_push_null.txt +++ /dev/null @@ -1,17 +0,0 @@ -=proto -void duk_push_null(duk_context *ctx); - -=stack -[ ... ] -> [ ... null! ] - -=summary -

Push null to the stack.

- -=example -duk_push_null(ctx); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_push_null.yaml b/website/api/duk_push_null.yaml new file mode 100644 index 00000000..b85b373a --- /dev/null +++ b/website/api/duk_push_null.yaml @@ -0,0 +1,18 @@ +name: duk_push_null + +proto: | + void duk_push_null(duk_context *ctx); + +stack: | + [ ... ] -> [ ... null! ] + +summary: | +

Push null to the stack.

+ +example: | + duk_push_null(ctx); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_push_number.txt b/website/api/duk_push_number.txt deleted file mode 100644 index 943d2042..00000000 --- a/website/api/duk_push_number.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -void duk_push_number(duk_context *ctx, duk_double_t val); - -=stack -[ ... ] -> [ ... val! ] - -=summary -

Push number (IEEE double) val to the stack.

- -

If val is a NaN it may be normalized into another -NaN form.

- -=example -duk_push_number(ctx, 123.0); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_push_number.yaml b/website/api/duk_push_number.yaml new file mode 100644 index 00000000..a2c0af66 --- /dev/null +++ b/website/api/duk_push_number.yaml @@ -0,0 +1,21 @@ +name: duk_push_number + +proto: | + void duk_push_number(duk_context *ctx, duk_double_t val); + +stack: | + [ ... ] -> [ ... val! ] + +summary: | +

Push number (IEEE double) val to the stack.

+ +

If val is a NaN it may be normalized into another + NaN form.

+ +example: | + duk_push_number(ctx, 123.0); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_push_object.txt b/website/api/duk_push_object.txt deleted file mode 100644 index 1ff85395..00000000 --- a/website/api/duk_push_object.txt +++ /dev/null @@ -1,30 +0,0 @@ -=proto -duk_idx_t duk_push_object(duk_context *ctx); - -=stack -[ ... ] -> [ ... obj! ] - -=summary -

Push an empty object to the stack. Returns non-negative index (relative -to stack bottom) of the pushed object.

- -

The internal prototype of the created object is Object.prototype. -Use duk_set_prototype() to change it.

- -=example -duk_idx_t obj_idx; - -obj_idx = duk_push_object(ctx); -duk_push_int(ctx, 42); -duk_put_prop_string(ctx, obj_idx, "meaningOfLife"); - -/* object is now: { "meaningOfLife": 42 } */ - -duk_pop(ctx); /* pop object */ - -=tags -stack -object - -=introduced -1.0.0 diff --git a/website/api/duk_push_object.yaml b/website/api/duk_push_object.yaml new file mode 100644 index 00000000..4d7e1b4f --- /dev/null +++ b/website/api/duk_push_object.yaml @@ -0,0 +1,31 @@ +name: duk_push_object + +proto: | + duk_idx_t duk_push_object(duk_context *ctx); + +stack: | + [ ... ] -> [ ... obj! ] + +summary: | +

Push an empty object to the stack. Returns non-negative index (relative + to stack bottom) of the pushed object.

+ +

The internal prototype of the created object is Object.prototype. + Use duk_set_prototype() to change it.

+ +example: | + duk_idx_t obj_idx; + + obj_idx = duk_push_object(ctx); + duk_push_int(ctx, 42); + duk_put_prop_string(ctx, obj_idx, "meaningOfLife"); + + /* object is now: { "meaningOfLife": 42 } */ + + duk_pop(ctx); /* pop object */ + +tags: + - stack + - object + +introduced: 1.0.0 diff --git a/website/api/duk_push_pointer.txt b/website/api/duk_push_pointer.txt deleted file mode 100644 index a94cae41..00000000 --- a/website/api/duk_push_pointer.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -void duk_push_pointer(duk_context *ctx, void *p); - -=stack -[ ... ] -> [ ... ptr! ] - -=summary -

Push p into the stack as a pointer value. Duktape won't -interpret the pointer in any manner.

- -=example -struct mystruct *p = /* ... */; - -duk_push_pointer(ctx, (void *) p); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_push_pointer.yaml b/website/api/duk_push_pointer.yaml new file mode 100644 index 00000000..8de35a8f --- /dev/null +++ b/website/api/duk_push_pointer.yaml @@ -0,0 +1,21 @@ +name: duk_push_pointer + +proto: | + void duk_push_pointer(duk_context *ctx, void *p); + +stack: | + [ ... ] -> [ ... ptr! ] + +summary: | +

Push p into the stack as a pointer value. Duktape won't + interpret the pointer in any manner.

+ +example: | + struct mystruct *p = /* ... */; + + duk_push_pointer(ctx, (void *) p); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_push_sprintf.txt b/website/api/duk_push_sprintf.txt deleted file mode 100644 index 7ca20911..00000000 --- a/website/api/duk_push_sprintf.txt +++ /dev/null @@ -1,30 +0,0 @@ -=proto -const char *duk_push_sprintf(duk_context *ctx, const char *fmt, ...); - -=stack -[ ... ] -> [ ... str! ] - -=summary -

Format a string like sprintf() (but safely) and push the result -to the value stack. Returns a non-NULL pointer to the resulting -string.

- -

If fmt is NULL, an empty string is pushed to the stack -and a non-NULL pointer to an empty string is returned (this -behavior mimics what sprintf() does for a NULL format -string, at least on Linux). The returned pointer can be dereferenced and a -NUL terminator character is guaranteed.

- -

Unlike sprintf() the string formatting is safe. Concretely, -the implementation will try increasing temporary buffer sizes until a -large enough buffer is found for the temporary formatted value.

- -=example -duk_push_sprintf(ctx, "meaning of life: %d, name: %s", 42, "Zaphod"); - -=tags -stack -string - -=introduced -1.0.0 diff --git a/website/api/duk_push_sprintf.yaml b/website/api/duk_push_sprintf.yaml new file mode 100644 index 00000000..c1449521 --- /dev/null +++ b/website/api/duk_push_sprintf.yaml @@ -0,0 +1,31 @@ +name: duk_push_sprintf + +proto: | + const char *duk_push_sprintf(duk_context *ctx, const char *fmt, ...); + +stack: | + [ ... ] -> [ ... str! ] + +summary: | +

Format a string like sprintf() (but safely) and push the result + to the value stack. Returns a non-NULL pointer to the resulting + string.

+ +

If fmt is NULL, an empty string is pushed to the stack + and a non-NULL pointer to an empty string is returned (this + behavior mimics what sprintf() does for a NULL format + string, at least on Linux). The returned pointer can be dereferenced and a + NUL terminator character is guaranteed.

+ +

Unlike sprintf() the string formatting is safe. Concretely, + the implementation will try increasing temporary buffer sizes until a + large enough buffer is found for the temporary formatted value.

+ +example: | + duk_push_sprintf(ctx, "meaning of life: %d, name: %s", 42, "Zaphod"); + +tags: + - stack + - string + +introduced: 1.0.0 diff --git a/website/api/duk_push_string.txt b/website/api/duk_push_string.txt deleted file mode 100644 index 0b5f30f8..00000000 --- a/website/api/duk_push_string.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -const char *duk_push_string(duk_context *ctx, const char *str); - -=stack -[ ... ] -> [ ... str! ] (if str != NULL) -[ ... ] -> [ ... null! ] (if str == NULL) - -=summary -

Push a C string into the stack. String length is automatically detected -with a strlen() equivalent (i.e. looking for the first NUL character). -A pointer to the interned string data is returned. If the operation fails, -throws an error.

- -

If str is NULL, an Ecmascript null is pushed -to the stack and NULL is returned. This behavior differs from -duk_push_lstring on purpose.

- -

C code should normally only push valid CESU-8 strings to the stack.

- -

If input string might contain internal NUL characters, use -duk_push_lstring() instead.

- -=example -duk_push_string(ctx, "foo"); -duk_push_string(ctx, "foo\0bar"); /* push "foo", not "foo\0bar" */ -duk_push_string(ctx, ""); /* push empty string */ -duk_push_string(ctx, NULL); /* push 'null' */ - -=tags -stack -string - -=introduced -1.0.0 diff --git a/website/api/duk_push_string.yaml b/website/api/duk_push_string.yaml new file mode 100644 index 00000000..3a9a6901 --- /dev/null +++ b/website/api/duk_push_string.yaml @@ -0,0 +1,35 @@ +name: duk_push_string + +proto: | + const char *duk_push_string(duk_context *ctx, const char *str); + +stack: | + [ ... ] -> [ ... str! ] (if str != NULL) + [ ... ] -> [ ... null! ] (if str == NULL) + +summary: | +

Push a C string into the stack. String length is automatically detected + with a strlen() equivalent (i.e. looking for the first NUL character). + A pointer to the interned string data is returned. If the operation fails, + throws an error.

+ +

If str is NULL, an Ecmascript null is pushed + to the stack and NULL is returned. This behavior differs from + duk_push_lstring on purpose.

+ +

C code should normally only push valid CESU-8 strings to the stack.

+ +

If input string might contain internal NUL characters, use + duk_push_lstring() instead.

+ +example: | + duk_push_string(ctx, "foo"); + duk_push_string(ctx, "foo\0bar"); /* push "foo", not "foo\0bar" */ + duk_push_string(ctx, ""); /* push empty string */ + duk_push_string(ctx, NULL); /* push 'null' */ + +tags: + - stack + - string + +introduced: 1.0.0 diff --git a/website/api/duk_push_string_file.txt b/website/api/duk_push_string_file.txt deleted file mode 100644 index 485490df..00000000 --- a/website/api/duk_push_string_file.txt +++ /dev/null @@ -1,26 +0,0 @@ -=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 -nonportable - -=introduced -1.0.0 diff --git a/website/api/duk_push_string_file.yaml b/website/api/duk_push_string_file.yaml new file mode 100644 index 00000000..57662988 --- /dev/null +++ b/website/api/duk_push_string_file.yaml @@ -0,0 +1,27 @@ +name: duk_push_string_file + +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 + - nonportable + +introduced: 1.0.0 diff --git a/website/api/duk_push_this.txt b/website/api/duk_push_this.txt deleted file mode 100644 index 8d12977c..00000000 --- a/website/api/duk_push_this.txt +++ /dev/null @@ -1,19 +0,0 @@ -=proto -void duk_push_this(duk_context *ctx); - -=stack -[ ... ] -> [ ... this! ] - -=summary -

Push the this binding of the currently running C function to -the stack.

- -=example -duk_push_this(ctx); - -=tags -stack -function - -=introduced -1.0.0 diff --git a/website/api/duk_push_this.yaml b/website/api/duk_push_this.yaml new file mode 100644 index 00000000..9068a8d9 --- /dev/null +++ b/website/api/duk_push_this.yaml @@ -0,0 +1,20 @@ +name: duk_push_this + +proto: | + void duk_push_this(duk_context *ctx); + +stack: | + [ ... ] -> [ ... this! ] + +summary: | +

Push the this binding of the currently running C function to + the stack.

+ +example: | + duk_push_this(ctx); + +tags: + - stack + - function + +introduced: 1.0.0 diff --git a/website/api/duk_push_thread.txt b/website/api/duk_push_thread.txt deleted file mode 100644 index 81ecb93b..00000000 --- a/website/api/duk_push_thread.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -duk_idx_t duk_push_thread(duk_context *ctx); - -=stack -[ ... ] -> [ ... thr! ] - -=summary -

Push a new Duktape thread (context, coroutine) to the stack. Returns -non-negative index (relative to stack bottom) of the pushed thread. -The new thread will be associated with the same Duktape heap as the -argument ctx, and will share the same global object -environment.

- -

To interact with the new thread with the Duktape API, use -duk_get_context() to get -a context pointer for API calls.

- -=example -duk_idx_t thr_idx; -duk_context *new_ctx; - -thr_idx = duk_push_thread(ctx); -new_ctx = duk_get_context(ctx, thr_idx); - -=tags -stack -thread -borrowed - -=seealso -duk_push_thread_new_globalenv - -=introduced -1.0.0 diff --git a/website/api/duk_push_thread.yaml b/website/api/duk_push_thread.yaml new file mode 100644 index 00000000..7d197080 --- /dev/null +++ b/website/api/duk_push_thread.yaml @@ -0,0 +1,35 @@ +name: duk_push_thread + +proto: | + duk_idx_t duk_push_thread(duk_context *ctx); + +stack: | + [ ... ] -> [ ... thr! ] + +summary: | +

Push a new Duktape thread (context, coroutine) to the stack. Returns + non-negative index (relative to stack bottom) of the pushed thread. + The new thread will be associated with the same Duktape heap as the + argument ctx, and will share the same global object + environment.

+ +

To interact with the new thread with the Duktape API, use + duk_get_context() to get + a context pointer for API calls.

+ +example: | + duk_idx_t thr_idx; + duk_context *new_ctx; + + thr_idx = duk_push_thread(ctx); + new_ctx = duk_get_context(ctx, thr_idx); + +tags: + - stack + - thread + - borrowed + +seealso: + - duk_push_thread_new_globalenv + +introduced: 1.0.0 diff --git a/website/api/duk_push_thread_new_globalenv.txt b/website/api/duk_push_thread_new_globalenv.txt deleted file mode 100644 index 42942e0b..00000000 --- a/website/api/duk_push_thread_new_globalenv.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -duk_idx_t duk_push_thread_new_globalenv(duk_context *ctx); - -=stack -[ ... ] -> [ ... thr! ] - -=summary -

Push a new Duktape thread (context, coroutine) to the stack. Returns -non-negative index (relative to stack bottom) of the pushed thread. -The new thread will be associated with the same Duktape heap as the -argument ctx, but will have a new global object environment -(separate from the one used by ctx).

- -

To interact with the new thread with the Duktape API, use -duk_get_context() to get -a context pointer for API calls.

- -=example -duk_idx_t thr_idx; -duk_context *new_ctx; - -thr_idx = duk_push_thread_new_globalenv(ctx); -new_ctx = duk_get_context(ctx, thr_idx); - -=tags -stack -thread -borrowed - -=seealso -duk_push_thread - -=introduced -1.0.0 diff --git a/website/api/duk_push_thread_new_globalenv.yaml b/website/api/duk_push_thread_new_globalenv.yaml new file mode 100644 index 00000000..acdd1c5d --- /dev/null +++ b/website/api/duk_push_thread_new_globalenv.yaml @@ -0,0 +1,35 @@ +name: duk_push_thread_new_globalenv + +proto: | + duk_idx_t duk_push_thread_new_globalenv(duk_context *ctx); + +stack: | + [ ... ] -> [ ... thr! ] + +summary: | +

Push a new Duktape thread (context, coroutine) to the stack. Returns + non-negative index (relative to stack bottom) of the pushed thread. + The new thread will be associated with the same Duktape heap as the + argument ctx, but will have a new global object environment + (separate from the one used by ctx).

+ +

To interact with the new thread with the Duktape API, use + duk_get_context() to get + a context pointer for API calls.

+ +example: | + duk_idx_t thr_idx; + duk_context *new_ctx; + + thr_idx = duk_push_thread_new_globalenv(ctx); + new_ctx = duk_get_context(ctx, thr_idx); + +tags: + - stack + - thread + - borrowed + +seealso: + - duk_push_thread + +introduced: 1.0.0 diff --git a/website/api/duk_push_thread_stash.txt b/website/api/duk_push_thread_stash.txt deleted file mode 100644 index 245ea22c..00000000 --- a/website/api/duk_push_thread_stash.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -void duk_push_thread_stash(duk_context *ctx, duk_context *target_ctx) { - -=stack -[ ... ] -> [ ... stash! ] - -=summary -

Push the stash object related to target_ctx to the stack (the -ctx and target_ctx arguments may refer to the same -thread). The thread stash is an internal object which can be used to store -key/value pairs from C code so that they are reachable for garbage collection, -but are not accessible from Ecmascript code. The stash is only accessible -from C code with a matching target_ctx argument.

- -

If target_ctx is NULL, throws an error.

- -=example -duk_push_thread_stash(ctx, ctx2); - -=tags -stack -stash -object -module -thread -sandbox - -=seealso -duk_push_heap_stash -duk_push_global_stash - -=introduced -1.0.0 diff --git a/website/api/duk_push_thread_stash.yaml b/website/api/duk_push_thread_stash.yaml new file mode 100644 index 00000000..f55b3c83 --- /dev/null +++ b/website/api/duk_push_thread_stash.yaml @@ -0,0 +1,34 @@ +name: duk_push_thread_stash + +proto: | + void duk_push_thread_stash(duk_context *ctx, duk_context *target_ctx) { + +stack: | + [ ... ] -> [ ... stash! ] + +summary: | +

Push the stash object related to target_ctx to the stack (the + ctx and target_ctx arguments may refer to the same + thread). The thread stash is an internal object which can be used to store + key/value pairs from C code so that they are reachable for garbage collection, + but are not accessible from Ecmascript code. The stash is only accessible + from C code with a matching target_ctx argument.

+ +

If target_ctx is NULL, throws an error.

+ +example: | + duk_push_thread_stash(ctx, ctx2); + +tags: + - stack + - stash + - object + - module + - thread + - sandbox + +seealso: + - duk_push_heap_stash + - duk_push_global_stash + +introduced: 1.0.0 diff --git a/website/api/duk_push_true.txt b/website/api/duk_push_true.txt deleted file mode 100644 index 68276ad1..00000000 --- a/website/api/duk_push_true.txt +++ /dev/null @@ -1,19 +0,0 @@ -=proto -void duk_push_true(duk_context *ctx); - -=stack -[ ... ] -> [ ... true! ] - -=summary -

Push true to stack. Equivalent to calling -duk_push_boolean(ctx, 1).

- -=example -duk_push_true(ctx); - -=tags -stack - - -=introduced -1.0.0 diff --git a/website/api/duk_push_true.yaml b/website/api/duk_push_true.yaml new file mode 100644 index 00000000..f7993cfd --- /dev/null +++ b/website/api/duk_push_true.yaml @@ -0,0 +1,19 @@ +name: duk_push_true + +proto: | + void duk_push_true(duk_context *ctx); + +stack: | + [ ... ] -> [ ... true! ] + +summary: | +

Push true to stack. Equivalent to calling + duk_push_boolean(ctx, 1).

+ +example: | + duk_push_true(ctx); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_push_uint.txt b/website/api/duk_push_uint.txt deleted file mode 100644 index f541bc3f..00000000 --- a/website/api/duk_push_uint.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -void duk_push_uint(duk_context *ctx, duk_uint_t val); - -=stack -[ ... ] -> [ ... val! ] - -=summary -

Convert val to an IEEE double and push it to the stack.

- -

This is a shorthand for calling -duk_push_number(ctx, (duk_double_t) val).

- -=example -duk_push_uint(ctx, 123); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_push_uint.yaml b/website/api/duk_push_uint.yaml new file mode 100644 index 00000000..c4645b29 --- /dev/null +++ b/website/api/duk_push_uint.yaml @@ -0,0 +1,21 @@ +name: duk_push_uint + +proto: | + void duk_push_uint(duk_context *ctx, duk_uint_t val); + +stack: | + [ ... ] -> [ ... val! ] + +summary: | +

Convert val to an IEEE double and push it to the stack.

+ +

This is a shorthand for calling + duk_push_number(ctx, (duk_double_t) val).

+ +example: | + duk_push_uint(ctx, 123); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_push_undefined.txt b/website/api/duk_push_undefined.txt deleted file mode 100644 index a58dba9f..00000000 --- a/website/api/duk_push_undefined.txt +++ /dev/null @@ -1,17 +0,0 @@ -=proto -void duk_push_undefined(duk_context *ctx); - -=stack -[ ... ] -> [ ... undefined! ] - -=summary -

Push undefined to the stack.

- -=example -duk_push_undefined(ctx); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_push_undefined.yaml b/website/api/duk_push_undefined.yaml new file mode 100644 index 00000000..e20d9386 --- /dev/null +++ b/website/api/duk_push_undefined.yaml @@ -0,0 +1,18 @@ +name: duk_push_undefined + +proto: | + void duk_push_undefined(duk_context *ctx); + +stack: | + [ ... ] -> [ ... undefined! ] + +summary: | +

Push undefined to the stack.

+ +example: | + duk_push_undefined(ctx); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_push_vsprintf.txt b/website/api/duk_push_vsprintf.txt deleted file mode 100644 index e872b1aa..00000000 --- a/website/api/duk_push_vsprintf.txt +++ /dev/null @@ -1,46 +0,0 @@ -=proto -const char *duk_push_vsprintf(duk_context *ctx, const char *fmt, va_list ap); - -=stack -[ ... ] -> [ ... str! ] - -=summary -

Format a string like vsprintf() (but safely) and push the result -value to the value stack. Returns a non-NULL pointer to the -resulting string.

- -

If fmt is NULL, an empty string is pushed to the stack -and a non-NULL pointer to an empty string is returned (this -behavior mimics what vsprintf() does for a NULL format -string, at least on Linux). The returned pointer can be dereferenced and a -NUL terminator character is guaranteed.

- -

Unlike vsprintf() the string formatting is safe. Concretely, -the implementation will try increasing temporary buffer sizes until a -large enough buffer is found for the temporary formatted value.

- -
-

The ap argument cannot be safely reused for multiple calls. -This is a limitation of the vararg mechanism.

-
- -=example -void test_vsprintf(duk_context *ctx, ...) { - va_list ap; - - va_start(ap, ctx); - duk_push_vsprintf(ctx, "test: %d+%d=%d", ap); - va_end(ap); -} - -void test(duk_context *ctx) { - test_vsprintf(ctx, 2, 3, 5); -} - -=tags -stack -string -vararg - -=introduced -1.0.0 diff --git a/website/api/duk_push_vsprintf.yaml b/website/api/duk_push_vsprintf.yaml new file mode 100644 index 00000000..4a0775fb --- /dev/null +++ b/website/api/duk_push_vsprintf.yaml @@ -0,0 +1,47 @@ +name: duk_push_vsprintf + +proto: | + const char *duk_push_vsprintf(duk_context *ctx, const char *fmt, va_list ap); + +stack: | + [ ... ] -> [ ... str! ] + +summary: | +

Format a string like vsprintf() (but safely) and push the result + value to the value stack. Returns a non-NULL pointer to the + resulting string.

+ +

If fmt is NULL, an empty string is pushed to the stack + and a non-NULL pointer to an empty string is returned (this + behavior mimics what vsprintf() does for a NULL format + string, at least on Linux). The returned pointer can be dereferenced and a + NUL terminator character is guaranteed.

+ +

Unlike vsprintf() the string formatting is safe. Concretely, + the implementation will try increasing temporary buffer sizes until a + large enough buffer is found for the temporary formatted value.

+ +
+

The ap argument cannot be safely reused for multiple calls. + This is a limitation of the vararg mechanism.

+
+ +example: | + void test_vsprintf(duk_context *ctx, ...) { + va_list ap; + + va_start(ap, ctx); + duk_push_vsprintf(ctx, "test: %d+%d=%d", ap); + va_end(ap); + } + + void test(duk_context *ctx) { + test_vsprintf(ctx, 2, 3, 5); + } + +tags: + - stack + - string + - vararg + +introduced: 1.0.0 diff --git a/website/api/duk_put_function_list.txt b/website/api/duk_put_function_list.txt deleted file mode 100644 index d5c47d83..00000000 --- a/website/api/duk_put_function_list.txt +++ /dev/null @@ -1,42 +0,0 @@ -=proto -void duk_put_function_list(duk_context *ctx, duk_idx_t obj_index, const duk_function_list_entry *funcs); - -=stack -[ ... obj! ... ] -> [ ... obj! ... ] - -=summary -

Set multiple function properties into a target object at obj_index. -The functions are specified as a list of triples (name, function, nargs), ending -with a triple where name is NULL (preferably also function is -NULL for sanity).

- -

This is useful e.g. when defining modules or classes implemented -as a set of Duktape/C functions.

- -=example -const duk_function_list_entry my_module_funcs[] = { - { "tweak", do_tweak, 0 /* no args */ }, - { "adjust", do_adjust, 3 /* 3 args */ }, - { "frobnicate", do_frobnicate, DUK_VARAGS /* variable args */ }, - { NULL, NULL, 0 } -}; - -/* Initialize an object with a set of function properties, and set it to - * global object 'MyModule'. - */ - -duk_push_global_object(ctx); -duk_push_object(ctx); /* -> [ ... global obj ] */ -duk_put_function_list(ctx, -1, my_module_funcs); -duk_put_prop_string(ctx, -2, "MyModule"); /* -> [ ... global ] */ -duk_pop(ctx); - -=tags -property -module - -=seealso -duk_put_number_list - -=introduced -1.0.0 diff --git a/website/api/duk_put_function_list.yaml b/website/api/duk_put_function_list.yaml new file mode 100644 index 00000000..3be7baa8 --- /dev/null +++ b/website/api/duk_put_function_list.yaml @@ -0,0 +1,43 @@ +name: duk_put_function_list + +proto: | + void duk_put_function_list(duk_context *ctx, duk_idx_t obj_index, const duk_function_list_entry *funcs); + +stack: | + [ ... obj! ... ] -> [ ... obj! ... ] + +summary: | +

Set multiple function properties into a target object at obj_index. + The functions are specified as a list of triples (name, function, nargs), ending + with a triple where name is NULL (preferably also function is + NULL for sanity).

+ +

This is useful e.g. when defining modules or classes implemented + as a set of Duktape/C functions.

+ +example: | + const duk_function_list_entry my_module_funcs[] = { + { "tweak", do_tweak, 0 /* no args */ }, + { "adjust", do_adjust, 3 /* 3 args */ }, + { "frobnicate", do_frobnicate, DUK_VARAGS /* variable args */ }, + { NULL, NULL, 0 } + }; + + /* Initialize an object with a set of function properties, and set it to + * global object 'MyModule'. + */ + + duk_push_global_object(ctx); + duk_push_object(ctx); /* -> [ ... global obj ] */ + duk_put_function_list(ctx, -1, my_module_funcs); + duk_put_prop_string(ctx, -2, "MyModule"); /* -> [ ... global ] */ + duk_pop(ctx); + +tags: + - property + - module + +seealso: + - duk_put_number_list + +introduced: 1.0.0 diff --git a/website/api/duk_put_global_string.txt b/website/api/duk_put_global_string.txt deleted file mode 100644 index c0ea21b2..00000000 --- a/website/api/duk_put_global_string.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -duk_bool_t duk_put_global_string(duk_context *ctx, const char *key); - -=stack -[ ... val! ] -> [ ... ] - -=summary -

Put property named key to the global object. -Return value behaves similarly to -duk_put_prop(). -This is a convenience function which does the equivalent of:

-
-duk_bool_t ret;
-
-duk_push_global_object(ctx);
-duk_insert(ctx, -2);
-ret = duk_put_prop_string(ctx, -2, key);
-duk_pop(ctx);
-/* 'ret' would be the return value from duk_put_global_string() */
-
- -=example -duk_push_string(ctx, "1.2.3"); -(void) duk_put_global_string(ctx, "my_app_version"); - -=tags -property - -=seealso -duk_get_global_string - -=introduced -1.0.0 diff --git a/website/api/duk_put_global_string.yaml b/website/api/duk_put_global_string.yaml new file mode 100644 index 00000000..95315451 --- /dev/null +++ b/website/api/duk_put_global_string.yaml @@ -0,0 +1,34 @@ +name: duk_put_global_string + +proto: | + duk_bool_t duk_put_global_string(duk_context *ctx, const char *key); + +stack: | + [ ... val! ] -> [ ... ] + +summary: | +

Put property named key to the global object. + Return value behaves similarly to + duk_put_prop(). + This is a convenience function which does the equivalent of:

+ 
+  duk_bool_t ret;
+
+  duk_push_global_object(ctx);
+  duk_insert(ctx, -2);
+  ret = duk_put_prop_string(ctx, -2, key);
+  duk_pop(ctx);
+  /* 'ret' would be the return value from duk_put_global_string() */
+
+ +example: | + duk_push_string(ctx, "1.2.3"); + (void) duk_put_global_string(ctx, "my_app_version"); + +tags: + - property + +seealso: + - duk_get_global_string + +introduced: 1.0.0 diff --git a/website/api/duk_put_number_list.txt b/website/api/duk_put_number_list.txt deleted file mode 100644 index e8820bc4..00000000 --- a/website/api/duk_put_number_list.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -void duk_put_number_list(duk_context *ctx, duk_idx_t obj_index, const duk_number_list_entry *numbers); - -=stack -[ ... obj! ... ] -> [ ... obj! ... ] - -=summary -

Set multiple number (double) properties into a target object -at obj_index. The number list is given as a list of pairs -(name, number), ending with a pair where the name is NULL.

- -

This is useful e.g. when defining numeric constants for modules or -classes implemented in C.

- -=example -const duk_number_list_entry my_module_consts[] = { - { "FLAG_FOO", (double) (1 << 0) }, - { "FLAG_BAR", (double) (1 << 1) }, - { "FLAG_QUUX", (double) (1 << 2) }, - { "DELAY", 300.0 }, - { NULL, 0.0 } -}; - -duk_put_number_list(ctx, -3, my_module_consts); - -=tags -property -module - -=seealso -duk_put_function_list - -=introduced -1.0.0 diff --git a/website/api/duk_put_number_list.yaml b/website/api/duk_put_number_list.yaml new file mode 100644 index 00000000..64716948 --- /dev/null +++ b/website/api/duk_put_number_list.yaml @@ -0,0 +1,35 @@ +name: duk_put_number_list + +proto: | + void duk_put_number_list(duk_context *ctx, duk_idx_t obj_index, const duk_number_list_entry *numbers); + +stack: | + [ ... obj! ... ] -> [ ... obj! ... ] + +summary: | +

Set multiple number (double) properties into a target object + at obj_index. The number list is given as a list of pairs + (name, number), ending with a pair where the name is NULL.

+ +

This is useful e.g. when defining numeric constants for modules or + classes implemented in C.

+ +example: | + const duk_number_list_entry my_module_consts[] = { + { "FLAG_FOO", (double) (1 << 0) }, + { "FLAG_BAR", (double) (1 << 1) }, + { "FLAG_QUUX", (double) (1 << 2) }, + { "DELAY", 300.0 }, + { NULL, 0.0 } + }; + + duk_put_number_list(ctx, -3, my_module_consts); + +tags: + - property + - module + +seealso: + - duk_put_function_list + +introduced: 1.0.0 diff --git a/website/api/duk_put_prop.txt b/website/api/duk_put_prop.txt deleted file mode 100644 index a44738e3..00000000 --- a/website/api/duk_put_prop.txt +++ /dev/null @@ -1,78 +0,0 @@ -=proto -duk_bool_t duk_put_prop(duk_context *ctx, duk_idx_t obj_index); - -=stack -[ ... obj! ... key! val! ] -> [ ... obj! ... ] - -=summary -

Write val to the property key of a value at -obj_index. key and val are removed -from the stack. Return code and error throwing behavior:

-
    -
  • If the property write succeeds, returns 1.
    • -
  • If the property write fails, throws an error (strict mode semantics). - An error may also be thrown by the "setter" function of an accessor property.
    • -
  • If the value at obj_index is not - object coercible, - throws an error.
    • -
  • If obj_index is invalid, throws an error.
    • -
- -

The property write is equivalent to the Ecmascript expression:

-
-obj[key] = val
-
- -

The exact rules of when a property write succeeds or fails are the same -as for Ecmascript code making the above assignment.

- -

For semantics, see -Property Accessors, -PutValue (V, W), -and [[Put]] (P, V, Throw). -Both the target value and the key are coerced:

-
    -
  • The target value is automatically coerced to an object. However, the object - is transitory so writing its properties is not very useful. Moreover, - Ecmascript semantics prevent new properties from being created for such - transitory objects (see - PutValue (V, W), - step 7 of the special [[Put]] variant).
    • -
  • The key argument is internally coerced to a string. There is - an internal fast path for arrays and numeric indices which avoids an - explicit string coercion, so use a numeric key when applicable.

    -
- -
-In Ecmascript an assignment expression has the value of the right-hand-side -expression, regardless of whether or not the assignment succeeds. The return -value for this API call is not specified by Ecmascript or available to -Ecmascript code: the API call returns 0 or 1 -depending on whether the assignment succeeded or not (with the 0 -return value promoted to an error in strict code). -
- -

If the key is a fixed string you can avoid one API call and use the -duk_put_prop_string() variant. -Similarly, if the key is an array index, you can use the -duk_put_prop_index() variant.

- -
- -=example -duk_bool_t rc; - -duk_push_string(ctx, "key"); -duk_push_string(ctx, "value"); -rc = duk_put_prop(ctx, -3); -printf("rc=%d\n", (int) rc); - -=tags -property - -=seealso -duk_put_prop_string -duk_put_prop_index - -=introduced -1.0.0 diff --git a/website/api/duk_put_prop.yaml b/website/api/duk_put_prop.yaml new file mode 100644 index 00000000..bebfe239 --- /dev/null +++ b/website/api/duk_put_prop.yaml @@ -0,0 +1,79 @@ +name: duk_put_prop + +proto: | + duk_bool_t duk_put_prop(duk_context *ctx, duk_idx_t obj_index); + +stack: | + [ ... obj! ... key! val! ] -> [ ... obj! ... ] + +summary: | +

Write val to the property key of a value at + obj_index. key and val are removed + from the stack. Return code and error throwing behavior:

+
    +
  • If the property write succeeds, returns 1.
    • +
  • If the property write fails, throws an error (strict mode semantics). + An error may also be thrown by the "setter" function of an accessor property.
    • +
  • If the value at obj_index is not + object coercible, + throws an error.
    • +
  • If obj_index is invalid, throws an error.
    • +
+ +

The property write is equivalent to the Ecmascript expression:

+ 
+  obj[key] = val
+
+ +

The exact rules of when a property write succeeds or fails are the same + as for Ecmascript code making the above assignment.

+ +

For semantics, see + Property Accessors, + PutValue (V, W), + and [[Put]] (P, V, Throw). + Both the target value and the key are coerced:

+
    +
  • The target value is automatically coerced to an object. However, the object + is transitory so writing its properties is not very useful. Moreover, + Ecmascript semantics prevent new properties from being created for such + transitory objects (see + PutValue (V, W), + step 7 of the special [[Put]] variant).
    • +
  • The key argument is internally coerced to a string. There is + an internal fast path for arrays and numeric indices which avoids an + explicit string coercion, so use a numeric key when applicable.

    +
+ +
+ In Ecmascript an assignment expression has the value of the right-hand-side + expression, regardless of whether or not the assignment succeeds. The return + value for this API call is not specified by Ecmascript or available to + Ecmascript code: the API call returns 0 or 1 + depending on whether the assignment succeeded or not (with the 0 + return value promoted to an error in strict code). +
+ +

If the key is a fixed string you can avoid one API call and use the + duk_put_prop_string() variant. + Similarly, if the key is an array index, you can use the + duk_put_prop_index() variant.

+ +
+ +example: | + duk_bool_t rc; + + duk_push_string(ctx, "key"); + duk_push_string(ctx, "value"); + rc = duk_put_prop(ctx, -3); + printf("rc=%d\n", (int) rc); + +tags: + - property + +seealso: + - duk_put_prop_string + - duk_put_prop_index + +introduced: 1.0.0 diff --git a/website/api/duk_put_prop_index.txt b/website/api/duk_put_prop_index.txt deleted file mode 100644 index c48cfdf0..00000000 --- a/website/api/duk_put_prop_index.txt +++ /dev/null @@ -1,27 +0,0 @@ -=proto -duk_bool_t duk_put_prop_index(duk_context *ctx, duk_idx_t obj_index, duk_uarridx_t arr_index); - -=stack -[ ... obj! ... val! ] -> [ ... obj! ... ] - -=summary -

Like duk_put_prop(), -but the property name is given as an unsigned integer -arr_index. This is especially useful for writing to -array elements (but is not limited to that).

- -

Conceptually the number is coerced to a string for the property -write, e.g. 123 would be equivalent to a property -name "123". Duktape avoids an explicit coercion whenever -possible.

- -=example -duk_push_string(ctx, "value"); -rc = duk_put_prop_index(ctx, -3, 123); /* write to obj[123] */ -printf("rc=%d\n", (int) rc); - -=tags -property - -=introduced -1.0.0 diff --git a/website/api/duk_put_prop_index.yaml b/website/api/duk_put_prop_index.yaml new file mode 100644 index 00000000..a2bdb5ed --- /dev/null +++ b/website/api/duk_put_prop_index.yaml @@ -0,0 +1,28 @@ +name: duk_put_prop_index + +proto: | + duk_bool_t duk_put_prop_index(duk_context *ctx, duk_idx_t obj_index, duk_uarridx_t arr_index); + +stack: | + [ ... obj! ... val! ] -> [ ... obj! ... ] + +summary: | +

Like duk_put_prop(), + but the property name is given as an unsigned integer + arr_index. This is especially useful for writing to + array elements (but is not limited to that).

+ +

Conceptually the number is coerced to a string for the property + write, e.g. 123 would be equivalent to a property + name "123". Duktape avoids an explicit coercion whenever + possible.

+ +example: | + duk_push_string(ctx, "value"); + rc = duk_put_prop_index(ctx, -3, 123); /* write to obj[123] */ + printf("rc=%d\n", (int) rc); + +tags: + - property + +introduced: 1.0.0 diff --git a/website/api/duk_put_prop_string.txt b/website/api/duk_put_prop_string.txt deleted file mode 100644 index 6912a465..00000000 --- a/website/api/duk_put_prop_string.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -duk_bool_t duk_put_prop_string(duk_context *ctx, duk_idx_t obj_index, const char *key); - -=stack -[ ... obj! ... val! ] -> [ ... obj! ... ] - -=summary -

Like duk_put_prop(), -but the property name is given as a NUL-terminated C string -key.

- -=example -duk_bool_t rc; - -duk_push_string(ctx, "value"); -rc = duk_put_prop_string(ctx, -3, "key"); -printf("rc=%d\n", (int) rc); - -=tags -property - -=introduced -1.0.0 diff --git a/website/api/duk_put_prop_string.yaml b/website/api/duk_put_prop_string.yaml new file mode 100644 index 00000000..f233d956 --- /dev/null +++ b/website/api/duk_put_prop_string.yaml @@ -0,0 +1,24 @@ +name: duk_put_prop_string + +proto: | + duk_bool_t duk_put_prop_string(duk_context *ctx, duk_idx_t obj_index, const char *key); + +stack: | + [ ... obj! ... val! ] -> [ ... obj! ... ] + +summary: | +

Like duk_put_prop(), + but the property name is given as a NUL-terminated C string + key.

+ +example: | + duk_bool_t rc; + + duk_push_string(ctx, "value"); + rc = duk_put_prop_string(ctx, -3, "key"); + printf("rc=%d\n", (int) rc); + +tags: + - property + +introduced: 1.0.0 diff --git a/website/api/duk_put_var.txt b/website/api/duk_put_var.txt deleted file mode 100644 index 7c0692ff..00000000 --- a/website/api/duk_put_var.txt +++ /dev/null @@ -1,35 +0,0 @@ -=proto -void duk_put_var(duk_context *ctx); - -=stack -[ ... varname! val! ] -> [ ... ] - -=summary - -

Write val to the identifier varname. Possible outcomes:

-
    -
  • If identifier is found and write succeeds: XXX.
    • -
  • If identifier is found and write fails (e.g. write-protected property): XXX.
    • -
  • If identifier is not found but can be created: XXX.
    • -
  • If identifier is not found and cannot be created (e.g. global object is - non-extensible): XXX.
    • -
  • If the input stack does not contain enough arguments (or some other internal - error occurs), throws an error.
    • -
- -XXX - -

The identifier write is equivalent to the Ecmascript expression:

-
-varname = val
-
- -=example -XXX - -=tags -variable -omit - -=introduced -1.0.0 diff --git a/website/api/duk_put_var.yaml b/website/api/duk_put_var.yaml new file mode 100644 index 00000000..d1568469 --- /dev/null +++ b/website/api/duk_put_var.yaml @@ -0,0 +1,36 @@ +name: duk_put_var + +proto: | + void duk_put_var(duk_context *ctx); + +stack: | + [ ... varname! val! ] -> [ ... ] + +summary: | + +

Write val to the identifier varname. Possible outcomes:

+
    +
  • If identifier is found and write succeeds: XXX.
    • +
  • If identifier is found and write fails (e.g. write-protected property): XXX.
    • +
  • If identifier is not found but can be created: XXX.
    • +
  • If identifier is not found and cannot be created (e.g. global object is + non-extensible): XXX.
    • +
  • If the input stack does not contain enough arguments (or some other internal + error occurs), throws an error.
    • +
+ + XXX + +

The identifier write is equivalent to the Ecmascript expression:

+ 
+  varname = val
+
+ +example: | + XXX + +tags: + - variable + - omit + +introduced: 1.0.0 diff --git a/website/api/duk_realloc.txt b/website/api/duk_realloc.txt deleted file mode 100644 index d397cfe4..00000000 --- a/website/api/duk_realloc.txt +++ /dev/null @@ -1,32 +0,0 @@ -=proto -void *duk_realloc(duk_context *ctx, void *ptr, duk_size_t size); - -=summary -

Like duk_realloc_raw() but may -trigger a garbage collection to satisfy the request. However, the -allocated memory itself is not automatically garbage collected. -If allocated size is extended from previous allocation, the newly allocated -bytes are not automatically zeroed and may contain arbitrary garbage.

- -

Memory reallocated with duk_realloc() can be freed with either -duk_free() or -duk_free_raw().

-=example -void *buf = duk_alloc(ctx, 1024); -if (buf) { - void *buf2 = duk_realloc(ctx, 2048); - if (!buf2) { - printf("failed to reallocate, 'buf' still valid\n"); - } else { - printf("reallocate successful, 'buf2' now valid\n"); - } -} - -=tags -memory - -=seealso -duk_realloc_raw - -=introduced -1.0.0 diff --git a/website/api/duk_realloc.yaml b/website/api/duk_realloc.yaml new file mode 100644 index 00000000..f73dc96c --- /dev/null +++ b/website/api/duk_realloc.yaml @@ -0,0 +1,34 @@ +name: duk_realloc + +proto: | + void *duk_realloc(duk_context *ctx, void *ptr, duk_size_t size); + +summary: | +

Like duk_realloc_raw() but may + trigger a garbage collection to satisfy the request. However, the + allocated memory itself is not automatically garbage collected. + If allocated size is extended from previous allocation, the newly allocated + bytes are not automatically zeroed and may contain arbitrary garbage.

+ +

Memory reallocated with duk_realloc() can be freed with either + duk_free() or + duk_free_raw().

+ +example: | + void *buf = duk_alloc(ctx, 1024); + if (buf) { + void *buf2 = duk_realloc(ctx, 2048); + if (!buf2) { + printf("failed to reallocate, 'buf' still valid\n"); + } else { + printf("reallocate successful, 'buf2' now valid\n"); + } + } + +tags: + - memory + +seealso: + - duk_realloc_raw + +introduced: 1.0.0 diff --git a/website/api/duk_realloc_raw.txt b/website/api/duk_realloc_raw.txt deleted file mode 100644 index 185c2636..00000000 --- a/website/api/duk_realloc_raw.txt +++ /dev/null @@ -1,61 +0,0 @@ -=proto -void *duk_realloc_raw(duk_context *ctx, void *ptr, duk_size_t size); - -=summary -

Resize a previous allocation made with the allocation functions -registered to the context. The ptr argument points to the -previous allocation while size is the new allocation size. -The call returns a pointer to the new allocation which may have a -different pointer than the previous one. If the reallocation fails, -a NULL is returned and the previous allocation is still valid. -Reallocation failure should only be possible when the new size is larger -than the previous size (i.e. caller tries to grow the allocation). -The attempt to reallocate cannot trigger a garbage collection, -and the allocated memory is not automatically garbage collected. -If allocated size is extended from previous allocation, the newly allocated -bytes are not automatically zeroed and may contain arbitrary garbage. -

- -

The exact behavior depends on the ptr and size -arguments as follows:

- -
    -
  • If ptr is non-NULL and size is greater - than zero, previous allocation is resized.
    • -
  • If ptr is non-NULL and size is zero, - the call is equivalent to a - duk_free_raw().
    • -
  • If ptr is NULL, and size is greater than - zero, the call is equivalent to a - duk_alloc_raw().
    • -
  • If ptr is NULL, and size is zero, the - call is equivalent to a - duk_alloc_raw() with a zero - size argument; the call may return NULL or some other value - which is safe to give to - duk_free_raw().
    • -
- -

Memory reallocated with duk_realloc_raw() can be freed with either -duk_free() or -duk_free_raw().

- -=example -void *buf = duk_alloc_raw(ctx, 1024); -if (buf) { - void *buf2 = duk_realloc_raw(ctx, 2048); - if (!buf2) { - printf("failed to reallocate, 'buf' still valid\n"); - } else { - printf("reallocate successful, 'buf2' now valid\n"); - } -} - -=tags -memory - -=seealso -duk_realloc - -=introduced -1.0.0 diff --git a/website/api/duk_realloc_raw.yaml b/website/api/duk_realloc_raw.yaml new file mode 100644 index 00000000..7e4f9e38 --- /dev/null +++ b/website/api/duk_realloc_raw.yaml @@ -0,0 +1,62 @@ +name: duk_realloc_raw + +proto: | + void *duk_realloc_raw(duk_context *ctx, void *ptr, duk_size_t size); + +summary: | +

Resize a previous allocation made with the allocation functions + registered to the context. The ptr argument points to the + previous allocation while size is the new allocation size. + The call returns a pointer to the new allocation which may have a + different pointer than the previous one. If the reallocation fails, + a NULL is returned and the previous allocation is still valid. + Reallocation failure should only be possible when the new size is larger + than the previous size (i.e. caller tries to grow the allocation). + The attempt to reallocate cannot trigger a garbage collection, + and the allocated memory is not automatically garbage collected. + If allocated size is extended from previous allocation, the newly allocated + bytes are not automatically zeroed and may contain arbitrary garbage. +

+ +

The exact behavior depends on the ptr and size + arguments as follows:

+ +
    +
  • If ptr is non-NULL and size is greater + than zero, previous allocation is resized.
    • +
  • If ptr is non-NULL and size is zero, + the call is equivalent to a + duk_free_raw().
    • +
  • If ptr is NULL, and size is greater than + zero, the call is equivalent to a + duk_alloc_raw().
    • +
  • If ptr is NULL, and size is zero, the + call is equivalent to a + duk_alloc_raw() with a zero + size argument; the call may return NULL or some other value + which is safe to give to + duk_free_raw().
    • +
+ +

Memory reallocated with duk_realloc_raw() can be freed with either + duk_free() or + duk_free_raw().

+ +example: | + void *buf = duk_alloc_raw(ctx, 1024); + if (buf) { + void *buf2 = duk_realloc_raw(ctx, 2048); + if (!buf2) { + printf("failed to reallocate, 'buf' still valid\n"); + } else { + printf("reallocate successful, 'buf2' now valid\n"); + } + } + +tags: + - memory + +seealso: + - duk_realloc + +introduced: 1.0.0 diff --git a/website/api/duk_remove.txt b/website/api/duk_remove.txt deleted file mode 100644 index 8354c49c..00000000 --- a/website/api/duk_remove.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -void duk_remove(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val(index)! ... ] -> [ ... ... ] - -=summary -

Remove value at index. Elements above index -are shifted down the stack by a step. If to_index is -an invalid index, throws an error.

- -=example -duk_push_int(ctx, 123); -duk_push_int(ctx, 234); -duk_push_int(ctx, 345); /* -> [ 123 234 345 ] */ -duk_remove(ctx, -2); /* -> [ 123 345 ] */ - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_remove.yaml b/website/api/duk_remove.yaml new file mode 100644 index 00000000..386e24ac --- /dev/null +++ b/website/api/duk_remove.yaml @@ -0,0 +1,23 @@ +name: duk_remove + +proto: | + void duk_remove(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val(index)! ... ] -> [ ... ... ] + +summary: | +

Remove value at index. Elements above index + are shifted down the stack by a step. If to_index is + an invalid index, throws an error.

+ +example: | + duk_push_int(ctx, 123); + duk_push_int(ctx, 234); + duk_push_int(ctx, 345); /* -> [ 123 234 345 ] */ + duk_remove(ctx, -2); /* -> [ 123 345 ] */ + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_replace.txt b/website/api/duk_replace.txt deleted file mode 100644 index 45b828e9..00000000 --- a/website/api/duk_replace.txt +++ /dev/null @@ -1,30 +0,0 @@ -=proto -void duk_replace(duk_context *ctx, duk_idx_t to_index); - -=stack -[ ... old(to_index)! ... val! ] -> [ ... val(to_index)! ... ] - -=summary -

Replace value at to_index with a value popped from the -stack top. If to_index is an invalid index, throws an error.

- -
-Negative indices are evaluated prior to popping the value at the stack -top. This is also illustrated by the example. -
- -=example -duk_push_int(ctx, 123); -duk_push_int(ctx, 234); -duk_push_int(ctx, 345); /* -> [ 123 234 345 ] */ -duk_push_string(ctx, "foo"); /* -> [ 123 234 345 "foo" ] */ -duk_replace(ctx, -3); /* -> [ 123 "foo" 345 ] */ - -=tags -stack - -=seealso -duk_insert - -=introduced -1.0.0 diff --git a/website/api/duk_replace.yaml b/website/api/duk_replace.yaml new file mode 100644 index 00000000..504fc06a --- /dev/null +++ b/website/api/duk_replace.yaml @@ -0,0 +1,31 @@ +name: duk_replace + +proto: | + void duk_replace(duk_context *ctx, duk_idx_t to_index); + +stack: | + [ ... old(to_index)! ... val! ] -> [ ... val(to_index)! ... ] + +summary: | +

Replace value at to_index with a value popped from the + stack top. If to_index is an invalid index, throws an error.

+ +
+ Negative indices are evaluated prior to popping the value at the stack + top. This is also illustrated by the example. +
+ +example: | + duk_push_int(ctx, 123); + duk_push_int(ctx, 234); + duk_push_int(ctx, 345); /* -> [ 123 234 345 ] */ + duk_push_string(ctx, "foo"); /* -> [ 123 234 345 "foo" ] */ + duk_replace(ctx, -3); /* -> [ 123 "foo" 345 ] */ + +tags: + - stack + +seealso: + - duk_insert + +introduced: 1.0.0 diff --git a/website/api/duk_require_boolean.txt b/website/api/duk_require_boolean.txt deleted file mode 100644 index 6ebee74b..00000000 --- a/website/api/duk_require_boolean.txt +++ /dev/null @@ -1,21 +0,0 @@ -=proto -duk_bool_t duk_require_boolean(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Like duk_get_boolean(), -but throws an error if the value at index is not a boolean -or if the index is invalid.

- -=example -if (duk_require_boolean(ctx, -3)) { - printf("value is true\n"); -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_require_boolean.yaml b/website/api/duk_require_boolean.yaml new file mode 100644 index 00000000..a9e2277f --- /dev/null +++ b/website/api/duk_require_boolean.yaml @@ -0,0 +1,22 @@ +name: duk_require_boolean + +proto: | + duk_bool_t duk_require_boolean(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_get_boolean(), + but throws an error if the value at index is not a boolean + or if the index is invalid.

+ +example: | + if (duk_require_boolean(ctx, -3)) { + printf("value is true\n"); + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_require_buffer.txt b/website/api/duk_require_buffer.txt deleted file mode 100644 index 48917522..00000000 --- a/website/api/duk_require_buffer.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -void *duk_require_buffer(duk_context *ctx, duk_idx_t index, duk_size_t *out_size); - -=stack -[ ... val! ... ] - -=summary -

Like duk_get_buffer(), -but throws an error if the value at index is not a buffer -or if the index is invalid.

- -=example -void *ptr; -duk_size_t sz; - -ptr = duk_require_buffer(ctx, -3, &sz); -printf("buf=%p, size=%lu\n", ptr, (unsigned long) sz); - -=tags -stack -buffer - -=introduced -1.0.0 diff --git a/website/api/duk_require_buffer.yaml b/website/api/duk_require_buffer.yaml new file mode 100644 index 00000000..3bdc3a3e --- /dev/null +++ b/website/api/duk_require_buffer.yaml @@ -0,0 +1,25 @@ +name: duk_require_buffer + +proto: | + void *duk_require_buffer(duk_context *ctx, duk_idx_t index, duk_size_t *out_size); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_get_buffer(), + but throws an error if the value at index is not a buffer + or if the index is invalid.

+ +example: | + void *ptr; + duk_size_t sz; + + ptr = duk_require_buffer(ctx, -3, &sz); + printf("buf=%p, size=%lu\n", ptr, (unsigned long) sz); + +tags: + - stack + - buffer + +introduced: 1.0.0 diff --git a/website/api/duk_require_c_function.txt b/website/api/duk_require_c_function.txt deleted file mode 100644 index c996be36..00000000 --- a/website/api/duk_require_c_function.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_c_function duk_require_c_function(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Like duk_get_c_function(), but -throws an error if the value at index is not an Ecmascript function -associated with a Duktape/C function or if the index is invalid.

- -=example -duk_c_function funcptr; - -funcptr = duk_require_c_function(ctx, -3); - -=tags -stack -function - -=introduced -1.0.0 diff --git a/website/api/duk_require_c_function.yaml b/website/api/duk_require_c_function.yaml new file mode 100644 index 00000000..ef34997b --- /dev/null +++ b/website/api/duk_require_c_function.yaml @@ -0,0 +1,23 @@ +name: duk_require_c_function + +proto: | + duk_c_function duk_require_c_function(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_get_c_function(), but + throws an error if the value at index is not an Ecmascript function + associated with a Duktape/C function or if the index is invalid.

+ +example: | + duk_c_function funcptr; + + funcptr = duk_require_c_function(ctx, -3); + +tags: + - stack + - function + +introduced: 1.0.0 diff --git a/website/api/duk_require_context.txt b/website/api/duk_require_context.txt deleted file mode 100644 index 373fe277..00000000 --- a/website/api/duk_require_context.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -duk_context *duk_require_context(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Like duk_get_context(), -but throws an error if the value at index is not a Duktape -thread or if the index is invalid.

- -=example -duk_context *new_ctx; - -(void) duk_push_thread(ctx); -new_ctx = duk_require_context(ctx, -1); - -=tags -stack -borrowed - -=introduced -1.0.0 diff --git a/website/api/duk_require_context.yaml b/website/api/duk_require_context.yaml new file mode 100644 index 00000000..60bd47be --- /dev/null +++ b/website/api/duk_require_context.yaml @@ -0,0 +1,24 @@ +name: duk_require_context + +proto: | + duk_context *duk_require_context(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_get_context(), + but throws an error if the value at index is not a Duktape + thread or if the index is invalid.

+ +example: | + duk_context *new_ctx; + + (void) duk_push_thread(ctx); + new_ctx = duk_require_context(ctx, -1); + +tags: + - stack + - borrowed + +introduced: 1.0.0 diff --git a/website/api/duk_require_heapptr.txt b/website/api/duk_require_heapptr.txt deleted file mode 100644 index 5af67f7a..00000000 --- a/website/api/duk_require_heapptr.txt +++ /dev/null @@ -1,26 +0,0 @@ -=proto -void *duk_require_heapptr(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Like duk_get_heapptr(), -but throws an error if the value at index is not a Duktape -heap allocated value (object, buffer, string) or if the index is invalid.

- -=example -void *ptr; - -ptr = duk_require_heapptr(ctx, -3); - -=tags -stack -borrowed - -=seealso -duk_get_heapptr -duk_push_heapptr - -=introduced -1.1.0 diff --git a/website/api/duk_require_heapptr.yaml b/website/api/duk_require_heapptr.yaml new file mode 100644 index 00000000..b608edf5 --- /dev/null +++ b/website/api/duk_require_heapptr.yaml @@ -0,0 +1,27 @@ +name: duk_require_heapptr + +proto: | + void *duk_require_heapptr(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_get_heapptr(), + but throws an error if the value at index is not a Duktape + heap allocated value (object, buffer, string) or if the index is invalid.

+ +example: | + void *ptr; + + ptr = duk_require_heapptr(ctx, -3); + +tags: + - stack + - borrowed + +seealso: + - duk_get_heapptr + - duk_push_heapptr + +introduced: 1.1.0 diff --git a/website/api/duk_require_int.txt b/website/api/duk_require_int.txt deleted file mode 100644 index 33ce03e5..00000000 --- a/website/api/duk_require_int.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -duk_int_t duk_require_int(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Like duk_get_int(), -but throws an error if the value at index is not a number -or if the index is invalid.

- - - -=example -printf("int value: %ld\n", (long) duk_require_int(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_require_int.yaml b/website/api/duk_require_int.yaml new file mode 100644 index 00000000..47cf0731 --- /dev/null +++ b/website/api/duk_require_int.yaml @@ -0,0 +1,25 @@ +name: duk_require_int + +proto: | + duk_int_t duk_require_int(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_get_int(), + but throws an error if the value at index is not a number + or if the index is invalid.

+ + + +example: | + printf("int value: %ld\n", (long) duk_require_int(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_require_lstring.txt b/website/api/duk_require_lstring.txt deleted file mode 100644 index d6e67e5d..00000000 --- a/website/api/duk_require_lstring.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -const char *duk_require_lstring(duk_context *ctx, duk_idx_t index, duk_size_t *out_len); - -=stack -[ ... val! ... ] - -=summary -

Like duk_get_lstring(), -but throws an error if the value at index is not a string -or if the index is invalid.

- -=example -const char *buf; -duk_size_t len; - -buf = duk_require_lstring(ctx, -3, &len); -printf("value is a string, %lu bytes\n", (unsigned long) len); - -=tags -stack -string - -=introduced -1.0.0 diff --git a/website/api/duk_require_lstring.yaml b/website/api/duk_require_lstring.yaml new file mode 100644 index 00000000..8679c755 --- /dev/null +++ b/website/api/duk_require_lstring.yaml @@ -0,0 +1,25 @@ +name: duk_require_lstring + +proto: | + const char *duk_require_lstring(duk_context *ctx, duk_idx_t index, duk_size_t *out_len); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_get_lstring(), + but throws an error if the value at index is not a string + or if the index is invalid.

+ +example: | + const char *buf; + duk_size_t len; + + buf = duk_require_lstring(ctx, -3, &len); + printf("value is a string, %lu bytes\n", (unsigned long) len); + +tags: + - stack + - string + +introduced: 1.0.0 diff --git a/website/api/duk_require_normalize_index.txt b/website/api/duk_require_normalize_index.txt deleted file mode 100644 index 61867a2c..00000000 --- a/website/api/duk_require_normalize_index.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -duk_idx_t duk_require_normalize_index(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Normalize argument index relative to the bottom of the current frame. -The resulting index will be 0 or greater and will be independent of -later stack modifications. If the input index is invalid, throws -an error.

- -=example -duk_idx_t idx = duk_require_normalize_index(-3); - -=tags -stack - -=seealso -duk_normalize_index - -=introduced -1.0.0 diff --git a/website/api/duk_require_normalize_index.yaml b/website/api/duk_require_normalize_index.yaml new file mode 100644 index 00000000..190f49f3 --- /dev/null +++ b/website/api/duk_require_normalize_index.yaml @@ -0,0 +1,24 @@ +name: duk_require_normalize_index + +proto: | + duk_idx_t duk_require_normalize_index(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Normalize argument index relative to the bottom of the current frame. + The resulting index will be 0 or greater and will be independent of + later stack modifications. If the input index is invalid, throws + an error.

+ +example: | + duk_idx_t idx = duk_require_normalize_index(-3); + +tags: + - stack + +seealso: + - duk_normalize_index + +introduced: 1.0.0 diff --git a/website/api/duk_require_null.txt b/website/api/duk_require_null.txt deleted file mode 100644 index eeaaf728..00000000 --- a/website/api/duk_require_null.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -void duk_require_null(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Throw an error if the value at index is not null -or if the index is invalid.

- -
-There is no "get" primitive (duk_get_null()) because such a -function would be a no-op. -
- -=example -duk_require_null(ctx, -3); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_require_null.yaml b/website/api/duk_require_null.yaml new file mode 100644 index 00000000..43c185b9 --- /dev/null +++ b/website/api/duk_require_null.yaml @@ -0,0 +1,24 @@ +name: duk_require_null + +proto: | + void duk_require_null(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Throw an error if the value at index is not null + or if the index is invalid.

+ +
+ There is no "get" primitive (duk_get_null()) because such a + function would be a no-op. +
+ +example: | + duk_require_null(ctx, -3); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_require_number.txt b/website/api/duk_require_number.txt deleted file mode 100644 index 06e20b95..00000000 --- a/website/api/duk_require_number.txt +++ /dev/null @@ -1,19 +0,0 @@ -=proto -duk_double_t duk_require_number(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Like duk_get_number(), -but throws an error if the value at index is not a number -or if the index is invalid.

- -=example -printf("value: %lf\n", (double) duk_require_number(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_require_number.yaml b/website/api/duk_require_number.yaml new file mode 100644 index 00000000..179e42fd --- /dev/null +++ b/website/api/duk_require_number.yaml @@ -0,0 +1,20 @@ +name: duk_require_number + +proto: | + duk_double_t duk_require_number(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_get_number(), + but throws an error if the value at index is not a number + or if the index is invalid.

+ +example: | + printf("value: %lf\n", (double) duk_require_number(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_require_object_coercible.txt b/website/api/duk_require_object_coercible.txt deleted file mode 100644 index 403b1777..00000000 --- a/website/api/duk_require_object_coercible.txt +++ /dev/null @@ -1,19 +0,0 @@ -=proto -void duk_require_object_coercible(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Like duk_is_object_coercible() -but throws a TypeError if val is not object coercible.

- -=example -duk_require_object_coercible(ctx, -3); - -=tags -stack -object - -=introduced -1.0.0 diff --git a/website/api/duk_require_object_coercible.yaml b/website/api/duk_require_object_coercible.yaml new file mode 100644 index 00000000..db172fb7 --- /dev/null +++ b/website/api/duk_require_object_coercible.yaml @@ -0,0 +1,20 @@ +name: duk_require_object_coercible + +proto: | + void duk_require_object_coercible(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_is_object_coercible() + but throws a TypeError if val is not object coercible.

+ +example: | + duk_require_object_coercible(ctx, -3); + +tags: + - stack + - object + +introduced: 1.0.0 diff --git a/website/api/duk_require_pointer.txt b/website/api/duk_require_pointer.txt deleted file mode 100644 index 95a0cfff..00000000 --- a/website/api/duk_require_pointer.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -void *duk_require_pointer(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Like duk_get_pointer(), -but throws an error if the value at index is not a pointer -or if the index is invalid.

- -=example -void *ptr; - -ptr = duk_require_pointer(ctx, -3); -printf("my pointer is: %p\n", ptr); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_require_pointer.yaml b/website/api/duk_require_pointer.yaml new file mode 100644 index 00000000..6d74e86e --- /dev/null +++ b/website/api/duk_require_pointer.yaml @@ -0,0 +1,23 @@ +name: duk_require_pointer + +proto: | + void *duk_require_pointer(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_get_pointer(), + but throws an error if the value at index is not a pointer + or if the index is invalid.

+ +example: | + void *ptr; + + ptr = duk_require_pointer(ctx, -3); + printf("my pointer is: %p\n", ptr); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_require_stack.txt b/website/api/duk_require_stack.txt deleted file mode 100644 index 94d78d9e..00000000 --- a/website/api/duk_require_stack.txt +++ /dev/null @@ -1,28 +0,0 @@ -=proto -void duk_require_stack(duk_context *ctx, duk_idx_t extra); - -=summary -

Like duk_check_stack() but an -error is thrown if the value stack needs to be reallocated and that -reallocation fails.

- -

As a general rule, callers should use this function to reserve more -stack space. If value stack cannot be extended, there is almost never a -useful recovery strategy except to throw an error and unwind.

- -=example -duk_idx_t nargs; - -nargs = duk_get_top(ctx); /* number or arguments */ - -/* reserve space for one temporary for each input argument */ -duk_require_stack(ctx, nargs * 2); - -=tags -stack - -=seealso -duk_check_stack - -=introduced -1.0.0 diff --git a/website/api/duk_require_stack.yaml b/website/api/duk_require_stack.yaml new file mode 100644 index 00000000..8087f475 --- /dev/null +++ b/website/api/duk_require_stack.yaml @@ -0,0 +1,29 @@ +name: duk_require_stack + +proto: | + void duk_require_stack(duk_context *ctx, duk_idx_t extra); + +summary: | +

Like duk_check_stack() but an + error is thrown if the value stack needs to be reallocated and that + reallocation fails.

+ +

As a general rule, callers should use this function to reserve more + stack space. If value stack cannot be extended, there is almost never a + useful recovery strategy except to throw an error and unwind.

+ +example: | + duk_idx_t nargs; + + nargs = duk_get_top(ctx); /* number or arguments */ + + /* reserve space for one temporary for each input argument */ + duk_require_stack(ctx, nargs * 2); + +tags: + - stack + +seealso: + - duk_check_stack + +introduced: 1.0.0 diff --git a/website/api/duk_require_stack_top.txt b/website/api/duk_require_stack_top.txt deleted file mode 100644 index 61ba3a11..00000000 --- a/website/api/duk_require_stack_top.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -void duk_require_stack_top(duk_context *ctx, duk_idx_t top); - -=summary -

Like duk_check_stack_top() -but an error is thrown if the value stack needs to be reallocated and that -reallocation fails.

- -

As a general rule, callers should use this function to reserve more -stack space. If value stack cannot be extended, there is almost never a -useful recovery strategy except to throw an error and unwind.

- -=example -duk_require_stack_top(ctx, 100); -printf("value stack guaranteed up to index 99\n"); - -=tags -stack - -=seealso -duk_check_stack_top - -=introduced -1.0.0 diff --git a/website/api/duk_require_stack_top.yaml b/website/api/duk_require_stack_top.yaml new file mode 100644 index 00000000..0dc4887e --- /dev/null +++ b/website/api/duk_require_stack_top.yaml @@ -0,0 +1,25 @@ +name: duk_require_stack_top + +proto: | + void duk_require_stack_top(duk_context *ctx, duk_idx_t top); + +summary: | +

Like duk_check_stack_top() + but an error is thrown if the value stack needs to be reallocated and that + reallocation fails.

+ +

As a general rule, callers should use this function to reserve more + stack space. If value stack cannot be extended, there is almost never a + useful recovery strategy except to throw an error and unwind.

+ +example: | + duk_require_stack_top(ctx, 100); + printf("value stack guaranteed up to index 99\n"); + +tags: + - stack + +seealso: + - duk_check_stack_top + +introduced: 1.0.0 diff --git a/website/api/duk_require_string.txt b/website/api/duk_require_string.txt deleted file mode 100644 index 14dcfd36..00000000 --- a/website/api/duk_require_string.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -const char *duk_require_string(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Like duk_get_string(), -but throws an error if the value at index is not a string -or if the index is invalid.

- -=example -const char *buf; - -buf = duk_require_string(ctx, -3); -printf("value is a string: %s\n", buf); - -=tags -stack -string - -=introduced -1.0.0 diff --git a/website/api/duk_require_string.yaml b/website/api/duk_require_string.yaml new file mode 100644 index 00000000..01a2c0a0 --- /dev/null +++ b/website/api/duk_require_string.yaml @@ -0,0 +1,24 @@ +name: duk_require_string + +proto: | + const char *duk_require_string(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_get_string(), + but throws an error if the value at index is not a string + or if the index is invalid.

+ +example: | + const char *buf; + + buf = duk_require_string(ctx, -3); + printf("value is a string: %s\n", buf); + +tags: + - stack + - string + +introduced: 1.0.0 diff --git a/website/api/duk_require_top_index.txt b/website/api/duk_require_top_index.txt deleted file mode 100644 index 1974164e..00000000 --- a/website/api/duk_require_top_index.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_idx_t duk_require_top_index(duk_context *ctx); - -=summary -

Get the absolute index (>= 0) of the topmost value on the stack. -If the stack is empty, throws an error.

- -=example -duk_idx_t idx_top; - -/* throws error if stack is empty */ -idx_top = duk_require_top_index(ctx); -printf("index of top element: %ld\n", (long) idx_top); - -=tags -stack - -=seealso -duk_get_top_index - -=introduced -1.0.0 diff --git a/website/api/duk_require_top_index.yaml b/website/api/duk_require_top_index.yaml new file mode 100644 index 00000000..70508957 --- /dev/null +++ b/website/api/duk_require_top_index.yaml @@ -0,0 +1,23 @@ +name: duk_require_top_index + +proto: | + duk_idx_t duk_require_top_index(duk_context *ctx); + +summary: | +

Get the absolute index (>= 0) of the topmost value on the stack. + If the stack is empty, throws an error.

+ +example: | + duk_idx_t idx_top; + + /* throws error if stack is empty */ + idx_top = duk_require_top_index(ctx); + printf("index of top element: %ld\n", (long) idx_top); + +tags: + - stack + +seealso: + - duk_get_top_index + +introduced: 1.0.0 diff --git a/website/api/duk_require_type_mask.txt b/website/api/duk_require_type_mask.txt deleted file mode 100644 index 1a563af4..00000000 --- a/website/api/duk_require_type_mask.txt +++ /dev/null @@ -1,20 +0,0 @@ -=proto -void duk_require_type_mask(duk_context *ctx, duk_idx_t index, duk_uint_t mask); - -=stack -[ ... val! ... ] - -=summary -

Like duk_check_type_mask() -but throws a TypeError if val type does not match any -of the mask bits.

- -=example -duk_require_type_mask(ctx, -3, DUK_TYPE_MASK_STRING | - DUK_TYPE_MASK_NUMBER); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_require_type_mask.yaml b/website/api/duk_require_type_mask.yaml new file mode 100644 index 00000000..9ddb8620 --- /dev/null +++ b/website/api/duk_require_type_mask.yaml @@ -0,0 +1,21 @@ +name: duk_require_type_mask + +proto: | + void duk_require_type_mask(duk_context *ctx, duk_idx_t index, duk_uint_t mask); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_check_type_mask() + but throws a TypeError if val type does not match any + of the mask bits.

+ +example: | + duk_require_type_mask(ctx, -3, DUK_TYPE_MASK_STRING | + DUK_TYPE_MASK_NUMBER); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_require_uint.txt b/website/api/duk_require_uint.txt deleted file mode 100644 index 0879151e..00000000 --- a/website/api/duk_require_uint.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -duk_uint_t duk_require_uint(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Like duk_get_uint(), -but throws an error if the value at index is not a number -or if the index is invalid.

- - - -=example -printf("unsigned int value: %lu\n", (unsigned long) duk_require_uint(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_require_uint.yaml b/website/api/duk_require_uint.yaml new file mode 100644 index 00000000..d759cb95 --- /dev/null +++ b/website/api/duk_require_uint.yaml @@ -0,0 +1,25 @@ +name: duk_require_uint + +proto: | + duk_uint_t duk_require_uint(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_get_uint(), + but throws an error if the value at index is not a number + or if the index is invalid.

+ + + +example: | + printf("unsigned int value: %lu\n", (unsigned long) duk_require_uint(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_require_undefined.txt b/website/api/duk_require_undefined.txt deleted file mode 100644 index a2ff624d..00000000 --- a/website/api/duk_require_undefined.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -void duk_require_undefined(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Throw an error if the value at index is not undefined -or if the index is invalid.

- -
-There is no "get" primitive (duk_get_undefined()) because such a -function would be a no-op. -
- -=example -duk_require_undefined(ctx, -3); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_require_undefined.yaml b/website/api/duk_require_undefined.yaml new file mode 100644 index 00000000..33392ea6 --- /dev/null +++ b/website/api/duk_require_undefined.yaml @@ -0,0 +1,24 @@ +name: duk_require_undefined + +proto: | + void duk_require_undefined(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Throw an error if the value at index is not undefined + or if the index is invalid.

+ +
+ There is no "get" primitive (duk_get_undefined()) because such a + function would be a no-op. +
+ +example: | + duk_require_undefined(ctx, -3); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_require_valid_index.txt b/website/api/duk_require_valid_index.txt deleted file mode 100644 index 358a29d5..00000000 --- a/website/api/duk_require_valid_index.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -void duk_require_valid_index(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] - -=summary -

Validate argument index. Throw an error if index is valid, return -(without a return value) otherwise.

- -=example -duk_require_valid_index(ctx, -3); -printf("index -3 is valid\n"); - -=tags -stack - -=seealso -duk_is_valid_index - -=introduced -1.0.0 diff --git a/website/api/duk_require_valid_index.yaml b/website/api/duk_require_valid_index.yaml new file mode 100644 index 00000000..f5971b7c --- /dev/null +++ b/website/api/duk_require_valid_index.yaml @@ -0,0 +1,23 @@ +name: duk_require_valid_index + +proto: | + void duk_require_valid_index(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] + +summary: | +

Validate argument index. Throw an error if index is valid, return + (without a return value) otherwise.

+ +example: | + duk_require_valid_index(ctx, -3); + printf("index -3 is valid\n"); + +tags: + - stack + +seealso: + - duk_is_valid_index + +introduced: 1.0.0 diff --git a/website/api/duk_resize_buffer.txt b/website/api/duk_resize_buffer.txt deleted file mode 100644 index 639361cb..00000000 --- a/website/api/duk_resize_buffer.txt +++ /dev/null @@ -1,25 +0,0 @@ -=proto -void *duk_resize_buffer(duk_context *ctx, duk_idx_t index, duk_size_t new_size); - -=stack -[ ... val! ... ] - -=summary -

Resize a dynamic buffer at index to new_size bytes. -If new_size is larger than the current size, newly allocated bytes -(above old size) are automatically zeroed. Returns a pointer to the new buffer -data area. If new_size is zero, may return either NULL or some -non-NULL value. If resizing fails, the value at index is not -a dynamic buffer, or index is invalid, throws an error.

- -=example -void *ptr; - -ptr = duk_resize_buffer(ctx, -3, 4096); - -=tags -stack -buffer - -=introduced -1.0.0 diff --git a/website/api/duk_resize_buffer.yaml b/website/api/duk_resize_buffer.yaml new file mode 100644 index 00000000..eb8502d5 --- /dev/null +++ b/website/api/duk_resize_buffer.yaml @@ -0,0 +1,26 @@ +name: duk_resize_buffer + +proto: | + void *duk_resize_buffer(duk_context *ctx, duk_idx_t index, duk_size_t new_size); + +stack: | + [ ... val! ... ] + +summary: | +

Resize a dynamic buffer at index to new_size bytes. + If new_size is larger than the current size, newly allocated bytes + (above old size) are automatically zeroed. Returns a pointer to the new buffer + data area. If new_size is zero, may return either NULL or some + non-NULL value. If resizing fails, the value at index is not + a dynamic buffer, or index is invalid, throws an error.

+ +example: | + void *ptr; + + ptr = duk_resize_buffer(ctx, -3, 4096); + +tags: + - stack + - buffer + +introduced: 1.0.0 diff --git a/website/api/duk_safe_call.txt b/website/api/duk_safe_call.txt deleted file mode 100644 index b4a32a19..00000000 --- a/website/api/duk_safe_call.txt +++ /dev/null @@ -1,114 +0,0 @@ -=proto -duk_int_t duk_safe_call(duk_context *ctx, duk_safe_call_function func, duk_idx_t nargs, duk_idx_t nrets); - -=stack -[ ... arg1! ...! argN! ] -> [ ... ret1! ...! retN! ] - -=summary -

Perform a protected pure C function call inside the current value stack frame -(the call is not visible on the call stack). nargs topmost values in the -current value stack frame are identified as call arguments, and nrets -return values are provided after the call returns.

- -

The return value is:

-
    -
  • DUK_EXEC_SUCCESS (0): call succeeded, nargs arguments are replaced - with nrets return values. (This return code constant is guaranteed to be - zero, so that one can check for success with a "zero or non-zero" check.)
    • -
  • DUK_EXEC_ERROR: call failed, nargs arguments are replaced with - nrets values, first of which is an error value and the rest are undefined. - (In exceptional cases, e.g. when there are too few arguments on the value stack, the call - returns non-zero but may leave the stack in an inconsistent state.)
    • -
- -
-Unlike most Duktape API calls, this call returns zero on success. This allows -multiple error codes to be defined later. -
- -

Because this call operates on the current value stack frame, stack behavior -differs a bit from other call types. Although the target function signature -matches Duktape/C functions, value stack and return code policies are different.

- -

The top nargs elements of the stack top are identified as arguments to -func establishing a "base index" for the return stack as:

-
-(duk_get_top() - nargs)
-
- -

When func returns, it indicates with its return value the number of -return values it has pushed on top of the stack; multiple or zero return -values possible. The stack is then manipulated so that there are exactly -nrets values starting at the "base index" established before the call.

- -

Note that since func has full access to the value stack, it may modify -the stack below the indended arguments and even pop elements below the "base index" -off the stack. Such elements are restored with undefined values before -returning, to ensure that the stack is always in a consistent state upon returning.

- -

If an error occurs, the stack will still have nrets values at "base index"; -the first of such values is the error, and the remaining values are undefined. -If nrets is zero, the error will not be present on the stack (the return stack -top will equal the "base index"), so calling this function with nrets as 0 -is not very useful.

- -

Example with nargs = 3, nrets = 2, func returns 4. -Pipe chars indicate logical boundaries:

- -
-      .--- frame bottom
-      |
-      |     .--- "base index"
-      v     v
-[ ... | ... | a b c ]            stack before calling 'func'
-
-[ ... | ... | a b | x y z w ]    stack after calling 'func', which has
-                                 popped one argument and written four
-                                 return values (and returned 4)
-
-[ ... | ... | x y ]              stack after duk_safe_call() returns,
-                                 2 (= nrets) first 'func' return values
-                                 are left at "base index"
-
- -
-Note that func uses caller stack frame, so bottom-based references -are dangerous within 'func'. -
- -=example -duk_ret_t my_func(duk_context *ctx) { - double a, b, c; - - a = duk_get_number(ctx, -3); - b = duk_get_number(ctx, -2); - c = duk_get_number(ctx, -1); /* ignored on purpose */ - duk_push_number(ctx, a + b); - - /* Indicates that there is only one return value. Because the caller - * requested two (nrets == 2), Duktape will automatically add an - * additional "undefined" result value. - */ - return 1; -} - -duk_int_t rc; - -duk_push_int(ctx, 10); -duk_push_int(ctx, 11); -duk_push_int(ctx, 12); -rc = duk_safe_call(ctx, my_func, 3 /*nargs*/, 2 /*nrets*/); -if (rc == DUK_EXEC_SUCCESS) { - printf("1st return value: %s\n", duk_to_string(ctx, -2)); /* 21 */ - printf("2nd return value: %s\n", duk_to_string(ctx, -1)); /* undefined */ -} else { - printf("error value: %s\n", duk_to_string(ctx, -2)); -} -duk_pop_2(ctx); - -=tags -call -protected - -=introduced -1.0.0 diff --git a/website/api/duk_safe_call.yaml b/website/api/duk_safe_call.yaml new file mode 100644 index 00000000..01cb5f7f --- /dev/null +++ b/website/api/duk_safe_call.yaml @@ -0,0 +1,115 @@ +name: duk_safe_call + +proto: | + duk_int_t duk_safe_call(duk_context *ctx, duk_safe_call_function func, duk_idx_t nargs, duk_idx_t nrets); + +stack: | + [ ... arg1! ...! argN! ] -> [ ... ret1! ...! retN! ] + +summary: | +

Perform a protected pure C function call inside the current value stack frame + (the call is not visible on the call stack). nargs topmost values in the + current value stack frame are identified as call arguments, and nrets + return values are provided after the call returns.

+ +

The return value is:

+
    +
  • DUK_EXEC_SUCCESS (0): call succeeded, nargs arguments are replaced + with nrets return values. (This return code constant is guaranteed to be + zero, so that one can check for success with a "zero or non-zero" check.)
    • +
  • DUK_EXEC_ERROR: call failed, nargs arguments are replaced with + nrets values, first of which is an error value and the rest are undefined. + (In exceptional cases, e.g. when there are too few arguments on the value stack, the call + returns non-zero but may leave the stack in an inconsistent state.)
    • +
+ +
+ Unlike most Duktape API calls, this call returns zero on success. This allows + multiple error codes to be defined later. +
+ +

Because this call operates on the current value stack frame, stack behavior + differs a bit from other call types. Although the target function signature + matches Duktape/C functions, value stack and return code policies are different.

+ +

The top nargs elements of the stack top are identified as arguments to + func establishing a "base index" for the return stack as:

+ 
+  (duk_get_top() - nargs)
+
+ +

When func returns, it indicates with its return value the number of + return values it has pushed on top of the stack; multiple or zero return + values possible. The stack is then manipulated so that there are exactly + nrets values starting at the "base index" established before the call.

+ +

Note that since func has full access to the value stack, it may modify + the stack below the indended arguments and even pop elements below the "base index" + off the stack. Such elements are restored with undefined values before + returning, to ensure that the stack is always in a consistent state upon returning.

+ +

If an error occurs, the stack will still have nrets values at "base index"; + the first of such values is the error, and the remaining values are undefined. + If nrets is zero, the error will not be present on the stack (the return stack + top will equal the "base index"), so calling this function with nrets as 0 + is not very useful.

+ +

Example with nargs = 3, nrets = 2, func returns 4. + Pipe chars indicate logical boundaries:

+ + 
+        .--- frame bottom
+        |
+        |     .--- "base index"
+        v     v
+  [ ... | ... | a b c ]            stack before calling 'func'
+
+  [ ... | ... | a b | x y z w ]    stack after calling 'func', which has
+                                   popped one argument and written four
+                                   return values (and returned 4)
+
+  [ ... | ... | x y ]              stack after duk_safe_call() returns,
+                                   2 (= nrets) first 'func' return values
+                                   are left at "base index"
+
+ +
+ Note that func uses caller stack frame, so bottom-based references + are dangerous within 'func'. +
+ +example: | + duk_ret_t my_func(duk_context *ctx) { + double a, b, c; + + a = duk_get_number(ctx, -3); + b = duk_get_number(ctx, -2); + c = duk_get_number(ctx, -1); /* ignored on purpose */ + duk_push_number(ctx, a + b); + + /* Indicates that there is only one return value. Because the caller + * requested two (nrets == 2), Duktape will automatically add an + * additional "undefined" result value. + */ + return 1; + } + + duk_int_t rc; + + duk_push_int(ctx, 10); + duk_push_int(ctx, 11); + duk_push_int(ctx, 12); + rc = duk_safe_call(ctx, my_func, 3 /*nargs*/, 2 /*nrets*/); + if (rc == DUK_EXEC_SUCCESS) { + printf("1st return value: %s\n", duk_to_string(ctx, -2)); /* 21 */ + printf("2nd return value: %s\n", duk_to_string(ctx, -1)); /* undefined */ + } else { + printf("error value: %s\n", duk_to_string(ctx, -2)); + } + duk_pop_2(ctx); + +tags: + - call + - protected + +introduced: 1.0.0 diff --git a/website/api/duk_safe_to_lstring.txt b/website/api/duk_safe_to_lstring.txt deleted file mode 100644 index 487a772f..00000000 --- a/website/api/duk_safe_to_lstring.txt +++ /dev/null @@ -1,43 +0,0 @@ -=proto -const char *duk_safe_to_lstring(duk_context *ctx, duk_idx_t index, duk_size_t *out_len); - -=stack -[ ... val! ... ] -> [ ... ToString(val)! ... ] - -=summary -

Like duk_to_lstring() but if -the initial string coercion fails, the error value is coerced to a string. -If that also fails, a fixed error string is returned.

- -

The caller can safely use this function to coerce a value to a string, -which is useful in C code to print out a return value safely with -printf(). The only uncaught errors possible are out-of-memory -and other internal errors which trigger fatal error handling anyway.

- -=example -const char *ptr; -duk_size_t sz; - -/* Coercion causes error. */ -duk_eval_string(ctx, "({ toString: function () { throw new Error('toString error'); } })"); -ptr = duk_safe_to_lstring(ctx, -1, &sz); -printf("coerced string: %s (length %lu)\n", ptr, (unsigned long) sz); /* -> "Error: toString error" */ -duk_pop(ctx); - -/* Coercion causes error, and the error itself cannot be string coerced. */ -duk_eval_string(ctx, "({ toString: function () { var e = new Error('cannot string coerce me');" - " e.toString = function () { throw new Error('coercion error'); };" - " throw e; } })"); -ptr = duk_safe_to_lstring(ctx, -1, &sz); -printf("coerced string: %s (length %lu)\n", ptr, (unsigned long) sz); /* -> "Error" */ -duk_pop(ctx); - -=tags -stack -string - -=seealso -duk_to_lstring - -=introduced -1.0.0 diff --git a/website/api/duk_safe_to_lstring.yaml b/website/api/duk_safe_to_lstring.yaml new file mode 100644 index 00000000..94344bae --- /dev/null +++ b/website/api/duk_safe_to_lstring.yaml @@ -0,0 +1,44 @@ +name: duk_safe_to_lstring + +proto: | + const char *duk_safe_to_lstring(duk_context *ctx, duk_idx_t index, duk_size_t *out_len); + +stack: | + [ ... val! ... ] -> [ ... ToString(val)! ... ] + +summary: | +

Like duk_to_lstring() but if + the initial string coercion fails, the error value is coerced to a string. + If that also fails, a fixed error string is returned.

+ +

The caller can safely use this function to coerce a value to a string, + which is useful in C code to print out a return value safely with + printf(). The only uncaught errors possible are out-of-memory + and other internal errors which trigger fatal error handling anyway.

+ +example: | + const char *ptr; + duk_size_t sz; + + /* Coercion causes error. */ + duk_eval_string(ctx, "({ toString: function () { throw new Error('toString error'); } })"); + ptr = duk_safe_to_lstring(ctx, -1, &sz); + printf("coerced string: %s (length %lu)\n", ptr, (unsigned long) sz); /* -> "Error: toString error" */ + duk_pop(ctx); + + /* Coercion causes error, and the error itself cannot be string coerced. */ + duk_eval_string(ctx, "({ toString: function () { var e = new Error('cannot string coerce me');" + " e.toString = function () { throw new Error('coercion error'); };" + " throw e; } })"); + ptr = duk_safe_to_lstring(ctx, -1, &sz); + printf("coerced string: %s (length %lu)\n", ptr, (unsigned long) sz); /* -> "Error" */ + duk_pop(ctx); + +tags: + - stack + - string + +seealso: + - duk_to_lstring + +introduced: 1.0.0 diff --git a/website/api/duk_safe_to_string.txt b/website/api/duk_safe_to_string.txt deleted file mode 100644 index 244a5636..00000000 --- a/website/api/duk_safe_to_string.txt +++ /dev/null @@ -1,39 +0,0 @@ -=proto -const char *duk_safe_to_string(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... ToString(val)! ... ] - -=summary -

Like duk_to_string() but if -the initial string coercion fails, the error value is coerced to a string. -If that also fails, a fixed error string is returned.

- -

The caller can safely use this function to coerce a value to a string, -which is useful in C code to print out a return value safely with -printf(). The only uncaught errors possible are out-of-memory -and other internal errors which trigger fatal error handling anyway.

- -=example -/* Coercion causes error. */ -duk_eval_string(ctx, "({ toString: function () { throw new Error('toString error'); } })"); -printf("coerced string: %s\n", duk_safe_to_string(ctx, -1)); /* -> "Error: toString error" */ -duk_pop(ctx); - -/* Coercion causes error, and the error itself cannot be string coerced. */ -duk_eval_string(ctx, "({ toString: function () { var e = new Error('cannot string coerce me');" - " e.toString = function () { throw new Error('coercion error'); };" - " throw e; } })"); -printf("coerced string: %s\n", duk_safe_to_string(ctx, -1)); /* -> "Error" */ -duk_pop(ctx); - -=tags -stack -string -protected - -=seealso -duk_to_string - -=introduced -1.0.0 diff --git a/website/api/duk_safe_to_string.yaml b/website/api/duk_safe_to_string.yaml new file mode 100644 index 00000000..a9030a2b --- /dev/null +++ b/website/api/duk_safe_to_string.yaml @@ -0,0 +1,40 @@ +name: duk_safe_to_string + +proto: | + const char *duk_safe_to_string(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... ToString(val)! ... ] + +summary: | +

Like duk_to_string() but if + the initial string coercion fails, the error value is coerced to a string. + If that also fails, a fixed error string is returned.

+ +

The caller can safely use this function to coerce a value to a string, + which is useful in C code to print out a return value safely with + printf(). The only uncaught errors possible are out-of-memory + and other internal errors which trigger fatal error handling anyway.

+ +example: | + /* Coercion causes error. */ + duk_eval_string(ctx, "({ toString: function () { throw new Error('toString error'); } })"); + printf("coerced string: %s\n", duk_safe_to_string(ctx, -1)); /* -> "Error: toString error" */ + duk_pop(ctx); + + /* Coercion causes error, and the error itself cannot be string coerced. */ + duk_eval_string(ctx, "({ toString: function () { var e = new Error('cannot string coerce me');" + " e.toString = function () { throw new Error('coercion error'); };" + " throw e; } })"); + printf("coerced string: %s\n", duk_safe_to_string(ctx, -1)); /* -> "Error" */ + duk_pop(ctx); + +tags: + - stack + - string + - protected + +seealso: + - duk_to_string + +introduced: 1.0.0 diff --git a/website/api/duk_set_finalizer.txt b/website/api/duk_set_finalizer.txt deleted file mode 100644 index 1af8e9b4..00000000 --- a/website/api/duk_set_finalizer.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -void duk_set_finalizer(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... finalizer! ] -> [ ... val! ... ] - -=summary -

Set the finalizer of the value at index to the value at -stack top. If the target value is not an object an error is thrown. The -finalizer value can be an arbitrary one; non-function values are treated -as if no finalizer was set. To delete a finalizer from an object, set it -to undefined.

- -=example -duk_ret_t my_finalizer(duk_context *ctx) { - /* Object being finalized is at stack index 0. */ - printf("object being finalized\n"); - return 0; -} - -/* Create an object whose finalizer is my_finalizer(). */ -duk_push_object(ctx); -duk_push_c_function(ctx, my_finalizer, 1 /*nargs*/); -duk_set_finalizer(ctx, -2); - -=tags -object -finalizer - -=seealso -duk_get_finalizer - -=introduced -1.0.0 diff --git a/website/api/duk_set_finalizer.yaml b/website/api/duk_set_finalizer.yaml new file mode 100644 index 00000000..3598a7a8 --- /dev/null +++ b/website/api/duk_set_finalizer.yaml @@ -0,0 +1,35 @@ +name: duk_set_finalizer + +proto: | + void duk_set_finalizer(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... finalizer! ] -> [ ... val! ... ] + +summary: | +

Set the finalizer of the value at index to the value at + stack top. If the target value is not an object an error is thrown. The + finalizer value can be an arbitrary one; non-function values are treated + as if no finalizer was set. To delete a finalizer from an object, set it + to undefined.

+ +example: | + duk_ret_t my_finalizer(duk_context *ctx) { + /* Object being finalized is at stack index 0. */ + printf("object being finalized\n"); + return 0; + } + + /* Create an object whose finalizer is my_finalizer(). */ + duk_push_object(ctx); + duk_push_c_function(ctx, my_finalizer, 1 /*nargs*/); + duk_set_finalizer(ctx, -2); + +tags: + - object + - finalizer + +seealso: + - duk_get_finalizer + +introduced: 1.0.0 diff --git a/website/api/duk_set_global_object.txt b/website/api/duk_set_global_object.txt deleted file mode 100644 index 9f84d341..00000000 --- a/website/api/duk_set_global_object.txt +++ /dev/null @@ -1,43 +0,0 @@ -=proto -void duk_set_global_object(duk_context *ctx); - -=stack -[ ... new_global! ] -> [ ... ] - -=summary -

Replace the current context's global object with the object on top of the -value stack. If the value is not an object, an error is thrown.

- -

Note that this operation does not affect the global object of other -contexts, even those that have up to this point shared the same global -environment. To inherit the change to other contexts, replace the global -object first before calling duk_push_thread().

- -

See the test case -test-set-global-object.c -for discussion of detailed behavior after the change.

- -
-This API call is experimental at present, and some of the semantics may -change when other sandboxing features are implemented. -
- -=example -/* Build a global object with a subset of bindings. */ -duk_eval_string(ctx, - "({\n" - " print: this.print,\n" - " JSON: this.JSON\n" - "})\n"); - -/* Replace global object. */ -duk_set_global_object(ctx); - -=tags -stack -thread -sandbox -experimental - -=introduced -1.0.0 diff --git a/website/api/duk_set_global_object.yaml b/website/api/duk_set_global_object.yaml new file mode 100644 index 00000000..abb0d007 --- /dev/null +++ b/website/api/duk_set_global_object.yaml @@ -0,0 +1,44 @@ +name: duk_set_global_object + +proto: | + void duk_set_global_object(duk_context *ctx); + +stack: | + [ ... new_global! ] -> [ ... ] + +summary: | +

Replace the current context's global object with the object on top of the + value stack. If the value is not an object, an error is thrown.

+ +

Note that this operation does not affect the global object of other + contexts, even those that have up to this point shared the same global + environment. To inherit the change to other contexts, replace the global + object first before calling duk_push_thread().

+ +

See the test case + test-set-global-object.c + for discussion of detailed behavior after the change.

+ +
+ This API call is experimental at present, and some of the semantics may + change when other sandboxing features are implemented. +
+ +example: | + /* Build a global object with a subset of bindings. */ + duk_eval_string(ctx, + "({\n" + " print: this.print,\n" + " JSON: this.JSON\n" + "})\n"); + + /* Replace global object. */ + duk_set_global_object(ctx); + +tags: + - stack + - thread + - sandbox + - experimental + +introduced: 1.0.0 diff --git a/website/api/duk_set_magic.txt b/website/api/duk_set_magic.txt deleted file mode 100644 index 79354702..00000000 --- a/website/api/duk_set_magic.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -void duk_set_magic(duk_context *ctx, duk_idx_t index, duk_int_t magic); - -=stack -[ ... val! ... ] - -=summary -

Set the 16-bit signed "magic" value associated with the Duktape/C function -at index. If the value is not a Duktape/C function, an error is -thrown.

- -=example -duk_set_magic(ctx, -3, 0x1234); - -=tags -function -magic - -=seealso -duk_get_current_magic -duk_get_magic - -=introduced -1.0.0 diff --git a/website/api/duk_set_magic.yaml b/website/api/duk_set_magic.yaml new file mode 100644 index 00000000..503f4065 --- /dev/null +++ b/website/api/duk_set_magic.yaml @@ -0,0 +1,25 @@ +name: duk_set_magic + +proto: | + void duk_set_magic(duk_context *ctx, duk_idx_t index, duk_int_t magic); + +stack: | + [ ... val! ... ] + +summary: | +

Set the 16-bit signed "magic" value associated with the Duktape/C function + at index. If the value is not a Duktape/C function, an error is + thrown.

+ +example: | + duk_set_magic(ctx, -3, 0x1234); + +tags: + - function + - magic + +seealso: + - duk_get_current_magic + - duk_get_magic + +introduced: 1.0.0 diff --git a/website/api/duk_set_prototype.txt b/website/api/duk_set_prototype.txt deleted file mode 100644 index 34b31d18..00000000 --- a/website/api/duk_set_prototype.txt +++ /dev/null @@ -1,37 +0,0 @@ -=proto -void duk_set_prototype(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... proto! ] -> [ ... val! ... ] - -=summary -

Set the internal prototype of the value at index to the value -at stack top (which must be an object or undefined). If the -target value is not an object or the prototype value is not an object or -undefined, an error is thrown.

- -
-Unlike Ecmascript prototype manipulation primitives, this API call allows -creation of a prototype loop. Calling code should always avoid creating a -prototype loop: although Duktape detects long or looped prototype chains -and throws an error when it encounters one, such behavior is only intended -as a last resort to avoid an infinite loop. -
- -=example -/* Create new object, internal prototype is Object.prototype by default. */ -duk_push_object(ctx); - -/* Change the object's internal prototype to object at index -3. */ -duk_dup(ctx, -3); -duk_set_prototype(ctx, -2); /* [ obj proto ] -> [ obj ] */ - -=tags -object -prototype - -=seealso -duk_get_prototype - -=introduced -1.0.0 diff --git a/website/api/duk_set_prototype.yaml b/website/api/duk_set_prototype.yaml new file mode 100644 index 00000000..5e48238c --- /dev/null +++ b/website/api/duk_set_prototype.yaml @@ -0,0 +1,38 @@ +name: duk_set_prototype + +proto: | + void duk_set_prototype(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... proto! ] -> [ ... val! ... ] + +summary: | +

Set the internal prototype of the value at index to the value + at stack top (which must be an object or undefined). If the + target value is not an object or the prototype value is not an object or + undefined, an error is thrown.

+ +
+ Unlike Ecmascript prototype manipulation primitives, this API call allows + creation of a prototype loop. Calling code should always avoid creating a + prototype loop: although Duktape detects long or looped prototype chains + and throws an error when it encounters one, such behavior is only intended + as a last resort to avoid an infinite loop. +
+ +example: | + /* Create new object, internal prototype is Object.prototype by default. */ + duk_push_object(ctx); + + /* Change the object's internal prototype to object at index -3. */ + duk_dup(ctx, -3); + duk_set_prototype(ctx, -2); /* [ obj proto ] -> [ obj ] */ + +tags: + - object + - prototype + +seealso: + - duk_get_prototype + +introduced: 1.0.0 diff --git a/website/api/duk_set_top.txt b/website/api/duk_set_top.txt deleted file mode 100644 index c253e92e..00000000 --- a/website/api/duk_set_top.txt +++ /dev/null @@ -1,29 +0,0 @@ -=proto -void duk_set_top(duk_context *ctx, duk_idx_t index); - -=stack -[ ...! ] -> [ ...! ] - -=summary -

Set stack top (stack size) to match the argument index, -normalizing negative index values. If the value stack shrinks, -values above the new stack top are dropped; if the value stack grows, -undefined values are pushed to the new stack slots.

- -

Negative index values are interpreted relative to the current -stack top as in other API calls. For example, index -1 would -decrease the stack top by one.

- -=example -/* Assume stack is empty initially. */ - -duk_push_int(ctx, 123); /* -> top=1, stack: [ 123 ] */ -duk_set_top(ctx, 3); /* -> top=3, stack: [ 123 undefined undefined ] */ -duk_set_top(ctx, -1); /* -> top=2, stack: [ 123 undefined ] */ -duk_set_top(ctx, 0); /* -> top=0, stack: [ ] */ - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_set_top.yaml b/website/api/duk_set_top.yaml new file mode 100644 index 00000000..50b51244 --- /dev/null +++ b/website/api/duk_set_top.yaml @@ -0,0 +1,30 @@ +name: duk_set_top + +proto: | + void duk_set_top(duk_context *ctx, duk_idx_t index); + +stack: | + [ ...! ] -> [ ...! ] + +summary: | +

Set stack top (stack size) to match the argument index, + normalizing negative index values. If the value stack shrinks, + values above the new stack top are dropped; if the value stack grows, + undefined values are pushed to the new stack slots.

+ +

Negative index values are interpreted relative to the current + stack top as in other API calls. For example, index -1 would + decrease the stack top by one.

+ +example: | + /* Assume stack is empty initially. */ + + duk_push_int(ctx, 123); /* -> top=1, stack: [ 123 ] */ + duk_set_top(ctx, 3); /* -> top=3, stack: [ 123 undefined undefined ] */ + duk_set_top(ctx, -1); /* -> top=2, stack: [ 123 undefined ] */ + duk_set_top(ctx, 0); /* -> top=0, stack: [ ] */ + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_strict_equals.txt b/website/api/duk_strict_equals.txt deleted file mode 100644 index b58cb2fb..00000000 --- a/website/api/duk_strict_equals.txt +++ /dev/null @@ -1,34 +0,0 @@ -=proto -duk_bool_t duk_strict_equals(duk_context *ctx, duk_idx_t index1, duk_idx_t index2); - -=stack -[ ... val1! ... val2! ... ] - -=summary -

Compare values at index1 and index2 for equality. -Returns 1 if values are considered equal using Ecmascript -Strict Equals -operator (===) semantics, otherwise returns 0. Also returns 0 if either index -is invalid.

- -

Because -The Strict Equality Comparison Algorithm -used by the Strict Equals operator performs no value coercion, the comparison cannot have -side effects and cannot throw an error.

- -

Comparison algorithm for Duktape custom types is described in -Strict equality.

- -=example -if (duk_strict_equals(ctx, -3, -7)) { - printf("values at indices -3 and -7 are strictly equal\n"); -} - -=tags -compare - -=seealso -duk_equals - -=introduced -1.0.0 diff --git a/website/api/duk_strict_equals.yaml b/website/api/duk_strict_equals.yaml new file mode 100644 index 00000000..0c32a75c --- /dev/null +++ b/website/api/duk_strict_equals.yaml @@ -0,0 +1,35 @@ +name: duk_strict_equals + +proto: | + duk_bool_t duk_strict_equals(duk_context *ctx, duk_idx_t index1, duk_idx_t index2); + +stack: | + [ ... val1! ... val2! ... ] + +summary: | +

Compare values at index1 and index2 for equality. + Returns 1 if values are considered equal using Ecmascript + Strict Equals + operator (===) semantics, otherwise returns 0. Also returns 0 if either index + is invalid.

+ +

Because + The Strict Equality Comparison Algorithm + used by the Strict Equals operator performs no value coercion, the comparison cannot have + side effects and cannot throw an error.

+ +

Comparison algorithm for Duktape custom types is described in + Strict equality.

+ +example: | + if (duk_strict_equals(ctx, -3, -7)) { + printf("values at indices -3 and -7 are strictly equal\n"); + } + +tags: + - compare + +seealso: + - duk_equals + +introduced: 1.0.0 diff --git a/website/api/duk_substring.txt b/website/api/duk_substring.txt deleted file mode 100644 index 28b3965a..00000000 --- a/website/api/duk_substring.txt +++ /dev/null @@ -1,37 +0,0 @@ -=proto -void duk_substring(duk_context *ctx, duk_idx_t index, duk_size_t start_char_offset, duk_size_t end_char_offset); - -=stack -[ ... str! ... ] -> [ ... substr! ... ] - -=summary -

Replace a string at index with a substring [start_char_offset, -end_char_offset[ of the string itself. If the value at index is -not a string or the index is invalid, throws an error.

- -

The substring operation works with characters, not bytes, and the offsets -are character offsets. The semantics of this call are similar to -String.prototype.substring (start, end). -Offset values are clamped to string length (there is no need to clamp negative -values because size_t is unsigned) and if start offset is larger than -end offset, the result is an empty string.

- -
-To get a byte-oriented substring, use -duk_get_lstring() to get a string data -pointer and length, and -duk_push_lstring() to push a slice of -bytes. -
- -=example -/* String at index -3 is 'foobar'. Substring [2,5[ is "oba". */ - -duk_substring(ctx, -3, 2, 5); -printf("substring: %s\n", duk_get_string(ctx, -3)); - -=tags -string - -=introduced -1.0.0 diff --git a/website/api/duk_substring.yaml b/website/api/duk_substring.yaml new file mode 100644 index 00000000..6211638b --- /dev/null +++ b/website/api/duk_substring.yaml @@ -0,0 +1,38 @@ +name: duk_substring + +proto: | + void duk_substring(duk_context *ctx, duk_idx_t index, duk_size_t start_char_offset, duk_size_t end_char_offset); + +stack: | + [ ... str! ... ] -> [ ... substr! ... ] + +summary: | +

Replace a string at index with a substring [start_char_offset, + end_char_offset[ of the string itself. If the value at index is + not a string or the index is invalid, throws an error.

+ +

The substring operation works with characters, not bytes, and the offsets + are character offsets. The semantics of this call are similar to + String.prototype.substring (start, end). + Offset values are clamped to string length (there is no need to clamp negative + values because size_t is unsigned) and if start offset is larger than + end offset, the result is an empty string.

+ +
+ To get a byte-oriented substring, use + duk_get_lstring() to get a string data + pointer and length, and + duk_push_lstring() to push a slice of + bytes. +
+ +example: | + /* String at index -3 is 'foobar'. Substring [2,5[ is "oba". */ + + duk_substring(ctx, -3, 2, 5); + printf("substring: %s\n", duk_get_string(ctx, -3)); + +tags: + - string + +introduced: 1.0.0 diff --git a/website/api/duk_swap.txt b/website/api/duk_swap.txt deleted file mode 100644 index a20470a2..00000000 --- a/website/api/duk_swap.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -void duk_swap(duk_context *ctx, duk_idx_t index1, duk_idx_t index2); - -=stack -[ ... val1! ... val2! ... ] -> [ ... val2! ... val1! ... ] - -=summary -

Swap values at indices index1 and index2. If the -indices are the same, the call is a no-op. If either index is invalid, -throws an error.

- -=tags -stack - -=example -duk_swap(ctx, -5, -1); - -=seealso -duk_swap_top - -=introduced -1.0.0 diff --git a/website/api/duk_swap.yaml b/website/api/duk_swap.yaml new file mode 100644 index 00000000..3056abe3 --- /dev/null +++ b/website/api/duk_swap.yaml @@ -0,0 +1,23 @@ +name: duk_swap + +proto: | + void duk_swap(duk_context *ctx, duk_idx_t index1, duk_idx_t index2); + +stack: | + [ ... val1! ... val2! ... ] -> [ ... val2! ... val1! ... ] + +summary: | +

Swap values at indices index1 and index2. If the + indices are the same, the call is a no-op. If either index is invalid, + throws an error.

+ +example: | + duk_swap(ctx, -5, -1); + +tags: + - stack + +seealso: + - duk_swap_top + +introduced: 1.0.0 diff --git a/website/api/duk_swap_top.txt b/website/api/duk_swap_top.txt deleted file mode 100644 index 83325d51..00000000 --- a/website/api/duk_swap_top.txt +++ /dev/null @@ -1,19 +0,0 @@ -=proto -void duk_swap_top(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val1! ... val2! ] -> [ ... val2! ... val1! ] - -=summary -

Swap stack top with value at index. If index refers -to the stack top, the call is a no-op. If the value stack is empty or -index is invalid, throws an error.

- -=example -duk_swap_top(ctx, -3); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_swap_top.yaml b/website/api/duk_swap_top.yaml new file mode 100644 index 00000000..062af921 --- /dev/null +++ b/website/api/duk_swap_top.yaml @@ -0,0 +1,20 @@ +name: duk_swap_top + +proto: | + void duk_swap_top(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val1! ... val2! ] -> [ ... val2! ... val1! ] + +summary: | +

Swap stack top with value at index. If index refers + to the stack top, the call is a no-op. If the value stack is empty or + index is invalid, throws an error.

+ +example: | + duk_swap_top(ctx, -3); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_throw.txt b/website/api/duk_throw.txt deleted file mode 100644 index 7150e262..00000000 --- a/website/api/duk_throw.txt +++ /dev/null @@ -1,27 +0,0 @@ -=proto -void duk_throw(duk_context *ctx); - -=stack -[ ... val! ] - -=summary -

Throw the value on top of the stack. This call never returns.

- -=example -/* Throw a string value; equivalent to the Ecmascript code: - * - * throw "this string is thrown"; - */ - -duk_push_string(ctx, "this string is thrown"); -duk_throw(ctx); - -=tags -error - -=seealso -duk_error -duk_push_error_object - -=introduced -1.0.0 diff --git a/website/api/duk_throw.yaml b/website/api/duk_throw.yaml new file mode 100644 index 00000000..9c546323 --- /dev/null +++ b/website/api/duk_throw.yaml @@ -0,0 +1,28 @@ +name: duk_throw + +proto: | + void duk_throw(duk_context *ctx); + +stack: | + [ ... val! ] + +summary: | +

Throw the value on top of the stack. This call never returns.

+ +example: | + /* Throw a string value; equivalent to the Ecmascript code: + * + * throw "this string is thrown"; + */ + + duk_push_string(ctx, "this string is thrown"); + duk_throw(ctx); + +tags: + - error + +seealso: + - duk_error + - duk_push_error_object + +introduced: 1.0.0 diff --git a/website/api/duk_to_boolean.txt b/website/api/duk_to_boolean.txt deleted file mode 100644 index a741236a..00000000 --- a/website/api/duk_to_boolean.txt +++ /dev/null @@ -1,24 +0,0 @@ -=proto -duk_bool_t duk_to_boolean(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... ToBoolean(val)! ... ] - -=summary -

Replace the value at index with an Ecmascript -ToBoolean() -coerced value. Returns 1 if the result of the coercion true, 0 otherwise. -If index is invalid, throws an error.

- -
- -=example -if (duk_to_boolean(ctx, -3)) { - printf("coerced value is true\n"); -} - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_boolean.yaml b/website/api/duk_to_boolean.yaml new file mode 100644 index 00000000..bc6164e0 --- /dev/null +++ b/website/api/duk_to_boolean.yaml @@ -0,0 +1,25 @@ +name: duk_to_boolean + +proto: | + duk_bool_t duk_to_boolean(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... ToBoolean(val)! ... ] + +summary: | +

Replace the value at index with an Ecmascript + ToBoolean() + coerced value. Returns 1 if the result of the coercion true, 0 otherwise. + If index is invalid, throws an error.

+ +
+ +example: | + if (duk_to_boolean(ctx, -3)) { + printf("coerced value is true\n"); + } + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_to_buffer.txt b/website/api/duk_to_buffer.txt deleted file mode 100644 index 47499383..00000000 --- a/website/api/duk_to_buffer.txt +++ /dev/null @@ -1,38 +0,0 @@ -=proto -void *duk_to_buffer(duk_context *ctx, duk_idx_t index, duk_size_t *out_size); - -=stack -[ ... val! ... ] -> [ ... buffer(val)! ... ] - -=summary -

Replace the value at index with a buffer-coerced value. Returns -a pointer to the buffer data (may be NULL for a zero-size buffer), -and writes the size of the buffer into *out_size (if out_size -is non-NULL). If index is invalid, throws an error.

- -

Coercion rules:

-
    -
  • Buffer: no change, dynamic/fixed nature not changed
    • -
  • String: coerces into a fixed size buffer, byte-for-byte
    • -
  • Other types: first apply Ecmascript -ToString(), -then coerce into a fixed size buffer, byte-for-byte
    • -
- -=example -void *ptr; -duk_size_t sz; - -ptr = duk_to_buffer(ctx, -3, &sz); -printf("coerced data at %p, size %lu\n", ptr, (unsigned long) sz); - -=tags -stack -buffer - -=seealso -duk_to_fixed_buffer -duk_to_dynamic_buffer - -=introduced -1.0.0 diff --git a/website/api/duk_to_buffer.yaml b/website/api/duk_to_buffer.yaml new file mode 100644 index 00000000..dfcb70b4 --- /dev/null +++ b/website/api/duk_to_buffer.yaml @@ -0,0 +1,39 @@ +name: duk_to_buffer + +proto: | + void *duk_to_buffer(duk_context *ctx, duk_idx_t index, duk_size_t *out_size); + +stack: | + [ ... val! ... ] -> [ ... buffer(val)! ... ] + +summary: | +

Replace the value at index with a buffer-coerced value. Returns + a pointer to the buffer data (may be NULL for a zero-size buffer), + and writes the size of the buffer into *out_size (if out_size + is non-NULL). If index is invalid, throws an error.

+ +

Coercion rules:

+
    +
  • Buffer: no change, dynamic/fixed nature not changed
    • +
  • String: coerces into a fixed size buffer, byte-for-byte
    • +
  • Other types: first apply Ecmascript + ToString(), + then coerce into a fixed size buffer, byte-for-byte
    • +
+ +example: | + void *ptr; + duk_size_t sz; + + ptr = duk_to_buffer(ctx, -3, &sz); + printf("coerced data at %p, size %lu\n", ptr, (unsigned long) sz); + +tags: + - stack + - buffer + +seealso: + - duk_to_fixed_buffer + - duk_to_dynamic_buffer + +introduced: 1.0.0 diff --git a/website/api/duk_to_defaultvalue.txt b/website/api/duk_to_defaultvalue.txt deleted file mode 100644 index 78c742c2..00000000 --- a/website/api/duk_to_defaultvalue.txt +++ /dev/null @@ -1,31 +0,0 @@ -=proto -void duk_to_defaultvalue(duk_context *ctx, duk_idx_t index, duk_int_t hint); - -=stack -[ ... val! ... ] -> [ ... DefaultValue(val)! ... ] - -=summary -

Replace the object at index with an Ecmascript -[[DefaultValue]] -coerced value. The hint argument indicates preference for a string -(DUK_HINT_STRING), a number (DUK_HINT_NUMBER), or neither -(DUK_HINT_NONE). DUK_HINT_NONE causes a preference to a number, unless -the input value is a Date instance, in which case a string is preferred -(the exact coercion behavior is described in the Ecmascript specification). -If the value is not an object or index is invalid, throws an error.

- -
- -
-[[DefaultValue]] is a rather technical coercion, not usually needed by -calling code. -
- -=example -duk_to_defaultvalue(ctx, -3, DUK_HINT_NUMBER); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_defaultvalue.yaml b/website/api/duk_to_defaultvalue.yaml new file mode 100644 index 00000000..a3f593ee --- /dev/null +++ b/website/api/duk_to_defaultvalue.yaml @@ -0,0 +1,32 @@ +name: duk_to_defaultvalue + +proto: | + void duk_to_defaultvalue(duk_context *ctx, duk_idx_t index, duk_int_t hint); + +stack: | + [ ... val! ... ] -> [ ... DefaultValue(val)! ... ] + +summary: | +

Replace the object at index with an Ecmascript + [[DefaultValue]] + coerced value. The hint argument indicates preference for a string + (DUK_HINT_STRING), a number (DUK_HINT_NUMBER), or neither + (DUK_HINT_NONE). DUK_HINT_NONE causes a preference to a number, unless + the input value is a Date instance, in which case a string is preferred + (the exact coercion behavior is described in the Ecmascript specification). + If the value is not an object or index is invalid, throws an error.

+ +
+ +
+ [[DefaultValue]] is a rather technical coercion, not usually needed by + calling code. +
+ +example: | + duk_to_defaultvalue(ctx, -3, DUK_HINT_NUMBER); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_to_dynamic_buffer.txt b/website/api/duk_to_dynamic_buffer.txt deleted file mode 100644 index 53575b61..00000000 --- a/website/api/duk_to_dynamic_buffer.txt +++ /dev/null @@ -1,21 +0,0 @@ -=proto -void *duk_to_dynamic_buffer(duk_context *ctx, duk_idx_t index, duk_size_t *out_size); - -=stack -[ ... val! ... ] - -=summary -

Like duk_to_buffer() but the -result is always a dynamic buffer (unless an error is thrown). If the value -is a fixed buffer, convert it to a dynamic buffer.

- -=example -duk_size_t sz; -void *buf = duk_to_dynamic_buffer(ctx, -3, &sz); - -=tags -stack -buffer - -=introduced -1.0.0 diff --git a/website/api/duk_to_dynamic_buffer.yaml b/website/api/duk_to_dynamic_buffer.yaml new file mode 100644 index 00000000..dbc13b64 --- /dev/null +++ b/website/api/duk_to_dynamic_buffer.yaml @@ -0,0 +1,22 @@ +name: duk_to_dynamic_buffer + +proto: | + void *duk_to_dynamic_buffer(duk_context *ctx, duk_idx_t index, duk_size_t *out_size); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_to_buffer() but the + result is always a dynamic buffer (unless an error is thrown). If the value + is a fixed buffer, convert it to a dynamic buffer.

+ +example: | + duk_size_t sz; + void *buf = duk_to_dynamic_buffer(ctx, -3, &sz); + +tags: + - stack + - buffer + +introduced: 1.0.0 diff --git a/website/api/duk_to_fixed_buffer.txt b/website/api/duk_to_fixed_buffer.txt deleted file mode 100644 index 4f125318..00000000 --- a/website/api/duk_to_fixed_buffer.txt +++ /dev/null @@ -1,21 +0,0 @@ -=proto -void *duk_to_fixed_buffer(duk_context *ctx, duk_idx_t index, duk_size_t *out_size); - -=stack -[ ... val! ... ] - -=summary -

Like duk_to_buffer() but if -the value is a dynamic buffer, convert it to a fixed buffer. The result -is thus always a fixed buffer (unless an error is thrown).

- -=example -duk_size_t sz; -void *buf = duk_to_fixed_buffer(ctx, -3, &sz); - -=tags -stack -buffer - -=introduced -1.0.0 diff --git a/website/api/duk_to_fixed_buffer.yaml b/website/api/duk_to_fixed_buffer.yaml new file mode 100644 index 00000000..53a4df7d --- /dev/null +++ b/website/api/duk_to_fixed_buffer.yaml @@ -0,0 +1,22 @@ +name: duk_to_fixed_buffer + +proto: | + void *duk_to_fixed_buffer(duk_context *ctx, duk_idx_t index, duk_size_t *out_size); + +stack: | + [ ... val! ... ] + +summary: | +

Like duk_to_buffer() but if + the value is a dynamic buffer, convert it to a fixed buffer. The result + is thus always a fixed buffer (unless an error is thrown).

+ +example: | + duk_size_t sz; + void *buf = duk_to_fixed_buffer(ctx, -3, &sz); + +tags: + - stack + - buffer + +introduced: 1.0.0 diff --git a/website/api/duk_to_int.txt b/website/api/duk_to_int.txt deleted file mode 100644 index 992fcca8..00000000 --- a/website/api/duk_to_int.txt +++ /dev/null @@ -1,41 +0,0 @@ -=proto -duk_int_t duk_to_int(duk_context *ctx, duk_int_t index); - -=stack -[ ... val! ... ] -> [ ... ToNumber(val)! ... ] - -=summary -

Replace the value at index with an Ecmascript -ToInteger() -coerced value. Returns an duk_int_t further coerced from the ToInteger() -result using the algorithm described in -duk_get_int() (this second coercion is not -reflected in the new stack value). If index is invalid, throws an error.

- -
- -

If you want the double version of the ToInteger() coerced value, -use:

-
-double d;
-
-(void) duk_to_int(ctx, -3);
-d = (double) duk_get_number(ctx, -3);
-
- -
-duk_get_int() int coercion is applied only to the return value, it is not -reflected on the value stack. For instance, if value stack contains the string -"Infinity", the value on the stack will be coerced to the number -Infinity and DUK_INT_MAX will be returned from the API call. -
- -=example -printf("ToInteger() + int coercion: %ld\n", (long) duk_to_int(ctx, -3)); -printf("ToInteger() coercion: %lf\n", (double) duk_get_number(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_int.yaml b/website/api/duk_to_int.yaml new file mode 100644 index 00000000..84977b06 --- /dev/null +++ b/website/api/duk_to_int.yaml @@ -0,0 +1,42 @@ +name: duk_to_int + +proto: | + duk_int_t duk_to_int(duk_context *ctx, duk_int_t index); + +stack: | + [ ... val! ... ] -> [ ... ToNumber(val)! ... ] + +summary: | +

Replace the value at index with an Ecmascript + ToInteger() + coerced value. Returns an duk_int_t further coerced from the ToInteger() + result using the algorithm described in + duk_get_int() (this second coercion is not + reflected in the new stack value). If index is invalid, throws an error.

+ +
+ +

If you want the double version of the ToInteger() coerced value, + use:

+ 
+  double d;
+
+  (void) duk_to_int(ctx, -3);
+  d = (double) duk_get_number(ctx, -3);
+
+ +
+ duk_get_int() int coercion is applied only to the return value, it is not + reflected on the value stack. For instance, if value stack contains the string + "Infinity", the value on the stack will be coerced to the number + Infinity and DUK_INT_MAX will be returned from the API call. +
+ +example: | + printf("ToInteger() + int coercion: %ld\n", (long) duk_to_int(ctx, -3)); + printf("ToInteger() coercion: %lf\n", (double) duk_get_number(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_to_int32.txt b/website/api/duk_to_int32.txt deleted file mode 100644 index e2fd217f..00000000 --- a/website/api/duk_to_int32.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_int32_t duk_to_int32(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... ToInt32(val)! ... ] - -=summary -

Replace the value at index with an Ecmascript -ToInt32() -coerced value. Returns the coerced value. If index is invalid, throws -an error.

- -
- -=example -printf("ToInt32(): %ld\n", (long) duk_to_int32(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_int32.yaml b/website/api/duk_to_int32.yaml new file mode 100644 index 00000000..e70f75b5 --- /dev/null +++ b/website/api/duk_to_int32.yaml @@ -0,0 +1,23 @@ +name: duk_to_int32 + +proto: | + duk_int32_t duk_to_int32(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... ToInt32(val)! ... ] + +summary: | +

Replace the value at index with an Ecmascript + ToInt32() + coerced value. Returns the coerced value. If index is invalid, throws + an error.

+ +
+ +example: | + printf("ToInt32(): %ld\n", (long) duk_to_int32(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_to_lstring.txt b/website/api/duk_to_lstring.txt deleted file mode 100644 index bfcec2d4..00000000 --- a/website/api/duk_to_lstring.txt +++ /dev/null @@ -1,32 +0,0 @@ -=proto -const char *duk_to_lstring(duk_context *ctx, duk_idx_t index, duk_size_t *out_len); - -=stack -[ ... val! ... ] -> [ ... ToString(val)! ... ] - -=summary -

Replace the value at index with an Ecmascript -ToString() -coerced value. Returns a non-NULL pointer to the read-only, -NUL-terminated string data, and writes the string byte length to *out_len -(if out_len is non-NULL). If index is invalid, throws -an error.

- -
- -=example -const char *ptr; -duk_size_t sz; - -ptr = duk_to_lstring(ctx, -3, &sz); -printf("coerced string: %s (length %lu)\n", ptr, (unsigned long) sz); - -=tags -stack -string - -=seealso -duk_safe_to_lstring - -=introduced -1.0.0 diff --git a/website/api/duk_to_lstring.yaml b/website/api/duk_to_lstring.yaml new file mode 100644 index 00000000..2aa46ed4 --- /dev/null +++ b/website/api/duk_to_lstring.yaml @@ -0,0 +1,33 @@ +name: duk_to_lstring + +proto: | + const char *duk_to_lstring(duk_context *ctx, duk_idx_t index, duk_size_t *out_len); + +stack: | + [ ... val! ... ] -> [ ... ToString(val)! ... ] + +summary: | +

Replace the value at index with an Ecmascript + ToString() + coerced value. Returns a non-NULL pointer to the read-only, + NUL-terminated string data, and writes the string byte length to *out_len + (if out_len is non-NULL). If index is invalid, throws + an error.

+ +
+ +example: | + const char *ptr; + duk_size_t sz; + + ptr = duk_to_lstring(ctx, -3, &sz); + printf("coerced string: %s (length %lu)\n", ptr, (unsigned long) sz); + +tags: + - stack + - string + +seealso: + - duk_safe_to_lstring + +introduced: 1.0.0 diff --git a/website/api/duk_to_null.txt b/website/api/duk_to_null.txt deleted file mode 100644 index c368c59b..00000000 --- a/website/api/duk_to_null.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -void duk_to_null(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... null! ... ] - -=summary -

Replace the value at index with null, regardless -of the previous value. Throws an error if index is invalid.

- -
-Equivalent to duk_push_null() followed by duk_replace() -to target index. -
- -=example -duk_to_null(ctx, -3); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_null.yaml b/website/api/duk_to_null.yaml new file mode 100644 index 00000000..48aa1a7e --- /dev/null +++ b/website/api/duk_to_null.yaml @@ -0,0 +1,24 @@ +name: duk_to_null + +proto: | + void duk_to_null(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... null! ... ] + +summary: | +

Replace the value at index with null, regardless + of the previous value. Throws an error if index is invalid.

+ +
+ Equivalent to duk_push_null() followed by duk_replace() + to target index. +
+ +example: | + duk_to_null(ctx, -3); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_to_number.txt b/website/api/duk_to_number.txt deleted file mode 100644 index ce5d0514..00000000 --- a/website/api/duk_to_number.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_double_t duk_to_number(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... ToNumber(val)! ... ] - -=summary -

Replace the value at index with an Ecmascript -ToNumber() -coerced value. Returns the coerced value. If index is invalid, throws -an error.

- -
- -=example -printf("coerced number: %lf\n", (double) duk_to_number(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_number.yaml b/website/api/duk_to_number.yaml new file mode 100644 index 00000000..324cfb1a --- /dev/null +++ b/website/api/duk_to_number.yaml @@ -0,0 +1,23 @@ +name: duk_to_number + +proto: | + duk_double_t duk_to_number(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... ToNumber(val)! ... ] + +summary: | +

Replace the value at index with an Ecmascript + ToNumber() + coerced value. Returns the coerced value. If index is invalid, throws + an error.

+ +
+ +example: | + printf("coerced number: %lf\n", (double) duk_to_number(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_to_object.txt b/website/api/duk_to_object.txt deleted file mode 100644 index 47f6faa9..00000000 --- a/website/api/duk_to_object.txt +++ /dev/null @@ -1,29 +0,0 @@ -=proto -void duk_to_object(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... ToObject(val)! ... ] - -=summary -

Replace the value at index with an Ecmascript -ToObject() -coerced value. There is no return value. Throws an error if value at -index is not -object coercible, -or if index is invalid.

- -

The following types are not object coercible:

-
    -
  • undefined
    • -
  • null
    • -
- -=example -duk_to_object(ctx, -3); - -=tags -stack -object - -=introduced -1.0.0 diff --git a/website/api/duk_to_object.yaml b/website/api/duk_to_object.yaml new file mode 100644 index 00000000..6ee876df --- /dev/null +++ b/website/api/duk_to_object.yaml @@ -0,0 +1,30 @@ +name: duk_to_object + +proto: | + void duk_to_object(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... ToObject(val)! ... ] + +summary: | +

Replace the value at index with an Ecmascript + ToObject() + coerced value. There is no return value. Throws an error if value at + index is not + object coercible, + or if index is invalid.

+ +

The following types are not object coercible:

+
    +
  • undefined
    • +
  • null
    • +
+ +example: | + duk_to_object(ctx, -3); + +tags: + - stack + - object + +introduced: 1.0.0 diff --git a/website/api/duk_to_pointer.txt b/website/api/duk_to_pointer.txt deleted file mode 100644 index 999bef46..00000000 --- a/website/api/duk_to_pointer.txt +++ /dev/null @@ -1,37 +0,0 @@ -=proto -void *duk_to_pointer(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... pointer(val)! ... ] - -=summary -

Replaces the value at index with a pointer-coerced value. Returns -the resulting void * value. If index is invalid, throws an -error.

- -

Coercion rules:

-
    -
  • Pointer: coerces to itself, no change
    • -
  • All heap allocated objects (string, object, buffer): coerce to a pointer - which points to the Duktape internal heap header (use for debugging only, - do not read/write)
    • -
  • Other types: coerce to NULL
    • -
- -
-This API call is really only useful for debugging. Note in particular that -the pointer returned must not be accessed, as it points to an internal heap -header. This is the case even for string/buffer values: the returned pointer -differs from the one returned by duk_get_string() and -duk_get_buffer(). -
- -=example -/* Don't dereference the pointer. */ -printf("coerced pointer: %p\n", duk_to_pointer(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_pointer.yaml b/website/api/duk_to_pointer.yaml new file mode 100644 index 00000000..3fb72a5a --- /dev/null +++ b/website/api/duk_to_pointer.yaml @@ -0,0 +1,38 @@ +name: duk_to_pointer + +proto: | + void *duk_to_pointer(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... pointer(val)! ... ] + +summary: | +

Replaces the value at index with a pointer-coerced value. Returns + the resulting void * value. If index is invalid, throws an + error.

+ +

Coercion rules:

+
    +
  • Pointer: coerces to itself, no change
    • +
  • All heap allocated objects (string, object, buffer): coerce to a pointer + which points to the Duktape internal heap header (use for debugging only, + do not read/write)
    • +
  • Other types: coerce to NULL
    • +
+ +
+ This API call is really only useful for debugging. Note in particular that + the pointer returned must not be accessed, as it points to an internal heap + header. This is the case even for string/buffer values: the returned pointer + differs from the one returned by duk_get_string() and + duk_get_buffer(). +
+ +example: | + /* Don't dereference the pointer. */ + printf("coerced pointer: %p\n", duk_to_pointer(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_to_primitive.txt b/website/api/duk_to_primitive.txt deleted file mode 100644 index 41a1421c..00000000 --- a/website/api/duk_to_primitive.txt +++ /dev/null @@ -1,35 +0,0 @@ -=proto -void duk_to_primitive(duk_context *ctx, duk_idx_t index, duk_int_t hint); - -=stack -[ ... val! ... ] -> [ ... ToPrimitive(val)! ] - -=summary -

Replace the object at index with an Ecmascript -ToPrimitive() -coerced value. The hint argument affects coercion of an object into a -primitive type, and indicates preference for a string (DUK_HINT_STRING), -a number (DUK_HINT_NUMBER), or neither (DUK_HINT_NONE). -DUK_HINT_NONE causes a preference to a number, unless the input value -is a Date instance, in which case a string is preferred (the exact -coercion behavior is described in the Ecmascript specification). If index -is invalid, throws an error.

- -

Custom type coercion:

-
    -
  • Buffer value (plain): keep existing value
    • -
  • Buffer object: coerces to the underlying plain buffer value
    • -
  • Pointer value (plain): keep existing value
    • -
  • Pointer object: coerces to the underlying plain pointer value
    • -
- -
- -=example -duk_to_primitive(ctx, -3, DUK_HINT_NUMBER); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_primitive.yaml b/website/api/duk_to_primitive.yaml new file mode 100644 index 00000000..af7b2cc2 --- /dev/null +++ b/website/api/duk_to_primitive.yaml @@ -0,0 +1,36 @@ +name: duk_to_primitive + +proto: | + void duk_to_primitive(duk_context *ctx, duk_idx_t index, duk_int_t hint); + +stack: | + [ ... val! ... ] -> [ ... ToPrimitive(val)! ] + +summary: | +

Replace the object at index with an Ecmascript + ToPrimitive() + coerced value. The hint argument affects coercion of an object into a + primitive type, and indicates preference for a string (DUK_HINT_STRING), + a number (DUK_HINT_NUMBER), or neither (DUK_HINT_NONE). + DUK_HINT_NONE causes a preference to a number, unless the input value + is a Date instance, in which case a string is preferred (the exact + coercion behavior is described in the Ecmascript specification). If index + is invalid, throws an error.

+ +

Custom type coercion:

+
    +
  • Buffer value (plain): keep existing value
    • +
  • Buffer object: coerces to the underlying plain buffer value
    • +
  • Pointer value (plain): keep existing value
    • +
  • Pointer object: coerces to the underlying plain pointer value
    • +
+ +
+ +example: | + duk_to_primitive(ctx, -3, DUK_HINT_NUMBER); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_to_string.txt b/website/api/duk_to_string.txt deleted file mode 100644 index 7f9a4f4f..00000000 --- a/website/api/duk_to_string.txt +++ /dev/null @@ -1,26 +0,0 @@ -=proto -const char *duk_to_string(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... ToString(val)! ... ] - -=summary -

Replace the value at index with an Ecmascript -ToString() -coerced value. Returns a non-NULL pointer to the read-only, -NUL-terminated string data. If index is invalid, throws an error.

- -
- -=example -printf("coerced string: %s\n", duk_to_string(ctx, -3)); - -=tags -stack -string - -=seealso -duk_safe_to_string - -=introduced -1.0.0 diff --git a/website/api/duk_to_string.yaml b/website/api/duk_to_string.yaml new file mode 100644 index 00000000..b636240b --- /dev/null +++ b/website/api/duk_to_string.yaml @@ -0,0 +1,27 @@ +name: duk_to_string + +proto: | + const char *duk_to_string(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... ToString(val)! ... ] + +summary: | +

Replace the value at index with an Ecmascript + ToString() + coerced value. Returns a non-NULL pointer to the read-only, + NUL-terminated string data. If index is invalid, throws an error.

+ +
+ +example: | + printf("coerced string: %s\n", duk_to_string(ctx, -3)); + +tags: + - stack + - string + +seealso: + - duk_safe_to_string + +introduced: 1.0.0 diff --git a/website/api/duk_to_uint.txt b/website/api/duk_to_uint.txt deleted file mode 100644 index 1094624e..00000000 --- a/website/api/duk_to_uint.txt +++ /dev/null @@ -1,26 +0,0 @@ -=proto -duk_uint_t duk_to_uint(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... ToNumber(val)! ... ] - -=summary -

Like duk_to_int() but the return value -coercion is the same as in duk_get_uint().

- -
-duk_get_uint() int coercion is applied only to the return value, it is not -reflected on the value stack. For instance, if value stack contains the string -"Infinity", the value on the stack will be coerced to the number -Infinity and DUK_UINT_MAX will be returned from the API call. -
- -=example -printf("ToInteger() + uint coercion: %lu\n", (unsigned long) duk_to_uint(ctx, -3)); -printf("ToInteger() coercion: %lf\n", (double) duk_get_number(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_uint.yaml b/website/api/duk_to_uint.yaml new file mode 100644 index 00000000..745cc4f1 --- /dev/null +++ b/website/api/duk_to_uint.yaml @@ -0,0 +1,27 @@ +name: duk_to_uint + +proto: | + duk_uint_t duk_to_uint(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... ToNumber(val)! ... ] + +summary: | +

Like duk_to_int() but the return value + coercion is the same as in duk_get_uint().

+ +
+ duk_get_uint() int coercion is applied only to the return value, it is not + reflected on the value stack. For instance, if value stack contains the string + "Infinity", the value on the stack will be coerced to the number + Infinity and DUK_UINT_MAX will be returned from the API call. +
+ +example: | + printf("ToInteger() + uint coercion: %lu\n", (unsigned long) duk_to_uint(ctx, -3)); + printf("ToInteger() coercion: %lf\n", (double) duk_get_number(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_to_uint16.txt b/website/api/duk_to_uint16.txt deleted file mode 100644 index 226aae4c..00000000 --- a/website/api/duk_to_uint16.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_uint16_t duk_to_uint16(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... ToUint16(val)! ... ] - -=summary -

Replace the value at index with an Ecmascript -ToUint16() -coerced value. Returns the coerced value. If index is invalid, throws -an error.

- -
- -=example -printf("ToUint16(): %u\n", (unsigned int) duk_to_uint16(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_uint16.yaml b/website/api/duk_to_uint16.yaml new file mode 100644 index 00000000..266673ec --- /dev/null +++ b/website/api/duk_to_uint16.yaml @@ -0,0 +1,23 @@ +name: duk_to_uint16 + +proto: | + duk_uint16_t duk_to_uint16(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... ToUint16(val)! ... ] + +summary: | +

Replace the value at index with an Ecmascript + ToUint16() + coerced value. Returns the coerced value. If index is invalid, throws + an error.

+ +
+ +example: | + printf("ToUint16(): %u\n", (unsigned int) duk_to_uint16(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_to_uint32.txt b/website/api/duk_to_uint32.txt deleted file mode 100644 index e63e359b..00000000 --- a/website/api/duk_to_uint32.txt +++ /dev/null @@ -1,22 +0,0 @@ -=proto -duk_uint32_t duk_to_uint32(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... ToUint32(val)! ... ] - -=summary -

Replace the value at index with an Ecmascript -ToUint32() -coerced value. Returns the coerced value. If index is invalid, throws -an error.

- -
- -=example -printf("ToUint32(): %lu\n", (unsigned long) duk_to_uint32(ctx, -3)); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_uint32.yaml b/website/api/duk_to_uint32.yaml new file mode 100644 index 00000000..a0a87bda --- /dev/null +++ b/website/api/duk_to_uint32.yaml @@ -0,0 +1,23 @@ +name: duk_to_uint32 + +proto: | + duk_uint32_t duk_to_uint32(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... ToUint32(val)! ... ] + +summary: | +

Replace the value at index with an Ecmascript + ToUint32() + coerced value. Returns the coerced value. If index is invalid, throws + an error.

+ +
+ +example: | + printf("ToUint32(): %lu\n", (unsigned long) duk_to_uint32(ctx, -3)); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_to_undefined.txt b/website/api/duk_to_undefined.txt deleted file mode 100644 index a5b339b9..00000000 --- a/website/api/duk_to_undefined.txt +++ /dev/null @@ -1,23 +0,0 @@ -=proto -void duk_to_undefined(duk_context *ctx, duk_idx_t index); - -=stack -[ ... val! ... ] -> [ ... undefined! ... ] - -=summary -

Replace the value at index with undefined, regardless -of the previous value. Throws an error if index is invalid.

- -
-Equivalent to duk_push_undefined() followed by duk_replace() -to target index. -
- -=example -duk_to_undefined(ctx, -3); - -=tags -stack - -=introduced -1.0.0 diff --git a/website/api/duk_to_undefined.yaml b/website/api/duk_to_undefined.yaml new file mode 100644 index 00000000..2f2212ac --- /dev/null +++ b/website/api/duk_to_undefined.yaml @@ -0,0 +1,24 @@ +name: duk_to_undefined + +proto: | + void duk_to_undefined(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... val! ... ] -> [ ... undefined! ... ] + +summary: | +

Replace the value at index with undefined, regardless + of the previous value. Throws an error if index is invalid.

+ +
+ Equivalent to duk_push_undefined() followed by duk_replace() + to target index. +
+ +example: | + duk_to_undefined(ctx, -3); + +tags: + - stack + +introduced: 1.0.0 diff --git a/website/api/duk_trim.txt b/website/api/duk_trim.txt deleted file mode 100644 index 8fa8a68d..00000000 --- a/website/api/duk_trim.txt +++ /dev/null @@ -1,33 +0,0 @@ -=proto -void duk_trim(duk_context *ctx, duk_idx_t index); - -=stack -[ ... str! ... ] -> [ ... trimmed_str! ... ] - -=summary -

Trim string at index. If the value at index is not a -string or the index is invalid, throws an error.

- -

Trimming removes white space characters from the beginning and -end the end of the string. The result is an empty string if the string -consists entirely of white space characters. -The set of characters considered to be white space is defined by the -StrWhiteSpace -production, which contains both -WhiteSpace and -LineTerminator characters. -The trimming behavior matches those of -String.prototype.trim(), -parseInt(), and -parseFloat(). -

- -=example -duk_trim(ctx, -3); - -=tags -stack -string - -=introduced -1.0.0 diff --git a/website/api/duk_trim.yaml b/website/api/duk_trim.yaml new file mode 100644 index 00000000..b2a76802 --- /dev/null +++ b/website/api/duk_trim.yaml @@ -0,0 +1,34 @@ +name: duk_trim + +proto: | + void duk_trim(duk_context *ctx, duk_idx_t index); + +stack: | + [ ... str! ... ] -> [ ... trimmed_str! ... ] + +summary: | +

Trim string at index. If the value at index is not a + string or the index is invalid, throws an error.

+ +

Trimming removes white space characters from the beginning and + end the end of the string. The result is an empty string if the string + consists entirely of white space characters. + The set of characters considered to be white space is defined by the + StrWhiteSpace + production, which contains both + WhiteSpace and + LineTerminator characters. + The trimming behavior matches those of + String.prototype.trim(), + parseInt(), and + parseFloat(). +

+ +example: | + duk_trim(ctx, -3); + +tags: + - stack + - string + +introduced: 1.0.0 diff --git a/website/api/duk_xcopy_top.txt b/website/api/duk_xcopy_top.txt deleted file mode 100644 index c02d2355..00000000 --- a/website/api/duk_xcopy_top.txt +++ /dev/null @@ -1,29 +0,0 @@ -=proto -void duk_xcopy_top(duk_context *to_ctx, duk_context *from_ctx, duk_idx_t count); - -=stack -[ ... val1! ...! valN! ] -> [ ... val1! ...! valN! ] (on source stack, from_ctx) -[ ... ] -> [ ... val1! ...! valN! ] (on target stack, to_ctx) - -=summary -

Like duk_xmove_top() but the elements being -copied are not popped of the source stack. -Both source and target stack must reside in the same Duktape heap.

- -
-The order of from/to stack is reversed as compared to Lua's -lua_xmove(). -
- -=example -duk_xcopy_top(new_ctx, ctx, 7); - -=tags -stack -slice - -=seealso -duk_xmove_top - -=introduced -1.0.0 diff --git a/website/api/duk_xcopy_top.yaml b/website/api/duk_xcopy_top.yaml new file mode 100644 index 00000000..31ef6384 --- /dev/null +++ b/website/api/duk_xcopy_top.yaml @@ -0,0 +1,30 @@ +name: duk_xcopy_top + +proto: | + void duk_xcopy_top(duk_context *to_ctx, duk_context *from_ctx, duk_idx_t count); + +stack: | + [ ... val1! ...! valN! ] -> [ ... val1! ...! valN! ] (on source stack, from_ctx) + [ ... ] -> [ ... val1! ...! valN! ] (on target stack, to_ctx) + +summary: | +

Like duk_xmove_top() but the elements being + copied are not popped of the source stack. + Both source and target stack must reside in the same Duktape heap.

+ +
+ The order of from/to stack is reversed as compared to Lua's + lua_xmove(). +
+ +example: | + duk_xcopy_top(new_ctx, ctx, 7); + +tags: + - stack + - slice + +seealso: + - duk_xmove_top + +introduced: 1.0.0 diff --git a/website/api/duk_xmove_top.txt b/website/api/duk_xmove_top.txt deleted file mode 100644 index 7867318e..00000000 --- a/website/api/duk_xmove_top.txt +++ /dev/null @@ -1,61 +0,0 @@ -=proto -void duk_xmove_top(duk_context *to_ctx, duk_context *from_ctx, duk_idx_t count); - -=stack -[ ... val1! ...! valN! ] -> [ ... ] (on source stack, from_ctx) -[ ... ] -> [ ... val1! ...! valN! ] (on target stack, to_ctx) - -=summary -

Remove count arguments from the top of the source stack and push -them onto the target stack. The caller must ensure that the target stack has -enough allocated space with e.g. -duk_require_stack(). Both source -and target stack must reside in the same Duktape heap.

- -

If the source and target stacks are the same, an error is currently thrown.

- -
-The order of from/to stack is reversed as compared to Lua's -lua_xmove(). -
- -=example -/* A Duktape/C function which executes a given function in a new thread. - */ -static duk_ret_t call_in_thread(duk_context *ctx) { - duk_idx_t nargs; - duk_context *new_ctx; - - /* Arguments: func, arg1, ... argN. */ - nargs = duk_get_top(ctx); - if (nargs < 1) { - return DUK_RET_TYPE_ERROR; /* missing func argument */ - } - - /* Create a new context. */ - duk_push_thread(); - new_ctx = duk_require_context(ctx, -1); - - /* Move arguments to the new context. Note that we need to extend - * the target stack allocation explicitly. - */ - duk_require_stack(new_ctx, nargs); - duk_xmove_top(ctx, new_ctx, nargs); - - /* Call the function; new_ctx is now: [ func arg1 ... argN ]. */ - duk_call(new_ctx, nargs - 1); - - /* Return the function call result by copying it to the original stack. */ - duk_xmove_top(new_ctx, ctx, 1); - return 1; -} - -=tags -stack -slice - -=seealso -duk_xcopy_top - -=introduced -1.0.0 diff --git a/website/api/duk_xmove_top.yaml b/website/api/duk_xmove_top.yaml new file mode 100644 index 00000000..ef753022 --- /dev/null +++ b/website/api/duk_xmove_top.yaml @@ -0,0 +1,62 @@ +name: duk_xmove_top + +proto: | + void duk_xmove_top(duk_context *to_ctx, duk_context *from_ctx, duk_idx_t count); + +stack: | + [ ... val1! ...! valN! ] -> [ ... ] (on source stack, from_ctx) + [ ... ] -> [ ... val1! ...! valN! ] (on target stack, to_ctx) + +summary: | +

Remove count arguments from the top of the source stack and push + them onto the target stack. The caller must ensure that the target stack has + enough allocated space with e.g. + duk_require_stack(). Both source + and target stack must reside in the same Duktape heap.

+ +

If the source and target stacks are the same, an error is currently thrown.

+ +
+ The order of from/to stack is reversed as compared to Lua's + lua_xmove(). +
+ +example: | + /* A Duktape/C function which executes a given function in a new thread. + */ + static duk_ret_t call_in_thread(duk_context *ctx) { + duk_idx_t nargs; + duk_context *new_ctx; + + /* Arguments: func, arg1, ... argN. */ + nargs = duk_get_top(ctx); + if (nargs < 1) { + return DUK_RET_TYPE_ERROR; /* missing func argument */ + } + + /* Create a new context. */ + duk_push_thread(); + new_ctx = duk_require_context(ctx, -1); + + /* Move arguments to the new context. Note that we need to extend + * the target stack allocation explicitly. + */ + duk_require_stack(new_ctx, nargs); + duk_xmove_top(ctx, new_ctx, nargs); + + /* Call the function; new_ctx is now: [ func arg1 ... argN ]. */ + duk_call(new_ctx, nargs - 1); + + /* Return the function call result by copying it to the original stack. */ + duk_xmove_top(new_ctx, ctx, 1); + return 1; + } + +tags: + - stack + - slice + +seealso: + - duk_xcopy_top + +introduced: 1.0.0 diff --git a/website/api2yaml.py b/website/api2yaml.py new file mode 100644 index 00000000..40d35cac --- /dev/null +++ b/website/api2yaml.py @@ -0,0 +1,107 @@ +#!/usr/bin/python +# +# One-time tool to convert from old custom API document format to YAML. +# +# $ for i in api/*.txt; do python api2yaml.py $i ${i%%.txt}.yaml; done +# + +import os +import sys + +def main(f_in, f_out, funcname): + parts = {} + curr = None + partname = None + + def quoted(line): + if line.strip() == '': + # Don't print whitespace indent for empty lines + f_out.write('\n') + else: + f_out.write(' %s\n' % line) + + for line in f_in: + if len(line) > 0 and line[-1] == '\n': + line = line[:-1] + if len(line) > 0 and line[0] == '=': + partname = line[1:] + curr = [] + parts[partname] = curr + continue + + curr.append(line) + + # Although the key order in the YAML output doesn't matter, + # we want it to be in a specific order to make manual edits + # nicer. Do this by emitting the YAML manually. + + #print(repr(parts)) + + for key in parts.keys(): + part = parts[key] + while len(part) > 0 and part[-1] == '': + part = part[:-1] + parts[key] = part + + for key in parts.keys(): + part = parts[key] + if len(part) == 0: + del parts[key] + + f_out.write('name: %s\n' % funcname) + + assert(parts.has_key('proto')) + + f_out.write('\n') + f_out.write('proto: |\n') + for p in parts['proto']: + quoted(p) + + if parts.has_key('stack'): + f_out.write('\n') + f_out.write('stack: |\n') + for p in parts['stack']: + quoted(p) + + assert(parts.has_key('summary')) + + f_out.write('\n') + f_out.write('summary: |\n') + for p in parts['summary']: + quoted(p) + + assert(parts.has_key('example')) + + f_out.write('\n') + f_out.write('example: |\n') + for p in parts['example']: + quoted(p) + + if parts.has_key('tags'): + f_out.write('\n') + f_out.write('tags:\n') + for p in parts['tags']: + f_out.write(' - %s\n' % p) + + if parts.has_key('seealso'): + f_out.write('\n') + f_out.write('seealso:\n') + for p in parts['seealso']: + f_out.write(' - %s\n' % p) + + if parts.has_key('introduced'): + assert(len(parts['introduced']) == 1) + f_out.write('\n') + f_out.write('introduced: %s\n' % parts['introduced'][0]) + + if parts.has_key('fixme'): + f_out.write('fixme: |\n') + for p in parts['fixme']: + quote(p) + +if __name__ == '__main__': + with open(sys.argv[1], 'rb') as f_in, \ + open(sys.argv[2], 'wb') as f_out: + fn = os.path.basename(sys.argv[1]) + fn_plain = os.path.splitext(fn)[0] + main(f_in, f_out, fn_plain) diff --git a/website/buildsite.py b/website/buildsite.py index 2905c1ce..d298e559 100644 --- a/website/buildsite.py +++ b/website/buildsite.py @@ -5,6 +5,7 @@ import os import sys +import traceback import time import datetime import shutil @@ -12,6 +13,8 @@ import re import tempfile import atexit import md5 +import json +import yaml from bs4 import BeautifulSoup, Tag colorize = True @@ -92,6 +95,13 @@ def stripNewline(x): return x[:-1] return x +def splitNewlineNoLastEmpty(x): + assert(x is not None) + res = x.split('\n') + if len(res) > 0 and res[-1] == '': + res = res[:-1] + return res + def validateAndParseHtml(data): # first parse as xml to get errors out ign_soup = BeautifulSoup(data, 'xml') @@ -186,36 +196,6 @@ def renderFancyStack(inp_line): return ' '.join(res) + '\n' # stack is a one-liner; spaces are for text browser rendering -def parseApiDoc(filename): - f = open(filename, 'rb') - parts = {} - state = None - for line in f.readlines(): - line = stripNewline(line) - if line.startswith('='): - state = line[1:] - elif state is not None: - if not parts.has_key(state): - parts[state] = [] - parts[state].append(line) - else: - if line != '': - raise Exception('unparsed non-empty line: %r' % line) - else: - # ignore - pass - f.close() - - # remove leading and trailing empty lines - for k in parts: - p = parts[k] - while len(p) > 0 and p[0] == '': - p.pop(0) - while len(p) > 0 and p[-1] == '': - p.pop() - - return parts - # C99: these are used if available type_repl_c99_32bit = [ ['duk_int_t', 'int' ], @@ -275,22 +255,22 @@ def substitutePrototypeTypes(line, repl): line = line.replace(t[0], t[1]) return line -def processApiDoc(parts, funcname, testrefs, used_tags): +def processApiDoc(doc, testrefs, used_tags): res = [] # the 'hidechar' span is to allow browser search without showing the char - res.append('

' % funcname) - res.append('.%s()' % (funcname, funcname)) - if floating_list_tags and parts.has_key('tags'): - p = sorted(parts['tags'], reverse=True) # reversed because floated to right (which reverses DOM order) + res.append('

' % doc['name']) + res.append('.%s()' % (doc['name'], doc['name'])) + if floating_list_tags and len(doc['tags']) > 0: + p = sorted(doc['tags'], reverse=True) # reversed because floated to right (which reverses DOM order) # For now, add the introduced version as a tag - if parts.has_key('introduced'): - p = [ parts['introduced'][0] ] + p - if parts.has_key('deprecated'): + if doc.has_key('introduced'): + p = [ doc['introduced'] ] + p + if doc.has_key('deprecated'): # XXX: must mark deprecation pass - if parts.has_key('removed'): + if doc.has_key('removed'): # XXX: must mark removal pass @@ -306,8 +286,8 @@ def processApiDoc(parts, funcname, testrefs, used_tags): res.append('
') - if parts.has_key('proto'): - p = parts['proto'] + if doc.has_key('proto'): + p = splitNewlineNoLastEmpty(doc['proto']) res.append('
') res.append('

Prototype

') alt_typing_c99 = [] @@ -334,10 +314,11 @@ def processApiDoc(parts, funcname, testrefs, used_tags): else: pass - if parts.has_key('stack'): - p = parts['stack'] + if doc.has_key('stack'): + p = splitNewlineNoLastEmpty(doc['stack']) res.append('
') res.append('

Stack

') + assert(len(p) > 0) for line in p: res.append('
' + \
 			           '%s' % htmlEscape(line) + \
@@ -351,8 +332,8 @@ def processApiDoc(parts, funcname, testrefs, used_tags):
 		res.append('
') # api-part res.append('') - if parts.has_key('summary'): - p = parts['summary'] + if doc.has_key('summary'): + p = splitNewlineNoLastEmpty(doc['summary']) res.append('
') res.append('

Summary

') @@ -376,8 +357,8 @@ def processApiDoc(parts, funcname, testrefs, used_tags): res.append('
') # api-part res.append('') - if parts.has_key('example'): - p = parts['example'] + if doc.has_key('example'): + p = splitNewlineNoLastEmpty(doc['example']) res.append('
') res.append('

Example

') res.append('
')
@@ -387,8 +368,8 @@ def processApiDoc(parts, funcname, testrefs, used_tags):
 		res.append('
') # api-part res.append('') - if parts.has_key('seealso'): - p = parts['seealso'] + if doc.has_key('seealso'): + p = doc['seealso'] res.append('
') res.append('

See also

') res.append('
    ') @@ -401,9 +382,9 @@ def processApiDoc(parts, funcname, testrefs, used_tags): if testcase_refs: res.append('
    ') res.append('

    Related test cases

    ') - if testrefs.has_key(funcname): + if testrefs.has_key(doc['name']): res.append('
      ') - for i in testrefs[funcname]: + for i in testrefs[doc['name']]: res.append('
    • %s
      • ' % htmlEscape(i)) res.append('
    ') else: @@ -411,15 +392,15 @@ def processApiDoc(parts, funcname, testrefs, used_tags): res.append('
    ') # api-part res.append('') - if not testrefs.has_key(funcname): + if not testrefs.has_key(doc['name']): res.append('
    This API call has no test cases.
    ') - if list_tags and parts.has_key('tags'): + if list_tags and len(doc['tags']) > 0: # FIXME: placeholder res.append('
    ') res.append('

    Tags

    ') res.append('

    ') - p = parts['tags'] + p = doc['tags'] for idx, val in enumerate(p): if idx > 0: res.append(' ') @@ -428,8 +409,8 @@ def processApiDoc(parts, funcname, testrefs, used_tags): res.append('

    ') # api-part res.append('') - if parts.has_key('fixme'): - p = parts['fixme'] + if doc.has_key('fixme'): + p = splitNewlineNoLastEmpty(doc['fixme']) res.append('
    ') for i in p: res.append(htmlEscape(i)) @@ -704,9 +685,7 @@ def createTagIndex(api_docs, used_tags): res.append('

    ' + htmlEscape(tag) + '

    ') res.append('
      ') for doc in api_docs: - if not doc['parts'].has_key('tags'): - continue - for i in doc['parts']['tags']: + for i in doc['tags']: if i != tag: continue res.append('
    • %s
      • ' % (htmlEscape(doc['name']), htmlEscape(doc['name']))) @@ -723,7 +702,7 @@ def generateApiDoc(apidocdir, apitestdir): tmpfiles = os.listdir(apidocdir) apifiles = [] for filename in tmpfiles: - if os.path.splitext(filename)[1] == '.txt': + if os.path.splitext(filename)[1] == '.yaml': apifiles.append(filename) apifiles.sort() #print(apifiles) @@ -743,19 +722,40 @@ def generateApiDoc(apidocdir, apitestdir): # scan api doc files used_tags = [] - api_docs = [] # [ { 'parts': xxx, 'name': xxx } ] + api_docs = [] # structure from YAML file directly for filename in apifiles: - parts = parseApiDoc(os.path.join(apidocdir, filename)) + apidoc = None + try: + with open(os.path.join(apidocdir, filename), 'rb') as f: + apidoc = yaml.safe_load(f) + if isinstance(apidoc, (str, unicode)): + apidoc = None + raise Exception('parsed as string') + except: + print 'WARNING: FAILED TO PARSE API DOC: ' + str(filename) + print traceback.format_exc() + pass + funcname = os.path.splitext(os.path.basename(filename))[0] - if parts.has_key('tags') and 'omit' in parts['tags']: - print 'Omit API doc: ' + str(funcname) - continue - if parts.has_key('tags'): - for i in parts['tags']: + + #print(json.dumps(apidoc, indent=4)) + + if apidoc is not None: + if not apidoc.has_key('tags'): + apidoc['tags'] = [] # ensures tags is present + apidoc['name'] = funcname # add funcname automatically + + if 'omit' in apidoc['tags']: + print 'Omit API doc: ' + str(funcname) + continue + + for i in apidoc['tags']: + assert(i is not None) if i not in used_tags: used_tags.append(i) - api_docs.append({ 'parts': parts, 'name': funcname }) + + api_docs.append(apidoc) used_tags.sort() @@ -805,11 +805,11 @@ def generateApiDoc(apidocdir, apitestdir): data = None try: - data = processApiDoc(doc['parts'], doc['name'], testrefs, used_tags) + data = processApiDoc(doc, testrefs, used_tags) res += data except: print repr(data) - print 'FAIL: ' + repr(filename) + print 'FAIL: ' + repr(doc['name']) raise print('used tags: ' + repr(used_tags))