From f97f82f7bea9408cbd73cd8640ceb664c14282dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A1szl=C3=B3=20Lang=C3=B3?= Date: Thu, 17 May 2018 07:40:49 +0200 Subject: [PATCH] Update the webpage (#2334) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit JerryScript-DCO-1.0-Signed-off-by: László Langó llango.u-szeged@partner.samsung.com --- 01.GETTING-STARTED.md | 2 + 02.API-REFERENCE.md | 175 ++++++++++++++++++------------------ 03.API-EXAMPLE.md | 6 +- 05.PORT-API.md | 36 ++++++-- 06.REFERENCE-COUNTING.md | 4 +- 07.DEBUGGER.md | 2 +- 09.EXT-REFERENCE-ARG.md | 6 +- 10.EXT-REFERENCE-HANDLER.md | 2 +- 12.EXT-REFERENCE-MODULE.md | 27 +++++- 9 files changed, 152 insertions(+), 108 deletions(-) diff --git a/01.GETTING-STARTED.md b/01.GETTING-STARTED.md index ba0797fa6..ae2a15c5d 100644 --- a/01.GETTING-STARTED.md +++ b/01.GETTING-STARTED.md @@ -61,6 +61,8 @@ python tools/build.py --cmake-param=CMAKE_PARAM python tools/build.py --profile=es5.1|es2015-subset|minimal ``` +See also the related [README.md](https://github.com/jerryscript-project/jerryscript/blob/master/jerry-core/profiles/README.md). + **Use (jerry, compiler-default, external) libc** The default libc is jerry-libc, but you can use compiler-default libc or an external libc: diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 064dfd51d..cad788d01 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -957,7 +957,7 @@ main (void) /* Setup Global scope code */ jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS); - if (!jerry_value_has_error_flag (parsed_code)) + if (!jerry_value_is_error (parsed_code)) { /* Execute the parsed source code in the Global scope */ jerry_value_t ret_value = jerry_run (parsed_code); @@ -1099,6 +1099,45 @@ jerry_get_global_object (void); Functions to check the type of an API value ([jerry_value_t](#jerry_value_t)). +## jerry_value_is_abort + +**Summary** + +Returns whether the given `jerry_value_t` has the error and abort value set. + +**Prototype** + +```c +bool +jerry_value_is_abort (const jerry_value_t value); +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` has the error and abort value set + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_abort (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_t](#jerry_value_t) +- [jerry_value_is_error](#jerry_value_is_error) + ## jerry_value_is_array **Summary** @@ -1254,6 +1293,44 @@ jerry_value_is_constructor (const jerry_value_t value) - [jerry_release_value](#jerry_release_value) +## jerry_value_is_error + +**Summary** + +Returns whether the given `jerry_value_t` is error value. + +**Prototype** + +```c +bool +jerry_value_is_error (const jerry_value_t value); +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is error value. + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_error (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_t](#jerry_value_t) +- [jerry_value_is_abort](#jerry_value_is_abort) ## jerry_value_is_function @@ -1651,7 +1728,7 @@ If a non-error object is used as the input for the function the method will return `JERRY_ERROR_NONE` indicating that the value was not an Error object. However it is still possible that the value contains error semantics. To correctly detect if a value have error use the -[jerry_value_has_error_flag](#jerry_value_has_error_flag) method. +[jerry_value_is_error](#jerry_value_is_error) method. **Prototype** @@ -1682,87 +1759,7 @@ jerry_get_error_type (const jerry_value_t value); **See also** - [jerry_create_error](#jerry_create_error) -- [jerry_value_has_error_flag](#jerry_value_has_error_flag) - -## jerry_value_has_error_flag - -**Summary** - -Returns whether the given `jerry_value_t` has the error flag set. - -**Prototype** - -```c -bool -jerry_value_has_error_flag (const jerry_value_t value); -``` - -- `value` - api value -- return value - - true, if the given `jerry_value_t` has the error flag set - - false, otherwise - -**Example** - -```c -{ - jerry_value_t value; - ... // create or acquire value - - if (jerry_value_has_error_flag (value)) - { - ... - } - - jerry_release_value (value); -} -``` - -**See also** - -- [jerry_value_t](#jerry_value_t) -- [jerry_value_has_abort_flag](#jerry_value_has_abort_flag) - - -## jerry_value_has_abort_flag - -**Summary** - -Returns whether the given `jerry_value_t` has the error and abort flags set. - -**Prototype** - -```c -bool -jerry_value_has_abort_flag (const jerry_value_t value); -``` - -- `value` - api value -- return value - - true, if the given `jerry_value_t` has the error and abort flags set - - false, otherwise - -**Example** - -```c -{ - jerry_value_t value; - ... // create or acquire value - - if (jerry_value_has_abort_flag (value)) - { - ... - } - - jerry_release_value (value); -} -``` - -**See also** - -- [jerry_value_t](#jerry_value_t) -- [jerry_value_has_error_flag](#jerry_value_has_error_flag) - +- [jerry_value_is_error](#jerry_value_is_error) ## jerry_value_clear_error_flag @@ -2657,7 +2654,7 @@ jerry_resolve_or_reject_promise (jerry_value_t promise, argument, is_resolve); - if (jerry_value_has_error_flag (is_ok)) + if (jerry_value_is_error (is_ok)) { // handle the error. } @@ -2671,7 +2668,7 @@ jerry_resolve_or_reject_promise (jerry_value_t promise, **See also** - [jerry_release_value](#jerry_release_value) -- [jerry_value_has_error_flag](#jerry_value_has_error_flag) +- [jerry_value_is_error](#jerry_value_is_error) # Acquire and release API values @@ -2945,7 +2942,7 @@ jerry_create_error (jerry_error_t error_type, **See also** -- [jerry_value_has_error_flag](#jerry_value_has_error_flag) +- [jerry_value_is_error](#jerry_value_is_error) - [jerry_value_clear_error_flag](#jerry_value_clear_error_flag) - [jerry_value_set_error_flag](#jerry_value_set_error_flag) @@ -4184,7 +4181,7 @@ jerry_call_function (const jerry_value_t func_obj_val, jerry_value_t this_val = jerry_create_undefined (); jerry_value_t ret_val = jerry_call_function (val, this_val, NULL, 0); - if (!jerry_value_has_error_flag (ret_val)) + if (!jerry_value_is_error (ret_val)) { ... // handle return value } @@ -4239,7 +4236,7 @@ jerry_construct_object (const jerry_value_t func_obj_val, { jerry_value_t ret_val = jerry_construct_object (val, NULL, 0); - if (!jerry_value_has_error_flag (ret_val)) + if (!jerry_value_is_error (ret_val)) { ... // handle return value } @@ -4710,7 +4707,7 @@ find_my_object(const jerry_value_t candidate, { find_my_object_info_t *info_p = (find_my_object_info_t *) user_data_p; jerry_value_t has_property = jerry_object_has_property (candidate, info_p->property_name); - bool keep_searching = (jerry_value_has_error_flag (has_property) || !jerry_get_boolean_value ()); + bool keep_searching = (jerry_value_is_error (has_property) || !jerry_get_boolean_value ()); if (!keep_searching) { /* We found it, so we acquire the value and record it. */ diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md index 373e6ec1d..f87a428cc 100644 --- a/03.API-EXAMPLE.md +++ b/03.API-EXAMPLE.md @@ -67,7 +67,7 @@ main (void) /* Setup Global scope code */ jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS); - if (!jerry_value_has_error_flag (parsed_code)) + if (!jerry_value_is_error (parsed_code)) { /* Execute the parsed source code in the Global scope */ jerry_value_t ret_value = jerry_run (parsed_code); @@ -335,7 +335,7 @@ main (void) false); /* If command evaluated successfully, print value, returned by eval */ - if (jerry_value_has_error_flag (ret_val)) + if (jerry_value_is_error (ret_val)) { /* Evaluated JS code thrown an exception * and didn't handle it with try-catch-finally */ @@ -472,7 +472,7 @@ add_handler (const jerry_value_t func_value, /**< function object */ jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "x"); jerry_value_t x_val = jerry_get_property (this_val, prop_name); - if (!jerry_value_has_error_flag (x_val)) + if (!jerry_value_is_error (x_val)) { /* Convert Jerry API values to double */ double x = jerry_get_number_value (x_val); diff --git a/05.PORT-API.md b/05.PORT-API.md index 2c0728586..d152a57b1 100644 --- a/05.PORT-API.md +++ b/05.PORT-API.md @@ -21,7 +21,8 @@ It is questionable whether a library should be able to terminate an application. * * @param code gives the cause of the error. * - * Note: jerry expects the function not to return. + * Note: + * Jerry expects the function not to return. * * Example: a libc-based port may implement this with exit() or abort(), or both. */ @@ -91,14 +92,26 @@ typedef struct /** * Get timezone and daylight saving data * + * Note: + * This port function is called by jerry-core when + * CONFIG_DISABLE_DATE_BUILTIN is _not_ defined. Otherwise this function is + * not used. + * + * @param[out] tz_p time zone structure to fill. * @return true - if success * false - otherwise */ -bool jerry_port_get_time_zone (jerry_time_zone_t *); +bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p); /** * Get system time * + * Note: + * This port function is called by jerry-core when + * CONFIG_DISABLE_DATE_BUILTIN is _not_ defined. It is also common practice + * in application code to use this function for the initialization of the + * random number generator. + * * @return milliseconds since Unix epoch */ double jerry_port_get_current_time (void); @@ -110,12 +123,13 @@ Allow user to provide external buffer for jerry instance (which includes an isol ```c /** - * Get the current instance, which contains the current context, heap and other infomation. - * Each port should provide its own implementation of this interface. + * Get the current instance which contains the current context, heap and other + * structures. Each port should provide its own implementation of this interface. * - *Note: - * This port function will be called automatically by jerry-core - * when JERRY_ENABLE_EXTERNAL_CONTEXT is defined. If not, this function will never be called. + * Note: + * This port function is called by jerry-core when + * JERRY_ENABLE_EXTERNAL_CONTEXT is defined. Otherwise this function is not + * used. * * @return the pointer to the jerry instance. */ @@ -127,6 +141,12 @@ struct jerry_instance_t *jerry_port_get_current_instance (void); ```c /** * Makes the process sleep for a given time. + * + * Note: + * This port function is called by jerry-core when JERRY_DEBUGGER is + * defined. Otherwise this function is not used. + * + * @param sleep_time milliseconds to sleep. */ void jerry_port_sleep (uint32_t sleep_time); ``` @@ -269,7 +289,7 @@ void jerry_port_sleep (uint32_t sleep_time) #ifdef HAVE_TIME_H nanosleep (&(const struct timespec) { - sleep_time / 1000, (sleep_time % 1000) * 1000000L /* Seconds, nanoseconds */ + (time_t) sleep_time / 1000, ((long int) sleep_time % 1000) * 1000000L /* Seconds, nanoseconds */ } , NULL); #elif defined (HAVE_UNISTD_H) diff --git a/06.REFERENCE-COUNTING.md b/06.REFERENCE-COUNTING.md index a80e5e049..fc9eb7880 100644 --- a/06.REFERENCE-COUNTING.md +++ b/06.REFERENCE-COUNTING.md @@ -71,7 +71,7 @@ behaviour through property getting and setting. * prop_value contains a live reference to an error object. * This reference must be released as well. */ - if (jerry_value_has_error_flag (prop_value)) + if (jerry_value_is_error (prop_value)) { /* Errors can be handled here. */ } @@ -103,7 +103,7 @@ behaviour through property getting and setting. /* The reference stored in the 'result' variable is live whether * the operation is successful or not, and must also be freed. */ - if (jerry_value_has_error_flag (result)) + if (jerry_value_is_error (result)) { /* Errors can be handled here. */ } diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md index 2f4cb0a47..ee9a0eb54 100644 --- a/07.DEBUGGER.md +++ b/07.DEBUGGER.md @@ -315,7 +315,7 @@ wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource nam source_size, JERRY_PARSE_NO_OPTS); - if (!jerry_value_has_error_flag (ret_val)) + if (!jerry_value_is_error (ret_val)) { jerry_value_t func_val = ret_val; ret_val = jerry_run (func_val); diff --git a/09.EXT-REFERENCE-ARG.md b/09.EXT-REFERENCE-ARG.md index 9f1fe3de2..6235b11a1 100644 --- a/09.EXT-REFERENCE-ARG.md +++ b/09.EXT-REFERENCE-ARG.md @@ -254,7 +254,7 @@ my_external_handler (const jerry_value_t function_obj, mapping, 4); - if (jerry_value_has_error_flag (rv)) + if (jerry_value_is_error (rv)) { /* Handle error. */ return rv; @@ -650,7 +650,7 @@ my_external_handler (const jerry_value_t function_obj, mapping, 1); - if (jerry_value_has_error_flag (rv)) + if (jerry_value_is_error (rv)) { /* Handle error. */ return rv; @@ -741,7 +741,7 @@ my_external_handler (const jerry_value_t function_obj, mapping, 1); - if (jerry_value_has_error_flag (rv)) + if (jerry_value_is_error (rv)) { /* Handle error. */ return rv; diff --git a/10.EXT-REFERENCE-HANDLER.md b/10.EXT-REFERENCE-HANDLER.md index 689f1260f..c2e7f7b30 100644 --- a/10.EXT-REFERENCE-HANDLER.md +++ b/10.EXT-REFERENCE-HANDLER.md @@ -146,7 +146,7 @@ register_common_functions (void) { jerry_value_t ret = jerry_create_undefined (); - for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_has_error_flag (ret); i++) + for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_is_error (ret); i++) { ret = jerryx_handler_register_global ((const jerry_char_t *) common_functions[i].name_p, common_functions[i].handler_p); diff --git a/12.EXT-REFERENCE-MODULE.md b/12.EXT-REFERENCE-MODULE.md index b3fd28169..beffb16d6 100644 --- a/12.EXT-REFERENCE-MODULE.md +++ b/12.EXT-REFERENCE-MODULE.md @@ -37,6 +37,11 @@ The purpose of having resolvers is to be able to account for the fact that diffe differently and thus, for each type of module a module resolver must be supplied at the point where an instance of that type of module is requested. +Individual modules may be removed from the cache by calling `jerryx_module_clear_cache`. This function behaves +identically to `jerryx_module_resolve` in that it first checks the cache for the requested module, except that it +removes the module if found. Additionally, it clears the entire cache of all modules if called using a JavaScript value +of `undefined` as its first parameter. + Additionally, this extension provides a means of easily defining so-called "native" JerryScript modules which can be resolved using the native JerryScript module resolver `jerryx_module_native_resolver`, which can be passed to `jerryx_module_resolve()`. Native modules are registered during application startup and by calling `dlopen()` by means @@ -66,7 +71,7 @@ to `jerryx_module_resolve` with a module name whose canonical name matches an al ```c jerry_value_t -jerryx_module_resolve (const jerry_char_t *name, +jerryx_module_resolve (const jerry_value_t name, const jerryx_module_resolver_t *resolvers_p, size_t resolver_count); ``` @@ -77,6 +82,26 @@ jerryx_module_resolve (const jerry_char_t *name, - return value - `jerry_value_t` representing the module that was loaded, or the error that occurred in the process. +## jerryx_module_clear_cache + +**Summary** + +Remove a module from the current context's cache, or clear the cache entirely. + +**Prototype** + +```c +void +jerryx_module_clear_cache (const jerry_value_t name, + const jerryx_module_resolver_t *resolvers_p, + size_t resolver_count); +``` + +- `name` - the name of the module to remove from cache or a JavaScript `undefined` to clear the entire cache +- `resolvers_p` - the list of resolvers to call in sequence +- `resolver_count` - the number of resolvers in `resolvers_p` + + ## jerryx_module_native_resolver **Summary**