From 5d2b25659d4da0517823df8f51915e3785fb2b3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zsolt=20Borb=C3=A9ly?= Date: Mon, 15 May 2017 08:42:18 +0200 Subject: [PATCH] Update the webpage (#1820) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add docs of extensions * Use `category` to distinct dropdown pages * Sort the documents alphabetical JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com --- 01.GETTING-STARTED.md | 1 + 02.API-REFERENCE.md | 240 +++++++++++++++++++- 03.API-EXAMPLE.md | 25 ++- 04.INTERNALS.md | 1 + 05.PORT-API.md | 28 +-- 06.REFERENCE-COUNTING.md | 1 + 07.DEBUGGER.md | 1 + 08.CODING-STANDARDS.md | 1 + 09.EXT-REFERENCE-ARG.md | 423 ++++++++++++++++++++++++++++++++++++ 10.EXT-REFERENCE-HANDLER.md | 189 ++++++++++++++++ _includes/header.html | 11 +- 11 files changed, 874 insertions(+), 47 deletions(-) create mode 100644 09.EXT-REFERENCE-ARG.md create mode 100644 10.EXT-REFERENCE-HANDLER.md diff --git a/01.GETTING-STARTED.md b/01.GETTING-STARTED.md index b771f1a30..ba0797fa6 100644 --- a/01.GETTING-STARTED.md +++ b/01.GETTING-STARTED.md @@ -1,6 +1,7 @@ --- layout: page title: Getting Started +category: navbar permalink: /getting-started/ --- diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 1dc2dcfda..88ee181d3 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -1,6 +1,7 @@ --- layout: page title: API Reference +category: navbar permalink: /api-reference/ --- @@ -45,6 +46,7 @@ Possible compile time enabled feature types: - JERRY_FEATURE_SNAPSHOT_SAVE - saving snapshot files - JERRY_FEATURE_SNAPSHOT_EXEC - executing snapshot files - JERRY_FEATURE_DEBUGGER - debugging + - JERRY_FEATURE_VM_EXEC_STOP - stopping ECMAScript execution ## jerry_char_t @@ -243,6 +245,28 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na void *user_data_p); ``` +## jerry_vm_exec_stop_callback_t + +**Summary** + +Callback which tells whether the ECMAScript execution should be stopped. +If it returns with undefined value the ECMAScript execution continues. +Otherwise the result is thrown by the engine (if the error flag is not +set for the returned value the engine automatically sets it). The +callback function might be called again even if it threw an error. +In this case the function must throw the same error again. + +**Prototype** + +```c +typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p); +``` + +**See also** + +- [jerry_set_vm_exec_stop_callback](#jerry_set_vm_exec_stop_callback) + + # General engine functions ## jerry_init @@ -1058,6 +1082,47 @@ jerry_value_is_object (const jerry_value_t value) - [jerry_release_value](#jerry_release_value) +## jerry_value_is_promise + +**Summary** + +Returns whether the given `jerry_value_t` is a promise value. + +*Note*: This API depends on the ES2015-subset profile. + +**Prototype** + +```c +bool +jerry_value_is_promise (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a promise + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_promise (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) + + ## jerry_value_is_string **Summary** @@ -1966,6 +2031,64 @@ jerry_value_to_string (const jerry_value_t value); - [jerry_value_to_primitive](#jerry_value_to_primitive) +# Functions for promise objects + +These APIs all depends on the ES2015-subset profile. + +## jerry_resolve_or_reject_promise + +**Summary** + +Resolve or reject the promise with an argument. + +**Prototype** + +```c +jerry_value_t +jerry_resolve_or_reject_promise (jerry_value_t promise, + jerry_value_t argument, + bool is_resolve) +``` + +- `promise` - the promise value +- `argument` - the argument for resolve or reject +- `is_resolve` - whether the promise should be resolved or rejected +- return value + - undefined jerry value - resolve or reject successed + - jerry value with error flag - otherwise + +**Example** + +```c +{ + jerry_value_t promise = ... // acquire/create a promise object. + + ... + + bool is_resolve = ... // whether the promise should be resolved or rejected + jerry_value_t argument = ... // prepare the argumnent for the resolve or reject. + + jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise, + argument, + is_resolve); + + if (jerry_value_has_error_flag (is_ok)) + { + // handle the error. + } + + jerry_release_value (is_ok); + jerry_release_value (argument); + jerry_release_value (promise); +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) +- [jerry_value_has_error_flag](#jerry_value_has_error_flag) + + # Acquire and release API values ## jerry_acquire_value @@ -2411,6 +2534,41 @@ jerry_create_object (void); - [jerry_release_value](#jerry_release_value) +## jerry_create_promise + +**Summary** + +Create an empty promise object which can be resolved or rejected later +by calling jerry_resolve_or_reject_promise. + +*Note*: This API depends on the ES2015-subset profile. + +**Prototype** + +```c +jerry_value_t +jerry_create_promise (void) +``` + +- return value - value of the newly created promise + +**Example** + +```c +{ + jerry_value_t p = jerry_create_promise (); + + ...// usage of the promise + + jerry_release_value (p); +} + +**See also** + +- [jerry_resolve_or_reject_promise](#jerry_resolve_or_reject_promise) +- [jerry_release_value](#jerry_release_value) + + ## jerry_create_string **Summary** @@ -3514,7 +3672,7 @@ static const jerry_object_native_info_t native_obj_type_info = { // The type of this's native pointer matches what is expected. // Only now is it safe to cast to native_obj_t * and dereference the - // pointer: + // pointer: native_obj_t *native_obj = native_p; native_obj->bar = ...; // Safe to access now! } @@ -3568,7 +3726,7 @@ jerry_set_object_native_pointer (const jerry_value_t obj_val, **Example** See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) for a -best-practice example. +best-practice example. **See also** @@ -3905,3 +4063,81 @@ jerry_parse_and_save_literals (const jerry_char_t *source_p, - [jerry_init](#jerry_init) - [jerry_cleanup](#jerry_cleanup) - [jerry_register_magic_strings](#jerry_register_magic_strings) + + +# Miscellaneous functions + +## jerry_set_vm_exec_stop_callback + +**Summary** + +When JERRY_FEATURE_VM_EXEC_STOP is enabled a callback function can be +specified by this function. This callback is periodically called when +JerryScript executes an ECMAScript program. + +If the callback returns with undefined value the ECMAScript execution +continues. Otherwise the result is thrown by the engine (if the error +flag is not set for the returned value the engine automatically sets +it). The callback function might be called again even if it threw +an error. In this case the function must throw the same error again. + +To reduce the CPU overhead of constantly checking the termination +condition the callback is called when a backward jump is executed +or an exception is caught. Setting the `frequency` to a greater +than `1` value reduces this overhead further. If its value is N +only every Nth event (backward jump, etc.) trigger the next check. + + +**Prototype** + +```c +void +jerry_set_vm_exec_stop_callback (jerry_vm_exec_stop_callback_t stop_cb, + void *user_p, + uint32_t frequency); +``` + +- `stop_cb` - periodically called callback (passing NULL disables this feature) +- `user_p` - user pointer passed to the `stop_cb` function +- `frequency` - frequency of calling the `stop_cb` function + +**Example** + +```c +static jerry_value_t +vm_exec_stop_callback (void *user_p) +{ + static int countdown = 10; + + while (countdown > 0) + { + countdown--; + return jerry_create_undefined (); + } + + // The error flag is added automatically. + return jerry_create_string ((const jerry_char_t *) "Abort script"); +} + +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_set_vm_exec_stop_callback (vm_exec_stop_callback, &countdown, 16); + + // Inifinte loop. + const char *src_p = "while(true) {}"; + + jerry_value_t src = jerry_parse ((jerry_char_t *) src_p, strlen (src_p), false); + jerry_release_value (jerry_run (src)); + jerry_release_value (src); + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_parse](#jerry_parse) +- [jerry_run](#jerry_run) +- [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t) diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md index 30a35bca3..217295848 100644 --- a/03.API-EXAMPLE.md +++ b/03.API-EXAMPLE.md @@ -1,6 +1,7 @@ --- layout: page title: API Examples +category: navbar permalink: /api-example/ --- @@ -182,38 +183,38 @@ created by API functions has the error flag set. The following example function will output a JavaScript value: ```c +#include #include #include #include "jerryscript.h" -#include "jerryscript-port.h" static void print_value (const jerry_value_t value) { if (jerry_value_is_undefined (value)) { - jerry_port_console ("undefined"); + printf ("undefined"); } else if (jerry_value_is_null (value)) { - jerry_port_console ("null"); + printf ("null"); } else if (jerry_value_is_boolean (value)) { if (jerry_get_boolean_value (value)) { - jerry_port_console ("true"); + printf ("true"); } else { - jerry_port_console ("false"); + printf ("false"); } } /* Float value */ else if (jerry_value_is_number (value)) { - jerry_port_console ("number"); + printf ("number"); } /* String value */ else if (jerry_value_is_string (value)) @@ -225,15 +226,15 @@ print_value (const jerry_value_t value) jerry_string_to_char_buffer (value, str_buf_p, req_sz); str_buf_p[req_sz] = '\0'; - jerry_port_console ("%s", (const char *) str_buf_p); + printf ("%s", (const char *) str_buf_p); } /* Object reference */ else if (jerry_value_is_object (value)) { - jerry_port_console ("[JS object]"); + printf ("[JS object]"); } - jerry_port_console ("\n"); + printf ("\n"); } ``` @@ -252,11 +253,11 @@ Shell operation can be described with the following loop: - loop. ```c +#include #include #include #include "jerryscript.h" -#include "jerryscript-port.h" static void print_value (const jerry_value_t); @@ -274,7 +275,7 @@ main (int argc, char *argv[]) char *cmd_tail = cmd; size_t len = 0; - jerry_port_console ("> "); + printf ("> "); /* Read next command */ while (true) @@ -311,7 +312,7 @@ main (int argc, char *argv[]) { /* Evaluated JS code thrown an exception * and didn't handle it with try-catch-finally */ - jerry_port_console ("Unhandled JS exception occured: "); + printf ("Unhandled JS exception occured: "); } print_value (ret_val); diff --git a/04.INTERNALS.md b/04.INTERNALS.md index ed65274ff..2199e6a98 100644 --- a/04.INTERNALS.md +++ b/04.INTERNALS.md @@ -1,6 +1,7 @@ --- layout: page title: Internals +category: documents permalink: /internals/ --- diff --git a/05.PORT-API.md b/05.PORT-API.md index 4af4c3212..8e423e0b2 100644 --- a/05.PORT-API.md +++ b/05.PORT-API.md @@ -1,6 +1,7 @@ --- layout: page title: Port API +category: documents permalink: /port-api/ --- @@ -44,20 +45,6 @@ typedef enum These are the only I/O functions jerry calls. ```c -/** - * Print a string to the console. The function should implement a printf-like - * interface, where the first argument specifies a format string on how to - * stringify the rest of the parameter list. - * - * This function is only called with strings coming from the executed ECMAScript - * wanting to print something as the result of its normal operation. - * - * It should be the port that decides what a "console" is. - * - * Example: a libc-based port may implement this with vprintf(). - */ -void jerry_port_console (const char *fmt, ...); - /** * Jerry log levels. The levels are in severity order * where the most serious levels come first. @@ -142,19 +129,6 @@ void jerry_port_fatal (jerry_fatal_code_t code) #include #include "jerryscript-port.h" -/** - * Provide console message implementation for the engine. - */ -void -jerry_port_console (const char *format, /**< format string */ - ...) /**< parameters */ -{ - va_list args; - va_start (args, format); - vfprintf (stdout, format, args); - va_end (args); -} /* jerry_port_console */ - /** * Provide log message implementation for the engine. * diff --git a/06.REFERENCE-COUNTING.md b/06.REFERENCE-COUNTING.md index 2b607820d..a80e5e049 100644 --- a/06.REFERENCE-COUNTING.md +++ b/06.REFERENCE-COUNTING.md @@ -1,6 +1,7 @@ --- layout: page title: Reference Counting +category: documents permalink: /reference-counting/ --- diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md index c8ad09d0f..6adcea377 100644 --- a/07.DEBUGGER.md +++ b/07.DEBUGGER.md @@ -1,6 +1,7 @@ --- layout: page title: Debugger +category: documents permalink: /debugger/ --- diff --git a/08.CODING-STANDARDS.md b/08.CODING-STANDARDS.md index 7cb336ee7..f20064d04 100644 --- a/08.CODING-STANDARDS.md +++ b/08.CODING-STANDARDS.md @@ -1,6 +1,7 @@ --- layout: page title: Coding Standards +category: documents permalink: /coding-standards/ --- diff --git a/09.EXT-REFERENCE-ARG.md b/09.EXT-REFERENCE-ARG.md new file mode 100644 index 000000000..49aaecb08 --- /dev/null +++ b/09.EXT-REFERENCE-ARG.md @@ -0,0 +1,423 @@ +--- +layout: page +title: 'Extension API: Argument Validation' +category: documents +permalink: /ext-reference-arg/ +--- + +* toc +{:toc} + +# jerryx_arg types + +## jerryx_arg_t + +**Summary** + +The structure defining a single validation/transformation step. + +*Note*: For commonly used validators, `arg.h` provides helpers to create the `jerryx_arg_t`s. +For example, `jerryx_arg_number ()`, `jerryx_arg_boolean ()`, etc. + +**Prototype** + +```c +typedef struct +{ + /** the transform function */ + jerryx_arg_transform_func_t func; + /** pointer to destination where func should store the result */ + void *dest; + /** extra information, specific to func */ + uintptr_t extra_info; +} jerryx_arg_t; +``` + +**See also** + +- [jerryx_arg_number](#jerryx_arg_number) +- [jerryx_arg_boolean](#jerryx_arg_boolean) +- [jerryx_arg_string](#jerryx_arg_string) +- [jerryx_arg_function](#jerryx_arg_function) +- [jerryx_arg_native_pointer](#jerryx_arg_native_pointer) +- [jerryx_arg_ignore](#jerryx_arg_ignore) + +## jerryx_arg_transform_func_t + +**Summary** + +Signature of the transform function. + +Users can create custom transformations by implementing a transform function +and using `jerryx_arg_custom ()`. + +The function is expected to return `undefined` if it ran successfully or +return an `Error` in case it failed. The function can use the iterator and the +helpers `jerryx_arg_js_iterator_pop ()` and `jerryx_arg_js_iterator_peek ()` to +get the next input value. + +*Note*: A transform function is allowed to consume any number of input values! +This enables complex validation like handling different JS function signatures, +mapping multiple input arguments to a C struct, etc. + +The function is expected to store the result of +a successful transformation into `c_arg_p->dest`. In case the validation did +not pass, the transform should not modify `c_arg_p->dest`. + +Additional parameters can be provided to the function through `c_arg_p->extra_info`. + +**Prototype** + +```c +typedef jerry_value_t (*jerryx_arg_transform_func_t) (jerryx_arg_js_iterator_t *js_arg_iter_p, + const jerryx_arg_t *c_arg_p); +``` + +**See also** + +- [jerryx_arg_custom](#jerryx_arg_custom) +- [jerryx_arg_js_iterator_pop](#jerryx_arg_js_iterator_pop) +- [jerryx_arg_js_iterator_peek](#jerryx_arg_js_iterator_peek) + + +## jerryx_arg_coerce_t + +Enum that indicates whether an argument is allowed to be coerced into the expected JS type. + + - JERRYX_ARG_COERCE - the transform will invoke toNumber, toBoolean, toString, etc. + - JERRYX_ARG_NO_COERCE - the type coercion is not allowed. The transform will fail if the type does not match the expectation. + +**See also** + +- [jerryx_arg_number](#jerryx_arg_number) +- [jerryx_arg_boolean](#jerryx_arg_boolean) +- [jerryx_arg_string](#jerryx_arg_string) + +## jerryx_arg_optional_t + +Enum that indicates whether an argument is optional or required. + + - JERRYX_ARG_OPTIONAL - The argument is optional. If the argument is `undefined` the transform is successful and `c_arg_p->dest` remains untouched. + - JERRYX_ARG_REQUIRED - The argument is required. If the argument is `undefined` the transform will fail and `c_arg_p->dest` remains untouched. + +**See also** + +- [jerryx_arg_number](#jerryx_arg_number) +- [jerryx_arg_boolean](#jerryx_arg_boolean) +- [jerryx_arg_string](#jerryx_arg_string) +- [jerryx_arg_function](#jerryx_arg_function) +- [jerryx_arg_native_pointer](#jerryx_arg_native_pointer) + +# Main functions + +## jerryx_arg_transform_this_and_args + +**Summary** + +Validate the this value and the JS arguments, and assign them to the native arguments. +This function is useful to perform input validation inside external function handlers (see `jerry_external_handler_t`). + +**Prototype** + +```c +jerry_value_t +jerryx_arg_transform_this_and_args (const jerry_value_t this_val, + const jerry_value_t *js_arg_p, + const jerry_length_t js_arg_cnt, + const jerryx_arg_t *c_arg_p, + jerry_length_t c_arg_cnt) +``` + + - `this_val` - `this` value. Note this is processed as the first value, before the array of arguments. + - `js_arg_p` - points to the array with JS arguments. + - `js_arg_cnt` - the count of the `js_arg_p` array. + - `c_arg_p` - points to the array of validation/transformation steps + - `c_arg_cnt` - the count of the `c_arg_p` array. + - return value - a `jerry_value_t` representing `undefined` if all validators passed or an `Error` if a validator failed. + +**Example** + +```c +// JS signature: function (requiredBool, requiredString, optionalNumber) +static jerry_value_t my_external_handler (const jerry_value_t function_obj, + const jerry_value_t this_val, + const jerry_value_t args_p[], + const jerry_length_t args_count) +{ + bool required_bool; + char required_str[16]; + double optional_num = 1234.567; // default value + + // "mapping" defines the steps to transform input arguments to C variables: + const jerryx_arg_t mapping[] = + { + // `this` is the first value. No checking needed on `this` for this function. + jerryx_arg_ignore (), + + jerryx_arg_boolean (&required_bool, JERRYX_ARG_NO_COERCE, JERRYX_ARG_REQUIRED), + jerryx_arg_string (&required_str, sizeof (required_str), JERRYX_ARG_NO_COERCE, JERRYX_ARG_REQUIRED), + jerryx_arg_number (&optional_num, JERRYX_ARG_NO_COERCE, JERRYX_ARG_OPTIONAL), + }; + + // Validate and transform: + const jerry_value_t rv = jerryx_arg_transform_this_and_args (this_val, + args_p, + args_count, + mapping, + ARRAY_LENGTH (mapping)); + + if (jerry_value_has_error_flag (rv)) + { + // Handle error + return rv; + } + + // Validated and tranformed successfully! + // required_bool, required_str and optional_num can now be used. + // ... +} +``` + +**See also** + +- [jerryx_arg_ignore](#jerryx_arg_ignore) +- [jerryx_arg_number](#jerryx_arg_number) +- [jerryx_arg_boolean](#jerryx_arg_boolean) +- [jerryx_arg_string](#jerryx_arg_string) +- [jerryx_arg_function](#jerryx_arg_function) +- [jerryx_arg_native_pointer](#jerryx_arg_native_pointer) +- [jerryx_arg_custom](#jerryx_arg_custom) + + +## jerryx_arg_transform_args + +**Summary** + +Validate an array of `jerry_value_t` and assign them to the native arguments. + +**Prototype** + +```c +jerry_value_t +jerryx_arg_transform_args (const jerry_value_t *js_arg_p, + const jerry_length_t js_arg_cnt, + const jerryx_arg_t *c_arg_p, + jerry_length_t c_arg_cnt) +``` + + - `js_arg_p` - points to the array with JS arguments. + - `js_arg_cnt` - the count of the `js_arg_p` array. + - `c_arg_p` - points to the array of validation/transformation steps + - `c_arg_cnt` - the count of the `c_arg_p` array. + - return value - a `jerry_value_t` representing `undefined` if all validators passed or an `Error` if a validator failed. + +**See also** + +- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) + + +# Helpers for commonly used validations + +## jerryx_arg_number + +**Summary** + +Create a validation/transformation step (`jerryx_arg_t`) that expects to consume +one `number` JS argument and stores it into a C `double`. + +**Prototype** + +```c +static inline jerryx_arg_t +jerryx_arg_number (double *dest, + jerryx_arg_coerce_t coerce_flag, + jerryx_arg_optional_t opt_flag) +``` + + - return value - the created `jerryx_arg_t` instance. + - `dest` - pointer to the `double` where the result should be stored. + - `coerce_flag` - whether type coercion is allowed. + - `opt_flag` - whether the argument is optional. + +**See also** + +- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) + +## jerryx_arg_boolean + +**Summary** + +Create a validation/transformation step (`jerryx_arg_t`) that expects to +consume one `boolean` JS argument and stores it into a C `bool`. + +**Prototype** + +```c +static inline jerryx_arg_t +jerryx_arg_boolean (bool *dest, + jerryx_arg_coerce_t coerce_flag, + jerryx_arg_optional_t opt_flag) +``` + - return value - the created `jerryx_arg_t` instance. + - `dest` - pointer to the `bool` where the result should be stored. + - `coerce_flag` - whether type coercion is allowed. + - `opt_flag` - whether the argument is optional. + +**See also** + +- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) + + +## jerryx_arg_string + +**Summary** + +Create a validation/transformation step (`jerryx_arg_t`) that expects to +consume one `string` JS argument and stores it into a C `char` array. + +**Prototype** + +```c +static inline jerryx_arg_t +jerryx_arg_string (char *dest, + uint32_t size, + jerryx_arg_coerce_t coerce_flag, + jerryx_arg_optional_t opt_flag) +``` + + - return value - the created `jerryx_arg_t` instance. + - `dest` - pointer to the native char array where the result should be stored. + - `size` - the size of native char array. + - `coerce_flag` - whether type coercion is allowed. + - `opt_flag` - whether the argument is optional. + +**See also** + +- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) + + +## jerryx_arg_function + +**Summary** + +Create a validation/transformation step (`jerryx_arg_t`) that expects to +consume one `function` JS argument and stores it into a C `jerry_value_t`. + +**Prototype** + +```c +static inline jerryx_arg_t +jerryx_arg_function (jerry_value_t *dest, + jerryx_arg_optional_t opt_flag) + +``` + - return value - the created `jerryx_arg_t` instance. + - `dest` - pointer to the `jerry_value_t` where the result should be stored. + - `opt_flag` - whether the argument is optional. + +**See also** + +- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) + +## jerryx_arg_native_pointer + +**Summary** + +Create a validation/transformation step (`jerryx_arg_t`) that expects to +consume one `Object` JS argument that is 'backed' with a native pointer with +a given type info. In case the native pointer info matches, the transform +will succeed and the object's native pointer will be assigned to `*dest`. + +**Prototype** + +```c +static inline jerryx_arg_t +jerryx_arg_native_pointer (void **dest, + const jerry_object_native_info_t *info_p, + jerryx_arg_optional_t opt_flag) +``` + - return value - the created `jerryx_arg_t` instance. + - `dest` - pointer to where the resulting native pointer should be stored. + - `info_p` - expected the type info. + - `opt_flag` - whether the argument is optional. + +**See also** + +- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) + + +# Functions to create custom validations + +## jerryx_arg_custom + +**Summary** + +Create a jerryx_arg_t instance with custom transform. + +**Prototype** + +```c +static inline jerryx_arg_t +jerryx_arg_custom (void *dest, + uintptr_t extra_info, + jerryx_arg_transform_func_t func) + +``` + - return value - the created `jerryx_arg_t` instance. + - `dest` - pointer to the native argument where the result should be stored. + - `extra_info` - the extra parameter data, specific to the transform function. + - `func` - the custom transform function. + +**See also** + +- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) + + + +## jerryx_arg_js_iterator_pop + +**Summary** + +Pop the current `jerry_value_t` argument from the iterator. +It will change the `js_arg_idx` and `js_arg_p` value in the iterator. + +**Prototype** + +```c +jerry_value_t +jerryx_arg_js_iterator_pop (jerryx_arg_js_iterator_t *js_arg_iter_p) +``` + - return value - the `jerry_value_t` argument that was popped. + - `js_arg_iter_p` - the JS arg iterator from which to pop. + +## jerryx_arg_js_iterator_peek + +**Summary** + +Get the current JS argument from the iterator, without moving the iterator forward. +*Note:* Unlike `jerryx_arg_js_iterator_pop ()`, it will not change `js_arg_idx` and +`js_arg_p` value in the iterator. + +**Prototype** + +```c +jerry_value_t +jerryx_arg_js_iterator_peek (jerryx_arg_js_iterator_t *js_arg_iter_p) +``` + - return value - the current `jerry_value_t` argument. + - `js_arg_iter_p` - the JS arg iterator from which to peek. + +## jerryx_arg_js_iterator_index + +**Summary** + +Get the index of the current JS argument from the iterator. + +**Prototype** + +```c +jerry_length_t +jerryx_arg_js_iterator_index (jerryx_arg_js_iterator_t *js_arg_iter_p) +``` + - return value - the index of current JS argument. + - `js_arg_iter_p` - the JS arg iterator from which to peek. diff --git a/10.EXT-REFERENCE-HANDLER.md b/10.EXT-REFERENCE-HANDLER.md new file mode 100644 index 000000000..61c3b2e66 --- /dev/null +++ b/10.EXT-REFERENCE-HANDLER.md @@ -0,0 +1,189 @@ +--- +layout: page +title: 'Extension API: External Function Handlers' +category: documents +permalink: /ext-reference-handler/ +--- + +* toc +{:toc} + +# Common external function handlers + +## jerryx_handler_assert + +**Summary** + +Assert for scripts. The routine calls `jerry_port_fatal` on assertion failure. + +**Prototype** + +```c +jerry_value_t +jerryx_handler_assert (const jerry_value_t func_obj_val, const jerry_value_t this_p, + const jerry_value_t args_p[], const jerry_length_t args_cnt); +``` + +- `func_obj_val` - the function object that was called (unused). +- `this_p` - the `this` value of the call (unused). +- `args_p` - the array of function arguments. +- `args_cnt` - the number of function arguments. +- return value - `jerry_value_t` representing boolean true, if only one argument + was passed and that argument was a boolean true. Note that the function does + not return otherwise. + +**See also** + +- [jerryx_handler_register_global](#jerryx_handler_register_global) + + +## jerryx_handler_gc + +**Summary** + +Expose garbage collector to scripts. + +**Prototype** + +```c +jerry_value_t +jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p, + const jerry_value_t args_p[], const jerry_length_t args_cnt); +``` + +- `func_obj_val` - the function object that was called (unused). +- `this_p` - the `this` value of the call (unused). +- `args_p` - the array of function arguments (unused). +- `args_cnt` - the number of function arguments (unused). +- return value - `jerry_value_t` representing `undefined`. + +**See also** + +- [jerryx_handler_register_global](#jerryx_handler_register_global) + + +## jerryx_handler_print + +**Summary** + +Provide a `print` implementation for scripts. The routine converts all of its +arguments to strings and outputs them char-by-char using +`jerryx_port_handler_print_char`. The NUL character is output as "\u0000", +other characters are output bytewise. + +*Note*: This implementation does not use standard C `printf` to print its +output. This allows more flexibility but also extends the core JerryScript +engine port API. Applications that want to use `jerryx_handler_print` must +ensure that their port implementation also provides +`jerryx_port_handler_print_char`. + +**Prototype** + +```c +jerry_value_t +jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this_p, + const jerry_value_t args_p[], const jerry_length_t args_cnt); +``` + +- `func_obj_val` - the function object that was called (unused). +- `this_p` - the `this` value of the call (unused). +- `args_p` - the array of function arguments. +- `args_cnt` - the number of function arguments. +- return value - `jerry_value_t` representing `undefined` if all arguments could + be converted to strings, an `Error` otherwise. + +**See also** + +- [jerryx_handler_register_global](#jerryx_handler_register_global) +- [jerryx_port_handler_print_char](#jerryx_port_handler_print_char) + + +# Handler registration helper + +## jerryx_handler_register_global + +**Summary** + +Register a JavaScript function in the global object. + +*Note*: Returned value must be freed with `jerry_release_value`, when it is no +longer needed. + +**Prototype** + +```c +jerry_value_t +jerryx_handler_register_global (const jerry_char_t *name_p, + jerry_external_handler_t handler_p); +``` + +- `name_p` - the name of the function to be registered. +- `handler_p` - the address of the external function handler. +- return value - `jerry_value_t` representing boolean true, if the operation was + successful, an `Error` otherwise. + +**Example** + +```c +#include "jerryscript.h" +#include "jerryscript-ext/handler.h" + +static const struct { + const char *name_p; + jerry_external_handler_t handler_p; +} common_functions[] = +{ + { "assert", jerryx_handler_assert }, + { "gc", jerryx_handler_gc }, + { "print", jerryx_handler_print }, + { NULL, NULL } +}; + +static void register_common_functions () +{ + jerry_value_t ret = jerry_create_undefined (); + + for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_has_error_flag (ret); i++) + { + ret = jerryx_handler_register_global ((const jerry_char_t *) common_functions[i].name_p, + common_functions[i].handler_p); + } + + return ret; +} +``` + + +# Port API extension + +## jerryx_port_handler_print_char + +**Summary** + +Print a single character. + +**Prototype** + +```c +void +jerryx_port_handler_print_char (char c); +``` + +- `c` - the character to print. + +**Example** + +```c +/** + * Print a character to stdout with printf. + */ +void +jerryx_port_handler_print_char (char c) +{ + printf ("%c", c); +} /* jerryx_port_handler_print_char */ +``` + +**See also** + +- [jerryx_handler_print](#jerryx_handler_print) diff --git a/_includes/header.html b/_includes/header.html index 68f7d9a84..bd8c9dd77 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -21,7 +21,7 @@
    {% for p in site.pages %} {% if p.title %} - {% if p.url != "/coding-standards/" and p.url != "/debugger/" and p.url != "/internals/" and p.url != "/port-api/" and p.url != "/reference-counting/" %} + {% if p.category == "navbar" %} {% if page.url == p.url %}
  • {{ p.title }}
    • {% else %} @@ -32,11 +32,10 @@ {% endfor %}
  • Documents
      - {% for p in site.pages %} - {% if p.title %} - {% if p.url == "/coding-standards/" or p.url == "/debugger/" or p.url == "/internals/" or p.url == "/port-api/" or p.url == "/reference-counting/" %} -
    • {{ p.title }}
      • - {% endif %} + {% assign doclist = site.pages | sort: 'title' %} + {% for p in doclist %} + {% if p.title and p.category == "documents" %} +
    • {{ p.title }}
      • {% endif %} {% endfor %}