diff options
-rw-r--r-- | 01.CONFIGURATION.md | 39 | ||||
-rw-r--r-- | 02.API-REFERENCE.md | 799 | ||||
-rw-r--r-- | 03.API-EXAMPLE.md | 22 | ||||
-rw-r--r-- | 04.INTERNALS.md | 3 | ||||
-rw-r--r-- | 05.PORT-API.md | 55 |
5 files changed, 865 insertions, 53 deletions
diff --git a/01.CONFIGURATION.md b/01.CONFIGURATION.md index dbd87a51..1f77e6c6 100644 --- a/01.CONFIGURATION.md +++ b/01.CONFIGURATION.md @@ -15,16 +15,19 @@ A configuration option's value can be changed either by providing specific C pre This document lists the available configuration options, shows the configuration name for C, CMake, and python, and provides a brief description that explains the effect of the options. -### All-in-one build +### Amalgamated build -Enables the All-in-one build process, which aggregates the contents of each source file, and uses this combined file to compile the JerryScript library. -This process can provide comparable results to link time optimization, and can be useful when LTO is not available otherwise. +Enables the amalgamated build process, which aggregates the contents of each source file per library +(i.e., JerryScript's core, port, and math libraries), and uses these combined files to compile the project. +This process can provide comparable results to link-time optimization, and can be useful when LTO is not available otherwise. | Options | | |---------|----------------------------------------------| | C: | `<none>` | -| CMake: | `-DENABLE_ALL_IN_ONE=ON/OFF` | -| Python: | `--all-in-one=ON/OFF` | +| CMake: | `-DENABLE_AMALGAM=ON/OFF` | +| Python: | `--amalgam=ON/OFF` | + +See also: [Amalgamated sources](#amalgamated-sources) ### Jerry debugger @@ -288,25 +291,27 @@ This option is disabled by default. | Python: | `--mem-stress-test=ON/OFF` | -# Single source build mode +# Amalgamated sources -There is a special mode to use/"build" JerryScript. That is generating a single C file which can be -included into projects quickly. To achive this the following command can be executed to create -a set of files into the `gen_src` directory (Note that the command is executed in the jerryscript root directory -but can be adapted to run outside of the project root dir): +The sources of JerryScript can be combined into a handful of files to allow their easy integration +in other projects. To achieve this, the following command can be executed to create a set of files +into the `amalgam` directory: ```sh -$ python tools/srcgenerator.py --output-dir gen_src --jerry-core --jerry-port-default --jerry-libm +$ python tools/amalgam.py --output-dir amalgam --jerry-core --jerry-port-default --jerry-math ``` -The command creates the following files in the `gen_src` dir: +(Note: In the example above, the command is executed from the project's root directory, but that is +not mandatory.) + +The command creates the following files in the `amalgam` dir: * `jerryscript.c` * `jerryscript.h` * `jerryscript-config.h` * `jerryscript-port-default.c` * `jerryscript-port-default.h` -* `jerryscript-libm.c` +* `jerryscript-math.c` * `math.h` **Important**: the `jerryscript-config.h` contains the configurations mentioned above and @@ -314,15 +319,15 @@ should be adapted to the required use-case. See the file contents for more detai default configuration. (Note: This config file is created from the the `jerry-core/config.h` file.) These files can be directly compiled with an application using the JerryScript API. -For example with the following command: +E.g., using a command similar to the one below: ```sh -$ gcc -Wall -o demo_app demo_app.c gen_src/jerryscript.c gen_src/jerryscript-port-default.c jerryscript-libm.c -Igen_src/ +$ gcc -Wall -o demo_app demo_app.c amalgam/jerryscript.c amalgam/jerryscript-port-default.c amalgam/jerryscript-math.c -Iamalgam/ ``` -Please note that the headers must be available on the include path. +(Note: The headers must be available on the include path.) -In addition there is a `-DENABLE_ALL_IN_ONE_SOURCE=ON` CMake option to use this kind of sources during the build. +This approach is also under the hood of the [amalgamated build](#amalgamated-build) process. # Target specific information diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index e7864dcb..cf01b70e 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -37,9 +37,12 @@ Enum that contains JerryScript API value types: - JERRY_TYPE_FUNCTION - function type - JERRY_TYPE_ERROR - error/abort type - JERRY_TYPE_SYMBOL - symbol type + - JERRY_TYPE_BIGINT - bigint type *New in version 2.0*. +*Changed in version 2.4*: Added `JERRY_TYPE_BIGINT` value. + ## jerry_object_type_t Enum that contains JerryScript **object** value types: @@ -63,7 +66,7 @@ Enum that contains JerryScript **object** value types: - JERRY_OBJECT_TYPE_GENERATOR - Generator object - JERRY_OBJECT_TYPE_BIGINT - BigInt object -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. ## jerry_function_type_t @@ -76,7 +79,7 @@ Enum that contains JerryScript **function** value types: - JERRY_FUNCTION_TYPE_ARROW - Arrow fuction - JERRY_FUNCTION_TYPE_GENERATOR - Generator function object -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. ## jerry_iterator_type_t @@ -88,7 +91,23 @@ Enum that contains JerryScript **iterator** value types: - JERRY_ITERATOR_TYPE_MAP - Map iterator - JERRY_ITERATOR_TYPE_SET - Set iterator -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. + +## jerry_property_filter_t + +Enum that contains JerryScript **property filter** options bits: + + - JERRY_PROPERTY_FILTER_ALL - List all property keys independently from key type or property value attributes (equivalent to Reflect.ownKeys call) + - JERRY_PROPERTY_FILTER_TRAVERSE_PROTOTYPE_CHAIN - Include keys from the objects's prototype chain as well + - JERRY_PROPERTY_FILTER_EXLCUDE_NON_CONFIGURABLE - Exclude property key if the property is non-configurable + - JERRY_PROPERTY_FILTER_EXLCUDE_NON_ENUMERABLE - Exclude property key if the property is non-enumerable + - JERRY_PROPERTY_FILTER_EXLCUDE_NON_WRITABLE - Exclude property key if the property is non-writable + - JERRY_PROPERTY_FILTER_EXLCUDE_STRINGS - Exclude property key if it is a string + - JERRY_PROPERTY_FILTER_EXLCUDE_SYMBOLS - Exclude property key if it is a symbol + - JERRY_PROPERTY_FILTER_EXLCUDE_INTEGER_INDICES - Exclude property key if it is an integer index + - JERRY_PROPERTY_FILTER_INTEGER_INDICES_AS_NUMBER - By default integer index property keys are converted to string. Enabling this flags keeps integer index property keys as numbers + +*New in version 2.4*. ## jerry_error_t @@ -135,10 +154,14 @@ Possible compile time enabled feature types: - JERRY_FEATURE_SET - Set support - JERRY_FEATURE_WEAKMAP - WeakMap support - JERRY_FEATURE_WEAKSET - WeakSet support + - JERRY_FEATURE_BIGINT - BigInt support + - JERRY_FEATURE_REALM - realm support *New in version 2.0*. -*Changed in version 2.3* : Added `JERRY_FEATURE_WEAKMAP`, `JERRY_FEATURE_WEAKSET` values. +*Changed in version 2.3*: Added `JERRY_FEATURE_WEAKMAP`, `JERRY_FEATURE_WEAKSET` values. + +*Changed in version 2.4*: Added `JERRY_FEATURE_BIGINT`, `JERRY_FEATURE_REALM` values. ## jerry_container_type_t @@ -156,10 +179,10 @@ Container object types: Well-known symbols: + - JERRY_SYMBOL_ASYNC_ITERATOR - @@asyncIterator well-known symbol - JERRY_SYMBOL_HAS_INSTANCE - @@hasInstance well-known symbol - JERRY_SYMBOL_IS_CONCAT_SPREADABLE - @@isConcatSpreadable well-known symbol - JERRY_SYMBOL_ITERATOR - @@iterator well-known symbol - - JERRY_SYMBOL_ASYNC_ITERATOR - @@asyncIterator well-known symbol - JERRY_SYMBOL_MATCH - @@match well-known symbol - JERRY_SYMBOL_REPLACE - @@replace well-known symbol - JERRY_SYMBOL_SEARCH - @@search well-known symbol @@ -168,8 +191,9 @@ Well-known symbols: - JERRY_SYMBOL_TO_PRIMITIVE - @@toPrimitive well-known symbol - JERRY_SYMBOL_TO_STRING_TAG - @@toStringTag well-known symbol - JERRY_SYMBOL_UNSCOPABLES - @@unscopables well-known symbol + - JERRY_SYMBOL_MATCH_ALL - @@matchAll well-known symbol - *New in version [[NEXT_RELEASE]]*. + *New in version 2.4*. ## jerry_regexp_flags_t @@ -177,12 +201,22 @@ RegExp object optional flags: - JERRY_REGEXP_FLAG_GLOBAL - global match; find all matches rather than stopping after the first match - JERRY_REGEXP_FLAG_IGNORE_CASE - ignore case - - JERRY_REGEXP_FLAG_MULTILINE - multiline; treat beginning and end characters (^ and $) as working over - multiple lines (i.e., match the beginning or end of each line (delimited by \n or \r), not only the - very beginning or end of the whole input string) + - JERRY_REGEXP_FLAG_MULTILINE - multiline; treat beginning and end characters (^ and $) as working + over + multiple lines (i.e., match the beginning or end of each line (delimited by \n or \r), not only the + very beginning or end of the whole input string) + - JERRY_REGEXP_FLAG_STICKY - The sticky flag indicates that it matches only from the index indicated + by the lastIndex property + - JERRY_REGEXP_FLAG_UNICODE - The unicode flag enables various Unicode-related features + - JERRY_REGEXP_FLAG_DOTALL -The dotall flag indicates that the dot special character (".") should + additionally match the following line terminator ("newline") characters in a string; + *New in version 2.0*. +*Changed in version 2.4*: Added `JERRY_REGEXP_FLAG_STICKY`, `JERRY_REGEXP_FLAG_UNICODE` , `JERRY_REGEXP_FLAG_DOTALL` values. + + ## jerry_parse_opts_t Option bits for [jerry_parse](#jerry_parse) and @@ -190,9 +224,12 @@ Option bits for [jerry_parse](#jerry_parse) and - JERRY_PARSE_NO_OPTS - no options passed - JERRY_PARSE_STRICT_MODE - enable strict mode + - JERRY_PARSE_MODULE - parse source as an ECMAScript module *New in version 2.0*. +*Changed in version 2.4: Added `JERRY_PARSE_MODULE`.* + ## jerry_gc_mode_t Set garbage collection operational mode @@ -562,6 +599,33 @@ typedef void (*jerry_object_native_free_callback_t) (void *native_p); - [jerry_object_native_info_t](#jerry_object_native_info_t) - [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) +## jerry_error_object_created_callback_t + +**Summary** + +Decorator callback for Error objects. This native callback is called every time when an Error +object is created and the decorator can create or update any properties of the newly created +Error object. + +*Note*: + - The callback function cannot be called recursively, so the Error objects created + when the callback is running are not updated. + +**Prototype** + +```c +typedef void (*jerry_error_object_created_callback_t) (const jerry_value_t error_object, void *user_p); +``` + +- `error_object` - the newly created Error object. +- `user_p` - pointer passed to [jerry_set_error_object_created_callback](#jerry_set_error_object_created_callback). + +*New in version 2.4*. + +**See also** + +- [jerry_set_error_object_created_callback](#jerry_set_error_object_created_callback) + ## jerry_object_native_info_t **Summary** @@ -740,7 +804,7 @@ TypedArray support is not in the engine. *New in version 2.0*. -*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_TYPEDARRAY_BIGINT64`, `JERRY_TYPEDARRAY_BIGUINT64` values. +*Changed in version 2.4*: Added `JERRY_TYPEDARRAY_BIGINT64`, `JERRY_TYPEDARRAY_BIGUINT64` values. **See also** @@ -1374,6 +1438,9 @@ jerry_eval (const jerry_char_t *source_p, Run enqueued Promise jobs until the first thrown error or until all get executed. +*Important Note*: The job queue is not guaranteed to be empty, after the function call has returned a value. +Therefore, this function is best used in a while loop, handling each error it returns, until the job queue is empty. + *Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. @@ -1404,7 +1471,27 @@ main (void) jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); jerry_value_t script_value = jerry_run (parsed_code); - jerry_value_t job_value = jerry_run_all_enqueued_jobs (); + + jerry_value_t job_value; + while (true) + { + job_value = jerry_run_all_enqueued_jobs (); + + if (jerry_value_is_error (job_value)) + { + if (jerry_value_is_abort (job_value)) + { + // Terminate the engine + } + + // Handle the error here + } + else + { + // The queue should be empty now + break; + } + } jerry_release_value (job_value); jerry_release_value (script_value); @@ -1820,6 +1907,8 @@ jerry_value_is_async_function (const jerry_value_t value) - true, if the given `jerry_value_t` is an async function - false, otherwise +*New in version 2.4*. + **Example** ```c @@ -2179,7 +2268,7 @@ jerry_value_is_bigint (const jerry_value_t value) - true, if the given `jerry_value_t` is a BigInt - false, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -2441,7 +2530,7 @@ jerry_object_get_type (const jerry_value_t value); - return value - One of the [jerry_object_type_t](#jerry_object_type_t) value. -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -2484,7 +2573,7 @@ jerry_function_get_type (const jerry_value_t value); Note: For non-function parameters `JERRY_FUNCTION_TYPE_NONE` is returned. -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -2528,7 +2617,7 @@ jerry_iterator_get_type (const jerry_value_t value); Note: For non-iterator parameters `JERRY_ITERATOR_TYPE_NONE` is returned. -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -2949,6 +3038,54 @@ jerry_get_value_from_error (jerry_value_t value, bool release) - [jerry_create_error_from_value](#jerry_create_error_from_value) - [jerry_create_abort_from_value](#jerry_create_abort_from_value) +## jerry_set_error_object_created_callback + +**Summary** + +Set the decorator callback for newly created Error objects. The operation of the callback +is described in [jerry_error_object_created_callback_t](#jerry_error_object_created_callback_t). + +**Prototype** + +```c +void jerry_set_error_object_created_callback (jerry_error_object_created_callback_t callback, void *user_p); +``` + +- `callback` - callback function, the previously set value is overwritten, and setting NULL + disables the operation +- `user_p` - pointer passed to the callback function, can be NULL + +*New in version 2.4*. + +**Example** + +```c +static void +error_object_created_callback (const jerry_value_t error_object) /**< new error object */ + void *user_p) /**< user pointer */ +{ + (void) error_object; + (void) user_p; + printf ("Notification: a new error is created\n"); +} /* error_object_created_callback */ + +void main(void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_set_error_object_created_callback (error_object_created_callback, NULL); + + jerry_release_value (jerry_create_error (JERRY_ERROR_COMMON, + (const jerry_char_t *) "Message")); + + jerry_cleanup (); +} /* main */ +``` + +**See also** + +- [jerry_error_object_created_callback_t](#jerry_error_object_created_callback_t) + # Getter functions of 'jerry_value_t' Get raw data from API values. @@ -3717,7 +3854,7 @@ jerry_value_to_bigint (const jerry_value_t value); - converted BigInt value, if success - thrown error, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -3739,6 +3876,92 @@ jerry_value_to_bigint (const jerry_value_t value); - [jerry_value_is_bigint](#jerry_value_is_bigint) - [jerry_get_bigint_digits](#jerry_get_bigint_digits) +## jerry_value_as_integer + +**Summary** + +Convert any number to integer number. Returns 0 if value is not number. +Based on ECMA 262 v11 7.1.5 + +**Prototype** + +```c +double +jerry_value_as_integer (const jerry_value_t value); +``` + +- `value` - api value +- return + - 0, if value is not a number + - integer representation of the number, otherwise + +**Example** + +```c +{ + jerry_value_t number_val = jerry_create_number (123321); + double number = jerry_value_as_integer (number_val); + jerry_release_value (number_val); +} +``` + +## jerry_value_as_int32 + +**Summary** + +Convert any number to int32 number. Returns 0 if value is not number. +Based on ECMA 262 v11 7.1.6 + +**Prototype** + +```c +int32_t +jerry_value_as_int32 (const jerry_value_t value); +``` + +- `value` - api value +- return + - 0, if value is not a number + - int32 representation of the number, otherwise + +**Example** + +```c +{ + jerry_value_t number_val = jerry_create_number (123321); + int32_t number = jerry_value_as_int32 (number_val); + jerry_release_value (number_val); +} +``` + +## jerry_value_as_uint32 + +**Summary** + +Convert any number to uint32 number. Returns 0 if value is not number. +Based on ECMA 262 v11 7.1.7 + +**Prototype** + +```c +uint32_t +jerry_value_as_uint32 (const jerry_value_t value); +``` + +- `value` - api value +- return + - 0, if value is not a number + - uint32 representation of the number, otherwise + +**Example** + +```c +{ + jerry_value_t number_val = jerry_create_number (123321); + uint32_t number = jerry_value_as_uint32 (number_val); + jerry_release_value (number_val); +} +``` # Functions for promise objects @@ -3882,6 +4105,109 @@ example (void) - [jerry_create_promise](#jerry_create_promise) - [jerry_promise_state_t](#jerry_promise_state_t) +## jerry_from_property_descriptor + +**Summary** + +This API function is equivalent to FromPropertyDescriptor operation defined in ECMA 262 v11 6.2.5.4. +It returns with an ECMAScript Object which represents the property attributes. + +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_from_property_descriptor (const jerry_property_descriptor_t *src_prop_desc_p) +``` + +- `src_prop_desc_p` - the input property descriptor. +- return + - [jerry_value_t](#jerry_value_t) + - jerry value - if success + - value marked with error flag - otherwise + +**Example** + +[doctest]: # (test="compile") + +```c +#include <jerryscript.h> + +static void +example (void) +{ + jerry_value_t prop_name = jerry_create_string_from_utf8 ((jerry_char_t *) "value"); + + jerry_property_descriptor_t prop_desc; + jerry_init_property_descriptor_fields (&prop_desc); + + prop_desc.value = prop_name; + prop_desc.is_value_defined = true; + + jerry_value_t from_object = jerry_from_property_descriptor (&prop_desc); + + jerry_release_value (prop_name); + jerry_release_value (from_object); + jerry_free_property_descriptor_fields (&prop_desc); +} +``` + +## jerry_to_property_descriptor + +**Summary** + +This API function is equivalent to ToPropertyDescriptor operation defined in ECMA 262 v11 6.2.5.5. +It decodes the ECMAScript object and fills the fields of a JerryScript property descriptor. + +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_to_property_descriptor (jerry_value_t obj_value, jerry_property_descriptor_t *out_prop_desc_p); +``` + +- `obj_value` - the input object +- `src_prop_desc_p` - the output property descriptor. +- return + - [jerry_value_t](#jerry_value_t) + - true, if success + - thrown error, otherwise + +*New in version 2.4*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include <jerryscript.h> + +static void +example (void) +{ + jerry_value_t object = jerry_create_object (); + jerry_value_t prop_name = jerry_create_string_from_utf8 ((jerry_char_t *) "value"); + jerry_value_t value = jerry_create_boolean (true); + jerry_property_descriptor_t prop_desc; + + jerry_release_value (jerry_set_property (object, prop_name, prop_name)); + + jerry_release_value (jerry_to_property_descriptor (object, &prop_desc)); + + jerry_release_value (object); + jerry_release_value (prop_name); + jerry_release_value (value); + jerry_free_property_descriptor_fields (&prop_desc); +} +``` + ## jerry_resolve_or_reject_promise **Summary** @@ -3977,7 +4303,7 @@ jerry_get_well_known_symbol (jerry_well_known_symbol_t symbol); - undefined value - if invalid well-known symbol was requested - well-known symbol value, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -4037,7 +4363,7 @@ jerry_get_symbol_description (const jerry_value_t value); - string or undefined value containing the symbol's description - if success - thrown error, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -4166,7 +4492,7 @@ jerry_get_bigint_size_in_digits (jerry_value_t value) - number of digits (can be zero for BigInt zero) - if value is not a BigInt value, it returns with zero -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -4229,7 +4555,7 @@ jerry_get_bigint_digits (jerry_value_t value, uint64_t *digits_p, uint32_t size, - `sign_p` - the boolean passed to the function is set to false when the BigInt is positive, and set to true otherwise (this parameter can be NULL) -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -4263,6 +4589,62 @@ main (void) - [jerry_get_bigint_size_in_digits](#jerry_get_bigint_size_in_digits) +# Functions for Proxy objects + +These APIs all depend on build option (`JERRY_BUILTIN_PROXY`). + +## jerry_get_proxy_target + +**Summary** + +Gets the target object of a Proxy object + +*Notes*: +- This API depends on a build option (`JERRY_BUILTIN_PROXY`) and can be checked + in runtime with the `JERRY_FEATURE_PROXY` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The es.next profile enables this by default. + + +**Prototype** + +```c +jerry_value_t +jerry_get_proxy_target (jerry_value_t proxy_value) +``` + +- `proxy_value` - Proxy object value +- return value + - type error - if proxy_value is not a Proxy object + - target object - otherwise + +*New in version 2.4*. + +**Example** + +```c +{ + jerry_value_t target = jerry_create_object (); + jerry_value_t handler = jerry_create_object (); + jerry_value_t proxy = jerry_create_proxy (target, handler); + + jerry_release_value (target); + jerry_release_value (handler); + + target = jerry_get_proxy_target (proxy); + + // ... usage of the target + + jerry_release_value (target); + jerry_release_value (proxy); +} +``` + +**See also** + +- [jerry_create_proxy](#jerry_create_proxy) + + # Acquire and release API values ## jerry_acquire_value @@ -5206,7 +5588,7 @@ jerry_create_external_string (const jerry_char_t *str_p, - `free_cb` - optional callback which is called right before the string is freed - return value - value of the created string -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -5253,7 +5635,7 @@ jerry_create_external_string_sz (const jerry_char_t *str_p, - `free_cb` - optional callback which is called right before the string is freed - return value - value of the created string -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -5362,7 +5744,7 @@ jerry_create_bigint (const uint64_t *digits_p, uint32_t size, bool sign) - value of the created bigint, if success - thrown error, otherwise -*New in version [[NEXT_RELEASE]]*. +*New in version 2.4*. **Example** @@ -5745,6 +6127,40 @@ jerry_create_undefined (void); - [jerry_release_value](#jerry_release_value) +## jerry_create_realm + +**Summary** + +Creates a `jerry_value_t` representing a new global object. + +**Prototype** + +```c +jerry_value_t +jerry_create_realm (void); +``` + +- return value - realm object value + +*New in version 2.4*. + +**Example** + +```c +{ + jerry_value_t realm_value = jerry_create_realm (); + + ... // usage of the value + + jerry_release_value (realm_value); +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) + + # General API functions of JS objects ## jerry_has_property @@ -7250,6 +7666,44 @@ best-practice example. - [jerry_object_native_info_t](#jerry_object_native_info_t) +## jerry_object_get_property_names + +**Summary** + +Gets the property keys for the given object using the selected filters. + +**Prototype** + +```c +jerry_value_t +jerry_object_get_property_names (jerry_value_t obj_val, + jerry_property_filter_t filter); +``` + +- `obj_val` - object value +- `filter` - any combination of [jerry_property_filter_t](#jerry_property_filter_t) options +- return value + - array containing the filtered property keys in successful operation + - error marked with error flag, otherwise + +**Example** + +```c +{ + jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t keys = jerry_object_get_property_names (object, JERRY_PROPERTY_FILTER_ALL); + + ... // usage of keys + + jerry_release_value (keys); + jerry_release_value (global_object); +} +``` + +**See also** + +- [jerry_property_filter_t](#jerry_property_filter_t) + ## jerry_foreach_object_property **Summary** @@ -8514,6 +8968,7 @@ backtrace_handler (const jerry_value_t function_obj, if (!jerry_is_feature_enabled (JERRY_FEATURE_LINE_INFO)) { printf ("Line info disabled, no backtrace will be printed\n"); + return jerry_create_undefined (); } /* If the line info feature is disabled an empty array will be returned. */ @@ -8586,9 +9041,146 @@ main (void) **See also** +- [jerry_get_backtrace_from](#jerry_get_backtrace_from) - [jerry_create_external_function](#jerry_create_external_function) +## jerry_get_backtrace_from + +**Summary** + +Get backtrace. The backtrace is an array of strings where +each string contains the position of the corresponding frame. +The array length is zero if the backtrace is not available. + +Collecting the trace starts after the function specified in +the `ignored_function` parameter. This parameter can be used to +skip the helper function(s) which collects the backtrace from +the backtrace data. + +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it +is no longer needed. +- This feature depends on build option (`JERRY_LINE_INFO`) and can be checked + in runtime with the `JERRY_FEATURE_LINE_INFO` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_value_t +jerry_get_backtrace_from (uint32_t max_depth, jerry_value_t ignored_function); +``` + +- `max_depth` - backtrace collection stops after reaching this value, 0 = unlimited +- `ignored_function` - if this function is present in the backtrace, the backtrace + only contains the stack frames after the topmost instance of + this function. Otherwise this parameter is ignored +- return value + - a newly constructed JS array + +*New in version 2.4*. + +**Example** + +[doctest]: # (name="02.API-REFERENCE-jsbacktracefrom.c") + +```c +#include <stdio.h> +#include <string.h> +#include "jerryscript.h" + +static jerry_value_t +backtrace_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) +{ + if (!jerry_is_feature_enabled (JERRY_FEATURE_LINE_INFO)) + { + printf ("Line info disabled, no backtrace will be printed\n"); + return jerry_create_undefined (); + } + + if (args_count < 1) + { + printf ("Ignored function is not specified\n"); + return jerry_create_undefined (); + } + + /* If the line info feature is disabled an empty array will be returned. */ + jerry_value_t backtrace_array = jerry_get_backtrace_from (0, args_p[0]); + uint32_t array_length = jerry_get_array_length (backtrace_array); + + for (uint32_t idx = 0; idx < array_length; idx++) + { + jerry_value_t property = jerry_get_property_by_index (backtrace_array, idx); + + jerry_char_t string_buffer[64]; + jerry_size_t copied_bytes = jerry_substring_to_char_buffer (property, + 0, + 63, + string_buffer, + 63); + string_buffer[copied_bytes] = '\0'; + printf(" %d: %s\n", idx, string_buffer); + + jerry_release_value (property); + } + + jerry_release_value (backtrace_array); + + return jerry_create_undefined (); +} /* backtrace_handler */ + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t global = jerry_get_global_object (); + + /* Register the "dump_backtrace" method. */ + { + jerry_value_t func = jerry_create_external_function (backtrace_handler); + jerry_value_t name = jerry_create_string ((const jerry_char_t *) "backtrace"); + jerry_value_t result = jerry_set_property (global, name, func); + jerry_release_value (result); + jerry_release_value (name); + jerry_release_value (func); + } + + jerry_release_value (global); + + const char *source = ("function f() { g (); }\n" + "function g() { h (); }\n" + "function h() { backtrace (g); }\n" + "f ();\n"); + const char *resource = "demo_memoryjs"; + + jerry_value_t program = jerry_parse ((const jerry_char_t *) resource, + strlen (resource), + (const jerry_char_t *) source, + strlen (source), + JERRY_PARSE_NO_OPTS); + if (!jerry_value_is_error (program)) + { + jerry_value_t run_result = jerry_run (program); + jerry_release_value (run_result); + } + + jerry_release_value (program); + jerry_cleanup (); + + return 0; +} +``` + +**See also** + +- [jerry_get_backtrace](#jerry_get_backtrace) + + ## jerry_get_resource_name **Summary** @@ -8822,6 +9414,161 @@ main (int argc, char** argv) - [jerry_construct_object](#jerry_construct_object) +# Functions for realm objects + +These APIs all depend on build option (`JERRY_BUILTIN_REALMS`). + +## jerry_set_realm + +**Summary** + +Replaces the currently active realm (including the global object) with another realm. +The replacement should be temporary, and the original realm must be restored after +the tasks are completed. During the replacement, the realm must be referenced +by the application (i.e. the gc must not reclaim it). This is also true to +the returned previously active realm, so there is no need to free the value +after the restoration. The function can only fail if realms are not supported +or the passed argument is not a realm. In this case the returned exception must +be freed by [jerry_release_value](#jerry_release_value). + +This function is useful to parse a script, create a native function, load a snapshot +or create an exception in another realm. Each ECMAScript code runs in the realm +which was active when the code was parsed or loaded regardless of the current realm. + +*Notes*: +- This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked + in runtime with the `JERRY_FEATURE_REALM` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The es.next profile enables this by default. + +**Prototype** + +```c +jerry_value_t +jerry_set_realm (jerry_value_t realm_value); +``` +- `realm_value` - the new realm value +- return + - previous realm value - if the passed value is a realm + - exception - otherwise + +*New in version 2.4*. + +**Example** + +```c +{ + jerry_value_t realm_value = jerry_create_realm (); + + jerry_value_t old_realm = jerry_set_realm (realm_value); + + ... // usage of the realm + + jerry_set_realm (old_realm); +} +``` + +**See also** + +- [jerry_create_realm](#jerry_create_realm) + +## jerry_realm_get_this + +**Summary** + +Gets the 'this' binding of a realm. The 'this' binding is always an object. +By default the 'this' binding is the same as the realm object and can be +changed by [jerry_realm_set_this](#jerry_realm_set_this). + +*Notes*: +- This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked + in runtime with the `JERRY_FEATURE_REALM` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The es.next profile enables this by default. + +**Prototype** + +```c +jerry_value_t +jerry_realm_get_this (jerry_value_t realm_value) +``` +- `realm_value` - realm value +- return + - type error - if realm_value is not a realm + - 'this' binding object - otherwise + +*New in version 2.4*. + +**Example** + +```c +{ + jerry_value_t realm_value = jerry_create_realm (); + + jerry_value_t this_value = jerry_realm_get_this (realm_value); + + ... // usage of the this_value + + jerry_release_value (this_value); + jerry_release_value (realm_value); +} +``` + +**See also** + +- [jerry_create_realm](#jerry_create_realm) +- [jerry_realm_set_this](#jerry_realm_set_this) + +## jerry_realm_set_this + +**Summary** + +Sets the 'this' binding of a realm. This function must be called before executing +any script on the realm. Otherwise the operation is undefined. + +*Notes*: +- This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked + in runtime with the `JERRY_FEATURE_REALM` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The es.next profile enables this by default. + +**Prototype** + +```c +jerry_value_t +jerry_realm_set_this (jerry_value_t realm_value, jerry_value_t this_value) +``` +- `realm_value` - realm value +- `this_value` - new this value +- return + - type error - if realm_value is not a realm or this_value is not object + - true - otherwise + +*New in version 2.4*. + +**Example** + +```c +{ + jerry_value_t realm_value = jerry_create_realm (); + + jerry_value_t old_realm = jerry_set_realm (realm_value); + /* The prototype of the object comes from the new realm. */ + jerry_value_t this_value = jerry_create_object (); + jerry_set_realm (old_realm); + + jerry_value_t result = jerry_realm_set_this (realm_value, this_value); + + ... // usage of the realm +} +``` + +**See also** + +- [jerry_create_realm](#jerry_create_realm) +- [jerry_set_realm](#jerry_set_realm) +- [jerry_realm_get_this](#jerry_realm_get_this) + # ArrayBuffer and TypedArray functions These APIs all depend on the es.next profile. @@ -9021,7 +9768,9 @@ jerry_get_arraybuffer_pointer (const jerry_value_t value); - `value` - Array Buffer object. - return value - pointer to the Array Buffer's data area. - - NULL if the `value` is not an Array Buffer object. + - NULL if the `value` is: + - not an ArrayBuffer object + - an external ArrayBuffer has been detached *New in version 2.0*. @@ -9106,6 +9855,8 @@ jerry_value_t jerry_detach_arraybuffer (const jerry_value_t value); ``` +*Note*: If the ArrayBuffer has been created with `jerry_create_arraybuffer_external` the optional free callback is called on a successful detach operation + - `value` - ArrayBuffer to be detached - return - null value if success diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md index cdffaee4..54b0978f 100644 --- a/03.API-EXAMPLE.md +++ b/03.API-EXAMPLE.md @@ -42,7 +42,7 @@ $ export PKG_CONFIG_PATH=$(pwd)/example_install/lib/pkgconfig/ Test if the `pkg-config` works for JerryScript: ```sh -$ pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-ext libjerry-libm +$ pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-ext libjerry-math ``` ## Example 1. Execute JavaScript from your application @@ -68,7 +68,7 @@ main (void) To compile it one can use the following command: ```sh -$ gcc api-example-1.c -o api-example-1 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-libm) +$ gcc api-example-1.c -o api-example-1 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math) ``` If everything is correct the application returns with a zero exit code: @@ -128,7 +128,7 @@ main (void) To compile it one can use the following command: ```sh -$ gcc api-example-2.c -o api-example-2 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-libm) +$ gcc api-example-2.c -o api-example-2 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math) ``` If everything is correct the application returns with a zero exit code: @@ -191,7 +191,7 @@ main (void) To compile it one can use the following command: ```sh -$ gcc api-example-3.c -o api-example-3 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-libm) +$ gcc api-example-3.c -o api-example-3 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math) ``` If everything is correct the application returns with a zero exit code: @@ -295,7 +295,7 @@ main (void) To compile it one can use the following command: ```sh -$ gcc api-example-4.c -o api-example-4 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-libm) +$ gcc api-example-4.c -o api-example-4 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math) ``` If everything is correct the application should print out the message present in the `print_handler` method: @@ -415,7 +415,7 @@ main (void) To compile it one can use the following command: ```sh -$ gcc api-example-5.c -o api-example-5 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-libm) +$ gcc api-example-5.c -o api-example-5 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math) ``` If everything is correct the application should print out the string passed for the `print` method in the JS code: @@ -483,7 +483,7 @@ To compile it one can use the following command: (**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call. ```sh -$ gcc api-example-6.c -o api-example-6 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-libm) +$ gcc api-example-6.c -o api-example-6 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math) ``` If everything is correct the application should print out the string passed for the `print` method in the JS code: @@ -559,7 +559,7 @@ To compile it one can use the following command: (**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call. ```sh -$ gcc api-example-7.c -o api-example-7 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-libm) +$ gcc api-example-7.c -o api-example-7 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math) ``` The sample will output 'Hello from C!'. However, now it is not just a part of the source script, but the value, dynamically supplied to the engine: @@ -832,7 +832,7 @@ To compile it one can use the following command: (**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call. ```sh -$ gcc api-example-8-shell.c -o api-example-8-shell $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-libm) +$ gcc api-example-8-shell.c -o api-example-8-shell $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math) ``` The application reads lines from standard input and evaluates them, one after another. To try out run: @@ -932,7 +932,7 @@ To compile it one can use the following command: (**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call. ```sh -$ gcc api-example-9.c -o api-example-9 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-libm) +$ gcc api-example-9.c -o api-example-9 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math) ``` Execute the example with: @@ -1063,7 +1063,7 @@ To compile it one can use the following command: (**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call. ```sh -$ gcc api-example-10.c -o api-example-10 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-libm) +$ gcc api-example-10.c -o api-example-10 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math) ``` Execute the example with: diff --git a/04.INTERNALS.md b/04.INTERNALS.md index 7d2a4663..b22bfd09 100644 --- a/04.INTERNALS.md +++ b/04.INTERNALS.md @@ -290,7 +290,8 @@ The objects are represented as following structure: ![Object properties]({{ site.github.url }}/img/ecma_object_property.png){: class="thumbnail center-block img-responsive" } Objects have a linked list that contains their properties. This list actually contains property pairs, in order to save memory described in the followings: -A property is 7 bit long and its type field is 2 bit long which consumes 9 bit which does not fit into 1 byte but consumes 2 bytes. Hence, placing together two properties (14 bit) with the 2 bit long type field fits into 2 bytes. +A property has a one byte long descriptor, a two byte long name and four byte long value. Hence 14 bytes consumed by a property pair. Another two bytes is +used to show the next property pair, so the total size (16 byte) is divisible by 8. #### Property Hashmap diff --git a/05.PORT-API.md b/05.PORT-API.md index 02bb4fe0..35254319 100644 --- a/05.PORT-API.md +++ b/05.PORT-API.md @@ -161,6 +161,32 @@ jerry_port_get_native_module (jerry_value_t name) /**< module specifier */ } ``` +## Promise + +```c +/** + * HostPromiseRejectionTracker operations + */ +typedef enum +{ + JERRY_PROMISE_REJECTION_OPERATION_REJECT, /**< promise is rejected without any handlers */ + JERRY_PROMISE_REJECTION_OPERATION_HANDLE, /**< handler is added to a rejected promise for the first time */ +} jerry_promise_rejection_operation_t; + +/** + * Track unhandled promise rejections. + * + * Note: + * This port function is called by jerry-core when JERRY_BUILTIN_PROMISE + * is enabled. + * + * @param promise rejected promise + * @param operation HostPromiseRejectionTracker operation + */ +void jerry_port_track_promise_rejection (const jerry_value_t promise, + const jerry_promise_rejection_operation_t operation); +``` + ## Date ```c @@ -402,3 +428,32 @@ void jerry_port_sleep (uint32_t sleep_time) } /* jerry_port_sleep */ #endif /* defined (JERRY_DEBUGGER) && (JERRY_DEBUGGER == 1) */ ``` + +## Promise + +```c +#include "jerryscript-port.h" + +/** + * Default implementation of jerry_port_track_promise_rejection. + * Prints the reason of the unhandled rejections. + */ +void +jerry_port_track_promise_rejection (const jerry_value_t promise, /**< rejected promise */ + const jerry_promise_rejection_operation_t operation) /**< operation */ +{ + (void) operation; /* unused */ + + jerry_value_t reason = jerry_get_promise_result (promise); + jerry_value_t reason_to_string = jerry_value_to_string (reason); + jerry_size_t req_sz = jerry_get_utf8_string_size (reason_to_string); + jerry_char_t str_buf_p[req_sz + 1]; + jerry_string_to_utf8_char_buffer (reason_to_string, str_buf_p, req_sz); + str_buf_p[req_sz] = '\0'; + + jerry_release_value (reason_to_string); + jerry_release_value (reason); + + printf ("Uncaught (in promise) %s\n", str_buf_p); +} /* jerry_port_track_promise_rejection */ +``` |