diff --git a/01.CONFIGURATION.md b/01.CONFIGURATION.md index 1f77e6c66..c97ab2857 100644 --- a/01.CONFIGURATION.md +++ b/01.CONFIGURATION.md @@ -63,6 +63,17 @@ To see how a profile file should be created, or what configuration options are a | CMake: | `-DJERRY_PROFILE="path"` | | Python: | `--profile="path"` | +### Promise callback + +Enables Promise event notification support. This feature allows setting a user callback, which is called when certain Promise related events occur such as +creating a new Promise, resolving a Promise with a value, etc. + +| Options | | +|---------|----------------------------------------------| +| C: | `-DJERRY_PROMISE_CALLBACK=0/1` | +| CMake: | `-DJERRY_PROMISE_CALLBACK=ON/OFF` | +| Python: | `--promise-callback=ON/OFF` | + ### External context Enables external context support in the engine. By default, JerryScript uses a statically allocated context to store the current state of the engine internals. @@ -149,7 +160,7 @@ Enabling this feature provides detailed error messages where available, like lin | Options | | |---------|----------------------------------------------| | C: | `-DJERRY_ERROR_MESSAGES=0/1` | -| CMake: | `--DJERRY_ERROR_MESSAGES=ON/OFF` | +| CMake: | `-DJERRY_ERROR_MESSAGES=ON/OFF` | | Python: | `--error-messages=ON/OFF` | ### Logging @@ -183,7 +194,7 @@ This option is enabled by default. | Options | | |---------|----------------------------------------------| -| C: | `-DJERRY_PROPRETY_HASHMAP=0/1` | +| C: | `-DJERRY_PROPERTY_HASHMAP=0/1` | | CMake: | `` | | Python: | `` | @@ -206,7 +217,7 @@ The default value is 512. | Options | | |---------|----------------------------------------------| | C: | `-DJERRY_GLOBAL_HEAP_SIZE=(int)` | -| CMake: | `--DJERRY_GLOBAL_HEAP_SIZE=(int)` | +| CMake: | `-DJERRY_GLOBAL_HEAP_SIZE=(int)` | | Python: | `--mem-heap=(int)` | ### Garbage collection limit diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index cf01b70ef..1788d35bb 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -49,12 +49,19 @@ Enum that contains JerryScript **object** value types: - JERRY_OBJECT_TYPE_NONE - Non-object type - JERRY_OBJECT_TYPE_GENERIC - Generic JavaScript object without any internal property + - JERRY_OBJECT_TYPE_MODULE_NAMESPACE - Module namespace object - JERRY_OBJECT_TYPE_ARRAY - Array object - JERRY_OBJECT_TYPE_PROXY - Proxy object + - JERRY_OBJECT_TYPE_SCRIPT - Script object (see [jerry_parse](#jerry_parse)) + - JERRY_OBJECT_TYPE_MODULE - Module object (see [jerry_parse](#jerry_parse)) + - JERRY_OBJECT_TYPE_PROMISE - Promise object + - JERRY_OBJECT_TYPE_DATAVIEW - Dataview object - JERRY_OBJECT_TYPE_FUNCTION - Function object (see [jerry_function_get_type](#jerry_function_get_type)) - JERRY_OBJECT_TYPE_TYPEDARRAY - %TypedArray% object (see [jerry_get_typedarray_type](#jerry_get_typedarray_type)) - JERRY_OBJECT_TYPE_ITERATOR - Iterator object (see [jerry_iterator_get_type](#jerry_get_typedarray_type)) - JERRY_OBJECT_TYPE_CONTAINER - Container object (see [jerry_get_container_type](#jerry_get_container_type)) + - JERRY_OBJECT_TYPE_ERROR - Error object + - JERRY_OBJECT_TYPE_ARRAYBUFFER - Array buffer object - JERRY_OBJECT_TYPE_ARGUMENTS - Arguments object - JERRY_OBJECT_TYPE_BOOLEAN - Boolean object @@ -65,9 +72,12 @@ Enum that contains JerryScript **object** value types: - JERRY_OBJECT_TYPE_SYMBOL - Symbol object - JERRY_OBJECT_TYPE_GENERATOR - Generator object - JERRY_OBJECT_TYPE_BIGINT - BigInt object + - JERRY_OBJECT_TYPE_WEAKREF - WeakRef object *New in version 2.4*. +*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_OBJECT_TYPE_SCRIPT`, `JERRY_OBJECT_TYPE_MODULE` values. + ## jerry_function_type_t Enum that contains JerryScript **function** value types: @@ -93,6 +103,18 @@ Enum that contains JerryScript **iterator** value types: *New in version 2.4*. +## jerry_proxy_object_options_t + +These option bits allow specializing Proxies with non-standard behaviour. +These flags are recommended only for those trusted Proxies, whose handlers +produce correct results. + +- JERRY_PROXY_SKIP_RESULT_VALIDATION - skip result validation for [[GetPrototypeOf]], [[SetPrototypeOf]], [[IsExtensible]], + [[PreventExtensions]], [[GetOwnProperty]], [[DefineOwnProperty]], [[HasProperty]], + [[Get]], [[Set]], [[Delete]] and [[OwnPropertyKeys]] + +*New in version [[NEXT_RELEASE]]*. + ## jerry_property_filter_t Enum that contains JerryScript **property filter** options bits: @@ -156,6 +178,9 @@ Possible compile time enabled feature types: - JERRY_FEATURE_WEAKSET - WeakSet support - JERRY_FEATURE_BIGINT - BigInt support - JERRY_FEATURE_REALM - realm support + - JERRY_FEATURE_GLOBAL_THIS - GlobalThisValue support + - JERRY_FEATURE_PROMISE_CALLBACK - Promise callback support + - JERRY_FEATURE_MODULE - Module support *New in version 2.0*. @@ -163,6 +188,8 @@ Possible compile time enabled feature types: *Changed in version 2.4*: Added `JERRY_FEATURE_BIGINT`, `JERRY_FEATURE_REALM` values. +*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_FEATURE_GLOBAL_THIS`, `JERRY_FEATURE_PROMISE_CALLBACK`, `JERRY_FEATURE_MODULE` values. + ## jerry_container_type_t Container object types: @@ -217,18 +244,21 @@ RegExp object optional flags: *Changed in version 2.4*: Added `JERRY_REGEXP_FLAG_STICKY`, `JERRY_REGEXP_FLAG_UNICODE` , `JERRY_REGEXP_FLAG_DOTALL` values. -## jerry_parse_opts_t +## jerry_parse_option_enable_feature_t -Option bits for [jerry_parse](#jerry_parse) and -[jerry_parse_function](#jerry_parse_function) functions: +Option bits for [jerry_parse_options_t](#jerry_parse_options_t). - - JERRY_PARSE_NO_OPTS - no options passed - - JERRY_PARSE_STRICT_MODE - enable strict mode - - JERRY_PARSE_MODULE - parse source as an ECMAScript module + - JERRY_PARSE_NO_OPTS - No options passed + - JERRY_PARSE_STRICT_MODE - Enable strict mode + - JERRY_PARSE_MODULE - Parse source as an ECMAScript module + - JERRY_PARSE_HAS_RESOURCE - `resource_name_p` and `resource_name_length` fields are valid + - JERRY_PARSE_HAS_START - `start_line` and `start_column` fields are valid -*New in version 2.0*. +*New in version [[NEXT_RELEASE]]*. -*Changed in version 2.4: Added `JERRY_PARSE_MODULE`.* +**See also** + +- [jerry_parse_options_t](#jerry_parse_options_t) ## jerry_gc_mode_t @@ -244,13 +274,21 @@ memory blocks but the performance may drop after the garbage collection. *New in version 2.0*. +## jerry_backtrace_frame_types_t + +List of backtrace frame types returned by +[jerry_backtrace_get_frame_type](#jerry_backtrace_get_frame_type). + + - JERRY_BACKTRACE_FRAME_JS - indicates that the frame is created for a JavaScript function/method + +*New in version [[NEXT_RELEASE]]*. + ## jerry_generate_snapshot_opts_t Flags for [jerry_generate_snapshot](#jerry_generate_snapshot) and [jerry_generate_function_snapshot](#jerry_generate_function_snapshot) functions: - JERRY_SNAPSHOT_SAVE_STATIC - generate static snapshot (see below) - - JERRY_SNAPSHOT_SAVE_STRICT - strict source code provided **Generate static snapshots** Snapshots contain literal pools, and these literal pools contain references @@ -273,6 +311,7 @@ when the snapshot is generated and executed. Furthermore the `JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed. *New in version 2.0*. +*Changed in version [[NEXT_RELEASE]]*: The `JERRY_SNAPSHOT_SAVE_STRICT` value is removed, `JERRY_PARSE_STRICT_MODE` should be used instead. ## jerry_exec_snapshot_opts_t @@ -463,6 +502,60 @@ Enum that contains the supported binary operation types - [jerry_binary_operation](#jerry_binary_operation) +## jerry_property_descriptor_flags_t + +Enum that contains the flags of property descriptors. + + - JERRY_PROP_NO_OPTS - empty property descriptor + - JERRY_PROP_IS_CONFIGURABLE - [[Configurable]] + - JERRY_PROP_IS_ENUMERABLE - [[Enumerable]] + - JERRY_PROP_IS_WRITABLE - [[Writable]] + - JERRY_PROP_IS_CONFIGURABLE_DEFINED - Is [[Configurable]] defined? + - JERRY_PROP_IS_ENUMERABLE_DEFINED - Is [[Enumerable]] defined? + - JERRY_PROP_IS_WRITABLE_DEFINED - Is [[Writable]] defined? + - JERRY_PROP_IS_VALUE_DEFINED - Is [[Value]] defined? + - JERRY_PROP_IS_GET_DEFINED - Is [[Get]] defined? + - JERRY_PROP_IS_SET_DEFINED - Is [[Set]] defined? + - JERRY_PROP_SHOULD_THROW - Should throw on error, instead of returning with false + +*New in version [[NEXT_RELEASE]]*. + +**See also** + +- [jerry_property_descriptor_t](#jerry_property_descriptor_t) + +## jerry_parse_options_t + +**Summary** + +Various configuration options for parsing functions such as [jerry_parse](#jerry_parse) +or [jerry_parse_function](#jerry_parse_function) + +**Prototype** + +```c +typedef struct +{ + uint32_t options; /**< combination of jerry_parse_option_enable_feature_t values */ + const jerry_char_t *resource_name_p; /**< resource name (usually a file name) + * if JERRY_PARSE_HAS_RESOURCE is set in options */ + size_t resource_name_length; /**< length of resource name + * if JERRY_PARSE_HAS_RESOURCE is set in options */ + uint32_t start_line; /**< start line of the source code if JERRY_PARSE_HAS_START is set in options */ + uint32_t start_column; /**< start column of the source code if JERRY_PARSE_HAS_START is set in options */ +} jerry_parse_options_t; +``` + +*New in version [[NEXT_RELEASE]]*. + +**See also** + +- [jerry_parse](#jerry_parse) +- [jerry_parse_function](#jerry_parse_function) +- [jerry_generate_snapshot](#jerry_generate_snapshot) +- [jerry_generate_function_snapshot](#jerry_generate_function_snapshot) +- [jerry_parse_option_enable_feature_t](#jerry_parse_option_enable_feature_t) + ## jerry_property_descriptor_t **Summary** @@ -481,48 +574,62 @@ the `value` field should contain the value for the property. ```c typedef struct { - /** Is [[Value]] defined? */ - bool is_value_defined; - - /** Is [[Get]] defined? */ - bool is_get_defined; - - /** Is [[Set]] defined? */ - bool is_set_defined; - - /** Is [[Writable]] defined? */ - bool is_writable_defined; - - /** [[Writable]] */ - bool is_writable; - - /** Is [[Enumerable]] defined? */ - bool is_enumerable_defined; - - /** [[Enumerable]] */ - bool is_enumerable; - - /** Is [[Configurable]] defined? */ - bool is_configurable_defined; - - /** [[Configurable]] */ - bool is_configurable; - - /** [[Value]] */ - jerry_value_t value; - - /** [[Get]] */ - jerry_value_t getter; - - /** [[Set]] */ - jerry_value_t setter; + uint16_t flags; /**< any combination of jerry_property_descriptor_flags_t bits */ + jerry_value_t value; /**< [[Value]] */ + jerry_value_t getter; /**< [[Get]] */ + jerry_value_t setter; /**< [[Set]] */ } jerry_property_descriptor_t; ``` **See also** +- [jerry_property_descriptor_flags_t](#jerry_property_descriptor_flags_t) - [jerry_define_own_property](#jerry_define_own_property) +## jerry_backtrace_location_t + +**Summary** + +Source code location data retreived by +[jerry_backtrace_get_location](#jerry_backtrace_get_location). + +**Prototype** + +```c +typedef struct +{ + jerry_value_t resource_name; /**< resource name */ + jerry_size_t line; /**< line index */ + jerry_size_t column; /**< column index */ +} jerry_backtrace_location_t; +``` + +*New in version [[NEXT_RELEASE]]*. + +## jerry_backtrace_frame_t + +**Summary** + +Backtrace frame data passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) +handler. This is an internal data structure which fields can be accessed by helper functions +such as [jerry_backtrace_get_location](#jerry_backtrace_get_location). + +**Prototype** + +```c +/** + * Internal data structure for jerry_backtrace_frame_t definition. + */ +struct jerry_backtrace_frame_internal_t; + +/** + * Backtrace frame data passed to the jerry_backtrace_callback_t handler. + */ +typedef struct jerry_backtrace_frame_internal_t jerry_backtrace_frame_t; +``` + +*New in version [[NEXT_RELEASE]]*. + ## jerry_heap_stats_t **Summary** @@ -549,6 +656,29 @@ typedef struct - [jerry_get_memory_stats](#jerry_get_memory_stats) +## jerry_call_info_t + +**Summary** + +Call related information passed to [jerry_external_handler_t](#jerry_external_handler_t). + +**Prototype** + +```c +typedef struct jerry_call_info_t +{ + jerry_value_t function; /**< invoked function object */ + jerry_value_t this_value; /**< this value passed to the function */ + jerry_value_t new_target; /**< current new target value, undefined for non-constructor calls */ +} jerry_call_info_t; +``` + +*New in version [[NEXT_RELEASE]]*. + +**See also** + +- [jerry_external_handler_t](#jerry_external_handler_t) + ## jerry_external_handler_t **Summary** @@ -558,14 +688,13 @@ Type of an external function handler **Prototype** ```c -typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj, - const jerry_value_t this_val, +typedef jerry_value_t (*jerry_external_handler_t) (const jerry_call_info_t *call_info_p, const jerry_value_t args_p[], const jerry_length_t args_count); ``` -- `function_object` - the JavaScript function object which was invoked. -- `this_val` - the `this` value provided for the function call. +- `call_info_p` - pointer to a [jerry_call_info_t](#jerry_call_info_t) + structure which holds call related information. - `args_p` - the function arguments, array of JavaScript values. - `args_count` - the number of arguments. - return value @@ -575,11 +704,11 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_ - [jerry_create_external_function](#jerry_create_external_function) -## jerry_object_native_free_callback_t +## jerry_value_free_callback_t **Summary** -Native free callback of an object. It is used in `jerry_object_native_info_t` and for external Array buffers. +Native free callback of generic value types. *Note*: - Referred values by this method must have at least 1 reference. (Correct API usage satisfies this condition) @@ -587,17 +716,45 @@ Native free callback of an object. It is used in `jerry_object_native_info_t` an **Prototype** ```c -typedef void (*jerry_object_native_free_callback_t) (void *native_p); +typedef void (*jerry_value_free_callback_t) (void *native_p); ``` +*New in version [[NEXT_RELEASE]]*. + +**See also** + +- [jerry_create_external_string](#jerry_create_external_string) +- [jerry_create_external_string_sz](#jerry_create_external_string_sz) +- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) + +## jerry_object_native_free_callback_t + +**Summary** + +Native free callback of an object. The callback receives both the memory pointer and the type +information passed to [jerry_set_object_native_pointer](#jerry_set_object_native_pointer). + +*Note*: + - Referred values by this method must have at least 1 reference. (Correct API usage satisfies this condition) + +**Prototype** + +```c +typedef void (*jerry_object_native_free_callback_t) (void *native_p, struct jerry_object_native_info_t *info_p); +``` + +- `native_p` - native pointer passed to [jerry_set_object_native_pointer](#jerry_set_object_native_pointer). +- `info_p` - native type info passed to [jerry_set_object_native_pointer](#jerry_set_object_native_pointer). + *New in version 2.0*: Renamed from `jerry_object_free_callback_t`. *Changed in version 2.2*: API calls are once again allowed. (See note) +*Changed in version [[NEXT_RELEASE]]*: `info_p` argument is added + **See also** - [jerry_object_native_info_t](#jerry_object_native_info_t) -- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) ## jerry_error_object_created_callback_t @@ -626,37 +783,183 @@ typedef void (*jerry_error_object_created_callback_t) (const jerry_value_t error - [jerry_set_error_object_created_callback](#jerry_set_error_object_created_callback) +## jerry_module_state_t + +An enum representing the current status of a module + + - JERRY_MODULE_STATE_INVALID - Return value for jerry_module_get_state when its argument is not a module + - JERRY_MODULE_STATE_UNLINKED - Module is currently unlinked + - JERRY_MODULE_STATE_LINKING - Module is currently being linked + - JERRY_MODULE_STATE_LINKED - Module has been linked (its depencencies has been resolved) + - JERRY_MODULE_STATE_EVALUATING - Module is currently being evaluated + - JERRY_MODULE_STATE_EVALUATED - Module has been evaluated (its source code has been executed) + - JERRY_MODULE_STATE_ERROR - An error has been encountered before the evaluated state is reached + +*New in version [[NEXT_RELEASE]]*. + +## jerry_module_resolve_callback_t + +**Summary** + +Callback which is called by [jerry_module_link](#jerry_module_link) to get the referenced module. + +*Note*: + - If realms are enabled, the returned module should be created in the current realm + (see: [jerry_get_global_object](#jerry_get_global_object)) + +**Prototype** + +```c +typedef jerry_value_t (*jerry_module_resolve_callback_t) (const jerry_value_t specifier, + const jerry_value_t referrer, + void *user_p); +``` + +- `specifier` - a module specifier string (usually used as a path to the module) +- `referrer` - a module object which contains the `specifier` in its source code +- `user_p` - pointer passed to [jerry_module_link](#jerry_module_link). +- return value + - a module object - if it can be resolved successfully + - an error - otherwise + +*New in version [[NEXT_RELEASE]]*. + +**See also** +- [jerry_module_link](#jerry_module_link) +- [jerry_get_global_object](#jerry_get_global_object) + +## jerry_module_state_changed_callback_t + +**Summary** + +Callback which is called after the module enters into linked, evaluated or error state. + +**Prototype** + +```c +typedef void (*jerry_module_state_changed_callback_t) (jerry_module_state_t new_state, + const jerry_value_t module, + const jerry_value_t value, + void *user_p); +``` + +- `new_state` - new state of the module. +- `module` - a module whose state is changed +- `value` - depends on the state: undefined for linked, module script result for evaluated, + and error value for error state. +- `user_p` - pointer passed to [jerry_module_set_state_changed_callback](#jerry_module_set_state_changed_callback). + +*New in version [[NEXT_RELEASE]]*. + +**See also** +- [jerry_module_set_state_changed_callback](#jerry_module_set_state_changed_callback) + +## jerry_native_module_evaluate_callback_t + +**Summary** + +Callback which is called by [jerry_module_evaluate](#jerry_module_evaluate) to evaluate the native module. + +Note: + - Native pointers can be used to assign private data to a native module, + see [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) + +**Prototype** + +```c +typedef jerry_value_t (*jerry_native_module_evaluate_callback_t) (const jerry_value_t native_module); +``` + +- `native_module` - a native module +- return value + - any non-error value - if the module is evaluated successfully + - an error - otherwise + +*New in version [[NEXT_RELEASE]]*. + +**See also** +- [jerry_module_evaluate](#jerry_module_evaluate) + +## jerry_backtrace_callback_t + +**Summary** + +Callback function which is called by [jerry_backtrace_capture](#jerry_backtrace_capture) +for each stack frame. + +**Prototype** + +```c +typedef bool (*jerry_backtrace_callback_t) (jerry_backtrace_frame_t *frame_p, void *user_p); +``` + +- `frame_p` - pointer to [jerry_backtrace_frame_t](#jerry_backtrace_frame_t) data. +- `user_p` - pointer passed to [jerry_backtrace_capture](#jerry_backtrace_capture). +- return value + - true, to continue capturing more frames + - false, to end the stack capturing + +*New in version [[NEXT_RELEASE]]*. + +**See also** + +- [jerry_backtrace_capture](#jerry_backtrace_capture) +- [jerry_backtrace_frame_t](#jerry_backtrace_frame_t) + ## jerry_object_native_info_t **Summary** -The type information of the native pointer. -It includes the free callback that will be called when associated JavaScript object is garbage collected. It can be left NULL in case it is not needed. +Type information for native pointers. Since each native pointer has a type information, +multiple native pointers can be assigned to an object, and these can be updated or +deleted independently. -Typically, one would create a `static const jerry_object_native_info_t` for -each distinct C type for which a pointer is used with -`jerry_set_object_native_pointer ()` and `jerry_get_object_native_pointer ()`. -This way, each `const jerry_object_native_info_t *` pointer address value itself -uniquely identifies the C type of the native pointer. +The type information has a free callback, which is called when the object is freed +by the garbage collector. If the callback is NULL, the application is not notified +about the destruction of the object. -See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) -for a best-practice code example. +The buffer pointed by the native pointer can have a fixed number of jerry values, +which refer to other values as long as the object is alive. The starting byte +offset and the number of these values are specified by `offset_of_references` and +`number_of_references` fields respectively. Before a buffer is attached to an +object by [jerry_set_object_native_pointer](#jerry_set_object_native_pointer), +the values must be initialized to undefined by +[jerry_native_pointer_init_references](#jerry_native_pointer_init_references). +When a buffer is no longer attached to any object, the +[jerry_native_pointer_release_references](#jerry_native_pointer_release_references) +must be called to release the values. A single buffer can be attached to any +number of living objects. When a buffer is currently attached to at least +one object, the references can be updated by +[jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference). +However, if the buffer is no longer attached to an object, the finalize function +must be called even if the buffer is reattached to another object later. In this +case, calling the init function after the finalization is optional, because the +finalize function also initializes all values to undefined. **Prototype** ```c typedef struct { - jerry_object_native_free_callback_t free_cb; + jerry_object_native_free_callback_t free_cb; /**< the free callback of the native pointer */ + uint16_t number_of_references; /**< the number of value references which are marked by the garbage collector */ + uint16_t offset_of_references; /**< byte offset indicating the start offset of value + * references in the user allocated buffer */ } jerry_object_native_info_t; ``` *New in version 2.0*. +*Changed in version [[NEXT_RELEASE]]*: Added `number_of_references`, and `offset_of_references` fields. + **See also** - [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) - [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) +- [jerry_delete_object_native_pointer](#jerry_delete_object_native_pointer) +- [jerry_native_pointer_init_references](#jerry_native_pointer_init_references) +- [jerry_native_pointer_release_references](#jerry_native_pointer_release_references) +- [jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference) ## jerry_object_property_foreach_t @@ -781,6 +1084,130 @@ Possible values: - [jerry_get_promise_result](#jerry_get_promise_result) +## jerry_promise_event_type_t + +Event types for [jerry_promise_callback_t](#jerry_promise_callback_t) callback function. +The description of the `object` and `value` arguments are provided for each type. + +Possible values: + +- JERRY_PROMISE_EVENT_CREATE - A new Promise object is created. + - object - the new Promise object + - value - parent Promise for `then` chains, undefined otherwise. +- JERRY_PROMISE_EVENT_RESOLVE - Called when a Promise is about to be resolved. + - object - the Promise object + - value - value for resolving. +- JERRY_PROMISE_EVENT_REJECT - Called when a Promise is about to be rejected. + - object - the Promise object + - value - value for rejecting. +- JERRY_PROMISE_EVENT_RESOLVE_FULFILLED - Called when a resolve is called on a fulfilled Promise. + - object - the Promise object + - value - value for resolving +- JERRY_PROMISE_EVENT_REJECT_FULFILLED - Called when a reject is called on a fulfilled Promise. + - object - the Promise object + - value - value for rejecting +- JERRY_PROMISE_EVENT_REJECT_WITHOUT_HANDLER - Called when a Promise is rejected without a handler. + - object - the Promise object + - value - value for rejecting +- JERRY_PROMISE_EVENT_CATCH_HANDLER_ADDED - Called when a catch handler is added to a rejected + Promise which did not have a catch handler before. + - object - the Promise object + - value - undefined +- JERRY_PROMISE_EVENT_BEFORE_REACTION_JOB - Called before executing a Promise reaction job. + - object - the Promise object + - value - undefined +- JERRY_PROMISE_EVENT_AFTER_REACTION_JOB - Called after a Promise reaction job is completed. + - object - the Promise object + - value - undefined +- JERRY_PROMISE_EVENT_ASYNC_AWAIT - Called when an async function awaits the result of a Promise object. + - object - internal object representing the execution status + - value - the Promise object +- JERRY_PROMISE_EVENT_ASYNC_BEFORE_RESOLVE - Called when an async function is continued with resolve. + - object - internal object representing the execution status + - value - value for resolving +- JERRY_PROMISE_EVENT_ASYNC_BEFORE_REJECT - Called when an async function is continued with reject. + - object - internal object representing the execution status + - value - value for rejecting +- JERRY_PROMISE_EVENT_ASYNC_AFTER_RESOLVE - Called when an async function resolve is completed. + - object - internal object representing the execution status + - value - value for resolving +- JERRY_PROMISE_EVENT_ASYNC_AFTER_REJECT - Called when an async function reject is completed. + - object - internal object representing the execution status + - value - value for rejecting + +*New in version [[NEXT_RELEASE]]*. + +**See also** + +- [jerry_promise_callback_t](#jerry_promise_callback_t) +- [jerry_promise_set_callback](#jerry_promise_set_callback) + + +## jerry_promise_event_filter_t + +Filter types for [jerry_promise_set_callback](#jerry_promise_set_callback) callback function. +The callback is only called for those events which are enabled by the filters. The events are +described in [jerry_promise_event_type_t](#jerry_promise_event_type_t). + +Possible values: + +- JERRY_PROMISE_EVENT_FILTER_DISABLE - Disable reporting of all events. +- JERRY_PROMISE_EVENT_FILTER_MAIN - Enables the following events: + - JERRY_PROMISE_EVENT_CREATE + - JERRY_PROMISE_EVENT_RESOLVE + - JERRY_PROMISE_EVENT_REJECT +- JERRY_PROMISE_EVENT_FILTER_ERROR - Enables the following events: + - JERRY_PROMISE_EVENT_RESOLVE_FULFILLED + - JERRY_PROMISE_EVENT_REJECT_FULFILLED + - JERRY_PROMISE_EVENT_REJECT_WITHOUT_HANDLER + - JERRY_PROMISE_EVENT_CATCH_HANDLER_ADDED +- JERRY_PROMISE_EVENT_FILTER_REACTION_JOB - Enables the following events: + - JERRY_PROMISE_EVENT_BEFORE_REACTION_JOB + - JERRY_PROMISE_EVENT_AFTER_REACTION_JOB +- JERRY_PROMISE_EVENT_FILTER_ASYNC_MAIN - Enables the following events: + - JERRY_PROMISE_EVENT_ASYNC_AWAIT +- JERRY_PROMISE_EVENT_FILTER_ASYNC_REACTION_JOB - Enables the following events: + - JERRY_PROMISE_EVENT_ASYNC_BEFORE_RESOLVE + - JERRY_PROMISE_EVENT_ASYNC_BEFORE_REJECT + - JERRY_PROMISE_EVENT_ASYNC_AFTER_RESOLVE + - JERRY_PROMISE_EVENT_ASYNC_AFTER_REJECT + +*New in version [[NEXT_RELEASE]]*. + +**See also** + +- [jerry_promise_event_type_t](#jerry_promise_event_type_t) +- [jerry_promise_set_callback](#jerry_promise_set_callback) + + +## jerry_promise_callback_t + +**Summary** + +Notification callback for tracking Promise and async function operations. The arguments +passed to the callback depends on the `event_type` which is detailed in the +description of [jerry_promise_event_type_t](#jerry_promise_event_type_t). + +**Prototype** + +```c +typedef void (*jerry_promise_callback_t) (jerry_promise_event_type_t event_type, + const jerry_value_t object, const jerry_value_t value, + void *user_p); +``` + +- `event_type` - type of the event notification. +- `object` - object corresponding to the event. +- `value` - optional value argument. +- `user_data_p` - optional user data pointer supplied via the (jerry_promise_set_callback)[#jerry_promise_set_callback] method. + +*New in version [[NEXT_RELEASE]]*. + +**See also** + +- [jerry_promise_event_type_t](#jerry_promise_event_type_t) +- [jerry_promise_set_callback](#jerry_promise_set_callback) + ## jerry_typedarray_type_t Enum which describes the TypedArray types. @@ -1172,23 +1599,20 @@ is no longer needed. ```c jerry_value_t -jerry_parse (const jerry_char_t *resource_name_p, /**< resource name (usually a file name) */ - size_t resource_name_length, /**< length of resource name */ - const jerry_char_t *source_p, +jerry_parse (const jerry_char_t *source_p, size_t source_size, - uint32_t parse_opts); + const jerry_parse_options_t *options_p); ``` -- `resource_name_p` - resource name, usually a file name (must be a valid UTF8 string). -- `resource_name_length` - size of the resource name, in bytes. - `source_p` - string, containing source code to parse (must be a valid UTF8 string). - `source_size` - size of the string, in bytes. -- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags. +- `options_p` - additional parsing options, can be NULL if not used - return value - function object value, if script was parsed successfully, - thrown error, otherwise *Changed in version 2.0*: Added `resource_name_p`, and `resource_name_length` arguments. +*Changed in version [[NEXT_RELEASE]]*: The `resource_name_p`, `resource_name_length`, and `parse_opts` arguments are replaced by `options_p`. **Example** @@ -1203,8 +1627,17 @@ main (void) jerry_init (JERRY_INIT_EMPTY); const jerry_char_t script[] = "print ('Hello, World!');"; + const jerry_char_t file[] = "hello.js"; - jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_STRICT_MODE | JERRY_PARSE_HAS_RESOURCE | JERRY_PARSE_HAS_START; + parse_options.resource_name_p = file; + parse_options.resource_name_length = sizeof(file) - 1; + /* This example script is extracted from the middle of a file. */ + parse_options.start_line = 10; + parse_options.start_column = 1; + + jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, &parse_options); jerry_release_value (parsed_code); jerry_cleanup (); @@ -1216,6 +1649,7 @@ main (void) - [jerry_run](#jerry_run) - [jerry_parse_function](#jerry_parse_function) +- [jerry_parse_options_t](#jerry_parse_options_t) ## jerry_parse_function @@ -1235,27 +1669,24 @@ is no longer needed. ```c jerry_value_t -jerry_parse_function (const jerry_char_t *resource_name_p, /**< resource name (usually a file name) */ - size_t resource_name_length, /**< length of resource name */ - const jerry_char_t *arg_list_p, /**< script source */ - size_t arg_list_size, /**< script source size */ - const jerry_char_t *source_p, /**< script source */ - size_t source_size, /**< script source size */ - uint32_t parse_opts) /**< strict mode */ +jerry_parse_function (const jerry_char_t *arg_list_p, + size_t arg_list_size, + const jerry_char_t *source_p, + size_t source_size, + const jerry_parse_options_t *options_p); ``` -- `resource_name_p` - resource name, usually a file name (must be a valid UTF8 string). -- `resource_name_length` - size of the resource name, in bytes. - `arg_list_p` - argument list of the function (must be a valid UTF8 string). - `arg_list_size` - size of the argument list, in bytes. - `source_p` - string, containing source code to parse (must be a valid UTF8 string). - `source_size` - size of the string, in bytes. -- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags. +- `options_p` - additional parsing options, can be NULL if not used - return value - function object value, if script was parsed successfully, - thrown error, otherwise *New in version 2.0*. +*Changed in version [[NEXT_RELEASE]]*: The `resource_name_p`, `resource_name_length`, and `parse_opts` arguments are replaced by `options_p`. **Example** @@ -1278,13 +1709,11 @@ main (void) const char function_args[] = "a, b"; const char function_source[] = "return a + b"; - jerry_value_t parsed_function = jerry_parse_function (NULL, - 0, - (const jerry_char_t *) function_args, + jerry_value_t parsed_function = jerry_parse_function ((const jerry_char_t *) function_args, strlen (function_args), (const jerry_char_t *) function_source, strlen (function_source), - JERRY_PARSE_NO_OPTS); + NULL); if (!jerry_value_is_error (parsed_function)) { @@ -1329,13 +1758,14 @@ main (void) **See also** - [jerry_call_function](#jerry_call_function) +- [jerry_parse_options_t](#jerry_parse_options_t) ## jerry_run **Summary** -Run an EcmaScript function created by `jerry_parse`. +Run a Script or Module created by [jerry_parse](#jerry_parse). *Notes*: - The code should be previously parsed with `jerry_parse`. @@ -1370,7 +1800,7 @@ main (void) jerry_init (JERRY_INIT_EMPTY); /* Setup Global scope code */ - jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); + jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL); if (!jerry_value_is_error (parsed_code)) { @@ -1414,7 +1844,8 @@ jerry_eval (const jerry_char_t *source_p, - `source_p` - source code to evaluate, it must be a valid utf8 string. - `source_size` - length of the source code -- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags. +- `parse_opts` - combination of [jerry_parse_option_enable_feature_t](#jerry_parse_option_enable_feature_t) flags. + The following flags are allowed: JERRY_PARSE_STRICT_MODE - return value - result of eval, may be an error value. **Example** @@ -1469,7 +1900,7 @@ main (void) const jerry_char_t script[] = "new Promise(function(f,r) { f('Hello, World!'); }).then(function(x) { print(x); });"; - jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); + jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL); jerry_value_t script_value = jerry_run (parsed_code); jerry_value_t job_value; @@ -1710,6 +2141,85 @@ jerry_value_is_boolean (const jerry_value_t value) - [jerry_release_value](#jerry_release_value) +## jerry_value_is_true + +**Summary** + +Returns whether the given `jerry_value_t` is a true value. + +**Prototype** + +```c +bool +jerry_value_is_true (const jerry_value_t value); +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is true value + - false, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_true (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) + +## jerry_value_is_false + +**Summary** + +Returns whether the given `jerry_value_t` is a false value. + +**Prototype** + +```c +bool +jerry_value_is_false (const jerry_value_t value); +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is false value + - false, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_false (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerry_release_value) ## jerry_value_is_constructor @@ -2120,10 +2630,10 @@ jerry_value_is_proxy (const jerry_value_t value) - true, if the given `jerry_value_t` is a proxy object - false, otherwise -**Example** - *New in version 2.3*. +**Example** + ```c { jerry_value_t value; @@ -2142,6 +2652,7 @@ jerry_value_is_proxy (const jerry_value_t value) - [jerry_release_value](#jerry_release_value) - [jerry_create_proxy](#jerry_create_proxy) +- [jerry_create_special_proxy](#jerry_create_special_proxy) ## jerry_value_is_string @@ -2377,8 +2888,6 @@ Checks whether the given `jerry_value_t` is the given `jerry_container_type_t` t see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). - The es.next profile enables this by default. -*New in version 2.3*. - **Prototype** ```c @@ -2390,6 +2899,9 @@ jerry_get_container_type (const jerry_value_t value) - return value - The corresponding enum value of `jerry_container_type_t`, or `JERRY_CONTAINER_TYPE_INVALID` if the container was not a valid container object. + +*New in version 2.3*. + **Example** [doctest]: # () @@ -2721,7 +3233,7 @@ jerry_binary_operation (jerry_binary_operation_t op, if (!jerry_value_is_error (result)) { - if (jerry_get_boolean_value (result)) + if (jerry_value_is_true (result)) { // value1 and value2 are equal } @@ -2749,8 +3261,7 @@ jerry_binary_operation (jerry_binary_operation_t op, #include "jerryscript.h" static jerry_value_t -my_constructor (const jerry_value_t func_val, - const jerry_value_t this_val, +my_constructor (const jerry_call_info_t *call_info_p, const jerry_value_t argv[], const jerry_length_t argc) { @@ -2778,7 +3289,7 @@ main (void) instance_val, constructor); if (!jerry_value_is_error (is_instance) - && jerry_get_boolean_value (is_instance) == true) + && jerry_value_is_true (is_instance)) { /* ... */ } @@ -3090,48 +3601,6 @@ void main(void) Get raw data from API values. -## jerry_get_boolean_value - -**Summary** - -Gets the raw bool value from a `jerry_value_t`. - -**Prototype** - -```c -bool -jerry_get_boolean_value (const jerry_value_t value); -``` - -- `value` - api value -- return value - boolean value represented by the argument. - -**Example** - -```c -{ - jerry_value_t value; - ... // create or acquire value - - if (jerry_value_is_boolean (value)) - { - bool raw_value = jerry_get_boolean_value (value); - - ... // usage of raw value - - } - - jerry_release_value (value); -} - -``` - -**See also** - -- [jerry_value_is_boolean](#jerry_value_is_boolean) -- [jerry_release_value](#jerry_release_value) - - ## jerry_get_number_value **Summary** @@ -3895,6 +4364,8 @@ jerry_value_as_integer (const jerry_value_t value); - 0, if value is not a number - integer representation of the number, otherwise +*New in version 2.4*. + **Example** ```c @@ -3924,6 +4395,8 @@ jerry_value_as_int32 (const jerry_value_t value); - 0, if value is not a number - int32 representation of the number, otherwise +*New in version 2.4*. + **Example** ```c @@ -3953,6 +4426,8 @@ jerry_value_as_uint32 (const jerry_value_t value); - 0, if value is not a number - uint32 representation of the number, otherwise +*New in version 2.4*. + **Example** ```c @@ -3963,6 +4438,702 @@ jerry_value_as_uint32 (const jerry_value_t value); } ``` +# Functions for module objects + +These APIs all depend on module support. + +## jerry_module_link + +**Summary** + +Link modules to their dependencies. The dependencies are resolved by a user callback. + +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it + is no longer needed. +- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_value_t jerry_module_link (const jerry_value_t module_val, + jerry_module_resolve_callback_t callback, void *user_p) +``` + +- `module_val` - module object in unlinked state +- `callback` - user callback which is called to resolve dependencies, + uses `jerry_port_module_resolve` when NULL is passed +- `user_p` - user pointer passed to the callback +- return + - true - if linking is successful + - error - otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include + +static jerry_value_t +module_resolve_callback (const jerry_value_t specifier, + const jerry_value_t referrer, + void *user_data_p) +{ + /* In this case, the specifier contains 'b.mjs', and the referrer is the module + * created in the main() function below. Normally the specifier string should be + * extended to a full file system path, and it should be checked whether a module + * corresponding to this path has been loaded already. For simplicity, this function + * returns with a new module. */ + + const jerry_char_t script[] = "export var a = 5"; + const jerry_char_t file[] = "b.mjs"; + + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = file; + parse_options.resource_name_length = sizeof (file) - 1; + + return jerry_parse (script, sizeof (script) - 1, &parse_options); +} /* module_resolve_callback */ + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + const jerry_char_t script[] = "import a from 'b.mjs'"; + const jerry_char_t file[] = "a.mjs"; + + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = file; + parse_options.resource_name_length = sizeof (file) - 1; + + jerry_value_t ret_value = jerry_parse (script, sizeof (script) - 1, &parse_options); + + jerry_module_link (ret_value, module_resolve_callback, NULL); + + jerry_release_value (ret_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** +- [jerry_module_resolve_callback_t](#jerry_module_resolve_callback_t) + +## jerry_module_evaluate + +Evaluate a module and its dependencies. The module must be in linked state. + +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_value_t jerry_module_evaluate (const jerry_value_t module_val); +``` + +- `module_val` - module object +- return + - result of module bytecode execution - if evaluation was successful + - error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include +#include + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + const jerry_char_t script[] = "export var a = 6"; + const jerry_char_t file[] = "a.mjs"; + + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = file; + parse_options.resource_name_length = sizeof (file) - 1; + + jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); + + jerry_release_value (jerry_module_link (module_value, NULL, NULL)); + jerry_release_value (jerry_module_evaluate (module_value)); + + jerry_release_value (module_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_module_link](#jerry_module_link) + +## jerry_module_get_state + +**Summary** + +Returns the current status of a module. The available values +are listed in [jerry_module_state_t](#jerry_module_state_t) + +*Notes*: +- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_module_state_t jerry_module_get_state (const jerry_value_t module_val); +``` + +- `module_val` - module object +- return + - current status - if module_val is a module + - JERRY_MODULE_STATE_INVALID - otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include +#include + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + const jerry_char_t script[] = "import a from 'b.mjs'"; + const jerry_char_t file[] = "a.mjs"; + + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = file; + parse_options.resource_name_length = sizeof (file) - 1; + + jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); + + if (jerry_module_get_state (module_value) == JERRY_MODULE_STATE_UNLINKED) + { + printf ("Module parsing has been successful\n"); + } + + jerry_release_value (module_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_module_state_t](#jerry_module_state_t) + +## jerry_module_set_state_changed_callback + +**Summary** + +Sets a callback which is called after a module state is changed to linked, evaluated, or error. + +*Notes*: +- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +void +jerry_module_set_state_changed_callback (jerry_module_state_changed_callback_t callback, + void *user_p) +``` + +- `callback` - callback, which is called after the state change. +- `module_val` - pointer passed to the callback function. + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include +#include + +static void +module_state_changed (jerry_module_state_t new_state, /**< new state of the module */ + const jerry_value_t module_val, /**< a module whose state is changed */ + const jerry_value_t value, /**< value argument */ + void *user_p) /**< user pointer */ +{ + (void) module_val; + (void) value; + (void) user_p; + + if (new_state == JERRY_MODULE_STATE_LINKED) + { + printf ("A module is entered into linked state\n"); + } +} /* module_state_changed */ + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + const jerry_char_t script[] = "12"; + const jerry_char_t file[] = "a.mjs"; + + jerry_module_set_state_changed_callback (module_state_changed, NULL); + + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = file; + parse_options.resource_name_length = sizeof (file) - 1; + + jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); + + jerry_release_value (jerry_module_link (module_value, NULL, NULL)); + + jerry_release_value (module_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_module_state_t](#jerry_module_state_t) +- [jerry_module_state_changed_callback_t](#jerry_module_state_changed_callback_t) + +## jerry_module_get_number_of_requests + +**Summary** + +Returns the number of import/export requests of a module. +The requests can be queried by [jerry_module_get_request](#jerry_module_get_request). + + +*Notes*: +- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +size_t jerry_module_get_number_of_requests (const jerry_value_t module_val); +``` + +- `module_val` - module object +- return + - number of import/export requests of a module, if `module_val` is module, + - 0, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include +#include + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + const jerry_char_t script[] = "export * from 'b.mjs'" + "import a from 'c.mjs'"; + const jerry_char_t file[] = "a.mjs"; + + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = file; + parse_options.resource_name_length = sizeof (file) - 1; + + jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); + + /* Prints 2. */ + printf ("Number of requests: %d\n", (int) jerry_module_get_number_of_requests (module_value)); + + jerry_release_value (module_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_module_get_request](#jerry_module_get_request) +- [jerry_parse](#jerry_parse) +- [jerry_module_link](#jerry_module_link) + +## jerry_module_get_request + +**Summary** + +Returns the module request specified by the `request_index` argument. The requests +are ordered in source code occurence. When parsing is completed, all returned values +are strings. If [jerry_module_link](#jerry_module_link) is completed successfully +all returned values are module objects instead. If linking is in progress or fails, +the successfully resolved dependencies are module objects, the rest are strings. +The number of requests can be queried by +[jerry_module_get_number_of_requests](#jerry_module_get_number_of_requests). + +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_value_t jerry_module_get_request (const jerry_value_t module_val, size_t request_index); +``` + +- `module_val` - module object +- return + - string, if the request has not been resolved yet + - module object, if the request has been resolved successfully + - error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + const jerry_char_t script[] = "export * from 'b.mjs'" + "import a from 'c.mjs'"; + const jerry_char_t file[] = "a.mjs"; + + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = file; + parse_options.resource_name_length = sizeof (file) - 1; + + jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); + + jerry_value_t request_value = jerry_module_get_request (module_value, 0); + /* Returns with b.mjs */ + jerry_release_value (request_value); + + request_value = jerry_module_get_request (module_value, 1); + /* Returns with c.mjs */ + jerry_release_value (request_value); + + jerry_release_value (module_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_module_get_number_of_requests](#jerry_module_get_number_of_requests) +- [jerry_parse](#jerry_parse) +- [jerry_module_link](#jerry_module_link) + +## jerry_module_get_namespace + +Returns the namespace object of a module + +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_value_t jerry_module_get_namespace (const jerry_value_t module_val); +``` + +- `module_val` - module object +- return + - object, if namespace object is available + - error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include +#include + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + const jerry_char_t script[] = "export var a = 6"; + const jerry_char_t file[] = "a.mjs"; + + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = file; + parse_options.resource_name_length = sizeof (file) - 1; + + jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options); + + jerry_release_value (jerry_module_link (module_value, NULL, NULL)); + jerry_release_value (jerry_module_evaluate (module_value)); + + jerry_value_t namespace_value = jerry_module_get_namespace (module_value); + + /* Exports can be checked. */ + + jerry_release_value (namespace_value); + jerry_release_value (module_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_module_link](#jerry_module_link) +- [jerry_module_evaluate](#jerry_module_evaluate) + +## jerry_native_module_create + +Creates a native module with a list of exports. The initial state of the module is linked. + +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- Native pointers can be used to assign private data to a native module, + see [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) +- When `callback` is `NULL`, no function is called when the module is evaluated, + only its state is changed to evaluated. +- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_value_t +jerry_native_module_create (jerry_native_module_evaluate_callback_t callback, + const jerry_value_t * const exports_p, + size_t number_of_exports); +``` + +- `callback` - a [jerry_native_module_evaluate_callback_t](#jerry_native_module_evaluate_callback_t) callback + which is called by [jerry_module_evaluate](#jerry_module_evaluate) to evaluate the native module. +- `exports_p` - list of the exported bindings of the module, must be valid string identifiers. +- `number_of_exports` - number of exports in the `exports_p` list. +- return + - a native module, if the module is successfully created + - error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t exports[2] = + { + jerry_create_string ((const jerry_char_t *) "first_export"), + jerry_create_string ((const jerry_char_t *) "second_export") + }; + + jerry_value_t native_module = jerry_native_module_create (NULL, exports, 2); + + jerry_release_value (exports[0]); + jerry_release_value (exports[1]); + jerry_release_value (native_module); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_module_link](#jerry_module_link) +- [jerry_module_evaluate](#jerry_module_evaluate) +- [jerry_native_module_get_export](#jerry_native_module_get_export) +- [jerry_native_module_set_export](#jerry_native_module_set_export) + +## jerry_native_module_get_export + +Gets the value of an export binding which belongs to a native module. + +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_value_t +jerry_native_module_get_export (const jerry_value_t native_module_val, + const jerry_value_t export_name_val); +``` + +- `module_val` - a native module object. +- `export_name_val` - string identifier of the export. +- return + - value of the export, if success + - error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t export = jerry_create_string ((const jerry_char_t *) "an_export"); + + jerry_value_t native_module = jerry_native_module_create (NULL, &export, 1); + + jerry_value_t value = jerry_native_module_get_export (native_module, export); + jerry_release_value (value); + + jerry_release_value (export); + jerry_release_value (native_module); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_native_module_create](#jerry_native_module_create) +- [jerry_native_module_set_export](#jerry_native_module_set_export) + +## jerry_native_module_set_export + +Sets the value of an export binding which belongs to a native module. + +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_value_t +jerry_value_t jerry_native_module_set_export (const jerry_value_t native_mmodule_val, + const jerry_value_t export_name_val, + const jerry_value_t value_to_set) +``` + +- `module_val` - a native module object. +- `export_name_val` - string identifier of the export. +- `value_to_set` - new value of the export. +- return + - true, if success + - error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t export = jerry_create_string ((const jerry_char_t *) "an_export"); + + jerry_value_t native_module = jerry_native_module_create (NULL, &export, 1); + + jerry_value_t number = jerry_create_number (3.5); + jerry_value_t value = jerry_native_module_set_export (native_module, export, number); + jerry_release_value (value); + jerry_release_value (number); + + jerry_release_value (export); + jerry_release_value (native_module); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_native_module_create](#jerry_native_module_create) +- [jerry_native_module_get_export](#jerry_native_module_get_export) + # Functions for promise objects These APIs all depend on the es.next profile (or on some build options). @@ -4105,6 +5276,81 @@ example (void) - [jerry_create_promise](#jerry_create_promise) - [jerry_promise_state_t](#jerry_promise_state_t) +## jerry_promise_set_callback + +**Summary** + +Sets a callback for tracking Promise and async operations. + +*Notes*: +- This API depends on a build option (`JERRY_PROMISE_CALLBACK`) and can be checked + in runtime with the `JERRY_FEATURE_PROMISE_CALLBACK` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + + +**Prototype** + +```c +void jerry_promise_set_callback (jerry_promise_event_filter_t filters, jerry_promise_callback_t callback, + void *user_p); +``` + +- `filters` - combination of [jerry_promise_event_filter_t](#jerry_promise_event_filter_t) options +- `callback` - callback function, the previously set value is overwritten, + and setting NULL disables the tracking +- `user_p` - pointer passed to the callback function, can be NULL + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # () + +```c +#include +#include +#include "jerryscript.h" + +static void +promise_callback (jerry_promise_event_type_t event_type, /**< event type */ + const jerry_value_t object, /**< target object */ + const jerry_value_t value, /**< optional argument */ + void *user_p) /**< user pointer passed to the callback */ +{ + if (event_type == JERRY_PROMISE_EVENT_CREATE) + { + printf ("A new promise is created\n"); + + if (!jerry_value_is_undefined (value)) + { + printf (" The Promise is created by Promise.then() built-in.\n"); + } + } +} /* promise_callback */ + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_promise_set_callback (JERRY_PROMISE_EVENT_FILTER_MAIN, promise_callback, NULL); + + const char *source_p = "var p = Promise.resolve(0)\n" + "p.then(function (v) { return v; })"; + jerry_release_value (jerry_eval ((const jerry_char_t *) source_p, + strlen (source_p), + JERRY_PARSE_NO_OPTS)); + + jerry_cleanup (); + return 0; +} /* main */ +``` + +**See also** + +- [jerry_create_promise](#jerry_create_promise) +- [jerry_promise_state_t](#jerry_promise_state_t) + ## jerry_from_property_descriptor **Summary** @@ -4129,6 +5375,8 @@ jerry_from_property_descriptor (const jerry_property_descriptor_t *src_prop_desc - jerry value - if success - value marked with error flag - otherwise +*New in version 2.4*. + **Example** [doctest]: # (test="compile") @@ -4141,17 +5389,16 @@ 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); + jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); prop_desc.value = prop_name; - prop_desc.is_value_defined = true; + prop_desc.flags |= JERRY_PROP_IS_VALUE_DEFINED; 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_property_descriptor_free (&prop_desc); } ``` @@ -4204,7 +5451,7 @@ example (void) jerry_release_value (object); jerry_release_value (prop_name); jerry_release_value (value); - jerry_free_property_descriptor_fields (&prop_desc); + jerry_property_descriptor_free (&prop_desc); } ``` @@ -4597,7 +5844,7 @@ These APIs all depend on build option (`JERRY_BUILTIN_PROXY`). **Summary** -Gets the target object of a Proxy object +Gets the target object of a Proxy object. *Notes*: - This API depends on a build option (`JERRY_BUILTIN_PROXY`) and can be checked @@ -4610,7 +5857,7 @@ Gets the target object of a Proxy object ```c jerry_value_t -jerry_get_proxy_target (jerry_value_t proxy_value) +jerry_get_proxy_target (jerry_value_t proxy_value); ``` - `proxy_value` - Proxy object value @@ -4643,6 +5890,61 @@ jerry_get_proxy_target (jerry_value_t proxy_value) **See also** - [jerry_create_proxy](#jerry_create_proxy) +- [jerry_create_special_proxy](#jerry_create_special_proxy) +- [jerry_get_proxy_handler](#jerry_get_proxy_handler) + +## jerry_get_proxy_handler + +**Summary** + +Gets the handler 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_handler (jerry_value_t proxy_value); +``` + +- `proxy_value` - Proxy object value +- return value + - type error - if proxy_value is not a Proxy object + - handler object - otherwise + +*New in version [[NEXT_RELEASE]]*. + +**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); + + handler = jerry_get_proxy_handler (proxy); + + // ... usage of the handler + + jerry_release_value (handler); + jerry_release_value (proxy); +} +``` + +**See also** + +- [jerry_create_proxy](#jerry_create_proxy) +- [jerry_create_special_proxy](#jerry_create_special_proxy) +- [jerry_get_proxy_target](#jerry_get_proxy_target) # Acquire and release API values @@ -4826,7 +6128,7 @@ so the user can release the buffer which was provided. jerry_value_t jerry_create_arraybuffer_external (const jerry_length_t size uint8_t *buffer_p, - jerry_object_native_free_callback_t free_cb); + jerry_value_free_callback_t free_cb); ``` - `size` - size of the buffer to use **in bytes** (should not be 0) @@ -4838,6 +6140,8 @@ jerry_create_arraybuffer_external (const jerry_length_t size *New in version 2.0*. +*Changed in version [[NEXT_RELEASE]]*: type of `free_cb` has been changed. + **Example** ```c @@ -5071,12 +6375,11 @@ jerry_create_external_function (jerry_external_handler_t handler_p); #include "jerryscript.h" static jerry_value_t -handler (const jerry_value_t function_obj, - const jerry_value_t this_val, +handler (const jerry_call_info_t *call_info_p, const jerry_value_t args_p[], const jerry_length_t args_cnt) { - printf ("native handler called!\n"); + printf ("Native handler called!\n"); return jerry_create_boolean (true); } @@ -5354,7 +6657,7 @@ Create a new Proxy object with the given target and handler. ```c jerry_value_t jerry_create_proxy (const jerry_value_t target, - const jerry_value_t handler) + const jerry_value_t handler); ``` - `target` - proxy target @@ -5362,10 +6665,10 @@ jerry_create_proxy (const jerry_value_t target, - return thrown error - if the Proxy construction fails value of the newly created proxy object - otherwise -**Example** - *New in version 2.3*. +**Example** + [doctest]: # () ```c @@ -5394,6 +6697,70 @@ main (void) **See also** - [jerry_value_is_proxy](#jerry_value_is_proxy) +- [jerry_create_special_proxy](#jerry_create_special_proxy) +- [jerry_release_value](#jerry_release_value) + + +## jerry_create_special_proxy + +**Summary** + +Create a new Proxy object with the given target and handler. +The behaviour of the Proxy can be specialized with an options argument. + +*Note*: + - This API depends on the es.next profile. + - Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_create_special_proxy (const jerry_value_t target, + const jerry_value_t handler, + uint32_t options); +``` + +- `target` - proxy target +- `handler` - proxy handler +- `options` - any combination of [jerry_proxy_object_options_t](#jerry_proxy_object_options_t) options +- return thrown error - if the Proxy construction fails + value of the newly created proxy object - otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t target = jerry_create_object (); + jerry_value_t handler = jerry_create_object (); + jerry_value_t proxy = jerry_create_special_proxy (target, handler, JERRY_PROXY_SKIP_RESULT_VALIDATION); + + jerry_release_value (target); + jerry_release_value (handler); + + // usage of the proxy + + jerry_release_value (proxy); + + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_value_is_proxy](#jerry_value_is_proxy) +- [jerry_create_special_proxy](#jerry_create_special_proxy) - [jerry_release_value](#jerry_release_value) @@ -5581,7 +6948,7 @@ is no longer needed. ```c jerry_value_t jerry_create_external_string (const jerry_char_t *str_p, - jerry_object_native_free_callback_t free_cb) + jerry_value_free_callback_t free_cb) ``` - `str_p` - non-null pointer to string @@ -5590,6 +6957,8 @@ jerry_create_external_string (const jerry_char_t *str_p, *New in version 2.4*. +*Changed in version [[NEXT_RELEASE]]*: type of `free_cb` has been changed. + **Example** ```c @@ -5627,7 +6996,7 @@ is no longer needed. jerry_value_t jerry_create_external_string_sz (const jerry_char_t *str_p, jerry_size_t str_size, - jerry_object_native_free_callback_t free_cb) + jerry_value_free_callback_t free_cb) ``` - `str_p` - non-null pointer to string @@ -5637,6 +7006,8 @@ jerry_create_external_string_sz (const jerry_char_t *str_p, *New in version 2.4*. +*Changed in version [[NEXT_RELEASE]]*: type of `free_cb` has been changed. + **Example** ```c @@ -6047,8 +7418,6 @@ Create a jerry_value_t representing a given type container object. see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). - The es.next profile enables this by default. -*New in version 2.3*. - **Prototype** ```c @@ -6063,6 +7432,8 @@ jerry_create_container (jerry_container_type_t container_type, - `arguments_list_len` - The length of the above arguments. - return value - the new container object as a `jerry_value_t` +*New in version 2.3*. + **Example** [doctest]: # () @@ -6133,6 +7504,14 @@ jerry_create_undefined (void); Creates a `jerry_value_t` representing a new global object. +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- This API depends on a 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 @@ -6146,13 +7525,24 @@ jerry_create_realm (void); **Example** +[doctest]: # () + ```c +#include "jerryscript.h" + +int +main (void) { + jerry_init (JERRY_INIT_EMPTY); + jerry_value_t realm_value = jerry_create_realm (); - ... // usage of the value + // usage of the value jerry_release_value (realm_value); + jerry_cleanup (); + + return 0; } ``` @@ -6206,7 +7596,7 @@ main (void) jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field"); jerry_value_t has_prop_js = jerry_has_property (global_object, prop_name); - bool has_prop = jerry_get_boolean_value (has_prop_js); + bool has_prop = jerry_value_is_true (has_prop_js); jerry_release_value (has_prop_js); jerry_release_value (prop_name); @@ -6267,7 +7657,7 @@ main (void) jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field"); jerry_value_t has_prop_js = jerry_has_own_property (global_object, prop_name); - bool has_prop = jerry_get_boolean_value (has_prop_js); + bool has_prop = jerry_value_is_true (has_prop_js); jerry_release_value (has_prop_js); jerry_release_value (prop_name); @@ -6591,6 +7981,77 @@ jerry_get_property_by_index (const jerry_value_t obj_val, - [jerry_set_property](#jerry_set_property) - [jerry_set_property_by_index](#jerry_set_property_by_index) +## jerry_get_own_property + +**Summary** + +Get the own property value of an object with the given name. The function tells +whether the property is found, and the receiver object can be specified as well. +The receiver is passed as the `this` argument for getters, and the receiver +argument for Proxy `get` traps. + +*Notes*: + - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. + - The `found_p` argument is ignored if its value is NULL. + - The target value of `found_p` argument is set to false when the arguments are invalid, e.g. `obj_val` is not an object. + +**Prototype** + +```c +jerry_value_t +jerry_get_own_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + const jerry_value_t receiver_val, + bool *found_p); +``` + +- `obj_val` - object value +- `prop_name_val` - property name +- `receiver_val` - receiver object +- `found_p` - [out] true, if the property is found or obj_val is a Proxy object, false otherwise +- return value + - value of property, if success + - thrown error, otherwise + +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" +#include "stdio.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "Object"); + + bool found; + jerry_value_t prop_value = jerry_get_own_property (global_object, prop_name, global_object, &found); + + if (found) + { + printf ("Property is found!\n"); + } + + /* use "prop_value" then release it. */ + + jerry_release_value (prop_value); + jerry_release_value (prop_name); + jerry_release_value (global_object); + + return 0; +} +``` + +**See also** + +- [jerry_get_property](#jerry_get_property) +- [jerry_get_property_by_index](#jerry_get_property_by_index) + ## jerry_get_internal_property **Summary** @@ -6834,32 +8295,31 @@ main (void) - [jerry_get_internal_property](#jerry_get_internal_property) -## jerry_init_property_descriptor_fields +## jerry_property_descriptor_create **Summary** -Initialize property descriptor. This means that all fields in the `jerry_property_descriptor_t` -struct will be set to zero or false depending on the field's type. +Create a property descriptor and initialize it with default values. This means that all fields in +the `jerry_property_descriptor_t` struct will be set to zero or false depending on the field's type. **Prototype** ```c -void -jerry_init_property_descriptor_fields (jerry_property_descriptor_t *prop_desc_p); +jerry_property_descriptor_t +jerry_property_descriptor_create (void); ``` -- `prop_desc_p` - pointer to property descriptor +*New in version [[NEXT_RELEASE]]*: Replaces `jerry_init_property_descriptor_fields`. **Example** ```c { - jerry_property_descriptor_t prop_desc; - jerry_init_property_descriptor_fields (&prop_desc); + jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); ... // usage of prop_desc - jerry_free_property_descriptor_fields (&prop_desc); + jerry_property_descriptor_free (&prop_desc); } ``` @@ -6870,7 +8330,7 @@ For a more complete example see [jerry_define_own_property](#jerry_define_own_pr - [jerry_property_descriptor_t](#jerry_property_descriptor_t) - [jerry_define_own_property](#jerry_define_own_property) - [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) -- [jerry_free_property_descriptor_fields](#jerry_free_property_descriptor_fields) +- [jerry_property_descriptor_free](#jerry_property_descriptor_free) ## jerry_define_own_property @@ -6915,19 +8375,23 @@ main (void) jerry_value_t global_obj_val = jerry_get_global_object (); // configure the property - jerry_property_descriptor_t prop_desc; - jerry_init_property_descriptor_fields (&prop_desc); - - jerry_value_t value_to_set; + jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); // create or acquire value to set // For example: - value_to_set = jerry_create_number (33); + jerry_value_t value_to_set = jerry_create_number (33); // set the property descriptor fields: - // set the "is_value_defined" field to "true" to indicate the "value" + // set the "JERRY_PROP_IS_VALUE_DEFINED" flag to indicate the "value" // field should be used during the property registration. - prop_desc.is_value_defined = true; + // set the writable, configurable, enumerable flags to true + prop_desc.flags |= (JERRY_PROP_IS_WRITABLE_DEFINED + | JERRY_PROP_IS_WRITABLE + | JERRY_PROP_IS_CONFIGURABLE_DEFINED + | JERRY_PROP_IS_CONFIGURABLE + | JERRY_PROP_IS_ENUMERABLE_DEFINED + | JERRY_PROP_IS_ENUMERABLE + | JERRY_PROP_IS_VALUE_DEFINED); // set the "value" field to the number 33 prop_desc.value = value_to_set; @@ -6940,12 +8404,20 @@ main (void) // there was an error } + // re-define the property with the enumerable flag set to false + prop_desc.flags &= (uint16_t) ~JERRY_PROP_IS_ENUMERABLE; + return_value = jerry_define_own_property (global_obj_val, prop_name, &prop_desc); + if (jerry_value_is_error (return_value)) + { + // there was an error + } + // if there was no error at this point the global object should have a "my_prop" property jerry_release_value (return_value); jerry_release_value (prop_name); - jerry_free_property_descriptor_fields (&prop_desc); + jerry_property_descriptor_free (&prop_desc); jerry_release_value (global_obj_val); jerry_cleanup (); @@ -6966,8 +8438,7 @@ Registering a getter/setter property via the `jerry_define_own_property` method: static int counter = 0; static jerry_value_t -method_getter (const jerry_value_t this_obj, - const jerry_value_t func_obj, +method_getter (const jerry_call_info_t *call_info_p, const jerry_value_t args[], const jerry_length_t argc) { @@ -6978,8 +8449,7 @@ method_getter (const jerry_value_t this_obj, } static jerry_value_t -method_setter (const jerry_value_t this_obj, - const jerry_value_t func_obj, +method_setter (const jerry_call_info_t *call_info_p, const jerry_value_t args[], const jerry_length_t argc) { @@ -7002,14 +8472,12 @@ main (void) jerry_value_t global_obj_val = jerry_get_global_object (); // configure the property - jerry_property_descriptor_t prop_desc; - jerry_init_property_descriptor_fields (&prop_desc); + jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); // set the property descriptor fields: - prop_desc.is_get_defined = true; + prop_desc.flags |= JERRY_PROP_IS_GET_DEFINED | JERRY_PROP_IS_SET_DEFINED; prop_desc.getter = jerry_create_external_function (method_getter); - prop_desc.is_set_defined = true; prop_desc.setter = jerry_create_external_function (method_setter); // add the property as "my_prop" for the global object @@ -7025,7 +8493,7 @@ main (void) jerry_release_value (return_value); jerry_release_value (prop_name); - jerry_free_property_descriptor_fields (&prop_desc); + jerry_property_descriptor_free (&prop_desc); jerry_release_value (global_obj_val); // run an example js code to use the getter/setters @@ -7046,9 +8514,9 @@ main (void) **See also** - [jerry_property_descriptor_t](#jerry_property_descriptor_t) -- [jerry_init_property_descriptor_fields](#jerry_init_property_descriptor_fields) +- [jerry_property_descriptor_create](#jerry_property_descriptor_create) - [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) -- [jerry_free_property_descriptor_fields](#jerry_free_property_descriptor_fields) +- [jerry_property_descriptor_free](#jerry_property_descriptor_free) ## jerry_get_own_property_descriptor @@ -7060,7 +8528,7 @@ Construct property descriptor from specified property. **Prototype** ```c -bool +jerry_value_t jerry_get_own_property_descriptor (const jerry_value_t obj_val, const jerry_value_t prop_name_val, jerry_property_descriptor_t *prop_desc_p); @@ -7071,14 +8539,15 @@ jerry_get_own_property_descriptor (const jerry_value_t obj_val, - `prop_desc_p` - pointer to property descriptor - return value +*Changed in version [[NEXT_RELEASE]]*: return value is changed to `jerry_value_t` + **Example** ```c { jerry_value_t global_obj_val = jerry_get_global_object (); - jerry_property_descriptor_t prop_desc; - jerry_init_property_descriptor_fields (&prop_desc); + jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); jerry_get_own_property_descriptor (global_obj_val, prop_name, &prop_desc); @@ -7086,7 +8555,7 @@ jerry_get_own_property_descriptor (const jerry_value_t obj_val, ... // usage of property descriptor - jerry_free_property_descriptor_fields (&prop_desc); + jerry_property_descriptor_free (&prop_desc); jerry_release_value (global_obj_val); } ``` @@ -7094,12 +8563,12 @@ jerry_get_own_property_descriptor (const jerry_value_t obj_val, **See also** - [jerry_property_descriptor_t](#jerry_property_descriptor_t) -- [jerry_init_property_descriptor_fields](#jerry_init_property_descriptor_fields) +- [jerry_property_descriptor_create](#jerry_property_descriptor_create) - [jerry_define_own_property](#jerry_define_own_property) -- [jerry_free_property_descriptor_fields](#jerry_free_property_descriptor_fields) +- [jerry_property_descriptor_free](#jerry_property_descriptor_free) -## jerry_free_property_descriptor_fields +## jerry_property_descriptor_free **Summary** @@ -7109,27 +8578,28 @@ Free fields of property descriptor (setter, getter and value). ```c void -jerry_free_property_descriptor_fields (const jerry_property_descriptor_t *prop_desc_p); +jerry_property_descriptor_free (const jerry_property_descriptor_t *prop_desc_p); ``` - `prop_desc_p` - pointer to property descriptor +*New in version [[NEXT_RELEASE]]*: Replaces `jerry_free_property_descriptor_fields`. + **Example** ```c { - jerry_property_descriptor_t prop_desc; - jerry_init_property_descriptor_fields (&prop_desc); + jerry_property_descriptor_t prop_desc = jerry_property_descriptor_create (); ... // usage of property descriptor - jerry_free_property_descriptor_fields (&prop_desc); + jerry_property_descriptor_free (&prop_desc); } ``` **See also** -- [jerry_init_property_descriptor_fields](#jerry_init_property_descriptor_fields) +- [jerry_property_descriptor_create](#jerry_property_descriptor_create) - [jerry_define_own_property](#jerry_define_own_property) - [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) @@ -7427,8 +8897,11 @@ typedef struct #define SECRET_INFO ((void *) 42) static void -buffer_native_freecb (void *native_p) +buffer_native_freecb (void *native_p, + jerry_object_native_info_t *info_p) { + (void) info_p; + char *data_p = ((buffer_native_object_t*)native_p)->data_p; if (data_p != NULL) @@ -7440,14 +8913,21 @@ buffer_native_freecb (void *native_p) } static void -shape_native_freecb (void *native_p) +shape_native_freecb (void *native_p, + jerry_object_native_info_t *info_p) { + (void) info_p; + free (native_p); } static void -destructor_freecb (void *native_p) +destructor_freecb (void *native_p, + jerry_object_native_info_t *info_p) { + (void) native_p; + (void) info_p; + printf("Note: the object has been freed\n"); } @@ -7666,6 +9146,171 @@ best-practice example. - [jerry_object_native_info_t](#jerry_object_native_info_t) +## jerry_native_pointer_init_references + +**Summary** + +Initialize the references stored in a buffer pointed by a native pointer. +The references are initialized to undefined. This function must be called +before the buffer is attached to an object by +[jerry_set_object_native_pointer](#jerry_set_object_native_pointer). + +*Note*: + - The description of [jerry_object_native_info_t](#jerry_object_native_info_t) + provides detailed information about these references. + +**Prototype** + +```c +void +jerry_native_pointer_init_references (void *native_pointer_p, + const jerry_object_native_info_t *native_info_p); +``` + +- `native_pointer_p` - a valid non-NULL pointer to a native buffer. +- `native_info_p` - native pointer's type information. + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # () + +```c +#include +#include "jerryscript.h" + +typedef struct +{ + uint32_t user_data; + jerry_value_t a; + jerry_value_t b; + uint32_t user_other_data; +} user_buffer_t; + +static void +native_references_free_callback (void *native_p, /**< native pointer */ + jerry_object_native_info_t *info_p) /**< native info */ +{ + /* References must be finalized when a buffer is no longer attached. */ + jerry_native_pointer_release_references (native_p, info_p); + free (native_p); +} /* native_references_free_callback */ + +static const jerry_object_native_info_t native_info = +{ + .free_cb = native_references_free_callback, + .number_of_references = 2, + .offset_of_references = offsetof(user_buffer_t, a), +}; + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t object_value = jerry_create_object (); + + user_buffer_t *buffer_p = (user_buffer_t *) malloc (sizeof (user_buffer_t)); + + /* References must be initialized before a buffer is attached. */ + jerry_native_pointer_init_references ((void *) buffer_p, &native_info); + + jerry_set_object_native_pointer (object_value, (void *) buffer_p, &native_info); + + /* References can be modified after the buffer is attached. + * This example sets a self reference. */ + jerry_native_pointer_set_reference (&buffer_p->a, object_value); + + jerry_release_value (object_value); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) +- [jerry_native_pointer_release_references](#jerry_native_pointer_release_references) +- [jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference) + +## jerry_native_pointer_release_references + +**Summary** + +Release the value references stored in a buffer pointed by a native pointer. +This function must be called after a buffer is no longer attached to any +object, even if the buffer is attached to another object again. This +function also initializes the values to undefined, so calling +[jerry_native_pointer_init_references](#jerry_native_pointer_init_references) +is optional before the buffer is attached again. + +*Note*: + - The description of [jerry_object_native_info_t](#jerry_object_native_info_t) + provides detailed information about these references. + +**Prototype** + +```c +void +jerry_native_pointer_release_references (void *native_pointer_p, + const jerry_object_native_info_t *native_info_p); +``` + +- `native_pointer_p` - a valid non-NULL pointer to a native buffer. +- `native_info_p` - native pointer's type information. + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +See the example of [jerry_native_pointer_init_references](#jerry_native_pointer_init_references). + +**See also** + +- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) +- [jerry_native_pointer_init_references](#jerry_native_pointer_init_references) +- [jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference) + + +## jerry_native_pointer_set_reference + +**Summary** + +Updates a value reference inside the area specified by the `number_of_references` and +`offset_of_references` fields in its corresponding +[jerry_object_native_info_t](#jerry_object_native_info_t) data. The area must be +part of a buffer which is currently assigned to an object. + +*Note*: + - The description of [jerry_object_native_info_t](#jerry_object_native_info_t) + provides detailed information about these references. + +**Prototype** + +```c +void +jerry_native_pointer_set_reference (jerry_value_t *reference_p, + jerry_value_t value) +``` + +- `reference_p` - a valid non-NULL pointer to a reference in a native buffer. +- `value` - new value of the reference. + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +See the example of [jerry_native_pointer_init_references](#jerry_native_pointer_init_references). + +**See also** + +- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) +- [jerry_native_pointer_init_references](#jerry_native_pointer_init_references) +- [jerry_native_pointer_release_references](#jerry_native_pointer_release_references) + + ## jerry_object_get_property_names **Summary** @@ -7686,6 +9331,8 @@ jerry_object_get_property_names (jerry_value_t obj_val, - array containing the filtered property keys in successful operation - error marked with error flag, otherwise +*New in version 2.4*. + **Example** ```c @@ -7861,7 +9508,7 @@ find_my_object (const jerry_value_t candidate, /* Check if the given object has the required property. */ jerry_value_t has_property = jerry_has_property (candidate, info_p->property_name); - bool object_found = jerry_get_boolean_value (has_property); + bool object_found = jerry_value_is_true (has_property); if (object_found) { @@ -7997,8 +9644,11 @@ typedef struct int match_foo_value; } find_object_data_t; -static void native_freecb (void *native_p) +static void native_freecb (void *native_p, + jerry_object_native_info_t *info_p) { + (void) info_p; + /* `native_p` was allocated via malloc. */ free (native_p); } /* native_freecb */ @@ -8397,19 +10047,17 @@ Generate snapshot from the specified source code. ```c jerry_value_t -jerry_generate_snapshot (const jerry_char_t *resource_name_p, - size_t resource_name_length, - const jerry_char_t *source_p, +jerry_generate_snapshot (const jerry_char_t *source_p, size_t source_size, + const jerry_parse_options_t *options_p, uint32_t generate_snapshot_opts, uint32_t *buffer_p, size_t buffer_size); ``` -- `resource_name_p` - resource (file) name of the source code. Currently unused, the debugger may use it in the future. -- `resource_name_length` - length of resource name. - `source_p` - script source, it must be a valid utf8 string. - `source_size` - script source size, in bytes. +- `options_p` - additional parsing options, can be NULL if not used - `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags. - `buffer_p` - output buffer (aligned to 4 bytes) to save snapshot to. - `buffer_size` - the output buffer's size in bytes. @@ -8420,6 +10068,7 @@ jerry_generate_snapshot (const jerry_char_t *resource_name_p, - thrown error, otherwise. *New in version 2.0*. +*Changed in version [[NEXT_RELEASE]]*: The `resource_name_p`, and `resource_name_length` arguments are replaced by `options_p`. **Example** @@ -8437,10 +10086,9 @@ main (void) const jerry_char_t script_to_snapshot[] = "(function () { return 'string from snapshot'; }) ();"; jerry_value_t generate_result; - generate_result = jerry_generate_snapshot (NULL, - 0, - script_to_snapshot, + generate_result = jerry_generate_snapshot (script_to_snapshot, sizeof (script_to_snapshot) - 1, + NULL, 0, global_mode_snapshot_buffer, sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); @@ -8463,6 +10111,7 @@ main (void) - [jerry_cleanup](#jerry_cleanup) - [jerry_generate_function_snapshot](#jerry_generate_function_snapshot) - [jerry_exec_snapshot](#jerry_exec_snapshot) +- [jerry_parse_options_t](#jerry_parse_options_t) ## jerry_generate_function_snapshot @@ -8486,23 +10135,21 @@ passed as separated arguments. ```c jerry_value_t -jerry_generate_function_snapshot (const jerry_char_t *resource_name_p, - size_t resource_name_length, - const jerry_char_t *source_p, +jerry_generate_function_snapshot (const jerry_char_t *source_p, size_t source_size, const jerry_char_t *args_p, size_t args_size, + const jerry_parse_options_t *options_p, uint32_t generate_snapshot_opts, uint32_t *buffer_p, size_t buffer_size) ``` -- `resource_name_p` - resource (file) name of the source code. Currently unused, the debugger may use it in the future. -- `resource_name_length` - length of resource name. - `source_p` - script source, it must be a valid utf8 string. - `source_size` - script source size, in bytes. - `args_p` - function arguments, it must be a valid utf8 string. - `args_size` - function argument size, in bytes. +- `options_p` - additional parsing options, can be NULL if not used - `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags. - `buffer_p` - buffer (aligned to 4 bytes) to save snapshot to. - `buffer_size` - the buffer's size in bytes. @@ -8513,6 +10160,7 @@ jerry_generate_function_snapshot (const jerry_char_t *resource_name_p, - thrown error, otherwise. *New in version 2.0*. +*Changed in version [[NEXT_RELEASE]]*: The `resource_name_p`, and `resource_name_length` arguments are replaced by `options_p`. **Example** @@ -8531,12 +10179,11 @@ main (void) const jerry_char_t src[] = "return a + b;"; jerry_value_t generate_result; - generate_result = jerry_generate_function_snapshot (NULL, - 0, - src, + generate_result = jerry_generate_function_snapshot (src, sizeof (src) - 1, args, sizeof (args) - 1, + NULL, 0, func_snapshot_buffer, sizeof (func_snapshot_buffer) / sizeof (uint32_t)); @@ -8559,6 +10206,7 @@ main (void) - [jerry_cleanup](#jerry_cleanup) - [jerry_generate_snapshot](#jerry_generate_snapshot) - [jerry_load_function_snapshot_at](#jerry_load_function_snapshot_at) +- [jerry_parse_options_t](#jerry_parse_options_t) ## jerry_exec_snapshot @@ -8610,10 +10258,9 @@ main (void) jerry_init (JERRY_INIT_EMPTY); jerry_value_t generate_result; - generate_result = jerry_generate_snapshot (NULL, - 0, - script_to_snapshot, + generate_result = jerry_generate_snapshot (script_to_snapshot, sizeof (script_to_snapshot) - 1, + NULL, 0, global_mode_snapshot_buffer, sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); @@ -8699,13 +10346,12 @@ main (void) jerry_init (JERRY_INIT_EMPTY); jerry_value_t generate_result; - generate_result = jerry_generate_function_snapshot (NULL, - 0, - func_src, + generate_result = jerry_generate_function_snapshot (func_src, sizeof (func_src) - 1, func_args, sizeof (func_args) - 1, - false, + NULL, + 0, snapshot_buffer, sizeof (snapshot_buffer) / sizeof (uint32_t)); @@ -8800,10 +10446,9 @@ main (void) static uint32_t snapshot_buffer[256]; const jerry_char_t script_for_literal_save[] = "var obj = { a:'aa', bb:'Bb' }"; - jerry_value_t generate_result = jerry_generate_snapshot (NULL, - 0, - script_for_literal_save, + jerry_value_t generate_result = jerry_generate_snapshot (script_for_literal_save, sizeof (script_for_literal_save) - 1, + NULL, 0, snapshot_buffer, 256); @@ -8835,6 +10480,527 @@ main (void) - [jerry_register_magic_strings](#jerry_register_magic_strings) +# Backtrace functions + +## jerry_get_backtrace + +**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. + +This function is typically called from native callbacks. + +*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 (uint32_t max_depth); +``` + +- `max_depth` - backtrace collection stops after reaching this value, 0 = unlimited +- return value + - a newly constructed JS array + +*New in version 2.0*. + +**Example** + +[doctest]: # (name="02.API-REFERENCE-jsbacktrace.c") + +```c +#include +#include +#include "jerryscript.h" + +static jerry_value_t +backtrace_handler (const jerry_call_info_t *call_info_p, + 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 the line info feature is disabled an empty array will be returned. */ + jerry_value_t backtrace_array = jerry_get_backtrace (5); + 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 "capture_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 (); }\n" + "f ();\n"); + const char *resource = "demo_memoryjs"; + + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = (jerry_char_t *) resource; + parse_options.resource_name_length = (size_t) strlen (resource); + + jerry_value_t program = jerry_parse ((const jerry_char_t *) source, + strlen (source), + &parse_options); + 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_from](#jerry_get_backtrace_from) +- [jerry_create_external_function](#jerry_create_external_function) + + +## jerry_backtrace_capture + +**Summary** + +Low-level function to capture each backtrace frame. The captured frame data +is passed to a callback function. To improve performance, the majority of +the frame data is not initialized when the callback function is called. The +initialization of these fields can be done later by helper functions such +as [jerry_backtrace_get_location](#jerry_backtrace_get_location). + +**Prototype** + +```c +void +jerry_backtrace_capture (jerry_backtrace_callback_t callback, void *user_p); +``` + +- `callback` - a [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback + which is called for each captured frame +- `user_p` - pointer passed to the `callback` function, can be NULL + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (name="02.API-REFERENCE-jscapturebacktrace.c") + +```c +#include +#include +#include "jerryscript.h" + +static bool +backtrace_callback (jerry_backtrace_frame_t *frame_p, + void *user_p) +{ + printf (" A stack frame is captured\n"); + return true; +} + +static jerry_value_t +backtrace_handler (const jerry_call_info_t *call_info_p, + const jerry_value_t args_p[], + const jerry_length_t args_count) +{ + (void) call_info_p; + (void) args_p; + (void) args_count; + + jerry_backtrace_capture (&backtrace_callback, NULL); + + 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_backtrace.js"; + + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = (jerry_char_t *) resource; + parse_options.resource_name_length = (size_t) strlen (resource); + + jerry_value_t program = jerry_parse ((const jerry_char_t *) source, + strlen (source), + &parse_options); + 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_backtrace_get_frame_type](#jerry_backtrace_get_frame_type) +- [jerry_backtrace_get_location](#jerry_backtrace_get_location) +- [jerry_backtrace_get_function](#jerry_backtrace_get_function) +- [jerry_backtrace_get_this](#jerry_backtrace_get_this) +- [jerry_backtrace_is_strict](#jerry_backtrace_is_strict) + + +## jerry_backtrace_get_frame_type + +**Summary** + +Returns with the type of the backtrace frame. This function can only be called +from the callback function of [jerry_backtrace_capture](#jerry_backtrace_capture), +and the value becomes invalid after the callback returns. + +**Prototype** + +```c +jerry_backtrace_frame_types_t +jerry_backtrace_get_frame_type (jerry_backtrace_frame_t *frame_p); +``` + +- `frame_p` - a frame passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback +- return value + - frame type listed in [jerry_backtrace_frame_types_t](#jerry_backtrace_frame_types_t) + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +See the example of [jerry_backtrace_capture](#jerry_backtrace_capture) +with the following callback function: + +```c +static bool +backtrace_callback (jerry_backtrace_frame_t *frame_p, + void *user_p) +{ + switch (jerry_backtrace_get_frame_type (frame_p)) + { + case JERRY_BACKTRACE_FRAME_JS: + { + printf (" ECMAScript frame\n"); + break; + } + default: + { + printf (" Other frame\n"); + break; + } + } + + return true; +} +``` + +**See also** + +- [jerry_backtrace_capture](#jerry_backtrace_capture) + + +## jerry_backtrace_get_location + +**Summary** + +Initialize and return with the location private field of a backtrace +frame. If the location is not available, the returned value is NULL. +This function can only be called from the callback function of +[jerry_backtrace_capture](#jerry_backtrace_capture), and the value +becomes invalid after the callback returns. + +*Notes*: +- Location information can only be retrieved if JERRY_FEATURE_LINE_INFO feature is + enabled. Otherwise the function always returns with NULL. +- The returned data must not be modified, and does not need to be freed. + Any cleanup is done automatically after the callback is returned. + +**Prototype** + +```c +const jerry_backtrace_location_t * +jerry_backtrace_get_location (jerry_backtrace_frame_t *frame_p); +``` + +- `frame_p` - a frame passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback +- return value + - pointer to the location private field if the location is available, + - NULL otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +See the example of [jerry_backtrace_capture](#jerry_backtrace_capture) +with the following callback function: + +```c +static bool +backtrace_callback (jerry_backtrace_frame_t *frame_p, + void *user_p) +{ + const jerry_backtrace_location_t *location_p; + location_p = jerry_backtrace_get_location (frame_p); + + if (location_p == NULL) + { + printf ("No location info is available\n"); + return true; + } + + jerry_char_t string_buffer[64]; + jerry_size_t copied_bytes = jerry_substring_to_char_buffer (location_p->resource_name, + 0, + 63, + string_buffer, + 63); + string_buffer[copied_bytes] = '\0'; + printf(" %s:%d:%d\n", string_buffer, (int) location_p->line, (int) location_p->column); + return true; +} +``` + +**See also** + +- [jerry_backtrace_capture](#jerry_backtrace_capture) + + +## jerry_backtrace_get_function + +**Summary** + +Initialize and return with the called function private field of a backtrace frame. +The backtrace frame is created for running the code bound to this function. This +function can only be called from the callback function of +[jerry_backtrace_capture](#jerry_backtrace_capture), and the value becomes invalid +after the callback returns. + +*Notes*: +- The returned data must not be modified, and does not need to be freed. + Any cleanup is done automatically after the callback is returned. + +**Prototype** + +```c +const jerry_value_t * +jerry_backtrace_get_function (jerry_backtrace_frame_t *frame_p); +``` + +- `frame_p` - a frame passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback +- return value + - pointer to the called function if the function is available, + - NULL otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +See the example of [jerry_backtrace_capture](#jerry_backtrace_capture) +with the following callback function: + +```c +static bool +backtrace_callback (jerry_backtrace_frame_t *frame_p, + void *user_p) +{ + jerry_value_t *function_p = jerry_backtrace_get_function (frame_p); + + if (function_p != NULL) + { + printf ("Called function is available"); + return true; + } + + printf ("Called function is NOT available"); + return true; +} +``` + +**See also** + +- [jerry_backtrace_capture](#jerry_backtrace_capture) + + +## jerry_backtrace_get_this + +**Summary** + +Initialize and return with the 'this' binding private field of a backtrace frame. +The 'this' binding is a hidden value passed to the called function. As for arrow +functions, the 'this' binding is assigned at function creation. This getter +function can only be called from the callback function of +[jerry_backtrace_capture](#jerry_backtrace_capture), and the value becomes invalid +after the callback returns. + +*Notes*: +- The returned data must not be modified, and does not need to be freed. + Any cleanup is done automatically after the callback is returned. + +**Prototype** + +```c +const jerry_value_t * +jerry_backtrace_get_this (jerry_backtrace_frame_t *frame_p); +``` + +- `frame_p` - a frame passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback +- return value + - pointer to the 'this' binding if the binding is available, + - NULL otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +See the example of [jerry_backtrace_capture](#jerry_backtrace_capture) +with the following callback function: + +```c +static bool +backtrace_callback (jerry_backtrace_frame_t *frame_p, + void *user_p) +{ + jerry_value_t *this_p = jerry_backtrace_get_this (frame_p); + + if (this_p != NULL) + { + printf ("The 'this' binding is available"); + return true; + } + + printf ("The 'this' binding is NOT available"); + return true; +} +``` + +**See also** + +- [jerry_backtrace_capture](#jerry_backtrace_capture) + + +## jerry_backtrace_is_strict + +**Summary** + +Returns true, if the code bound to the backtrace frame is strict mode +code. This function can only be called from the callback function of +[jerry_backtrace_capture](#jerry_backtrace_capture), and the value +becomes invalid after the callback returns. + +**Prototype** + +```c +bool +jerry_backtrace_is_strict (jerry_backtrace_frame_t *frame_p); +``` + +- `frame_p` - a frame passed to the [jerry_backtrace_callback_t](#jerry_backtrace_callback_t) callback +- return value + - true, if strict mode code is bound to the frame + - false, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +See the example of [jerry_backtrace_capture](#jerry_backtrace_capture) +with the following callback function: + +```c +static bool +backtrace_callback (jerry_backtrace_frame_t *frame_p, + void *user_p) +{ + if (jerry_backtrace_is_strict (frame_p)) + { + printf ("Strict mode code is running"); + return truel + } + + printf ("Non-strict mode code is running"); + return true; +} +``` + +**See also** + +- [jerry_backtrace_capture](#jerry_backtrace_capture) + + # Miscellaneous functions ## jerry_set_vm_exec_stop_callback @@ -8902,10 +11068,10 @@ main (void) jerry_set_vm_exec_stop_callback (vm_exec_stop_callback, &countdown, 16); - // Inifinte loop. + // Infinite loop. const jerry_char_t script[] = "while(true) {}"; - jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); + jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL); jerry_release_value (jerry_run (parsed_code)); jerry_release_value (parsed_code); jerry_cleanup (); @@ -8920,267 +11086,6 @@ main (void) - [jerry_run](#jerry_run) - [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t) -## jerry_get_backtrace - -**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. - -This function is typically called from native callbacks. - -*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 (uint32_t max_depth); -``` - -- `max_depth` - backtrace collection stops after reaching this value, 0 = unlimited -- return value - - a newly constructed JS array - -*New in version 2.0*. - -**Example** - -[doctest]: # (name="02.API-REFERENCE-jsbacktrace.c") - -```c -#include -#include -#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 the line info feature is disabled an empty array will be returned. */ - jerry_value_t backtrace_array = jerry_get_backtrace (5); - 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 (); }\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_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 -#include -#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** @@ -9220,8 +11125,7 @@ jerry_get_resource_name (jerry_value_t value); #include "jerryscript.h" static jerry_value_t -resource_name_handler (const jerry_value_t function_obj, - const jerry_value_t this_val, +resource_name_handler (const jerry_call_info_t *call_info_p, const jerry_value_t args_p[], const jerry_length_t args_count) { @@ -9254,11 +11158,14 @@ main (void) const jerry_char_t source[] = "function myFunction() { return resourceName() }; myFunction()"; const jerry_char_t resource[] = "demo.js"; - jerry_value_t program = jerry_parse (resource, - sizeof (resource) - 1, - source, + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = resource; + parse_options.resource_name_length = sizeof (resource) - 1; + + jerry_value_t program = jerry_parse (source, sizeof (source) - 1, - JERRY_PARSE_NO_OPTS); + &parse_options); if (!jerry_value_is_error (program)) { @@ -9281,139 +11188,6 @@ main (void) - [jerry_create_external_function](#jerry_create_external_function) -## jerry_get_new_target - -**Summary** - -Returns the current "new.target" JavaScript function at the call site. - -If used outside of a native C function it will return "undefined" value. - -*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_ESNEXT`) and can be checked - in runtime with the `JERRY_FEATURE_SYMBOL` feature enum value (as symbols are enabled in case of ES.next), - see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). -- If the ES.next mode is not enabled this method will always return the "undefined" value. - -**Prototype** - -```c -jerry_value_t -jerry_get_new_target (void); -``` -- return - - "undefined" - if at the call site it was not a constructor call. - - function object - if the current call site is in a constructor call. - -*New in version 2.2*. - -**Example 1** - -[doctest]: # (name="02.API-REFERENCE-jsnewtarget-01.c") - -```c -#include -#include -#include - -static jerry_value_t -demo_handler (const jerry_value_t func_obj_val, - const jerry_value_t this_val, - const jerry_value_t args_p[], - const jerry_length_t args_cnt) -{ - jerry_value_t new_target = jerry_get_new_target (); - - /* new_target is the "demo" JS function object */ - if (jerry_value_get_type (new_target) == JERRY_TYPE_FUNCTION) - { - printf ("This is a construct call\r\n"); - } - - jerry_release_value (new_target); - - return jerry_create_undefined (); -} - -int -main (int argc, char** argv) -{ - jerry_init (JERRY_INIT_EMPTY); - - jerry_value_t function_val = jerry_create_external_function (demo_handler); - - jerry_value_t ret_val = jerry_construct_object (function_val, NULL, 0); - - jerry_release_value (ret_val); - jerry_release_value (function_val); - - jerry_cleanup (); - return 0; -} -``` - -**Example 2** - -[doctest]: # (name="02.API-REFERENCE-jsnewtarget-02.c") - -```c -#include -#include -#include - -static jerry_value_t -demo_handler (const jerry_value_t func_obj_val, - const jerry_value_t this_val, - const jerry_value_t args_p[], - const jerry_length_t args_cnt) -{ - jerry_value_t new_target = jerry_get_new_target (); - - /* new_target is a JS function object */ - if (jerry_value_get_type (new_target) == JERRY_TYPE_FUNCTION) - { - printf ("This is a construct call\r\n"); - } - - jerry_release_value (new_target); - - return jerry_create_undefined (); -} - -int -main (int argc, char** argv) -{ - jerry_init (JERRY_INIT_EMPTY); - - /* register C method */ - jerry_value_t global_obj_val = jerry_get_global_object (); - jerry_value_t function_val = jerry_create_external_function (demo_handler); - jerry_value_t function_name_val = jerry_create_string ((const jerry_char_t *) "demo"); - jerry_value_t result_val = jerry_set_property (global_obj_val, function_name_val, function_val); - jerry_release_value (result_val); - jerry_release_value (function_name_val); - jerry_release_value (function_val); - jerry_release_value (global_obj_val); - - /* Invoke C method via JS */ - const char *src = "new demo ()"; - jerry_value_t ret_val = jerry_eval ((const jerry_char_t *) src, - strlen (src), - JERRY_PARSE_NO_OPTS); - - jerry_release_value (ret_val); - - jerry_cleanup (); - return 0; -} -``` - -**See also** - -- [jerry_construct_object](#jerry_construct_object) - # Functions for realm objects These APIs all depend on build option (`JERRY_BUILTIN_REALMS`). @@ -9827,7 +11601,7 @@ jerry_is_arraybuffer_detachable (const jerry_value_t value); jerry_value_t buffer = jerry_create_arraybuffer (16); jerry_value_t res = jerry_is_arraybuffer_detachable (buffer); - bool is_detachable = jerry_get_boolean_value (res); + bool is_detachable = jerry_value_is_true (res); // release buffer as it is not needed after this point jerry_release_value (res); @@ -10205,3 +11979,72 @@ main (void) return 0; } ``` + +# Container Functions + +## jerry_get_array_from_container + +**Summary** + +Return a new array containing elements from a Container, or a Container Iterator. Sets the is_key_value_p to true. +if the container object contains key-value structure and false if not. + +*Notes* +- The return value will be an empty array if the Map/Set or Iterator object was empty or finished. +- This API function depends on a build option (`JERRY_BUILTIN_CONTAINER`) and can be checked + runtime with the `JERRY_FEATURE_MAP, JERRY_FEATURE_SET, JERRY_FEATURE_WEAKMAP, JERRY_FEATURE_WEAKSET` + feature enum values. + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). +- The es.next profile enables this by default. + +*New in version [[NEXT_RELEASE]]*. + +**Prototype** + +```c +jerry_value_t +jerry_get_array_from_container(jerry_value_t value, + bool *is_key_value_p); +``` + +- `value` - Map/Set or iterator object +- `is_key_value` - Will be set to `true` if the given container has key-value pairs, `false` otherwise. +- return value + - jerry_value_t containing an array of values from the Map/Set or iterator object + - Error if the `value` is nor a Container or a Container Iterator. + - `undefined` if the `value` is undefined/null. +**Example** + +[doctest]: # () + +```c +#include "jerryscript.h" +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_char_t src[] = "var map = new Map(); map.set(1,2); map.entries()"; + jerry_value_t iterable = jerry_eval (src, sizeof (src) - 1, JERRY_PARSE_NO_OPTS); + + bool is_key_value_container = false; + jerry_value_t buffer_from_map = jerry_get_array_from_container (iterable, &is_key_value_container); + + /* + The buffer_from_map contains two elements: 1 and 2, which is the key/value pair of the only item in the set. + is_key_value set to true, as the original is a key-value structure (a Map Iterator) + */ + + jerry_release_value (iterable); + jerry_release_value (buffer_from_map); + + jerry_cleanup (); + + return 0; +} +``` + +**See also** + +- [jerry_create_container](#jerry_create_container) +- [jerry_container_type_t](#jerry_container_type_t) diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md index 54b0978f3..ec180fccf 100644 --- a/03.API-EXAMPLE.md +++ b/03.API-EXAMPLE.md @@ -163,7 +163,7 @@ main (void) jerry_init (JERRY_INIT_EMPTY); /* Setup Global scope code */ - jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS); + jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL); /* Check if there is any JS code parse error */ if (!jerry_value_is_error (parsed_code)) @@ -224,8 +224,7 @@ The `api-example-4.c` file should contain the following code: #include "jerryscript.h" static jerry_value_t -print_handler (const jerry_value_t function_object, - const jerry_value_t function_this, +print_handler (const jerry_call_info_t *call_info_p, const jerry_value_t arguments[], const jerry_length_t argument_count) { @@ -270,7 +269,7 @@ main (void) } /* Setup Global scope code */ - jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS); + jerry_value_t parsed_code = jerry_parse (script, script_size, NULL); if (!jerry_value_is_error (parsed_code)) { @@ -326,8 +325,7 @@ The `api-example-5.c` file should contain the following code: #include "jerryscript.h" static jerry_value_t -print_handler (const jerry_value_t function_object, - const jerry_value_t function_this, +print_handler (const jerry_call_info_t *call_info_p, const jerry_value_t arguments[], const jerry_length_t arguments_count) { @@ -390,7 +388,7 @@ main (void) } /* Setup Global scope code */ - jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS); + jerry_value_t parsed_code = jerry_parse (script, script_size, NULL); if (!jerry_value_is_error (parsed_code)) { @@ -456,7 +454,7 @@ main (void) jerryx_handler_print); /* Setup Global scope code */ - jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS); + jerry_value_t parsed_code = jerry_parse (script, script_size, NULL); if (!jerry_value_is_error (parsed_code)) { @@ -627,7 +625,7 @@ print_value (const jerry_value_t jsvalue) } else if (jerry_value_is_boolean (value)) { - if (jerry_get_boolean_value (value)) + if (jerry_value_is_true (value)) { printf ("true"); } @@ -721,7 +719,7 @@ print_value (const jerry_value_t jsvalue) } else if (jerry_value_is_boolean (value)) { - if (jerry_get_boolean_value (value)) + if (jerry_value_is_true (value)) { printf ("true"); } @@ -861,8 +859,7 @@ struct my_struct * Get a string from a native object */ static jerry_value_t -get_msg_handler (const jerry_value_t func_value, /**< function object */ - const jerry_value_t this_value, /**< this arg */ +get_msg_handler (const jerry_call_info_t *call_info_p, /**< call information */ const jerry_value_t *args_p, /**< function arguments */ const jerry_length_t args_cnt) /**< number of function arguments */ { @@ -965,8 +962,7 @@ Use the following code for `api-example-10.c`: * Add param to 'this.x' */ static jerry_value_t -add_handler (const jerry_value_t func_value, /**< function object */ - const jerry_value_t this_val, /**< this arg */ +add_handler (const jerry_call_info_t *call_info_p, /**< call information */ const jerry_value_t args_p[], /**< function arguments */ const jerry_length_t args_cnt) /**< number of function arguments */ { @@ -975,7 +971,7 @@ add_handler (const jerry_value_t func_value, /**< function object */ /* Get 'this.x' */ 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); + jerry_value_t x_val = jerry_get_property (call_info_p->this_value, prop_name); if (!jerry_value_is_error (x_val)) { @@ -987,7 +983,7 @@ add_handler (const jerry_value_t func_value, /**< function object */ jerry_value_t res_val = jerry_create_number (x + d); /* Set the new value of 'this.x' */ - jerry_release_value (jerry_set_property (this_val, prop_name, res_val)); + jerry_release_value (jerry_set_property (call_info_p->this_value, prop_name, res_val)); jerry_release_value (res_val); } diff --git a/05.PORT-API.md b/05.PORT-API.md index 352543197..b8373f1a6 100644 --- a/05.PORT-API.md +++ b/05.PORT-API.md @@ -95,12 +95,10 @@ void jerry_port_print_char (char c); ### Jerry Module system -The port API provides functions that can be used by the module system to open -and close source files, and normalize file paths. -The `jerry_port_get_native_module` port function can be used to provide native -modules to the engine. This function will be called when an import/export -statement is encountered with an unknown module specifier, which embedders can -use to supply native module objects based on the module name argument. +The port API provides optional functions that can be used by the +user application to resolve modules. If no callback is provided +to `jerry_module_link`, the `jerry_port_module_resolve` function +is used for resolving modules. ```c /** @@ -125,66 +123,38 @@ jerry_port_release_source (uint8_t *buffer_p) /**< buffer to free */ } /* jerry_port_release_source */ /** - * Normalize a file path + * Default module resolver. * - * @return length of the path written to the output buffer - */ -size_t -jerry_port_normalize_path (const char *in_path_p, /**< input file path */ - char *out_buf_p, /**< output buffer */ - size_t out_buf_size, /**< size of output buffer */ - char *base_file_p) /**< base file path */ -{ - // normalize in_path_p by expanding relative paths etc. - // if base_file_p is not NULL, in_path_p is relative to that file - // write to out_buf_p the normalized path - // return length of written path -} /* jerry_port_normalize_path */ - -/** - * Get the module object of a native module. - * - * Note: - * This port function is called by jerry-core when JERRY_MODULE_SYSTEM - * is enabled. - * - * @param name String value of the module specifier. - * - * @return Undefined, if 'name' is not a native module - * jerry_value_t containing the module object, otherwise + * @return a module object if resolving is successful, an error otherwise */ jerry_value_t -jerry_port_get_native_module (jerry_value_t name) /**< module specifier */ +jerry_port_module_resolve (const jerry_value_t specifier, /**< module specifier string */ + const jerry_value_t referrer, /**< parent module */ + void *user_p) /**< user data */ { - (void) name; - return jerry_create_undefined (); -} -``` + // Resolves a module using the specifier string. If a referrer is a module, + // and specifier is a relative path, the base path should be the directory + // part extracted from the path of the referrer module. -## Promise + // The callback function of jerry_module_link may call this function + // if it cannot resolve a module. Furthermore if the callback is NULL, + // this function is used for resolving modules. -```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; + // The default implementation only resolves ECMAScript modules, and does + // not (currently) use the user data. +} /* jerry_port_module_resolve */ /** - * 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 + * Release known modules. */ -void jerry_port_track_promise_rejection (const jerry_value_t promise, - const jerry_promise_rejection_operation_t operation); +void +jerry_port_module_release (const jerry_value_t realm) /**< if this argument is object, release only those modules, + * which realm value is equal to this argument. */ +{ + // This function releases the known modules, forcing their reload + // when resolved again later. The released modules can be filtered + // by realms. This function is only called by user applications. +} /* jerry_port_module_release */ ``` ## Date @@ -428,32 +398,3 @@ 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 */ -``` diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md index 9c342b968..f43d329c2 100644 --- a/07.DEBUGGER.md +++ b/07.DEBUGGER.md @@ -324,11 +324,14 @@ wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource nam { (void) user_p; - jerry_value_t ret_val = jerry_parse (resource_name_p, - resource_name_size, - source_p, + jerry_parse_options_t parse_options; + parse_options.options = JERRY_PARSE_HAS_RESOURCE; + parse_options.resource_name_p = resource_name_p; + parse_options.resource_name_length = resource_name_size; + + jerry_value_t ret_val = jerry_parse (source_p, source_size, - JERRY_PARSE_NO_OPTS); + &parse_options); if (!jerry_value_is_error (ret_val)) { diff --git a/10.EXT-REFERENCE-HANDLER.md b/10.EXT-REFERENCE-HANDLER.md index 9bca3e918..c337749c2 100644 --- a/10.EXT-REFERENCE-HANDLER.md +++ b/10.EXT-REFERENCE-HANDLER.md @@ -277,8 +277,7 @@ jerryx_set_properties (const jerry_value_t target_object, #include "jerryscript-ext/handler.h" static jerry_value_t -handler (const jerry_value_t function_obj, - const jerry_value_t this_val, +handler (const jerry_call_info_t *call_info_p, const jerry_value_t args_p[], const jerry_length_t args_cnt) { @@ -341,8 +340,7 @@ when setting a property entry: #include "jerryscript-ext/handler.h" static jerry_value_t -handler (const jerry_value_t function_obj, - const jerry_value_t this_val, +handler (const jerry_call_info_t *call_info_p, const jerry_value_t args_p[], const jerry_length_t args_cnt) {