aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZsolt Borbély <zsborbely.u-szeged@partner.samsung.com>2021-11-02 19:13:12 +0100
committerGitHub <noreply@github.com>2021-11-02 19:13:12 +0100
commitd0671c4ff1bdf41a109823c427f2ea9385765123 (patch)
treeef64bd8cf43e02fa765930f67c8a9e0eb17f7512
parentacdecfc62a72304c992c29d77eff91a8ff16afdf (diff)
Update the webpage (#4813)
JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
-rw-r--r--01.CONFIGURATION.md2
-rw-r--r--02.API-REFERENCE.md2259
-rw-r--r--04.INTERNALS.md4
-rw-r--r--05.PORT-API.md6
-rw-r--r--07.DEBUGGER.md4
-rw-r--r--08.CODING-STANDARDS.md6
-rw-r--r--10.EXT-REFERENCE-HANDLER.md12
-rw-r--r--12.EXT-REFERENCE-MODULE.md2
-rw-r--r--13.DEBUGGER-TRANSPORT.md4
-rw-r--r--15.MODULE-SYSTEM.md6
-rw-r--r--16.MIGRATION-GUIDE.md6
11 files changed, 1877 insertions, 434 deletions
diff --git a/01.CONFIGURATION.md b/01.CONFIGURATION.md
index c97ab285..ea0c67ca 100644
--- a/01.CONFIGURATION.md
+++ b/01.CONFIGURATION.md
@@ -11,7 +11,7 @@ permalink: /configuration/
# Configuration
JerryScript provides a large number of configuration options which can be used to enable or disable specific features, allowing users to fine tune the engine to best suit their needs.
-A configuration option's value can be changed either by providing specific C preprocessor definitions, by adding CMake defininitions, or by using the arguments of the `tools/build.py` script.
+A configuration option's value can be changed either by providing specific C preprocessor definitions, by adding CMake definitions, or by using the arguments of the `tools/build.py` script.
This document lists the available configuration options, shows the configuration name for C, CMake, and python, and provides a brief description that explains the effect of the options.
diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md
index 1788d35b..1b403c83 100644
--- a/02.API-REFERENCE.md
+++ b/02.API-REFERENCE.md
@@ -62,6 +62,7 @@ Enum that contains JerryScript **object** value types:
- 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_SHARED_ARRAYBUFFER - Shared Array buffer object
- JERRY_OBJECT_TYPE_ARGUMENTS - Arguments object
- JERRY_OBJECT_TYPE_BOOLEAN - Boolean object
@@ -76,7 +77,9 @@ Enum that contains JerryScript **object** value types:
*New in version 2.4*.
-*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_OBJECT_TYPE_SCRIPT`, `JERRY_OBJECT_TYPE_MODULE` values.
+*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_OBJECT_TYPE_MODULE_NAMESPACE`, `JERRY_OBJECT_TYPE_PROMISE`, `JERRY_OBJECT_TYPE_DATAVIEW`,
+ `JERRY_OBJECT_TYPE_ERROR`, `JERRY_OBJECT_TYPE_SHARED_ARRAYBUFFER`, `JERRY_OBJECT_TYPE_WEAKREF`,
+ `JERRY_OBJECT_TYPE_SCRIPT`, and `JERRY_OBJECT_TYPE_MODULE` values.
## jerry_function_type_t
@@ -86,7 +89,7 @@ Enum that contains JerryScript **function** value types:
- JERRY_FUNCTION_TYPE_GENERIC - Generic JavaScript function
- JERRY_FUNCTION_TYPE_ACCESSOR - Accessor function
- JERRY_FUNCTION_TYPE_BOUND - Bound function
- - JERRY_FUNCTION_TYPE_ARROW - Arrow fuction
+ - JERRY_FUNCTION_TYPE_ARROW - Arrow function
- JERRY_FUNCTION_TYPE_GENERATOR - Generator function object
*New in version 2.4*.
@@ -119,18 +122,23 @@ produce correct results.
Enum that contains JerryScript **property filter** options bits:
- - JERRY_PROPERTY_FILTER_ALL - List all property keys independently from key type or property value attributes (equivalent to Reflect.ownKeys call)
- - JERRY_PROPERTY_FILTER_TRAVERSE_PROTOTYPE_CHAIN - Include keys from the objects's prototype chain as well
- - JERRY_PROPERTY_FILTER_EXLCUDE_NON_CONFIGURABLE - Exclude property key if the property is non-configurable
- - JERRY_PROPERTY_FILTER_EXLCUDE_NON_ENUMERABLE - Exclude property key if the property is non-enumerable
- - JERRY_PROPERTY_FILTER_EXLCUDE_NON_WRITABLE - Exclude property key if the property is non-writable
- - JERRY_PROPERTY_FILTER_EXLCUDE_STRINGS - Exclude property key if it is a string
- - JERRY_PROPERTY_FILTER_EXLCUDE_SYMBOLS - Exclude property key if it is a symbol
- - JERRY_PROPERTY_FILTER_EXLCUDE_INTEGER_INDICES - Exclude property key if it is an integer index
+ - JERRY_PROPERTY_FILTER_ALL - List all property keys independently from key type or property value attributes (equivalent to Reflect.ownKeys call)
+ - JERRY_PROPERTY_FILTER_TRAVERSE_PROTOTYPE_CHAIN - Include keys from the objects' prototype chain as well
+ - JERRY_PROPERTY_FILTER_EXCLUDE_NON_CONFIGURABLE - Exclude property key if the property is non-configurable
+ - JERRY_PROPERTY_FILTER_EXCLUDE_NON_ENUMERABLE - Exclude property key if the property is non-enumerable
+ - JERRY_PROPERTY_FILTER_EXCLUDE_NON_WRITABLE - Exclude property key if the property is non-writable
+ - JERRY_PROPERTY_FILTER_EXCLUDE_STRINGS - Exclude property key if it is a string
+ - JERRY_PROPERTY_FILTER_EXCLUDE_SYMBOLS - Exclude property key if it is a symbol
+ - JERRY_PROPERTY_FILTER_EXCLUDE_INTEGER_INDICES - Exclude property key if it is an integer index
- JERRY_PROPERTY_FILTER_INTEGER_INDICES_AS_NUMBER - By default integer index property keys are converted to string. Enabling this flags keeps integer index property keys as numbers
*New in version 2.4*.
+*Changed in version [[NEXT_RELEASE]]*: The following values are modified due to a typo in their names (exlcude/exclude):
+ `JERRY_PROPERTY_FILTER_EXLCUDE_NON_CONFIGURABLE`, `JERRY_PROPERTY_FILTER_EXLCUDE_NON_ENUMERABLE`,
+ `JERRY_PROPERTY_FILTER_EXLCUDE_NON_WRITABLE`, `JERRY_PROPERTY_FILTER_EXLCUDE_STRINGS`,
+ `JERRY_PROPERTY_FILTER_EXLCUDE_SYMBOLS`, `JERRY_PROPERTY_FILTER_EXLCUDE_INTEGER_INDICES`.
+
## jerry_error_t
Possible types of an error:
@@ -162,6 +170,7 @@ Possible compile time enabled feature types:
- JERRY_FEATURE_SNAPSHOT_EXEC - executing snapshot files
- JERRY_FEATURE_DEBUGGER - debugging
- JERRY_FEATURE_VM_EXEC_STOP - stopping ECMAScript execution
+ - JERRY_FEATURE_VM_THROW - capturing ECMAScript throws
- JERRY_FEATURE_JSON - JSON support
- JERRY_FEATURE_PROMISE - promise support
- JERRY_FEATURE_TYPEDARRAY - Typedarray support
@@ -181,6 +190,8 @@ Possible compile time enabled feature types:
- JERRY_FEATURE_GLOBAL_THIS - GlobalThisValue support
- JERRY_FEATURE_PROMISE_CALLBACK - Promise callback support
- JERRY_FEATURE_MODULE - Module support
+ - JERRY_FEATURE_WEAKREF - WeakRef support
+ - JERRY_FEATURE_FUNCTION_TO_STRING - function toString support
*New in version 2.0*.
@@ -188,7 +199,9 @@ 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.
+*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_FEATURE_VM_THROW`, `JERRY_FEATURE_GLOBAL_THIS`,
+ `JERRY_FEATURE_PROMISE_CALLBACK`, and `JERRY_FEATURE_MODULE`,
+ `JERRY_FEATURE_WEAKREF`, and `JERRY_FEATURE_FUNCTION_TO_STRING` values.
## jerry_container_type_t
@@ -251,11 +264,16 @@ 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_HAS_RESOURCE - `resource_name_p` and `resource_name_length` fields are valid
+ - JERRY_PARSE_HAS_ARGUMENT_LIST - `argument_list` field is valid, this also means that function parsing will be done
+ - JERRY_PARSE_HAS_RESOURCE - `resource_name` field is valid
- JERRY_PARSE_HAS_START - `start_line` and `start_column` fields are valid
+ - JERRY_PARSE_HAS_USER_VALUE - `user_value` field is valid
*New in version [[NEXT_RELEASE]]*.
+Using both `JERRY_PARSE_MODULE` and `JERRY_PARSE_HAS_ARGUMENT_LIST` is an invalid combination and will result in
+an error during parsing.
+
**See also**
- [jerry_parse_options_t](#jerry_parse_options_t)
@@ -285,8 +303,7 @@ List of backtrace frame types returned by
## jerry_generate_snapshot_opts_t
-Flags for [jerry_generate_snapshot](#jerry_generate_snapshot) and
-[jerry_generate_function_snapshot](#jerry_generate_function_snapshot) functions:
+Flags for [jerry_generate_snapshot](#jerry_generate_snapshot):
- JERRY_SNAPSHOT_SAVE_STATIC - generate static snapshot (see below)
@@ -304,22 +321,30 @@ so their constant pools do not need to be loaded into the memory.
Hence these snapshots can be executed from ROM.
***Important note:*** The [jerry_exec_snapshot](#jerry_exec_snapshot)
-function rejects static snaphots unless the `JERRY_SNAPSHOT_EXEC_ALLOW_STATIC`
+function rejects static snapshots unless the `JERRY_SNAPSHOT_EXEC_ALLOW_STATIC`
option bit is set. The caller must also ensure that the same magic
strings are set by [jerry_register_magic_strings](#jerry_register_magic_strings)
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
-Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) and
-[jerry_load_function_snapshot](#jerry_load_function_snapshot) functions:
+Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) functions:
- JERRY_SNAPSHOT_EXEC_COPY_DATA - copy snapshot data into memory (see below)
- JERRY_SNAPSHOT_EXEC_ALLOW_STATIC - allow executing static snapshots
+ - JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION - load snapshot as function instead of executing it
+ - JERRY_SNAPSHOT_EXEC_HAS_RESOURCE - `resource_name` field is valid
+ in [jerry_exec_snapshot_option_values_t](#jerry_exec_snapshot_option_values_t)
+ - JERRY_SNAPSHOT_EXEC_HAS_USER_VALUE - `user_value` field is valid
+ in [jerry_exec_snapshot_option_values_t](#jerry_exec_snapshot_option_values_t)
+
+*Changed in version [[NEXT_RELEASE]]*: The `JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION` value is added,
+ which replaces the `jerry_load_function_snapshot` function.
**Copy snapshot data into memory**
@@ -479,6 +504,18 @@ typedef struct jerry_context_t jerry_context_t;
*New in version 2.0*.
+## jerry_container_operation_t
+
+Enum that contains the supported container operation types
+ - JERRY_CONTAINER_OP_ADD - Set/WeakSet add operation
+ - JERRY_CONTAINER_OP_GET - Map/WeakMap get operation
+ - JERRY_CONTAINER_OP_SET - Map/WeakMap set operation
+ - JERRY_CONTAINER_OP_HAS - Set/WeakSet/Map/WeakMap has operation
+ - JERRY_CONTAINER_OP_DELETE - Set/WeakSet/Map/WeakMap delete operation
+ - JERRY_CONTAINER_OP_SIZE - Set/WeakSet/Map/WeakMap size operation
+ - JERRY_CONTAINER_OP_CLEAR - Set/Map clear operation
+
+*New in version [[NEXT_RELEASE]]*.
## jerry_binary_operation_t
@@ -528,8 +565,7 @@ Enum that contains the flags of property descriptors.
**Summary**
-Various configuration options for parsing functions such as [jerry_parse](#jerry_parse)
-or [jerry_parse_function](#jerry_parse_function)
+Various configuration options for parsing functions such as [jerry_parse](#jerry_parse).
**Prototype**
@@ -537,12 +573,15 @@ or [jerry_parse_function](#jerry_parse_function)
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 */
+ jerry_value_t argument_list; /**< function argument list if JERRY_PARSE_HAS_ARGUMENT_LIST is set in options
+ * Note: must be string value */
+ jerry_value_t resource_name; /**< resource name string (usually a file name)
+ * if JERRY_PARSE_HAS_RESOURCE is set in options
+ * Note: must be string value */
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_value_t user_value; /**< user value assigned to all functions created by this script including eval
+ * calls executed by the script if JERRY_PARSE_HAS_USER_VALUE is set in options */
} jerry_parse_options_t;
```
@@ -551,9 +590,8 @@ typedef struct
**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_exec_snapshot](#jerry_exec_snapshot)
- [jerry_parse_option_enable_feature_t](#jerry_parse_option_enable_feature_t)
## jerry_property_descriptor_t
@@ -581,6 +619,11 @@ typedef struct
} jerry_property_descriptor_t;
```
+*Changed in version [[NEXT_RELEASE]]*: The `is_value_defined`, `is_get_defined`, `is_set_defined`,
+ `is_writable_defined`, `is_writable`, `is_enumerable_defined`,
+ `is_enumerable`, `is_configurable_defined`, and `is_configurable`
+ fields are replaced by the `flags` field.
+
**See also**
- [jerry_property_descriptor_flags_t](#jerry_property_descriptor_flags_t)
@@ -590,7 +633,7 @@ typedef struct
**Summary**
-Source code location data retreived by
+Source code location data retrieved by
[jerry_backtrace_get_location](#jerry_backtrace_get_location).
**Prototype**
@@ -673,7 +716,7 @@ typedef struct jerry_call_info_t
} jerry_call_info_t;
```
-*New in version [[NEXT_RELEASE]]*.
+*New in version [[NEXT_RELEASE]]*. Contents of this struct replaces the `jerry_get_new_target` function.
**See also**
@@ -756,6 +799,34 @@ typedef void (*jerry_object_native_free_callback_t) (void *native_p, struct jerr
- [jerry_object_native_info_t](#jerry_object_native_info_t)
+## jerry_external_string_free_callback_t
+
+**Summary**
+
+Free callback for external strings. See
+[jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback)
+for more information.
+
+**Prototype**
+
+```c
+typedef void (*jerry_external_string_free_callback_t) (jerry_char_t *string_p,
+ jerry_size_t string_size,
+ void *user_p);
+```
+
+- `string_p` - external string pointer
+- `string_size` - size of external string
+- `user_p` - pointer passed when the external string is created
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback)
+- [jerry_create_external_string](#jerry_create_external_string)
+- [jerry_create_external_string_sz](#jerry_create_external_string_sz)
+
## jerry_error_object_created_callback_t
**Summary**
@@ -790,7 +861,7 @@ 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_LINKED - Module has been linked (its dependencies 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
@@ -828,6 +899,48 @@ typedef jerry_value_t (*jerry_module_resolve_callback_t) (const jerry_value_t sp
- [jerry_module_link](#jerry_module_link)
- [jerry_get_global_object](#jerry_get_global_object)
+## jerry_module_import_callback_t
+
+**Summary**
+
+Callback which is called when an import is resolved dynamically to get the referenced module.
+
+*Note*:
+ - If the function returns with a promise, the import call returns with this promise. The
+ application should try to resolve the requested module later. If the module is evaluated
+ successfully, the returned promise should be resolved with the namespace object of the
+ module. Otherwise, the returned promise should be rejected with an error.
+ - If the function returns with a resolved module, a promise is created and resolved with the
+ namespace object of the module. The import call returns with the resolved promise.
+ - If the function returns with an error, a promise is created and rejected with the
+ return error. The import call returns with the rejected promise.
+ - All other return values are considered invalid. In this case the import call returns
+ with a rejected promise. The rejected promise has a fixed error message, it does not
+ specify the reason of the fail.
+ - 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_import_callback_t) (const jerry_value_t specifier,
+ const jerry_value_t user_value,
+ void *user_p);
+```
+
+- `specifier` - a module specifier string (usually used as a path to the module)
+- `user_value` - the user value assigned to the script (see [jerry_parse_options_t](#jerry_parse_options_t))
+- `user_p` - pointer passed to [jerry_module_set_import_callback](#jerry_module_set_import_callback).
+- return value
+ - promise or resolved module - if the operation is successful
+ - an error - otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+- [jerry_module_set_import_callback](#jerry_module_set_import_callback)
+- [jerry_get_global_object](#jerry_get_global_object)
+
## jerry_module_state_changed_callback_t
**Summary**
@@ -854,6 +967,31 @@ typedef void (*jerry_module_state_changed_callback_t) (jerry_module_state_t new_
**See also**
- [jerry_module_set_state_changed_callback](#jerry_module_set_state_changed_callback)
+## jerry_module_import_meta_callback_t
+
+**Summary**
+
+Callback which is called when an import.meta expression of a module is evaluated the first time.
+The object returned by import.meta is passed as the `meta_object` argument to the callback, and
+the callback can set the initial status of the object (e.g. add properties or set prototype).
+
+**Prototype**
+
+```c
+typedef void (*jerry_module_import_meta_callback_t) (const jerry_value_t module,
+ const jerry_value_t meta_object,
+ void *user_p);
+```
+
+- `module` - module whose import.meta object is requested.
+- `meta_object` - import.meta object created for the module.
+- `user_p` - pointer passed to [jerry_module_set_import_meta_callback](#jerry_module_set_import_meta_callback).
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+- [jerry_module_set_import_meta_callback](#jerry_module_set_import_meta_callback)
+
## jerry_native_module_evaluate_callback_t
**Summary**
@@ -1067,6 +1205,32 @@ typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p);
- [jerry_set_vm_exec_stop_callback](#jerry_set_vm_exec_stop_callback)
+## jerry_vm_throw_callback_t
+
+**Summary**
+
+Callback which is called when a value is thrown in an ECMAScript code. The callback
+should not change the `error_value`. The callback is not called again until the value
+is caught.
+
+Note:
+ - The engine considers errors thrown by external functions as never caught. The
+ application can maintain a status flag to ignore the next call of the callback
+ if necessary.
+ See: [jerry_create_external_function](#jerry_create_external_function)
+
+**Prototype**
+
+```c
+typedef void (*jerry_vm_throw_callback_t) (const jerry_value_t error_value, void *user_p);
+```
+
+*New in [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback)
+
## jerry_promise_state_t
Enum which describes the state of a Promise.
@@ -1152,9 +1316,11 @@ 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_FILTER_CREATE - Enables the following event:
- JERRY_PROMISE_EVENT_CREATE
+- JERRY_PROMISE_EVENT_FILTER_RESOLVE - Enables the following event:
- JERRY_PROMISE_EVENT_RESOLVE
+- JERRY_PROMISE_EVENT_FILTER_REJECT - Enables the following event:
- JERRY_PROMISE_EVENT_REJECT
- JERRY_PROMISE_EVENT_FILTER_ERROR - Enables the following events:
- JERRY_PROMISE_EVENT_RESOLVE_FULFILLED
@@ -1238,6 +1404,155 @@ TypedArray support is not in the engine.
- [jerry_get_typedarray_type](#jerry_get_typedarray_type)
+## jerry_exec_snapshot_option_values_t
+
+**Summary**
+
+Various configuration options for [jerry_exec_snapshot](#jerry_exec_snapshot)
+
+**Prototype**
+
+```c
+typedef struct
+{
+ jerry_value_t resource_name; /**< resource name string (usually a file name)
+ * if JERRY_SNAPSHOT_EXEC_HAS_RESOURCE is set in exec_snapshot_opts
+ * Note: non-string values are ignored */
+ jerry_value_t user_value; /**< user value assigned to all functions created by this script including
+ * eval calls executed by the script if JERRY_SNAPSHOT_EXEC_HAS_USER_VALUE
+ * is set in exec_snapshot_opts */
+} jerry_exec_snapshot_option_values_t;
+```
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_exec_snapshot](#jerry_exec_snapshot)
+
+## jerry_source_info_enabled_fields_t
+
+Enum which describes the enabled fields of [jerry_source_info_t](#jerry_source_info_t).
+Possible values:
+
+ - JERRY_SOURCE_INFO_HAS_SOURCE_CODE - source_code field is valid
+ - JERRY_SOURCE_INFO_HAS_FUNCTION_ARGUMENTS - function_arguments field is valid
+ - JERRY_SOURCE_INFO_HAS_SOURCE_RANGE - both source_range_start and source_range_length fields are valid
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_source_info_t](#jerry_source_info_t)
+- [jerry_get_source_info](#jerry_get_source_info)
+
+## jerry_source_info_t
+
+**Summary**
+
+Source related information of a script/module/function.
+
+**Prototype**
+
+```c
+typedef struct
+{
+ uint32_t enabled_fields; /**< combination of jerry_source_info_enabled_fields_t values */
+ jerry_value_t source_code; /**< script source code or function body */
+ jerry_value_t function_arguments; /**< function arguments */
+ uint32_t source_range_start; /**< start position of the function in the source code */
+ uint32_t source_range_length; /**< source length of the function in the source code */
+} jerry_source_info_t;
+```
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_source_info_enabled_fields_t](#jerry_source_info_enabled_fields_t)
+- [jerry_get_source_info](#jerry_get_source_info)
+
+## jerry_arraybuffer_type_t
+
+**Summary**
+
+Enum that contains the JerryScript type of an array buffer:
+
+ - JERRY_ARRAYBUFFER_TYPE_ARRAYBUFFER - the object is an array buffer object
+ - JERRY_ARRAYBUFFER_TYPE_SHARED_ARRAYBUFFER - the object is a shared array buffer object
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_arraybuffer_allocate_t](#jerry_arraybuffer_allocate_t)
+- [jerry_arraybuffer_free_t](#jerry_arraybuffer_free_t)
+
+## jerry_arraybuffer_allocate_t
+
+**Summary**
+
+Callback for allocating the backing store of array buffer or shared array buffer objects.
+
+*Note*:
+- The value referenced by `arraybuffer_user_p` is always NULL unless the buffer is created by
+ [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) or
+ [jerry_create_shared_arraybuffer_external](#jerry_create_shared_arraybuffer_external).
+ The value referenced by `arraybuffer_user_p` can be changed, and the new value is passed to
+ [jerry_arraybuffer_free_t](#jerry_arraybuffer_free_t).
+
+**Prototype**
+
+```c
+typedef uint8_t *(*jerry_arraybuffer_allocate_t) (jerry_arraybuffer_type_t buffer_type, uint32_t buffer_size,
+ void **arraybuffer_user_p, void *user_p);
+```
+
+- `buffer_type` - type of the array buffer object, see: [jerry_arraybuffer_type_t](#jerry_arraybuffer_type_t).
+- `buffer_size` - size of the requested buffer.
+- `arraybuffer_user_p` - [in/out] user pointer assigned to the array buffer or shared array buffer object.
+- `user_p` - user pointer passed to [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks)
+- return value
+ - Pointer to the buffer, if the allocation is successful, NULL otherwise.
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks)
+
+## jerry_arraybuffer_free_t
+
+**Summary**
+
+Callback for freeing the backing store of array buffer or shared array buffer objects.
+
+*Note*:
+- The value passed to `arraybuffer_user_p` is always NULL unless the buffer is created by
+ [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external) or
+ [jerry_create_shared_arraybuffer_external](#jerry_create_shared_arraybuffer_external),
+ or the value is modified by [jerry_arraybuffer_allocate_t](#jerry_arraybuffer_allocate_t).
+
+**Prototype**
+
+```c
+typedef void (*jerry_arraybuffer_free_t) (jerry_arraybuffer_type_t buffer_type, uint8_t *buffer_p,
+ uint32_t buffer_size, void *arraybuffer_user_p, void *user_p);
+```
+
+- `buffer_type` - type of the array buffer object, see: [jerry_arraybuffer_type_t](#jerry_arraybuffer_type_t).
+- `buffer_p` - pointer to the allocated buffer.
+- `buffer_size` - size of the allocated buffer.
+- `arraybuffer_user_p` - [in/out] user pointer assigned to the array buffer or shared array buffer object.
+- `user_p` - user pointer passed to [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks)
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks)
+
+
# General engine functions
## jerry_init
@@ -1588,9 +1903,7 @@ main (void)
**Summary**
-Parse script and construct an EcmaScript function. The lexical environment is
-set to the global lexical environment. The resource name can be used by
-debugging systems to provide line / backtrace info.
+Parse a script, module, or function and create a compiled code using a character string.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
@@ -1612,11 +1925,13 @@ jerry_parse (const jerry_char_t *source_p,
- 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`.
+ This function replaces the `jerry_parse_function` method.
-**Example**
+**Example 1**
-[doctest]: # ()
+[doctest]: # (name="02.API-REFERENCE-parse-simple.c")
```c
#include "jerryscript.h"
@@ -1626,18 +1941,22 @@ main (void)
{
jerry_init (JERRY_INIT_EMPTY);
+ /* Parsing a script. */
const jerry_char_t script[] = "print ('Hello, World!');";
- const jerry_char_t file[] = "hello.js";
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;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "hello.js");
/* 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 (parse_options.resource_name);
+
+ /* Run the "parsed_code" script with "jerry_run". */
+
+ jerry_release_value (jerry_run (parsed_code));
jerry_release_value (parsed_code);
jerry_cleanup ();
@@ -1645,122 +1964,116 @@ main (void)
}
```
+**Example - function parsing**
+
+[doctest]: # (name="02.API-REFERENCE-parse-function.c")
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ /* Specify the argument list to parse a function. */
+ jerry_parse_options_t parse_options;
+ parse_options.options = JERRY_PARSE_HAS_ARGUMENT_LIST;
+ parse_options.argument_list = jerry_create_string ((const jerry_char_t *) "a, b");
+
+ const jerry_char_t function_code[] = "return a + b;";
+ jerry_value_t parsed_function = jerry_parse (function_code, sizeof (function_code) - 1, &parse_options);
+ jerry_release_value (parse_options.argument_list);
+
+ /* Use the "parsed_function" as a normal JavaScript function. */
+
+ jerry_value_t args[] = {
+ jerry_create_number (3),
+ jerry_create_number (4),
+ };
+ jerry_size_t argc = sizeof (args) / sizeof (args[0]);
+ jerry_value_t call_result = jerry_call_function (parsed_function,
+ jerry_create_undefined(),
+ args,
+ argc);
+
+ /* use the function result */
+ jerry_release_value (call_result);
+ jerry_release_value (parsed_function);
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
**See also**
+- [jerry_parse_value](#jerry_parse_value)
- [jerry_run](#jerry_run)
-- [jerry_parse_function](#jerry_parse_function)
- [jerry_parse_options_t](#jerry_parse_options_t)
-## jerry_parse_function
+## jerry_parse_value
**Summary**
-Parse function source code and construct an ECMAScript
-function. The function arguments and function body are
-passed as separated arguments. The lexical environment
-is set to the global lexical environment. The resource
-name (usually a file name) is also passed to this function
-which is used by the debugger to find the source code.
+Parse a script, module, or function and create a compiled code using a string value.
-*Note*: The returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
jerry_value_t
-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);
+jerry_parse_value (const jerry_value_t source_value,
+ const jerry_parse_options_t *options_p);
```
-- `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.
+- `source_value` - string value, containing source code to parse (only string values are accepted).
- `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`.
+*New in version [[NEXT_RELEASE]]*.
**Example**
-[doctest]: # (name="02.API-REFERENCE-parse-func.c")
+[doctest]: # ()
```c
-#include <stdio.h>
-#include <string.h>
#include "jerryscript.h"
int
main (void)
{
- int return_value = 1;
-
- /* Initialize engine */
jerry_init (JERRY_INIT_EMPTY);
- /* Parse the 'function (a,b) { return a + b; }' function */
- const char function_args[] = "a, b";
- const char function_source[] = "return a + b";
-
- 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),
- NULL);
-
- if (!jerry_value_is_error (parsed_function))
- {
- /* Run the parsed function */
- jerry_value_t args[] = {
- jerry_create_number (3),
- jerry_create_number (55),
- };
- jerry_size_t argc = sizeof (args) / sizeof (args[0]);
- jerry_value_t ret_value = jerry_call_function (parsed_function,
- jerry_create_undefined(),
- args,
- argc);
+ jerry_value_t script_value = jerry_create_string ((const jerry_char_t *) "print ('Hello, World!');");
- /* Process result value */
- if (jerry_value_is_number (ret_value)) {
- double value = jerry_get_number_value (ret_value);
- printf ("Function result: %lf\n", value);
-
- return_value = !(value == (3 + 55));
- }
-
- /* Release the function arguments */
- for (jerry_size_t idx = 0; idx < argc; idx++) {
- jerry_release_value (args[idx]);
- }
-
- /* Returned value must be freed */
- jerry_release_value (ret_value);
- }
+ 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 = jerry_create_string ((const jerry_char_t *) "hello.js");
+ /* This example script is extracted from the middle of a file. */
+ parse_options.start_line = 10;
+ parse_options.start_column = 1;
- /* Parsed function must be freed */
- jerry_release_value (parsed_function);
+ jerry_value_t parsed_code = jerry_parse_value (script_value, &parse_options);
+ jerry_release_value (parse_options.resource_name);
+ jerry_release_value (script_value);
+ jerry_release_value (parsed_code);
- /* Cleanup engine */
jerry_cleanup ();
-
- return return_value;
+ return 0;
}
```
**See also**
-- [jerry_call_function](#jerry_call_function)
+- [jerry_parse](#jerry_parse)
+- [jerry_run](#jerry_run)
- [jerry_parse_options_t](#jerry_parse_options_t)
-
## jerry_run
**Summary**
@@ -2102,6 +2415,53 @@ jerry_value_is_arraybuffer (const jerry_value_t value)
- [jerry_create_arraybuffer](#jerry_create_arraybuffer)
- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external)
+## jerry_value_is_shared_arraybuffer
+
+**Summary**
+
+Returns whether the given `jerry_value_t` is a SharedArrayBuffer object.
+
+*Notes*:
+- This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked
+ in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The es.next profile enables this by default.
+
+**Prototype**
+
+```c
+bool
+jerry_value_is_shared_arraybuffer (const jerry_value_t value);
+```
+
+- `value` - api value to check.
+- return value
+ - true, if the given `jerry_value_t` is a SharedArrayBuffer object.
+ - false, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+```c
+{
+ jerry_value_t value;
+ ... // create or acquire value
+
+ if (jerry_value_is_shared_arraybuffer (value))
+ {
+ ...
+ }
+
+ jerry_release_value (value);
+}
+```
+
+**See also**
+
+- [jerry_create_shared_arraybuffer](#jerry_create_shared_arraybuffer)
+- [jerry_create_shared_arraybuffer_external](#jerry_create_shared_arraybuffer_external)
+
## jerry_value_is_boolean
@@ -2159,7 +2519,7 @@ jerry_value_is_true (const jerry_value_t value);
- true, if the given `jerry_value_t` is true value
- false, otherwise
-*New in version [[NEXT_RELEASE]]*.
+*New in version [[NEXT_RELEASE]]*. Replaces the `jerry_get_boolean_value` method.
**Example**
@@ -2563,7 +2923,7 @@ jerry_value_is_object (const jerry_value_t value)
Returns whether the given `jerry_value_t` is a promise value.
*Notes*:
-- This API depends on a build option (`JERRY_BUILTIN_PROMISE`) and can be checked
+- This API depends on a build option (`JERRY_ESNEXT`) and can be checked
in runtime with the `JERRY_FEATURE_PROMISE` feature enum value,
see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
- The es.next profile enables this by default.
@@ -2583,6 +2943,8 @@ jerry_value_is_promise (const jerry_value_t value)
*New in version 2.0*.
+*Changed in version [[NEXT_RELEASE]]*: Build option dependency changed from `JERRY_BUILTIN_PROMISE` to `JERRY_ESNEXT`.
+
**Example**
```c
@@ -3597,6 +3959,228 @@ void main(void)
- [jerry_error_object_created_callback_t](#jerry_error_object_created_callback_t)
+## jerry_set_vm_throw_callback
+
+**Summary**
+
+The callback passed to this function is called when an error is thrown
+in ECMAScript code. The callback is not called again until the value is
+caught. See: [jerry_vm_throw_callback_t](#jerry_vm_throw_callback_t).
+
+*Notes*:
+- This API depends on a build option (`JERRY_VM_THROW`) and can be checked
+ in runtime with the `JERRY_FEATURE_VM_THROW` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+void
+jerry_set_vm_throw_callback (jerry_vm_throw_callback_t throw_cb,
+ void *user_p);
+```
+
+- `throw_cb` - callback which is called on throws (passing NULL disables this feature)
+- `user_p` - user pointer passed to the `throw_cb` function
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+
+static void
+vm_throw_callback (const jerry_value_t error_value, /**< captured error */
+ void *user_p) /**< user pointer */
+{
+ (void) error_value;
+
+ /* Counts the number of throws. */
+ int *counter_p = (int *) user_p;
+ (*counter_p)++;
+}
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ int counter = 0;
+ jerry_set_vm_throw_callback (vm_throw_callback, &counter);
+
+ const jerry_char_t script[] = "try { throw new Error('1') } catch (e) { throw new Error('2') }";
+
+ jerry_release_value (jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS));
+
+ /* The counter contains 2. */
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_vm_throw_callback_t](#jerry_vm_throw_callback_t)
+- [jerry_error_is_throw_captured](#jerry_error_is_throw_captured)
+- [jerry_error_set_throw_capture](#jerry_error_set_throw_capture)
+
+## jerry_error_is_throw_captured
+
+**Summary**
+
+Checks whether the callback set by [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback)
+captured the error.
+
+*Notes*:
+- This API depends on a build option (`JERRY_VM_THROW`) and can be checked
+ in runtime with the `JERRY_FEATURE_VM_THROW` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+bool jerry_error_is_throw_captured (jerry_value_t value);
+```
+
+- `value` - api value (should be an error reference)
+- return value
+ - true, if the vm throw callback captured the error
+ - false, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+
+static void
+vm_throw_callback (const jerry_value_t error_value, /**< captured error */
+ void *user_p) /**< user pointer */
+{
+ (void) error_value;
+ (void) user_p;
+}
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ int counter = 0;
+ jerry_set_vm_throw_callback (vm_throw_callback, &counter);
+
+ const jerry_char_t script[] = "throw new Error()";
+ jerry_value_t result_value = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
+
+ if (jerry_error_is_throw_captured (result_value))
+ {
+ /* Code enters here, because the vm_throw_callback function is called. */
+ }
+
+ jerry_release_value (result_value);
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback)
+- [jerry_error_set_throw_capture](#jerry_error_set_throw_capture)
+
+## jerry_error_set_throw_capture
+
+**Summary**
+
+Sets whether the callback set by [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback)
+should capture the error or not.
+
+*Notes*:
+- This API depends on a build option (`JERRY_VM_THROW`) and can be checked
+ in runtime with the `JERRY_FEATURE_VM_THROW` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+void jerry_error_set_throw_capture (jerry_value_t value, bool should_capture);
+```
+
+- `value` - api value (should be an error reference)
+- `should_capture` - callback should capture this error
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+
+static void
+vm_throw_callback (const jerry_value_t error_value, /**< captured error */
+ void *user_p) /**< user pointer */
+{
+ (void) error_value;
+ (void) user_p;
+}
+
+static jerry_value_t
+throw_exception (const jerry_call_info_t *call_info_p, /**< call info */
+ const jerry_value_t argv[], /**< argument list */
+ const jerry_length_t argc) /**< argument count */
+{
+ (void) call_info_p;
+ (void) argv;
+ (void) argc;
+
+ jerry_value_t result_value = jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Error!");
+
+ /* Ignore calling the vm_throw_callback function. */
+ jerry_error_set_throw_capture (result_value, false);
+ return result_value;
+}
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ int counter = 0;
+ jerry_set_vm_throw_callback (vm_throw_callback, &counter);
+
+ jerry_value_t global_object_value = jerry_get_global_object ();
+ jerry_value_t function_value = jerry_create_external_function (throw_exception);
+ jerry_value_t function_name_value = jerry_create_string ((const jerry_char_t *) "throw_exception");
+
+ jerry_release_value (jerry_set_property (global_object_value, function_name_value, function_value));
+ jerry_release_value (function_name_value);
+ jerry_release_value (function_value);
+ jerry_release_value (global_object_value);
+
+ const jerry_char_t script[] = "throw_exception()";
+ jerry_release_value (jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS));
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback)
+- [jerry_error_is_throw_captured](#jerry_error_is_throw_captured)
+
+
# Getter functions of 'jerry_value_t'
Get raw data from API values.
@@ -4068,6 +4652,141 @@ jerry_substring_to_utf8_char_buffer (const jerry_value_t value,
- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string)
+# jerry_string_set_external_free_callback
+
+**Summary**
+
+Sets the global callback which is called when the string data of an external
+string is no longer used. It is recommended to set this function before the
+first external string is created.
+
+*Note*:
+ - When the callback is NULL, no function is called when an external string is freed.
+ - In some cases (e.g. when the string is also a magic string registered by
+ [jerry_register_magic_strings](#jerry_register_magic_strings)), the callback
+ is called when the string is created, not when it is released.
+
+**Prototype**
+
+```c
+void jerry_string_set_external_free_callback (jerry_external_string_free_callback_t callback_p);
+```
+
+- `callback_p` - callback which is called when an external string is freed.
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+#include <stdio.h>
+
+static void
+external_string_free_callback (jerry_char_t *string_p, /**< string pointer */
+ jerry_size_t string_size, /**< size of the string */
+ void *user_p) /**< user pointer */
+{
+ printf ("External string is freed!\n");
+}
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ jerry_string_set_external_free_callback (external_string_free_callback);
+
+ const char *string_p = "This is a long external string, should not be duplicated!";
+ jerry_value_t external_string = jerry_create_external_string ((jerry_char_t *) string_p, NULL);
+ /* The external_string_free_callback is called. */
+ jerry_release_value (external_string);
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_external_string_free_callback_t](#jerry_external_string_free_callback_t)
+- [jerry_string_get_external_user_pointer](#jerry_string_get_external_user_pointer)
+- [jerry_create_external_string](#jerry_create_external_string)
+- [jerry_create_external_string_sz](#jerry_create_external_string_sz)
+
+
+# jerry_string_get_external_user_pointer
+
+**Summary**
+
+Returns the user pointer assigned to an external string.
+
+*Note*:
+ - In some cases (e.g. when the string is also a magic string registered by
+ [jerry_register_magic_strings](#jerry_register_magic_strings)), the
+ string is a normal string without a user pointer even if it is created
+ by [jerry_create_external_string](#jerry_create_external_string).
+
+**Prototype**
+
+```c
+void *jerry_string_get_external_user_pointer (const jerry_value_t value,
+ bool *is_external);
+```
+
+- `value` - string value.
+- `is_external` - when `is_external` is non-NULL, the referenced boolean value is set
+ to true, if `value` is an external string, and set to false otherwise
+- return value
+ - user pointer - if `value` argument is an external string
+ - NULL - otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+#include <stdio.h>
+
+static int user_value = 1;
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ const char *string_p = "This is a long external string, should not be duplicated!";
+
+ jerry_value_t external_string = jerry_create_external_string ((jerry_char_t *) string_p, (void *) &user_value);
+
+ bool is_external;
+ void *user_p = jerry_string_get_external_user_pointer (external_string, &is_external);
+
+ if (is_external)
+ {
+ /* Prints the address of user_value. */
+ printf("User pointer of an external string: %p\n", user_p);
+ }
+
+ jerry_release_value (external_string);
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_string_set_external_string_free_callback](#jerry_string_set_external_string_free_callback)
+- [jerry_create_external_string](#jerry_create_external_string)
+- [jerry_create_external_string_sz](#jerry_create_external_string_sz)
+
+
# Functions for array object values
## jerry_get_array_length
@@ -4491,14 +5210,14 @@ module_resolve_callback (const jerry_value_t specifier,
* 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;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "b.mjs");
- return jerry_parse (script, sizeof (script) - 1, &parse_options);
+ jerry_value_t result = jerry_parse (script, sizeof (script) - 1, &parse_options);
+ jerry_release_value (parse_options.resource_name);
+ return result;
} /* module_resolve_callback */
int
@@ -4507,14 +5226,13 @@ 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;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs");
jerry_value_t ret_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+ jerry_release_value (parse_options.resource_name);
jerry_module_link (ret_value, module_resolve_callback, NULL);
@@ -4566,14 +5284,13 @@ 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;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs");
jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+ jerry_release_value (parse_options.resource_name);
jerry_release_value (jerry_module_link (module_value, NULL, NULL));
jerry_release_value (jerry_module_evaluate (module_value));
@@ -4628,14 +5345,13 @@ 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;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs");
jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+ jerry_release_value (parse_options.resource_name);
if (jerry_module_get_state (module_value) == JERRY_MODULE_STATE_UNLINKED)
{
@@ -4667,13 +5383,12 @@ Sets a callback which is called after a module state is changed to linked, evalu
**Prototype**
```c
-void
-jerry_module_set_state_changed_callback (jerry_module_state_changed_callback_t callback,
- void *user_p)
+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.
+- `user_p` - pointer passed to the callback function.
*New in version [[NEXT_RELEASE]]*.
@@ -4707,16 +5422,15 @@ 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;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs");
jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+ jerry_release_value (parse_options.resource_name);
jerry_release_value (jerry_module_link (module_value, NULL, NULL));
@@ -4732,6 +5446,82 @@ main (void)
- [jerry_module_state_t](#jerry_module_state_t)
- [jerry_module_state_changed_callback_t](#jerry_module_state_changed_callback_t)
+## jerry_module_set_import_meta_callback
+
+**Summary**
+
+Sets a callback which is called when an import.meta expression of a module is evaluated the first time.
+
+*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_import_meta_callback (jerry_module_import_meta_callback_t callback,
+ void *user_p);
+```
+
+- `callback` - callback, which is called when an import.meta
+ expression of a module is evaluated the first time
+- `user_p` - pointer passed to the callback function.
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+#include <stdio.h>
+
+static void
+module_import_meta_callback (const jerry_value_t module, /**< module */
+ const jerry_value_t meta_object, /**< import.meta object */
+ void *user_p) /**< user pointer */
+{
+ (void) user_p;
+
+ /* Create a property for the meta object */
+ jerry_value_t property_name_value = jerry_create_string ((const jerry_char_t *) "prop");
+ jerry_value_t property_value = jerry_create_string ((const jerry_char_t *) "prop");
+ jerry_value_t result_value = jerry_set_property (meta_object, property_name_value, property_value);
+ jerry_release_value (result_value);
+ jerry_release_value (property_value);
+ jerry_release_value (property_name_value);
+} /* module_import_meta_callback */
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ const jerry_char_t script[] = "import.meta";
+
+ jerry_module_set_import_meta_callback (module_import_meta_callback, NULL);
+
+ jerry_parse_options_t parse_options;
+ parse_options.options = JERRY_PARSE_MODULE;
+
+ 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_import_meta_callback_t](#jerry_module_import_meta_callback_t)
+
## jerry_module_get_number_of_requests
**Summary**
@@ -4773,14 +5563,13 @@ main (void)
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;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs");
jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+ jerry_release_value (parse_options.resource_name);
/* Prints 2. */
printf ("Number of requests: %d\n", (int) jerry_module_get_number_of_requests (module_value));
@@ -4803,7 +5592,7 @@ main (void)
**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 ordered in source code occurrence. 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.
@@ -4849,10 +5638,10 @@ main (void)
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;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs");
jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+ jerry_release_value (parse_options.resource_name);
jerry_value_t request_value = jerry_module_get_request (module_value, 0);
/* Returns with b.mjs */
@@ -4913,14 +5702,13 @@ 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;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "a.mjs");
jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+ jerry_release_value (parse_options.resource_name);
jerry_release_value (jerry_module_link (module_value, NULL, NULL));
jerry_release_value (jerry_module_evaluate (module_value));
@@ -4942,6 +5730,130 @@ main (void)
- [jerry_module_link](#jerry_module_link)
- [jerry_module_evaluate](#jerry_module_evaluate)
+## jerry_module_set_import_callback
+
+Sets the callback which is called when dynamic imports are resolved. The resolver
+receives the `user_value` assigned to the currently executed script, which should
+provide all the information that is necessary for the resolve.
+
+*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).
+- The possible return values of the callback is explained
+ in [jerry_module_import_callback_t](#jerry_module_import_callback_t)
+
+**Prototype**
+
+```c
+void
+jerry_module_set_import_callback (jerry_module_import_callback_t callback_p,
+ void *user_p)
+```
+
+- `callback_p` - a [jerry_module_import_callback_t](#jerry_module_import_callback_t) callback which handles `import()` calls
+- `user_p` - user pointer passed to the callback
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+#include <stdio.h>
+
+typedef struct {
+ jerry_value_t specifier;
+ jerry_value_t user_value;
+ jerry_value_t promise;
+} resolve_module_task_t;
+
+static jerry_value_t
+resolve_dynamic (const jerry_value_t specifier, /**< module specifier */
+ const jerry_value_t user_value, /**< user value assigned to the script */
+ void *user_p) /**< user data */
+{
+ /* If the specified module has already been evaluated, this callback can
+ * return with it and the promise creation is automatically done by the engine.
+ * Otherwise the application usually adds a resolve task to a command queue. */
+
+ /* This very simple command queue supports only one task. */
+ resolve_module_task_t *task_p = (resolve_module_task_t *) user_p;
+ task_p->specifier = jerry_acquire_value (specifier);
+ task_p->user_value = jerry_acquire_value (user_value);
+
+ /* This Promise should be evaluated later. */
+ jerry_value_t promise = jerry_create_promise ();
+ task_p->promise = jerry_acquire_value (promise);
+ return promise;
+}
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ resolve_module_task_t task;
+ jerry_module_set_import_callback (resolve_dynamic, &task);
+
+ const jerry_char_t script[] = "import('modules/my_module.mjs').then(\n"
+ " function (namespace) { /* use namespace */},\n"
+ " function (error) { /* handle error */}\n"
+ ")";
+
+ jerry_parse_options_t parse_options;
+ parse_options.options = JERRY_PARSE_HAS_RESOURCE | JERRY_PARSE_HAS_USER_VALUE;
+
+ /* Resource is usually used for debugging purposes, e.g. for generating backtrace. */
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "dir/my_script.js");
+
+ /* User value should provide information for resolving dynamic imports.
+ * In this case it contains the full path excluding the filename. */
+ parse_options.user_value = jerry_create_string ((const jerry_char_t *) "/home/user/dir");
+
+ jerry_value_t script_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+ jerry_release_value (parse_options.resource_name);
+ jerry_release_value (parse_options.user_value);
+ jerry_release_value (jerry_run (script_value));
+ jerry_release_value (script_value);
+
+ /* The application resolves both the module and the promise using the specifier
+ * and the user_value. In this example the specifier is modules/my_module.mjs. */
+ const jerry_char_t module_script[] = "export var a = 5";
+
+ parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE | JERRY_PARSE_HAS_USER_VALUE;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "modules/my_module.mjs");
+ parse_options.user_value = jerry_create_string ((const jerry_char_t *) "/home/user/dir/modules");
+
+ jerry_value_t module_value = jerry_parse (module_script, sizeof (module_script) - 1, &parse_options);
+ jerry_release_value (parse_options.resource_name);
+ jerry_release_value (parse_options.user_value);
+ jerry_release_value (jerry_module_link (module_value, NULL, NULL));
+ jerry_release_value (jerry_module_evaluate (module_value));
+
+ /* The promise must be resolved with the namespace object, not the module. */
+ jerry_value_t namespace_value = jerry_module_get_namespace (module_value);
+ jerry_release_value (jerry_resolve_or_reject_promise (task.promise, namespace_value, true));
+
+ jerry_release_value (namespace_value);
+ jerry_release_value (module_value);
+ jerry_release_value (task.specifier);
+ jerry_release_value (task.user_value);
+ jerry_release_value (task.promise);
+
+ /* Process promise handlers. */
+ jerry_release_value (jerry_run_all_enqueued_jobs ());
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+- [jerry_module_import_callback_t](#jerry_module_import_callback_t)
+
## jerry_native_module_create
Creates a native module with a list of exports. The initial state of the module is linked.
@@ -5031,7 +5943,7 @@ 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.
+- `native_module_val` - a native module object.
- `export_name_val` - string identifier of the export.
- return
- value of the export, if success
@@ -5086,12 +5998,12 @@ Sets the value of an export binding which belongs to a native module.
```c
jerry_value_t
-jerry_value_t jerry_native_module_set_export (const jerry_value_t native_mmodule_val,
+jerry_value_t jerry_native_module_set_export (const jerry_value_t native_module_val,
const jerry_value_t export_name_val,
const jerry_value_t value_to_set)
```
-- `module_val` - a native module object.
+- `native_module_val` - a native module object.
- `export_name_val` - string identifier of the export.
- `value_to_set` - new value of the export.
- return
@@ -5147,7 +6059,7 @@ The function returns the result of a Promise 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_PROMISE`) and can be checked
+- This API depends on a build option (`JERRY_ESNEXT`) and can be checked
in runtime with the `JERRY_FEATURE_PROMISE` feature enum value,
see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
- The es.next profile enables this by default.
@@ -5169,6 +6081,8 @@ jerry_get_promise_result (const jerry_value_t promise);
*New in version 2.2*.
+*Changed in version [[NEXT_RELEASE]]*: Build option dependency changed from `JERRY_BUILTIN_PROMISE` to `JERRY_ESNEXT`.
+
**Example**
[doctest]: # (test="compile")
@@ -5182,7 +6096,7 @@ example (void)
// acquire/create a promise object.
jerry_value_t promise = jerry_create_promise ();
{
- // prepare the argumnent for the resolve or reject.
+ // prepare the argument for the resolve or reject.
jerry_value_t argument = jerry_create_number (33);
jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
@@ -5214,7 +6128,7 @@ example (void)
*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_PROMISE`) and can be checked
+- This API depends on a build option (`JERRY_ESNEXT`) and can be checked
in runtime with the `JERRY_FEATURE_PROMISE` feature enum value,
see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
- The es.next profile enables this by default.
@@ -5235,6 +6149,8 @@ jerry_get_promise_state (const jerry_value_t promise);
*New in version 2.2*.
+*Changed in version [[NEXT_RELEASE]]*: Build option dependency changed from `JERRY_BUILTIN_PROMISE` to `JERRY_ESNEXT`.
+
**Example**
[doctest]: # (test="compile")
@@ -5252,7 +6168,7 @@ example (void)
// a Promise have a default state of JERRY_PROMISE_STATE_PENDING
{
- // prepare the argumnent for the resolve or reject.
+ // prepare the argument for the resolve or reject.
jerry_value_t argument = jerry_create_number (33);
jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
@@ -5333,7 +6249,7 @@ main (void)
{
jerry_init (JERRY_INIT_EMPTY);
- jerry_promise_set_callback (JERRY_PROMISE_EVENT_FILTER_MAIN, promise_callback, NULL);
+ jerry_promise_set_callback (JERRY_PROMISE_EVENT_FILTER_CREATE, promise_callback, NULL);
const char *source_p = "var p = Promise.resolve(0)\n"
"p.then(function (v) { return v; })";
@@ -5464,7 +6380,7 @@ Resolve or reject the promise with an argument.
*Note*:
- 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_PROMISE`) and can be checked
+- This API depends on a build option (`JERRY_ESNEXT`) and can be checked
in runtime with the `JERRY_FEATURE_PROMISE` feature enum value,
see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
- The es.next profile enables this by default.
@@ -5483,11 +6399,13 @@ jerry_resolve_or_reject_promise (jerry_value_t promise,
- `argument` - the argument for resolve or reject
- `is_resolve` - whether the promise should be resolved or rejected
- return value
- - undefined jerry value - resolve or reject successed
+ - undefined jerry value - success of resolve or reject
- jerry value with error flag - otherwise
*New in version 2.0*.
+*Changed in version [[NEXT_RELEASE]]*: Build option dependency changed from `JERRY_BUILTIN_PROMISE` to `JERRY_ESNEXT`.
+
**Example**
```c
@@ -5497,7 +6415,7 @@ jerry_resolve_or_reject_promise (jerry_value_t promise,
...
bool is_resolve = ... // whether the promise should be resolved or rejected
- jerry_value_t argument = ... // prepare the argumnent for the resolve or reject.
+ jerry_value_t argument = ... // prepare the argument for the resolve or reject.
jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
argument,
@@ -5718,7 +6636,7 @@ These APIs all depend on build option (`JERRY_BUILTIN_BIGINT`).
Returns the size of uint64 digits of a BigInt value. This value is the
minimum size of the buffer which can hold all digits of a BigInt value when
-the digits are retreived by `[jerry_get_bigint_digits](#jerry_get_bigint_digits)`.
+the digits are retrieved by `[jerry_get_bigint_digits](#jerry_get_bigint_digits)`.
*Notes*:
- This API depends on a build option (`JERRY_BUILTIN_BIGINT`) and can be checked
@@ -6070,9 +6988,11 @@ jerry_create_array (uint32_t size);
Create a jerry_value_t representing an ArrayBuffer object.
*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.
+- This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked
+ in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- Returned value must be freed with [jerry_release_value](#jerry_release_value)
+ when it is no longer needed.
**Prototype**
@@ -6081,7 +7001,7 @@ jerry_value_t
jerry_create_arraybuffer (jerry_length_t size);
```
- - `size` - size of the ArrayBuffer to create **in bytes**
+ - `size` - size of the backing store allocated for the array buffer **in bytes**.
- return value - the new ArrayBuffer as a `jerry_value_t`
*New in version 2.0*.
@@ -6118,29 +7038,31 @@ After the object is not needed the GC will call the `free_cb`
so the user can release the buffer which was provided.
*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.
+- This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked
+ in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- If `buffer_p` is NULL, the buffer is allocated by the allocator callback passed to
+ [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks)
+- 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_arraybuffer_external (const jerry_length_t size
- uint8_t *buffer_p,
- jerry_value_free_callback_t free_cb);
+ uint8_t *buffer_p, void *arraybuffer_user_p);
```
-- `size` - size of the buffer to use **in bytes** (should not be 0)
-- `buffer_p` - the buffer used for the Array Buffer object (should not be a null pointer)
-- `free_cb` - the callback function called when the object is released
+- `size` - size of the buffer **in bytes**.
+- `buffer_p` - the backing store used by the array buffer object.
+- `arraybuffer_user_p` - user pointer assigned to the array buffer object.
- return value
- - the new ArrayBuffer as a `jerry_value_t`
- - if the `size` is zero or `buffer_p` is a null pointer this will return an empty ArrayBuffer.
+ - value of the newly constructed array buffer object.
*New in version 2.0*.
-*Changed in version [[NEXT_RELEASE]]*: type of `free_cb` has been changed.
+*Changed in version [[NEXT_RELEASE]]*: `free_cb` has been replaced by `arraybuffer_user_p`.
**Example**
@@ -6165,12 +7087,117 @@ jerry_create_arraybuffer_external (const jerry_length_t size
- [jerry_object_native_free_callback_t](#jerry_object_native_free_callback_t)
+## jerry_create_shared_arraybuffer
+
+**Summary**
+
+Create a jerry_value_t representing a SharedArrayBuffer object.
+
+*Note*:
+- This API depends on a build option (`JERRY_BUILTIN_SHAREDARRAYBUFFER`).
+- 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_shared_arraybuffer (jerry_length_t size);
+```
+
+- `size` - size of the backing store allocated for the shared array buffer **in bytes**.
+- return value - the new SharedArrayBuffer as a `jerry_value_t`
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+```c
+{
+ jerry_value_t buffer_value = jerry_create_shared_arraybuffer (15);
+
+ ... // use the SharedArrayBuffer
+
+ jerry_release_value (buffer_value);
+}
+```
+
+**See also**
+
+- [jerry_arraybuffer_read](#jerry_arraybuffer_read)
+- [jerry_arraybuffer_write](#jerry_arraybuffer_write)
+- [jerry_value_is_shared_arraybuffer](#jerry_value_is_shared_arraybuffer)
+- [jerry_release_value](#jerry_release_value)
+
+
+## jerry_create_shared_arraybuffer_external
+
+**Summary**
+
+Creates a jerry_value_t representing an SharedArrayBuffer object with
+user specified back-buffer.
+
+User must pass a buffer pointer which is at least `size` big.
+After the object is not needed the GC will call the `free_cb`
+so the user can release the buffer which was provided.
+
+*Note*:
+- This API depends on a build option (`JERRY_BUILTIN_SHAREDARRAYBUFFER`).
+- If `buffer_p` is NULL, the buffer is allocated by the allocator callback passed to
+ [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks)
+- 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_shared_arraybuffer_external (const jerry_length_t size
+ uint8_t *buffer_p,
+ jerry_value_free_callback_t free_cb);
+```
+
+- `size` - size of the buffer **in bytes**.
+- `buffer_p` - the backing store used by the shared array buffer object.
+- `arraybuffer_user_p` - user pointer assigned to the shared array buffer object.
+- return value
+ - value of the newly constructed shared array buffer object.
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+```c
+{
+ uint8_t buffer_p[15];
+ jerry_value_t buffer_value = jerry_create_shared_arraybuffer_external (15, buffer_p, NULL);
+
+ ... // use the shared array buffer
+
+ jerry_release_value (buffer_value);
+}
+```
+
+**See also**
+
+- [jerry_get_arraybuffer_pointer](#jerry_get_arraybuffer_pointer)
+- [jerry_arraybuffer_read](#jerry_arraybuffer_read)
+- [jerry_arraybuffer_write](#jerry_arraybuffer_write)
+- [jerry_value_is_shared_arraybuffer](#jerry_value_is_shared_arraybuffer)
+- [jerry_release_value](#jerry_release_value)
+- [jerry_object_native_free_callback_t](#jerry_object_native_free_callback_t)
+
+
## jerry_create_boolean
**Summary**
Create a jerry_value_t representing a boolean value from the given boolean parameter.
+*Notes*:
+- The boolean values (true/false) are fixed constants. Their values can be copied any number of times without calling
+ [jerry_acquire_value](#jerry_acquire_value), and freeing it with [jerry_release_value](#jerry_release_value) is optional.
+
**Prototype**
```c
@@ -6539,6 +7566,10 @@ jerry_create_number_nan (void);
Creates and returns a `jerry_value_t` with type null object.
+*Notes*:
+- The null value is a fixed constant. Its value can be copied any number of times without calling
+ [jerry_acquire_value](#jerry_acquire_value), and freeing it with [jerry_release_value](#jerry_release_value) is optional.
+
**Prototype**
```c
@@ -6940,24 +7971,25 @@ Create an external string from a valid CESU8 string. The string buffer passed to
should not be modified until the free callback is called. This function can be used to avoid
the duplication of large strings.
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
-is no longer needed.
+*Note*:
+ - The free callback can be set by [jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback)
+ - 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_external_string (const jerry_char_t *str_p,
- jerry_value_free_callback_t free_cb)
+jerry_create_external_string (const jerry_char_t *str_p, void *user_p);
```
- `str_p` - non-null pointer to string
-- `free_cb` - optional callback which is called right before the string is freed
+- `user_p` - user pointer passed to the callback when the string is freed
- return value - value of the created string
*New in version 2.4*.
-*Changed in version [[NEXT_RELEASE]]*: type of `free_cb` has been changed.
+*Changed in version [[NEXT_RELEASE]]*: `free_cb` is replaced by `user_p`.
**Example**
@@ -6977,6 +8009,7 @@ jerry_create_external_string (const jerry_char_t *str_p,
- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
- [jerry_create_external_string_sz](#jerry_create_external_string_sz)
+- [jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback)
## jerry_create_external_string_sz
@@ -6987,8 +8020,10 @@ Create an external string from a valid CESU8 string. The string buffer passed to
should not be modified until the free callback is called. This function can be used to avoid
the duplication of large strings.
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
-is no longer needed.
+*Note*:
+ - The free callback can be set by [jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback)
+ - Returned value must be freed with [jerry_release_value](#jerry_release_value)
+ when it is no longer needed.
**Prototype**
@@ -6996,17 +8031,17 @@ is no longer needed.
jerry_value_t
jerry_create_external_string_sz (const jerry_char_t *str_p,
jerry_size_t str_size,
- jerry_value_free_callback_t free_cb)
+ void *user_p);
```
- `str_p` - non-null pointer to string
- `str_size` - size of the string
-- `free_cb` - optional callback which is called right before the string is freed
+- `user_p` - user pointer passed to the callback when the string is freed
- return value - value of the created string
*New in version 2.4*.
-*Changed in version [[NEXT_RELEASE]]*: type of `free_cb` has been changed.
+*Changed in version [[NEXT_RELEASE]]*: `free_cb` is replaced by `user_p`.
**Example**
@@ -7028,6 +8063,7 @@ jerry_create_external_string_sz (const jerry_char_t *str_p,
- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
- [jerry_create_external_string](#jerry_create_external_string)
+- [jerry_string_set_external_free_callback](#jerry_string_set_external_free_callback)
## jerry_create_symbol
@@ -7472,6 +8508,10 @@ main (void)
Creates a `jerry_value_t` representing an undefined value.
+*Notes*:
+- The undefined value is a fixed constant. Its value can be copied any number of times without calling [jerry_acquire_value](#jerry_acquire_value), and freeing it with [jerry_release_value](#jerry_release_value) is optional.
+
+
**Prototype**
```c
@@ -8454,7 +9494,7 @@ method_setter (const jerry_call_info_t *call_info_p,
const jerry_length_t argc)
{
// Note: the arguments count and type should be checked
- // in this example it is ommitted!
+ // in this example it is omitted!
double new_value = jerry_get_number_value (args[0]);
counter = (int) new_value;
@@ -8539,7 +9579,7 @@ 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`
+*Changed in version [[NEXT_RELEASE]]*: Return value type is changed to `jerry_value_t`.
**Example**
@@ -9037,12 +10077,12 @@ main (void)
shape_p->perimeter = 12;
jerry_set_object_native_pointer (object, shape_p, &shape_obj_type_info);
- // The native pointer can be NULL. This gives possibily to get notified via the native type info's
+ // The native pointer can be NULL. This gives possibly to get notified via the native type info's
// free callback when the object has been freed by the GC.
jerry_set_object_native_pointer (object, NULL, &destructor_obj_type_info);
// The native type info can be NULL as well. In this case the registered property is simply freed
- // when the object is freed by te GC.
+ // when the object is freed by the GC.
jerry_set_object_native_pointer (object, SECRET_INFO, NULL);
do_stuff (object);
@@ -10047,29 +11087,30 @@ Generate snapshot from the specified source code.
```c
jerry_value_t
-jerry_generate_snapshot (const jerry_char_t *source_p,
- size_t source_size,
- const jerry_parse_options_t *options_p,
+jerry_generate_snapshot (jerry_value_t compiled_code,
uint32_t generate_snapshot_opts,
uint32_t *buffer_p,
size_t buffer_size);
```
-- `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
+- `compiled_code` - compiled script or function (see: [jerry_parse](#jerry_parse)).
- `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.
- return value
- - the size of the generated snapshot in bytes as number value, if it was generated succesfully (i.e. there
+ - the size of the generated snapshot in bytes as number value, if it was generated successfully (i.e. there
are no syntax errors in source code, buffer size is sufficient, and snapshot support is enabled in
current configuration through JERRY_SNAPSHOT_SAVE)
- 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`.
+*Changed in version [[NEXT_RELEASE]]*: The `source_p`, `source_size`, `resource_name_p`,
+ and `resource_name_length` arguments are replaced by `compiled_code`
+ which should contain a compiled ECMAScript script / function.
+ The `jerry_generate_function_snapshot` is now removed and can be reproduced
+ by calling `jerry_parse` with function arguments and using this method
+ (see [jerry_exec_snapshot](#jerry_exec_snapshot)).
**Example**
[doctest]: # ()
@@ -10085,108 +11126,16 @@ main (void)
static uint32_t global_mode_snapshot_buffer[256];
const jerry_char_t script_to_snapshot[] = "(function () { return 'string from snapshot'; }) ();";
- jerry_value_t generate_result;
- 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));
-
- if (!jerry_value_is_error (generate_result))
- {
- size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
- }
-
- jerry_release_value (generate_result);
-
- jerry_cleanup ();
- return 0;
-}
-```
-
-**See also**
-
-- [jerry_init](#jerry_init)
-- [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
-
-**Summary**
-
-Generate function snapshot from the specified source code
-with the given arguments.
-
-The function arguments and function body are
-passed as separated arguments.
-
-*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_SNAPSHOT_SAVE`) and can be checked in runtime with
- the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled).
- If the feature is not enabled the function will return an error.
-
-**Prototype**
-
-```c
-jerry_value_t
-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)
-```
-
-- `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.
-- return value
- - the size of the generated snapshot in bytes as number value, if it was generated succesfully (i.e. there
- are no syntax errors in source code, buffer size is sufficient, and snapshot support is enabled in
- current configuration through JERRY_SNAPSHOT_SAVE)
- - 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**
-
-[doctest]: # ()
-
-```c
-#include "jerryscript.h"
-
-int
-main (void)
-{
- jerry_init (JERRY_INIT_EMPTY);
-
- static uint32_t func_snapshot_buffer[256];
- const jerry_char_t args[] = "a, b";
- const jerry_char_t src[] = "return a + b;";
+ jerry_value_t parse_result = jerry_parse (script_to_snapshot,
+ sizeof (script_to_snapshot) - 1,
+ NULL);
- jerry_value_t generate_result;
- 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));
+ size_t buffer_size = sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t);
+ jerry_value_t generate_result = jerry_generate_snapshot (parse_result,
+ 0,
+ global_mode_snapshot_buffer,
+ buffer_size);
+ jerry_release_value (parse_result);
if (!jerry_value_is_error (generate_result))
{
@@ -10202,10 +11151,9 @@ main (void)
**See also**
-- [jerry_init](#jerry_init)
-- [jerry_cleanup](#jerry_cleanup)
-- [jerry_generate_snapshot](#jerry_generate_snapshot)
-- [jerry_load_function_snapshot_at](#jerry_load_function_snapshot_at)
+- [jerry_parse](#jerry_parse)
+- [jerry_parse_value](#jerry_parse_value)
+- [jerry_exec_snapshot](#jerry_exec_snapshot)
- [jerry_parse_options_t](#jerry_parse_options_t)
@@ -10213,7 +11161,7 @@ main (void)
**Summary**
-Execute snapshot from the specified buffer.
+Execute/load snapshot from the specified buffer.
*Notes*:
- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
@@ -10229,20 +11177,25 @@ jerry_value_t
jerry_exec_snapshot (const uint32_t *snapshot_p,
size_t snapshot_size,
size_t func_index,
- uint32_t exec_snapshot_opts);
+ uint32_t exec_snapshot_opts,
+ const jerry_exec_snapshot_option_values_t *options_values_p);
```
- `snapshot_p` - pointer to snapshot.
- `snapshot_size` - size of snapshot in bytes.
- `func_index` - index of executed function.
- `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags.
+- `options_values_p` - additional loading options, can be NULL if not used. The fields are described in
+ [jerry_exec_snapshot_option_values_t](#jerry_exec_snapshot_option_values_t).
- return value
- result of bytecode, if run was successful.
- thrown error, otherwise (an error is reported if the snapshot execution feature is not enabled).
*Changed in version 2.0*: Added `func_index` and `exec_snapshot_opts` arguments. Removed the `copy_bytecode` last argument.
-**Example**
+*Changed in version [[NEXT_RELEASE]]*: Added `options_p` argument.
+
+**Example 1**
[doctest]: # ()
@@ -10252,34 +11205,39 @@ jerry_exec_snapshot (const uint32_t *snapshot_p,
int
main (void)
{
- static uint32_t global_mode_snapshot_buffer[256];
- const jerry_char_t script_to_snapshot[] = "(function () { return 'string from snapshot'; }) ();";
+ static uint32_t snapshot_buffer[256];
+ /* 1st example: global mode snapshot. */
jerry_init (JERRY_INIT_EMPTY);
- jerry_value_t generate_result;
- 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));
- // generate_result should be checked if it is an error or not
+ const jerry_char_t script_to_snapshot[] = "(function () { return 'string from snapshot'; }) ();";
+
+ jerry_value_t parse_result = jerry_parse (script_to_snapshot,
+ sizeof (script_to_snapshot) - 1,
+ NULL);
+
+ size_t buffer_size = sizeof (snapshot_buffer) / sizeof (uint32_t);
+ jerry_value_t generate_result = jerry_generate_snapshot (parse_result,
+ 0,
+ snapshot_buffer,
+ buffer_size);
+ jerry_release_value (parse_result);
+
+ /* 'generate_result' variable should be checked whether it contains an error. */
- size_t global_mode_snapshot_size = (size_t) jerry_get_number_value (generate_result);
+ size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
jerry_release_value (generate_result);
jerry_cleanup ();
-
jerry_init (JERRY_INIT_EMPTY);
- jerry_value_t res = jerry_exec_snapshot (global_mode_snapshot_buffer,
- global_mode_snapshot_size,
+ jerry_value_t res = jerry_exec_snapshot (snapshot_buffer,
+ snapshot_size,
0,
- 0);
-
- // check the `res` value for error and process the result.
+ 0,
+ NULL);
+ /* 'res' now contains 'string from snapshot' */
jerry_release_value (res);
jerry_cleanup ();
@@ -10287,49 +11245,7 @@ main (void)
}
```
-**See also**
-
-- [jerry_init](#jerry_init)
-- [jerry_cleanup](#jerry_cleanup)
-- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot)
-
-
-## jerry_load_function_snapshot
-
-**Summary**
-
-Load the selected snapshot function from the specified buffer as a function object.
-
-The lexical environment of the loaded function is always the global lexical environment.
-
-*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_SNAPSHOT_EXEC`) and can be checked in runtime with
- the `JERRY_FEATURE_SNAPSHOT_EXEC` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled).
- If the feature is not enabled the function will return an error.
-
-**Prototype**
-
-```c
-jerry_value_t
-jerry_load_function_snapshot (const uint32_t *snapshot_p,
- size_t snapshot_size,
- size_t func_index,
- uint32_t exec_snapshot_opts);
-```
-
-- `snapshot_p` - pointer to snapshot.
-- `snapshot_size` - size of snapshot in bytes.
-- `func_index` - index of function to load from the snapshot.
-- `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags.
-- return value
- - function object built from the snapshot.
- - thrown error, otherwise.
-
-*New in version 2.0*.
-
-**Example**
+**Example 2**
[doctest]: # ()
@@ -10340,33 +11256,42 @@ int
main (void)
{
static uint32_t snapshot_buffer[256];
- const jerry_char_t func_args[] = "a, b";
- const jerry_char_t func_src[] = "return a + b;";
+ /* 2nd example: function snapshot. */
jerry_init (JERRY_INIT_EMPTY);
- jerry_value_t generate_result;
- generate_result = jerry_generate_function_snapshot (func_src,
- sizeof (func_src) - 1,
- func_args,
- sizeof (func_args) - 1,
- NULL,
- 0,
- snapshot_buffer,
- sizeof (snapshot_buffer) / sizeof (uint32_t));
+ const jerry_char_t function_to_snapshot[] = "return a + b;";
+
+ jerry_parse_options_t parse_options;
+ parse_options.options = JERRY_PARSE_HAS_ARGUMENT_LIST;
+ parse_options.argument_list = jerry_create_string ((const jerry_char_t *) "a, b");
+
+ jerry_value_t parse_result = jerry_parse (function_to_snapshot,
+ sizeof (function_to_snapshot) - 1,
+ &parse_options);
+
+ size_t buffer_size = sizeof (snapshot_buffer) / sizeof (uint32_t);
+ jerry_value_t generate_result = jerry_generate_snapshot (parse_result,
+ 0,
+ snapshot_buffer,
+ buffer_size);
+ jerry_release_value (parse_result);
+ jerry_release_value (parse_options.argument_list);
+
+ /* 'generate_result' variable should be checked whether it contains an error. */
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
jerry_release_value (generate_result);
jerry_cleanup ();
-
jerry_init (JERRY_INIT_EMPTY);
- jerry_value_t func = jerry_load_function_snapshot (snapshot_buffer,
- snapshot_size,
- 0,
- 0);
- /* 'func' can be used now as a function object */
+ jerry_value_t func = jerry_exec_snapshot (snapshot_buffer,
+ snapshot_size,
+ 0,
+ JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION,
+ NULL);
+ /* 'func' can be used now as a function object. */
jerry_value_t this_value = jerry_create_undefined ();
jerry_value_t args[2];
@@ -10375,8 +11300,8 @@ main (void)
jerry_value_t res = jerry_call_function (func, this_value, args, 2);
- /* 'res' now contains the value 3 as a jerry_value_t */
-
+ /* 'res' now contains the value 3 as a jerry_value_t. */
+ jerry_release_value (res);
jerry_release_value (args[0]);
jerry_release_value (args[1]);
jerry_release_value (this_value);
@@ -10391,7 +11316,7 @@ main (void)
- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)
-- [jerry_parse_and_save_function_snapshot](#jerry_parse_and_save_function_snapshot)
+- [jerry_generate_snapshot](#jerry_generate_snapshot)
## jerry_get_literals_from_snapshot
@@ -10423,7 +11348,7 @@ jerry_get_literals_from_snapshot (const uint32_t *snapshot_p,
- `lit_buf_size` - the buffer's size.
- `is_c_format` - the output format would be C-style (true) or a simple list (false).
- return value
- - the size of the literal-list, if it was generated succesfully (i.e. the list of literals isn't empty,
+ - the size of the literal-list, if it was generated successfully (i.e. the list of literals isn't empty,
and literal-save support is enabled in current configuration through JERRY_SNAPSHOT_SAVE)
- 0 otherwise.
@@ -10446,12 +11371,17 @@ 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 (script_for_literal_save,
- sizeof (script_for_literal_save) - 1,
- NULL,
+ jerry_value_t parse_result = jerry_parse (script_for_literal_save,
+ sizeof (script_for_literal_save) - 1,
+ NULL);
+
+ size_t buffer_size = sizeof (snapshot_buffer) / sizeof (uint32_t);
+ jerry_value_t generate_result = jerry_generate_snapshot (parse_result,
0,
snapshot_buffer,
- 256);
+ buffer_size);
+ jerry_release_value (parse_result);
+
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
jerry_release_value (generate_result);
@@ -10580,16 +11510,16 @@ main (void)
"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);
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "demo_memory.js");
jerry_value_t program = jerry_parse ((const jerry_char_t *) source,
strlen (source),
&parse_options);
+ jerry_release_value (parse_options.resource_name);
+
if (!jerry_value_is_error (program))
{
jerry_value_t run_result = jerry_run (program);
@@ -10686,16 +11616,16 @@ main (void)
"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);
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "demo_backtrace.js");
jerry_value_t program = jerry_parse ((const jerry_char_t *) source,
strlen (source),
&parse_options);
+ jerry_release_value (parse_options.resource_name);
+
if (!jerry_value_is_error (program))
{
jerry_value_t run_result = jerry_run (program);
@@ -10988,7 +11918,7 @@ backtrace_callback (jerry_backtrace_frame_t *frame_p,
if (jerry_backtrace_is_strict (frame_p))
{
printf ("Strict mode code is running");
- return truel
+ return true;
}
printf ("Non-strict mode code is running");
@@ -11007,8 +11937,7 @@ backtrace_callback (jerry_backtrace_frame_t *frame_p,
**Summary**
-When JERRY_FEATURE_VM_EXEC_STOP is enabled a callback function can be
-specified by this function. This callback is periodically called when
+The callback passed to this function is periodically called when
JerryScript executes an ECMAScript program.
If the callback returns with undefined value the ECMAScript execution
@@ -11023,6 +11952,10 @@ or an exception is caught. Setting the `frequency` to a greater
than `1` value reduces this overhead further. If its value is N
only every Nth event (backward jump, etc.) trigger the next check.
+*Notes*:
+- This API depends on a build option (`JERRY_VM_EXEC_STOP`) and can be checked
+ in runtime with the `JERRY_FEATURE_VM_EXEC_STOP` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
**Prototype**
@@ -11046,14 +11979,14 @@ jerry_set_vm_exec_stop_callback (jerry_vm_exec_stop_callback_t stop_cb,
```c
#include "jerryscript.h"
-static int countdown = 10;
-
static jerry_value_t
vm_exec_stop_callback (void *user_p)
{
- while (countdown > 0)
+ int *countdown_p = (int *) user_p;
+
+ while (*countdown_p > 0)
{
- countdown--;
+ (*countdown_p)--;
return jerry_create_undefined ();
}
@@ -11066,6 +11999,7 @@ main (void)
{
jerry_init (JERRY_INIT_EMPTY);
+ int countdown = 10;
jerry_set_vm_exec_stop_callback (vm_exec_stop_callback, &countdown, 16);
// Infinite loop.
@@ -11080,10 +12014,6 @@ main (void)
**See also**
-- [jerry_init](#jerry_init)
-- [jerry_cleanup](#jerry_cleanup)
-- [jerry_parse](#jerry_parse)
-- [jerry_run](#jerry_run)
- [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t)
## jerry_get_resource_name
@@ -11156,16 +12086,15 @@ main (void)
jerry_release_value (global);
const jerry_char_t source[] = "function myFunction() { return resourceName() }; myFunction()";
- const jerry_char_t resource[] = "demo.js";
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;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) "demo.js");
jerry_value_t program = jerry_parse (source,
sizeof (source) - 1,
&parse_options);
+ jerry_release_value (parse_options.resource_name);
if (!jerry_value_is_error (program))
{
@@ -11188,6 +12117,220 @@ main (void)
- [jerry_create_external_function](#jerry_create_external_function)
+## jerry_get_user_value
+
+**Summary**
+
+Returns the user value assigned to a script / module / function. This value is
+set by the parser when the JERRY_PARSE_HAS_USER_VALUE flag is set in the `options`
+member of the [jerry_parse_options_t](#jerry_parse_options_t) structure.
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_get_user_value (const jerry_value_t value);
+```
+- `value` - script / module / function value which executes ECMAScript
+ code (native modules / functions do not have user value).
+- return
+ - user value - if available,
+ - undefined - otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ const jerry_char_t script[] = "function abc() {} abc";
+
+ jerry_value_t user_value = jerry_create_object ();
+
+ jerry_parse_options_t parse_options;
+ parse_options.options = JERRY_PARSE_HAS_USER_VALUE;
+ parse_options.user_value = user_value;
+
+ jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, &parse_options);
+ jerry_release_value (user_value);
+
+ /* The jerry_get_user_value returns the object which
+ * was created by jerry_create_object before. */
+
+ user_value = jerry_get_user_value (parsed_code);
+ jerry_release_value (parsed_code);
+
+ jerry_release_value (user_value);
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_parse](#jerry_parse)
+- [jerry_generate_snapshot](#jerry_generate_snapshot)
+- [jerry_exec_snapshot](#jerry_exec_snapshot)
+
+## jerry_is_eval_code
+
+**Summary**
+
+Checks whether an ECMAScript code is compiled by eval like (eval, new Function,
+[jerry_eval](#jerry_eval), etc.) command.
+
+**Prototype**
+
+```c
+bool jerry_is_eval_code (const jerry_value_t value);
+```
+- `value` - script / module / function value which executes ECMAScript code
+- return
+ - true - if code is compiled by eval like command
+ - false - otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ const jerry_char_t script[] = "eval('(function (a) { return a; })')";
+
+ jerry_value_t script_value = jerry_parse (script, sizeof (script) - 1, NULL);
+ jerry_value_t function_value = jerry_run (script_value);
+ jerry_release_value (script_value);
+
+ if (jerry_is_eval_code (function_value))
+ {
+ /* Code enters here. */
+ }
+
+ jerry_release_value (function_value);
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_parse](#jerry_parse)
+- [jerry_generate_snapshot](#jerry_generate_snapshot)
+- [jerry_exec_snapshot](#jerry_exec_snapshot)
+
+## jerry_get_source_info
+
+**Summary**
+
+Returns a newly created source info structure corresponding to the passed script/module/function.
+The function is lower level than `toString()` operation, but provides more contextual information.
+
+*Notes*:
+- Returned value must be freed with [jerry_free_source_info](#jerry_free_source_info) when it
+is no longer needed.
+- This API depends on a build option (`JERRY_FUNCTION_TO_STRING`) and can be checked
+ in runtime with the `JERRY_FEATURE_FUNCTION_TO_STRING` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+jerry_source_info_t *jerry_get_source_info (const jerry_value_t value);
+```
+- `value` - script / module / function value which executes JavaScript
+ code (native modules / functions do not have source info).
+- return
+ - source info - a newly created source info, if at least one field is available,
+ - NULL - otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ const jerry_char_t script[] = "function abc() {} abc";
+
+ jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL);
+
+ jerry_source_info_t *source_info_p = jerry_get_source_info (parsed_code);
+ jerry_release_value (parsed_code);
+
+ if (source_info_p != NULL)
+ {
+ /* Check the information provided by jerry_get_source_info. */
+ }
+
+ jerry_free_source_info (source_info_p);
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_free_source_info](#jerry_free_source_info)
+- [jerry_source_info_t](#jerry_source_info_t)
+
+## jerry_free_source_info
+
+**Summary**
+
+Frees the the source info structure returned by [jerry_get_source_info](#jerry_get_source_info).
+
+*Notes*:
+- This API depends on a build option (`JERRY_FUNCTION_TO_STRING`) and can be checked
+ in runtime with the `JERRY_FEATURE_FUNCTION_TO_STRING` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+void jerry_free_source_info (jerry_source_info_t *source_info_p)
+```
+- `source_info_p` - source info structure returned by [jerry_get_source_info](#jerry_get_source_info)
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+See [jerry_get_source_info](#jerry_get_source_info)
+
+**See also**
+
+- [jerry_get_source_info](#jerry_get_source_info)
+- [jerry_source_info_t](#jerry_source_info_t)
+
+
# Functions for realm objects
These APIs all depend on build option (`JERRY_BUILTIN_REALMS`).
@@ -11351,7 +12494,7 @@ These APIs all depend on the es.next profile.
**Summary**
-Get the byte length property of the ArrayBuffer. This is the
+Get the byte length property of the ArrayBuffer or SharedArrayBuffer. This is the
same value which was passed to the ArrayBuffer constructor call.
**Prototype**
@@ -11388,7 +12531,7 @@ jerry_get_arraybuffer_byte_length (const jerry_value_t value);
**Summary**
-Copy the portion of the ArrayBuffer into a user provided buffer.
+Copy the portion of the ArrayBuffer or SharedArrayBuffer into a user provided buffer.
The start offset of the read operation can be specified.
The number bytes to be read can be specified via the `buf_size`
@@ -11426,7 +12569,7 @@ jerry_arraybuffer_read (const jerry_value_t value,
{
uint8_t data[20];
jerry_value_t buffer;
- // ... create the ArrayBuffer or acuiqre it from somewhere.
+ // ... create the ArrayBuffer or acquire it from somewhere.
jerry_value_t bytes_read;
@@ -11452,7 +12595,7 @@ jerry_arraybuffer_read (const jerry_value_t value,
**Summary**
-Copy the contents of a buffer into the ArrayBuffer.
+Copy the contents of a buffer into the ArrayBuffer or SharedArrayBuffer.
The start offset of the write operation can be specified.
The number bytes to be written can be specified via the `buf_size`
@@ -11659,6 +12802,231 @@ jerry_detach_arraybuffer (const jerry_value_t value);
- [jerry_is_arraybuffer_detachable](#jerry_is_arraybuffer_detachable)
+## jerry_arraybuffer_has_buffer
+
+**Summary**
+
+Checks whether a buffer is currently allocated for an array buffer or typed array.
+
+*Notes*:
+- This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked
+ in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+bool
+jerry_arraybuffer_has_buffer (const jerry_value_t value);
+```
+
+- `value` - array buffer or typed array value.
+- return
+ - true, if a buffer is allocated for an array buffer or typed array
+ - false, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ jerry_value_t array_buffer_value = jerry_create_arraybuffer (1024 * 1024);
+
+ /* By default, the backing store of large array buffers
+ * is allocated when it is used the first time. */
+
+ if (!jerry_arraybuffer_has_buffer (array_buffer_value))
+ {
+ /* Code enters here in this case. */
+ }
+
+ jerry_release_value (array_buffer_value);
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external)
+- [jerry_create_shared_arraybuffer_external](#jerry_create_shared_arraybuffer_external)
+- [jerry_arraybuffer_set_compact_allocation_limit](#jerry_arraybuffer_set_compact_allocation_limit)
+- [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks)
+
+## jerry_arraybuffer_set_compact_allocation_limit
+
+**Summary**
+
+Array buffers which size is less or equal than the limit passed to this
+function are allocated in a single memory block. The allocator callbacks set by
+[jerry_arraybuffer_set_allocation_callbacks](#jerry_arraybuffer_set_allocation_callbacks)
+are not called for these array buffers.
+
+*Notes*:
+- This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked
+ in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The default limit is 256 bytes.
+- When an array buffer is allocated in a single memory block, its
+ backing store is not freed when the array buffer is detached.
+- This limit does not affect shared array buffers, their backing store is always
+ allocated by the allocator callback.
+
+**Prototype**
+
+```c
+void
+jerry_arraybuffer_set_compact_allocation_limit (const jerry_length_t allocation_limit);
+```
+
+- `allocation_limit` - maximum size of compact allocation.
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ jerry_arraybuffer_set_compact_allocation_limit (1);
+
+ jerry_value_t array_buffer_value = jerry_create_arraybuffer (1);
+
+ if (jerry_arraybuffer_has_buffer (array_buffer_value))
+ {
+ /* Code enters here because the backing store
+ * is allocated during buffer creation. */
+ }
+
+ jerry_release_value (array_buffer_value);
+
+ array_buffer_value = jerry_create_arraybuffer (2);
+
+ if (jerry_arraybuffer_has_buffer (array_buffer_value))
+ {
+ /* Code does not enter here because the backing store
+ * is allocated when it is used the first time. */
+ }
+
+ jerry_release_value (array_buffer_value);
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_arraybuffer_has_buffer](#jerry_arraybuffer_has_buffer)
+- [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks)
+
+## jerry_arraybuffer_set_allocator_callbacks
+
+**Summary**
+
+Set callbacks for allocating and freeing backing stores for array buffer objects.
+
+*Notes*:
+- This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked
+ in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value,
+ see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- This function is recommended to be called after [jerry_init](#jerry_init) before
+ any array buffer is allocated.
+- The callbacks can be NULL to use the default callbacks. The default `allocate_callback`
+ allocates memory using [jerry_heap_alloc](#jerry_heap_alloc) and the default
+ `free_callback` frees memory using [jerry_heap_free](#jerry_heap_free).
+
+
+**Prototype**
+
+```c
+void
+jerry_arraybuffer_set_allocator_callbacks (jerry_arraybuffer_allocate_t allocate_callback,
+ jerry_arraybuffer_free_t free_callback,
+ void *user_p)
+```
+
+- `allocate_callback` - callback for allocating array buffer memory.
+- `free_callback` - callback for freeing array buffer memory.
+- `user_p` - user pointer passed to the callbacks.
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+
+static uint8_t global_buffer[64];
+
+static void
+array_buffer_free_cb (jerry_arraybuffer_type_t buffer_type, /**< type of the array buffer object */
+ uint8_t *buffer_p, /**< pointer to the allocated buffer */
+ uint32_t buffer_size, /**< size of the allocated buffer */
+ void *arraybuffer_user_p, /**< user pointer assigned to the array buffer object */
+ void *user_p) /**< user pointer passed to jerry_arraybuffer_set_allocation_callbacks */
+{
+ (void) buffer_type;
+ (void) user_p;
+
+ /* As for this example, only the free callback is redirected. This callback
+ * function does not free the memory if the arraybuffer_user_p is non-NULL. */
+
+ if (arraybuffer_user_p == NULL)
+ {
+ jerry_heap_free (buffer_p, buffer_size);
+ }
+} /* array_buffer_free_cb */
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ jerry_arraybuffer_set_allocator_callbacks (NULL, array_buffer_free_cb, NULL);
+
+ /* The buffer of the array buffer object is allocated by the default
+ * allocator using jerry_heap_alloc and freed by array_buffer_free_cb. */
+
+ const jerry_char_t script[] = "var result = new uint32Array(1024); result[0] = 1; result";
+ jerry_value_t array_buffer_value = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
+ jerry_release_value (array_buffer_value);
+
+ /* The buffer of the array buffer object has a non-NULL
+ * arraybuffer_user_p value, so it is not freed by array_buffer_free_cb. */
+
+ array_buffer_value = jerry_create_arraybuffer_external (sizeof (global_buffer), global_buffer, global_buffer);
+ jerry_release_value (array_buffer_value);
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_arraybuffer_has_buffer](#jerry_arraybuffer_has_buffer)
+- [jerry_arraybuffer_set_allocator_callbacks](#jerry_arraybuffer_set_allocator_callbacks)
+
## jerry_get_dataview_buffer
**Summary**
@@ -11753,7 +13121,7 @@ jerry_get_typedarray_type (jerry_value_t value);
```c
{
jerry_typedarray_type_t expected_type = JERRY_TYPEDARRAY_UINT32;
- jerry_value_t typedarray = jerry_create_typedarray (expected_klass, 25);
+ jerry_value_t typedarray = jerry_create_typedarray (expected_class, 25);
jerry_typedarray_type_t type = jerry_get_typedarray_type (typedarray);
@@ -11909,7 +13277,7 @@ main (void)
const jerry_char_t data[] = "{\"name\": \"John\", \"age\": 5}";
jerry_value_t obj = jerry_json_parse (data, sizeof (data) - 1);
- /* "obj" now conatins and object created from the "data" JSON string. */
+ /* "obj" now contains and object created from the "data" JSON string. */
jerry_release_value (obj);
@@ -12048,3 +13416,78 @@ main (void)
- [jerry_create_container](#jerry_create_container)
- [jerry_container_type_t](#jerry_container_type_t)
+
+
+## jerry_container_operation
+
+**Summary**
+
+Perform container operation on the given operands (add, delete, set, etc.).
+
+*Note*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+ is no longer needed.
+- 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.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_container_operation (jerry_container_operation_t operation,
+ jerry_value_t container,
+ jerry_value_t *arguments,
+ uint32_t arguments_number)
+```
+
+ - `operation` - container operation
+ - `container` - this value
+ - `arguments` - array of arguments
+ - `arguments_number` - number of arguments
+ - result if the operation is successful
+ - error, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+ jerry_init (JERRY_INIT_EMPTY);
+
+ jerry_value_t map = jerry_create_container (JERRY_CONTAINER_TYPE_MAP, NULL, 0);
+ jerry_value_t key_str = jerry_create_string ((jerry_char_t *) "number");
+ jerry_value_t number = jerry_create_number (10);
+ jerry_value_t args[2] = {key_str, number};
+
+ jerry_value_t result = jerry_container_operation (JERRY_CONTAINER_OP_SET, map, args, 2);
+ jerry_release_value (result);
+
+ result = jerry_container_operation (JERRY_CONTAINER_OP_SIZE, map, NULL, 0);
+ jerry_release_value (result);
+
+ result = jerry_container_operation (JERRY_CONTAINER_OP_CLEAR, map, NULL, 0);
+ jerry_release_value (result);
+
+ jerry_release_value (map);
+ jerry_release_value (key_str);
+ jerry_release_value (number);
+
+ jerry_cleanup ();
+ return 0;
+}
+```
+
+**See also**
+
+- [jerry_create_container](#jerry_create_container)
+- [jerry_container_type_t](#jerry_container_type_t)
diff --git a/04.INTERNALS.md b/04.INTERNALS.md
index b22bfd09..27a9cc6b 100644
--- a/04.INTERNALS.md
+++ b/04.INTERNALS.md
@@ -88,7 +88,7 @@ Argument combinations are limited to the following seven forms:
## Literals
Literals are organized into groups whose represent various literal types. Having these groups consuming less space than assigning flag bits to each literal.
-(In the followings, the mentioned ranges represent those indicies which are greater than or equal to the left side and less than the right side of the range. For example a range between `ident_end` and `literal_end` fields of the byte-code header contains those indicies, which are greater than or equal to `ident_end`
+(In the followings, the mentioned ranges represent those indices which are greater than or equal to the left side and less than the right side of the range. For example a range between `ident_end` and `literal_end` fields of the byte-code header contains those indices, which are greater than or equal to `ident_end`
and less than `literal_end`. If `ident_end` equals to `literal_end` the range is empty.)
The two major group of literals are _identifiers_ and _values_.
@@ -277,7 +277,7 @@ An object can be a conventional data object or a lexical environment object. Unl
[Lexical environments](http://www.ecma-international.org/ecma-262/5.1/#sec-10.2) are implemented as objects in JerryScript, since lexical environments contains key-value pairs (called bindings) like objects. This simplifies the implementation and reduces code size.
-![Object/Lexicat environment structures]({{ site.github.url }}/img/ecma_object.png){: class="thumbnail center-block img-responsive" }
+![Object/Lexical environment structures]({{ site.github.url }}/img/ecma_object.png){: class="thumbnail center-block img-responsive" }
The objects are represented as following structure:
diff --git a/05.PORT-API.md b/05.PORT-API.md
index b8373f1a..6a58f5f4 100644
--- a/05.PORT-API.md
+++ b/05.PORT-API.md
@@ -82,8 +82,8 @@ typedef enum
void jerry_port_log (jerry_log_level_t level, const char *fmt, ...);
```
-The `jerry_port_print_char` is currenlty not used by the jerry-core directly.
-However, it provides a port specifc way for `jerry-ext` components to print
+The `jerry_port_print_char` is currently not used by the jerry-core directly.
+However, it provides a port specific way for `jerry-ext` components to print
information.
```c
@@ -294,7 +294,7 @@ void
jerry_port_print_char (char c)
{
putchar (c);
-} /* jerr_port_print_char */
+} /* jerry_port_print_char */
```
## Date
diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md
index f43d329c..09b6bd70 100644
--- a/07.DEBUGGER.md
+++ b/07.DEBUGGER.md
@@ -326,12 +326,12 @@ wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource nam
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;
+ parse_options.resource_name = jerry_create_string ((const jerry_char_t *) resource_name_p);
jerry_value_t ret_val = jerry_parse (source_p,
source_size,
&parse_options);
+ jerry_release_value (parse_options.resource_name);
if (!jerry_value_is_error (ret_val))
{
diff --git a/08.CODING-STANDARDS.md b/08.CODING-STANDARDS.md
index 5c26ccca..444220f3 100644
--- a/08.CODING-STANDARDS.md
+++ b/08.CODING-STANDARDS.md
@@ -56,7 +56,7 @@ is doing.
/* not a complete sentence */
- /* A bad mulitiline
+ /* A bad multiline
comment. */
```
@@ -379,7 +379,7 @@ a = 6;
b = 7;
-/* No newlines are allowed between control staments
+/* No newlines are allowed between control statements
* and their code blocks. */
if (a > 6)
@@ -429,7 +429,7 @@ a=b+c;
a = b+c;
a += c + ( d );
/* Introduce temporary variables or macros
- * if the expression is too long. Occures rarely.. */
+ * if the expression is too long. Occurs rarely.. */
a = b
+ c;
if ( a + b > 0 )
diff --git a/10.EXT-REFERENCE-HANDLER.md b/10.EXT-REFERENCE-HANDLER.md
index c337749c..e9128e2b 100644
--- a/10.EXT-REFERENCE-HANDLER.md
+++ b/10.EXT-REFERENCE-HANDLER.md
@@ -151,7 +151,7 @@ jerryx_has_property_str (const jerry_value_t target_object,
- `target_object` - object on which the property name is accessed
- `name` - property name as an UTF-8 `char*`
- return value
- - true, if the given property name exsits on the object
+ - true, if the given property name exists on the object
- false, if there is no such property name or there was an error accessing the property
**Example**
@@ -190,7 +190,7 @@ for this the following utility structures and methods are provided.
Structure to define an array of properties with `name` and `value` fields which
can be registered to a target object.
-The engine must be initialied before specifying the `jerry_value_t` in the struct.
+The engine must be initialized before specifying the `jerry_value_t` in the struct.
**Prototype**
@@ -219,7 +219,7 @@ successfully registered methods.
This must be passed for the [jerryx_release_property_entry](#jerryx_release_property_entry) method
after the property registration.
-If any error occured during the property registration the `result` field of the structure
+If any error occurred during the property registration the `result` field of the structure
must be manually released after processing the error value.
**Prototype**
@@ -403,7 +403,7 @@ Release all `jerry_value_t` in a `jerryx_property_entry` array based on a previo
and also the error value (if any) in the `jerryx_register_result` structure.
In case of a successful registration it is safe to call this method.
-After the method call the `ęntries` array should not be used as all values are released.
+After the method call the `entries` array should not be used as all values are released.
**Prototype**
@@ -413,7 +413,7 @@ jerryx_release_property_entry (const jerryx_property_entry entries[],
const jerryx_register_result register_result);
```
-- `entires` - array of [jerryx_property_entry](#jerryx_property_entry).
+- `entries` - array of [jerryx_property_entry](#jerryx_property_entry).
- `register_result` - result of a previous [jerryx_set_properties](#jerryx_set_properties) call.
**Example**
@@ -523,7 +523,7 @@ jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,
Provide a `print` implementation for scripts. The routine converts all of its
arguments to strings and outputs them char-by-char using
-`jerry_port_print_char`. The NUL character is output as "\u0000",
+`jerry_port_print_char`. The NULL character is output as "\u0000",
other characters are output bytewise.
*Note*: This implementation does not use standard C `printf` to print its
diff --git a/12.EXT-REFERENCE-MODULE.md b/12.EXT-REFERENCE-MODULE.md
index fd29f4dd..981a0017 100644
--- a/12.EXT-REFERENCE-MODULE.md
+++ b/12.EXT-REFERENCE-MODULE.md
@@ -267,7 +267,7 @@ symbols so that they may be called explicitly from within the application.
#define JERRYX_NATIVE_MODULE(module_name, on_resolve_cb)
```
-- `module_name` - the name of the module without quotes. This value is used as the prefix for the registration and unregistration funtions. For example, when `module_name` is `example_module`, this results in the declaration of two functions `example_module_register()` and `example_module_unregister()`. These functions are declared global if support for library constructors/destructors is absent, allowing you to call them from other parts of the code by
+- `module_name` - the name of the module without quotes. This value is used as the prefix for the registration and unregistration functions. For example, when `module_name` is `example_module`, this results in the declaration of two functions `example_module_register()` and `example_module_unregister()`. These functions are declared global if support for library constructors/destructors is absent, allowing you to call them from other parts of the code by
first forward-declaring them.
- `on_resolve_cb` - the function of type `jerryx_native_module_on_resolve_t` that will be called when the module needs to be
loaded.
diff --git a/13.DEBUGGER-TRANSPORT.md b/13.DEBUGGER-TRANSPORT.md
index 6196e165..d1b77497 100644
--- a/13.DEBUGGER-TRANSPORT.md
+++ b/13.DEBUGGER-TRANSPORT.md
@@ -110,7 +110,7 @@ typedef bool (*jerry_debugger_transport_receive_t) (struct jerry_debugger_transp
**Summary**
-Add a new interface to the transporation interface chain. The interface
+Add a new interface to the transportation interface chain. The interface
will be the first item of the interface chain.
**Prototype**
@@ -121,7 +121,7 @@ void jerry_debugger_transport_add (jerry_debugger_transport_header_t *header_p,
size_t receive_message_header_size, size_t max_receive_message_size);
```
-- `header_p`: header of a transporation interface.
+- `header_p`: header of a transportation interface.
- `send_message_header_size`: size of the outgoing message header, can be 0.
- `max_send_message_size`: maximum outgoing message size supported by the interface.
- `receive_message_header_size`: size of the incoming message header, can be 0.
diff --git a/15.MODULE-SYSTEM.md b/15.MODULE-SYSTEM.md
index 3f7ecfe2..68c3a327 100644
--- a/15.MODULE-SYSTEM.md
+++ b/15.MODULE-SYSTEM.md
@@ -17,7 +17,7 @@ Embedders wishing to use native builtin modules with ES6 imports can use the [Po
## General
If a script contains import statements, then JerryScript will open and evaluate the the referenced modules before the main script runs, resolving and creating bindings for the referenced identifiers in the process.
-It is not necessary to use any specific filename extensions for modules, JerryScript will try to open the given file paths as they are, but will try to normalize them before doing so. The exact normalization process is dependant on the port implementation provided. It is the user's responsibility to verify that the given files are valid EcmaScript modules.
+It is not necessary to use any specific filename extensions for modules, JerryScript will try to open the given file paths as they are, but will try to normalize them before doing so. The exact normalization process is dependant on the port implementation provided. It is the user's responsibility to verify that the given files are valid ECMAScript modules.
main.js
@@ -86,7 +86,7 @@ export var version = "1.0 (e92ae0fb)";
```js
// module_2.js
-var featureName = "EcmaScript modules";
+var featureName = "ECMAScript modules";
var year = 2018;
export function getFeatureDetails() {
@@ -96,7 +96,7 @@ export function getFeatureDetails() {
### Module namespace import statements
-A module namespace object can be imported. In this case the local binding will contain an object holding the exported values of the module, including local exports and all indirect exports. Ambiguous exported names are exluded from the namespace object.
+A module namespace object can be imported. In this case the local binding will contain an object holding the exported values of the module, including local exports and all indirect exports. Ambiguous exported names are excluded from the namespace object.
```js
import * as module from './module.js';
diff --git a/16.MIGRATION-GUIDE.md b/16.MIGRATION-GUIDE.md
index 5a76334a..dffd665b 100644
--- a/16.MIGRATION-GUIDE.md
+++ b/16.MIGRATION-GUIDE.md
@@ -11,11 +11,11 @@ permalink: /migration-guide/
# Migration guide
This guide intends to describe the major changes between the JerryScript 1.0 and 2.0 versions.
-In addtion it is designed to provide a guide on how to modify the 1.0 version code to a
+In addition it is designed to provide a guide on how to modify the 1.0 version code to a
2.0 compliant code.
During the development it was important to minimize the changes in the API functions and types.
-Each API method removal or chang is described below providing a ***before*** and ***after***
+Each API method removal or change is described below providing a ***before*** and ***after***
code example.
For more information on the current API methods please check the [API reference](02.API-REFERENCE.md) document.
@@ -63,7 +63,7 @@ For more information on the current API methods please check the [API reference]
## Error manipulating functions
-The most important changes in the API are releated to error handling and manipulation.
+The most important changes in the API are related to error handling and manipulation.
### jerry_value_set_abort_flag