diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index a4a3b5d36..1dc2dcfda 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -44,6 +44,7 @@ Possible compile time enabled feature types: - JERRY_FEATURE_REGEXP_DUMP - regexp byte-code dumps - JERRY_FEATURE_SNAPSHOT_SAVE - saving snapshot files - JERRY_FEATURE_SNAPSHOT_EXEC - executing snapshot files + - JERRY_FEATURE_DEBUGGER - debugging ## jerry_char_t @@ -176,7 +177,9 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_ **Summary** -Native free callback of an object +**Deprecated: Please use jerry_object_native_free_callback_t instead.** + +Native free callback of an object. **Prototype** @@ -184,6 +187,48 @@ Native free callback of an object typedef void (*jerry_object_free_callback_t) (const uintptr_t native_p); ``` +## jerry_object_native_free_callback_t + +**Summary** + +Native free callback of an object. It is used in jerry_object_native_info_t. + +**Prototype** + +```c +typedef void (*jerry_object_native_free_callback_t) (void *native_p); +``` + +## jerry_object_native_info_t + +**Summary** + +The type infomation of the native pointer. +It includes the free callback that will be called when associated JavaScript object is garbage collected. It can be left NULL in case it is not needed. + +Typically, one would create a `static const jerry_object_native_info_t` for +each distinct C type for which a pointer is used with +`jerry_set_object_native_pointer ()` and `jerry_get_object_native_pointer ()`. +This way, each `const jerry_object_native_info_t *` pointer address value itself +uniquely identifies the C type of the native pointer. + +See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) +for a best-practice code example. + +**Prototype** + +```c +typedef struct +{ + jerry_object_native_free_callback_t free_cb; +} jerry_object_native_info_t; +``` + +**See also** + +- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) +- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) + ## jerry_object_property_foreach_t **Summary** @@ -204,8 +249,10 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na **Summary** -Initializes the JerryScript engine, making possible to run JavaScript code and perform operations on -JavaScript values. +Initializes the JerryScript engine, making it possible to run JavaScript code and perform operations +on JavaScript values. See also [jerry_init_with_user_context](#jerry_init_with_user_context) if you +wish to initialize the JerryScript engine in such a way that its context contains a custom pointer +which you can later retrieve using [jerry_get_user_context](#jerry_get_user_context). **Prototype** @@ -237,14 +284,92 @@ jerry_init (jerry_init_flag_t flags) **See also** -- [jerry_cleanup](#jerrycleanup) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_init_with_user_context](#jerry_init_with_user_context) + + +## jerry_init_with_user_context + +**Summary** + +Calls [jerry_init](#jerry_init) to initialize the JerryScript engine, thereby making it possible +to run JavaScript code and perform operations on JavaScript values. In addition to the first +parameter this function accepts two more parameters with which it allows the caller to store a +`void *` pointer inside the context being initialized with `jerry_init ()`. The function calls the +callback given in its `init_cb` parameter to allocate the memory for the pointer and it stores the +function pointer given in the `deinit_cb` parameter along with the pointer so that it may be called +to free the stored pointer when `jerry_cleanup ()` is later called to dispose of the context. + +**Prototype** + +```c +void +jerry_init_with_user_context (jerry_init_flag_t flags, + jerry_user_context_init_cb init_cb, + jerry_user_context_deinit_cb deinit_cb); +``` + +`flags` - combination of various engine configuration flags: + +- `JERRY_INIT_EMPTY` - no flags, just initialize in default configuration. +- `JERRY_INIT_SHOW_OPCODES` - print compiled byte-code. +- `JERRY_INIT_SHOW_REGEXP_OPCODES` - print compiled regexp byte-code. +- `JERRY_INIT_MEM_STATS` - dump memory statistics. +- `JERRY_INIT_MEM_STATS_SEPARATE` - dump memory statistics and reset peak values after parse. +- `JERRY_INIT_DEBUGGER` - enable all features required by debugging. + +`init_cb` - a function pointer that will be called to allocate the custom pointer. + +`deinit_cb` - a function pointer that will be called when the custom pointer must be freed. + +**Example** + +```c +void * +init_user_context (void) +{ + void *return_value; + + /* allocate and initialize return_value */ + + return return_value; +} /* init_user_context */ + +void +free_user_context (void *context) +{ + + /* free the value allocated above */ + +} /* free_user_context */ + +{ + /* init_user_context () will be called before the call below returns */ + jerry_init_with_user_context (JERRY_INIT_SHOW_OPCODES | JERRY_INIT_SHOW_REGEXP_OPCODES, + init_user_context, + free_user_context); + + /* ... */ + + /* free_user_context () will be called before the call below returns */ + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_cleanup](#jerry_cleanup) +- [jerry_get_user_context](#jerry_get_user_context) ## jerry_cleanup **Summary** -Finish JavaScript engine execution, freeing memory and JavaScript values. +Finish JavaScript engine execution, freeing memory and JavaScript values. If the context was +initialized with `jerry_init_with_user_context ()` and a `deinit_cb` was provided, then it will +be called to free the memory at the custom pointer which was associated with the context being +cleaned up. *Note*: JavaScript values, received from engine, will be inaccessible after the cleanup. @@ -257,7 +382,38 @@ jerry_cleanup (void); **See also** -- [jerry_init](#jerryinit) +- [jerry_init](#jerry_init) +- [jerry_init_with_user_context](#jerry_init_with_user_context) + + +## jerry_get_user_context + +**Summary** + +Retrieve the pointer stored within the current context. + +**Prototype** + +```c +void * +jerry_get_user_context (void); +``` + +- return value: the pointer that was assigned during `jerry_init_with_user_context ()` + +**Example** + +```c +{ + /* ... */ + my_context *custom_data = (my_context *) jerry_get_user_context (); + /* ... */ +} +``` + +**See also** +- [jerry_init_with_user_context](#jerry_init_with_user_context) +- [jerry_cleanup](#jerry_cleanup) ## jerry_register_magic_strings @@ -308,9 +464,9 @@ jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p, **See also** -- [jerry_init](#jerryinit) -- [jerry_cleanup](#jerrycleanup) -- [jerry_parse_and_save_literals](#jerryparseandsaveliterals) +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_parse_and_save_literals](#jerry_parse_and_save_literals) ## jerry_get_memory_limits @@ -344,8 +500,8 @@ jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p, **See also** -- [jerry_init](#jerryinit) -- [jerry_cleanup](#jerrycleanup) +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) ## jerry_gc @@ -369,8 +525,8 @@ jerry_gc (); **See also** -- [jerry_init](#jerryinit) -- [jerry_cleanup](#jerrycleanup) +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) # Parser and executor functions @@ -410,10 +566,10 @@ jerry_run_simple (const jerry_char_t *script_source_p, **See also** -- [jerry_init](#jerryinit) -- [jerry_cleanup](#jerrycleanup) -- [jerry_parse](#jerryparse) -- [jerry_run](#jerryrun) +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_parse](#jerry_parse) +- [jerry_run](#jerry_run) ## jerry_parse @@ -423,7 +579,7 @@ jerry_run_simple (const jerry_char_t *script_source_p, Parse script and construct an EcmaScript function. The lexical environment is set to the global lexical environment. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -460,7 +616,7 @@ jerry_parse (const jerry_char_t *source_p, **See also** -- [jerry_run](#jerryrun) +- [jerry_run](#jerry_run) ## jerry_parse_named_resource @@ -471,7 +627,7 @@ environment is set to the global lexical environment. The name (usually a file name) is also passed to this function which is used by the debugger to find the source code. -*Note*: The returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: The returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -495,7 +651,7 @@ jerry_parse_named_resource (const jerry_char_t *name_p, /**< name (usually a fil - function object value, if script was parsed successfully, - thrown error, otherwise -This function is identical to [jerry_parse](#jerryparse), except that an additional filename parameter has been added. +This function is identical to [jerry_parse](#jerry_parse), except that an additional filename parameter has been added. ## jerry_run @@ -549,7 +705,7 @@ jerry_run (const jerry_value_t func_val); **See also** -- [jerry_parse](#jerryparse) +- [jerry_parse](#jerry_parse) ## jerry_eval @@ -584,8 +740,8 @@ jerry_eval (const jerry_char_t *source_p, **See also** -- [jerry_create_external_function](#jerrycreateexternalfunction) -- [jerry_external_handler_t](#jerryexternalhandlert) +- [jerry_create_external_function](#jerry_create_external_function) +- [jerry_external_handler_t](#jerry_external_handler_t) # Get the global context @@ -596,7 +752,7 @@ jerry_eval (const jerry_char_t *source_p, Get the Global object. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -622,12 +778,12 @@ jerry_get_global_object (void); **See also** -- [jerry_release_value](#jerryreleasevalue) -- [jerry_define_own_property](#jerrydefineownproperty) +- [jerry_release_value](#jerry_release_value) +- [jerry_define_own_property](#jerry_define_own_property) # Checker functions -Functions to check the type of an API value ([jerry_value_t](#jerryvaluet)). +Functions to check the type of an API value ([jerry_value_t](#jerry_value_t)). ## jerry_value_is_array @@ -665,7 +821,7 @@ jerry_value_is_array (const jerry_value_t value) **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_value_is_boolean @@ -704,7 +860,7 @@ jerry_value_is_boolean (const jerry_value_t value) **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_value_is_constructor @@ -743,7 +899,7 @@ jerry_value_is_constructor (const jerry_value_t value) **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_value_is_function @@ -782,7 +938,7 @@ jerry_value_is_function (const jerry_value_t value) **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_value_is_number @@ -821,7 +977,7 @@ jerry_value_is_function (const jerry_value_t value) **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_value_is_null @@ -860,7 +1016,7 @@ jerry_value_is_null (const jerry_value_t value) **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_value_is_object @@ -899,7 +1055,7 @@ jerry_value_is_object (const jerry_value_t value) **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_value_is_string @@ -938,7 +1094,7 @@ jerry_value_is_string (const jerry_value_t value) **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_value_is_undefined @@ -977,7 +1133,7 @@ jerry_value_is_undefined (const jerry_value_t value) **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_is_feature_enabled @@ -1050,7 +1206,7 @@ jerry_value_has_error_flag (const jerry_value_t value); **See also** -- [jerry_value_t](#jerryvaluet) +- [jerry_value_t](#jerry_value_t) ## jerry_value_clear_error_flag @@ -1083,7 +1239,7 @@ jerry_value_clear_error_flag (jerry_value_t *value_p); **See also** -- [jerry_value_t](#jerryvaluet) +- [jerry_value_t](#jerry_value_t) ## jerry_value_set_error_flag @@ -1116,7 +1272,7 @@ jerry_value_set_error_flag (jerry_value_t *value_p); **See also** -- [jerry_value_t](#jerryvaluet) +- [jerry_value_t](#jerry_value_t) # Getter functions of 'jerry_value_t' @@ -1161,8 +1317,8 @@ jerry_get_boolean_value (const jerry_value_t value); **See also** -- [jerry_value_is_boolean](#jerryvalueisboolean) -- [jerry_release_value](#jerryreleasevalue) +- [jerry_value_is_boolean](#jerry_value_is_boolean) +- [jerry_release_value](#jerry_release_value) ## jerry_get_number_value @@ -1202,8 +1358,8 @@ jerry_get_number_value (const jerry_value_t value); **See also** -- [jerry_value_is_number](#jerryvalueisnumber) -- [jerry_release_value](#jerryreleasevalue) +- [jerry_value_is_number](#jerry_value_is_number) +- [jerry_release_value](#jerry_release_value) # Functions for string values @@ -1240,9 +1396,9 @@ jerry_get_string_size (const jerry_value_t value); **See also** -- [jerry_create_string](#jerrycreatestring) -- [jerry_get_string_length](#jerrygetstringlength) -- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) +- [jerry_create_string](#jerry_create_string) +- [jerry_get_string_length](#jerry_get_string_length) +- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) ## jerry_get_utf8_string_size @@ -1251,7 +1407,7 @@ jerry_get_string_size (const jerry_value_t value); Get the size of an utf8-encoded string. Returns zero, if the value parameter is not a string. -*Note*: The difference from [jerry_get_string_size](#jerrygetstringsize) is that it returns with utf-8 string size +*Note*: The difference from [jerry_get_string_size](#jerry_get_string_size) is that it returns with utf-8 string size instead of the cesu-8 string size. **Prototype** @@ -1280,9 +1436,9 @@ jerry_get_utf8_string_size (const jerry_value_t value); **See also** -- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) -- [jerry_get_utf8_string_length](#jerrygetutf8stringlength) -- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) +- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) +- [jerry_get_utf8_string_length](#jerry_get_utf8_string_length) +- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) ## jerry_get_string_length @@ -1318,9 +1474,9 @@ jerry_get_string_length (const jerry_value_t value); **See also** -- [jerry_create_string](#jerrycreatestring) -- [jerry_get_string_size](#jerrygetstringsize) -- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) +- [jerry_create_string](#jerry_create_string) +- [jerry_get_string_size](#jerry_get_string_size) +- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) ## jerry_get_utf8_string_length @@ -1329,7 +1485,7 @@ jerry_get_string_length (const jerry_value_t value); Get the length of an UTF-8 encoded string. Returns zero, if the value parameter is not a string. -*Note*: The difference from [jerry_get_string_length](#jerrygetstringlength) is that it +*Note*: The difference from [jerry_get_string_length](#jerry_get_string_length) is that it returns with utf-8 string length instead of the cesu-8 string length. **Prototype** @@ -1359,9 +1515,9 @@ jerry_get_utf8_string_length (const jerry_value_t value); **See also** -- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) -- [jerry_get_utf8_string_size](#jerrygetutf8stringsize) -- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) +- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) +- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size) +- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) ## jerry_string_to_char_buffer @@ -1408,9 +1564,9 @@ jerry_string_to_char_buffer (const jerry_value_t value, **See also** -- [jerry_create_string](#jerrycreatestring) -- [jerry_get_string_size](#jerrygetstringsize) -- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) +- [jerry_create_string](#jerry_create_string) +- [jerry_get_string_size](#jerry_get_string_size) +- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) ## jerry_string_to_utf8_char_buffer @@ -1457,9 +1613,9 @@ jerry_string_to_utf8_char_buffer (const jerry_value_t value, **See also** -- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) -- [jerry_get_utf8_string_size](#jerrygetutf8stringsize) -- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) +- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) +- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size) +- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) ## jerry_substring_to_char_buffer @@ -1513,10 +1669,10 @@ jerry_substring_to_char_buffer (const jerry_value_t value, **See also** -- [jerry_create_string](#jerrycreatestring) -- [jerry_get_string_size](#jerrygetstringsize) -- [jerry_get_string_length](#jerrygetstringlength) -- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) +- [jerry_create_string](#jerry_create_string) +- [jerry_get_string_size](#jerry_get_string_size) +- [jerry_get_string_length](#jerry_get_string_length) +- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) ## jerry_substring_to_utf8_char_buffer @@ -1570,10 +1726,10 @@ jerry_substring_to_utf8_char_buffer (const jerry_value_t value, **See also** -- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) -- [jerry_get_utf8_string_size](#jerrygetutf8stringsize) -- [jerry_get_utf8_string_length](#jerrygetutf8stringlength) -- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) +- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) +- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size) +- [jerry_get_utf8_string_length](#jerry_get_utf8_string_length) +- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) # Functions for array object values @@ -1609,7 +1765,7 @@ jerry_get_array_length (const jerry_value_t value); **See also** -- [jerry_create_array](#jerrycreatearray) +- [jerry_create_array](#jerry_create_array) # Converters of 'jerry_value_t' @@ -1650,7 +1806,7 @@ jerry_value_to_boolean (const jerry_value_t value); **See also** -- [jerry_value_to_primitive](#jerryvaluetoprimitive) +- [jerry_value_to_primitive](#jerry_value_to_primitive) ## jerry_value_to_number @@ -1658,7 +1814,7 @@ jerry_value_to_boolean (const jerry_value_t value); Call ToNumber operation on the api value. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -1690,7 +1846,7 @@ jerry_value_to_number (const jerry_value_t value); **See also** -- [jerry_value_to_primitive](#jerryvaluetoprimitive) +- [jerry_value_to_primitive](#jerry_value_to_primitive) ## jerry_value_to_object @@ -1698,7 +1854,7 @@ jerry_value_to_number (const jerry_value_t value); Call ToObject operation on the api value. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -1729,7 +1885,7 @@ jerry_value_to_object (const jerry_value_t value); **See also** -- [jerry_value_to_primitive](#jerryvaluetoprimitive) +- [jerry_value_to_primitive](#jerry_value_to_primitive) ## jerry_value_to_primitive @@ -1737,7 +1893,7 @@ jerry_value_to_object (const jerry_value_t value); Call ToPrimitive operation on the api value. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -1768,7 +1924,7 @@ jerry_value_to_primitive (const jerry_value_t value); **See also** -- [jerry_value_t](#jerryvaluet) +- [jerry_value_t](#jerry_value_t) ## jerry_value_to_string @@ -1776,7 +1932,7 @@ jerry_value_to_primitive (const jerry_value_t value); Call the ToString ecma builtin operation on the api value. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -1807,7 +1963,7 @@ jerry_value_to_string (const jerry_value_t value); **See also** -- [jerry_value_to_primitive](#jerryvaluetoprimitive) +- [jerry_value_to_primitive](#jerry_value_to_primitive) # Acquire and release API values @@ -1818,7 +1974,7 @@ jerry_value_to_string (const jerry_value_t value); Acquires the specified Jerry API value. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -1850,8 +2006,8 @@ jerry_acquire_value (jerry_value_t value); **See also** -- [jerry_release_value](#jerryreleasevalue) -- [jerry_value_t](#jerryvaluet) +- [jerry_release_value](#jerry_release_value) +- [jerry_value_t](#jerry_value_t) ## jerry_release_value @@ -1884,9 +2040,9 @@ jerry_release_value (jerry_value_t value); # Create API values -Function for creating [API values](#jerryvaluet). +Function for creating [API values](#jerry_value_t). -*Note*: Every created API value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Every created API value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. ## jerry_create_array @@ -1919,8 +2075,8 @@ jerry_create_array (uint32_t size); **See also** -- [jerry_set_property_by_index](#jerrysetpropertybyindex) -- [jerry_get_property_by_index](#jerrygetpropertybyindex) +- [jerry_set_property_by_index](#jerry_set_property_by_index) +- [jerry_get_property_by_index](#jerry_get_property_by_index) ## jerry_create_boolean @@ -1953,7 +2109,7 @@ jerry_create_boolean (bool value); **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_create_error @@ -1990,9 +2146,9 @@ jerry_create_error (jerry_error_t error_type, **See also** -- [jerry_value_has_error_flag](#jerryvaluehaserrorflag) -- [jerry_value_clear_error_flag](#jerryvalueclearerrorflag) -- [jerry_value_set_error_flag](#jerryvalueseterrorflag) +- [jerry_value_has_error_flag](#jerry_value_has_error_flag) +- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag) +- [jerry_value_set_error_flag](#jerry_value_set_error_flag) ## jerry_create_error_sz @@ -2032,7 +2188,7 @@ jerry_create_error_sz (jerry_error_t error_type, **See also** -- [jerry_create_error](#jerrycreateerror) +- [jerry_create_error](#jerry_create_error) ## jerry_create_external_function @@ -2082,9 +2238,9 @@ handler (const jerry_value_t function_obj, **See also** -- [jerry_external_handler_t](#jerryexternalhandlert) -- [jerry_set_property](#jerrysetproperty) -- [jerry_call_function](#jerrycallfunction) +- [jerry_external_handler_t](#jerry_external_handler_t) +- [jerry_set_property](#jerry_set_property) +- [jerry_call_function](#jerry_call_function) ## jerry_create_number @@ -2117,9 +2273,9 @@ jerry_create_number (double value); **See also** -- [jerry_release_value](#jerryreleasevalue) -- [jerry_create_number_infinity](#jerrycreatenumberinfinity) -- [jerry_create_number_nan](#jerrycreatenumbernan) +- [jerry_release_value](#jerry_release_value) +- [jerry_create_number_infinity](#jerry_create_number_infinity) +- [jerry_create_number_nan](#jerry_create_number_nan) ## jerry_create_number_infinity @@ -2152,9 +2308,9 @@ jerry_create_number_infinity (bool sign); **See also** -- [jerry_release_value](#jerryreleasevalue) -- [jerry_create_number](#jerrycreatenumber) -- [jerry_create_number_nan](#jerrycreatenumbernan) +- [jerry_release_value](#jerry_release_value) +- [jerry_create_number](#jerry_create_number) +- [jerry_create_number_nan](#jerry_create_number_nan) ## jerry_create_number_nan @@ -2186,9 +2342,9 @@ jerry_create_number_nan (void); **See also** -- [jerry_release_value](#jerryreleasevalue) -- [jerry_create_number](#jerrycreatenumber) -- [jerry_create_number_infinity](#jerrycreatenumberinfinity) +- [jerry_release_value](#jerry_release_value) +- [jerry_create_number](#jerry_create_number) +- [jerry_create_number_infinity](#jerry_create_number_infinity) ## jerry_create_null @@ -2220,7 +2376,7 @@ jerry_create_null (void); **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_create_object @@ -2252,7 +2408,7 @@ jerry_create_object (void); **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) ## jerry_create_string @@ -2286,8 +2442,8 @@ jerry_create_string (const jerry_char_t *str_p); **See also** -- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) -- [jerry_create_string_sz](#jerrycreatestringsz) +- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) +- [jerry_create_string_sz](#jerry_create_string_sz) ## jerry_create_string_sz @@ -2325,8 +2481,8 @@ jerry_create_string_sz (const jerry_char_t *str_p, **See also** -- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) -- [jerry_create_string](#jerrycreatestring) +- [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string) +- [jerry_create_string](#jerry_create_string) ## jerry_create_string_from_utf8 @@ -2335,7 +2491,7 @@ jerry_create_string_sz (const jerry_char_t *str_p, Create string from a valid UTF8 string. -*Note*: The difference from [jerry_create_string](#jerrycreatestring) is that it accepts utf-8 string instead of cesu-8 string. +*Note*: The difference from [jerry_create_string](#jerry_create_string) is that it accepts utf-8 string instead of cesu-8 string. **Prototype** @@ -2362,8 +2518,8 @@ jerry_create_string_from_utf8 (const jerry_char_t *str_p); **See also** -- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) -- [jerry_create_string_sz_from_utf8](#jerrycreatestringszfromutf8) +- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) +- [jerry_create_string_sz_from_utf8](#jerry_create_string_sz_from_utf8) ## jerry_create_string_sz_from_utf8 @@ -2372,7 +2528,7 @@ jerry_create_string_from_utf8 (const jerry_char_t *str_p); Create string from a valid UTF8 string. -*Note*: The difference from [jerry_create_string_sz](#jerrycreatestringsz) is that it accepts utf-8 string instead of cesu-8 string. +*Note*: The difference from [jerry_create_string_sz](#jerry_create_string_sz) is that it accepts utf-8 string instead of cesu-8 string. **Prototype** @@ -2403,8 +2559,8 @@ jerry_create_string_sz (const jerry_char_t *str_p, **See also** -- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) -- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) +- [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string) +- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) ## jerry_create_undefined @@ -2436,7 +2592,7 @@ jerry_create_undefined (void); **See also** -- [jerry_release_value](#jerryreleasevalue) +- [jerry_release_value](#jerry_release_value) # General API functions of JS objects @@ -2477,8 +2633,8 @@ jerry_has_property (const jerry_value_t obj_val, **See also** -- [jerry_has_own_property](#jerryhasownproperty) -- [jerry_delete_property](#jerrydeleteproperty) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_delete_property](#jerry_delete_property) ## jerry_has_own_property @@ -2517,8 +2673,8 @@ jerry_has_own_property (const jerry_value_t obj_val, **See also** -- [jerry_has_property](#jerryhasproperty) -- [jerry_delete_property](#jerrydeleteproperty) +- [jerry_has_property](#jerry_has_property) +- [jerry_delete_property](#jerry_delete_property) ## jerry_delete_property @@ -2557,9 +2713,9 @@ jerry_delete_property (const jerry_value_t obj_val, **See also** -- [jerry_has_property](#jerryhasproperty) -- [jerry_has_own_property](#jerryhasownproperty) -- [jerry_get_property](#jerrygetproperty) +- [jerry_has_property](#jerry_has_property) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_get_property](#jerry_get_property) ## jerry_get_property @@ -2568,7 +2724,7 @@ jerry_delete_property (const jerry_value_t obj_val, Get value of a property to the specified object with the given name. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -2601,12 +2757,12 @@ jerry_get_property (const jerry_value_t obj_val, **See also** -- [jerry_has_property](#jerryhasproperty) -- [jerry_has_own_property](#jerryhasownproperty) -- [jerry_delete_property](#jerrydeleteproperty) -- [jerry_set_property](#jerrysetproperty) -- [jerry_get_property_by_index](#jerrygetpropertybyindex) -- [jerry_set_property_by_index](#jerrysetpropertybyindex) +- [jerry_has_property](#jerry_has_property) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_delete_property](#jerry_delete_property) +- [jerry_set_property](#jerry_set_property) +- [jerry_get_property_by_index](#jerry_get_property_by_index) +- [jerry_set_property_by_index](#jerry_set_property_by_index) ## jerry_get_property_by_index @@ -2615,7 +2771,7 @@ jerry_get_property (const jerry_value_t obj_val, Get value by an index from the specified object. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -2651,12 +2807,12 @@ jerry_get_property_by_index (const jerry_value_t obj_val, **See also** -- [jerry_has_property](#jerryhasproperty) -- [jerry_has_own_property](#jerryhasownproperty) -- [jerry_delete_property](#jerrydeleteproperty) -- [jerry_get_property](#jerrygetproperty) -- [jerry_set_property](#jerrysetproperty) -- [jerry_set_property_by_index](#jerrysetpropertybyindex) +- [jerry_has_property](#jerry_has_property) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_delete_property](#jerry_delete_property) +- [jerry_get_property](#jerry_get_property) +- [jerry_set_property](#jerry_set_property) +- [jerry_set_property_by_index](#jerry_set_property_by_index) ## jerry_set_property @@ -2665,7 +2821,7 @@ jerry_get_property_by_index (const jerry_value_t obj_val, Set a property to the specified object with the given name. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -2711,12 +2867,12 @@ jerry_set_property (const jerry_value_t obj_val, **See also** -- [jerry_has_property](#jerryhasproperty) -- [jerry_has_own_property](#jerryhasownproperty) -- [jerry_delete_property](#jerrydeleteproperty) -- [jerry_get_property](#jerrygetproperty) -- [jerry_get_property_by_index](#jerrygetpropertybyindex) -- [jerry_set_property_by_index](#jerrysetpropertybyindex) +- [jerry_has_property](#jerry_has_property) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_delete_property](#jerry_delete_property) +- [jerry_get_property](#jerry_get_property) +- [jerry_get_property_by_index](#jerry_get_property_by_index) +- [jerry_set_property_by_index](#jerry_set_property_by_index) ## jerry_set_property_by_index @@ -2725,7 +2881,7 @@ jerry_set_property (const jerry_value_t obj_val, Set indexed value in the specified object -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -2765,12 +2921,12 @@ jerry_set_property_by_index (const jerry_value_t obj_val, **See also** -- [jerry_has_property](#jerryhasproperty) -- [jerry_has_own_property](#jerryhasownproperty) -- [jerry_delete_property](#jerrydeleteproperty) -- [jerry_get_property](#jerrygetproperty) -- [jerry_set_property](#jerrysetproperty) -- [jerry_get_property_by_index](#jerrygetpropertybyindex) +- [jerry_has_property](#jerry_has_property) +- [jerry_has_own_property](#jerry_has_own_property) +- [jerry_delete_property](#jerry_delete_property) +- [jerry_get_property](#jerry_get_property) +- [jerry_set_property](#jerry_set_property) +- [jerry_get_property_by_index](#jerry_get_property_by_index) ## jerry_init_property_descriptor_fields @@ -2803,9 +2959,9 @@ jerry_init_property_descriptor_fields (jerry_property_descriptor_t *prop_desc_p) **See also** -- [jerry_define_own_property](#jerrydefineownproperty) -- [jerry_get_own_property_descriptor](#jerrygetownpropertydescriptor) -- [jerry_free_property_descriptor_fields](#jerryfreepropertydescriptorfields) +- [jerry_define_own_property](#jerry_define_own_property) +- [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) +- [jerry_free_property_descriptor_fields](#jerry_free_property_descriptor_fields) ## jerry_define_own_property @@ -2814,7 +2970,7 @@ jerry_init_property_descriptor_fields (jerry_property_descriptor_t *prop_desc_p) Define a property to the specified object with the given name. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -2861,9 +3017,9 @@ jerry_define_own_property (const jerry_value_t obj_val, **See also** -- [jerry_init_property_descriptor_fields](#jerryinitpropertydescriptorfields) -- [jerry_get_own_property_descriptor](#jerrygetownpropertydescriptor) -- [jerry_free_property_descriptor_fields](#jerryfreepropertydescriptorfields) +- [jerry_init_property_descriptor_fields](#jerry_init_property_descriptor_fields) +- [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) +- [jerry_free_property_descriptor_fields](#jerry_free_property_descriptor_fields) ## jerry_get_own_property_descriptor @@ -2908,9 +3064,9 @@ jerry_get_own_property_descriptor (const jerry_value_t obj_val, **See also** -- [jerry_init_property_descriptor_fields](#jerryinitpropertydescriptorfields) -- [jerry_define_own_property](#jerrydefineownproperty) -- [jerry_free_property_descriptor_fields](#jerryfreepropertydescriptorfields) +- [jerry_init_property_descriptor_fields](#jerry_init_property_descriptor_fields) +- [jerry_define_own_property](#jerry_define_own_property) +- [jerry_free_property_descriptor_fields](#jerry_free_property_descriptor_fields) ## jerry_free_property_descriptor_fields @@ -2943,9 +3099,9 @@ jerry_free_property_descriptor_fields (const jerry_property_descriptor_t *prop_d **See also** -- [jerry_init_property_descriptor_fields](#jerryinitpropertydescriptorfields) -- [jerry_define_own_property](#jerrydefineownproperty) -- [jerry_get_own_property_descriptor](#jerrygetownpropertydescriptor) +- [jerry_init_property_descriptor_fields](#jerry_init_property_descriptor_fields) +- [jerry_define_own_property](#jerry_define_own_property) +- [jerry_get_own_property_descriptor](#jerry_get_own_property_descriptor) ## jerry_call_function @@ -2956,7 +3112,7 @@ Call function specified by a function value. Error flag must not be set for any arguments of this function. Value of `this` parameter should be set to `undefined` for non-method calls. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -3003,8 +3159,8 @@ jerry_call_function (const jerry_value_t func_obj_val, **See also** -- [jerry_is_function](#jerryisfunction) -- [jerry_create_external_function](#jerrycreateexternalfunction) +- [jerry_is_function](#jerry_is_function) +- [jerry_create_external_function](#jerry_create_external_function) ## jerry_construct_object @@ -3014,7 +3170,7 @@ jerry_call_function (const jerry_value_t func_obj_val, Construct object, invoking specified function object as constructor. Error flag must not be set for any arguments of this function. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -3055,7 +3211,7 @@ jerry_construct_object (const jerry_value_t func_obj_val, **See also** - - [jerry_is_constructor](#jerryisconstructor) + - [jerry_is_constructor](#jerry_is_constructor) ## jerry_get_object_keys @@ -3093,8 +3249,8 @@ jerry_get_object_keys (const jerry_value_t obj_val); **See also** -- [jerry_get_property](#jerrygetproperty) -- [jerry_set_property](#jerrysetproperty) +- [jerry_get_property](#jerry_get_property) +- [jerry_set_property](#jerry_set_property) ## jerry_get_prototype @@ -3133,7 +3289,7 @@ jerry_get_prototype (const jerry_value_t obj_val); **See also** -- [jerry_set_prototype](#jerrysetprototype) +- [jerry_set_prototype](#jerry_set_prototype) ## jerry_set_prototype @@ -3175,13 +3331,15 @@ jerry_set_prototype (const jerry_value_t obj_val, **See also** -- [jerry_get_prototype](#jerrygetprototype) +- [jerry_get_prototype](#jerry_get_prototype) ## jerry_get_object_native_handle **Summary** +**Deprecated: Please use jerry_get_object_native_pointer instead.** + Get native handle, previously associated with specified object. **Prototype** @@ -3218,14 +3376,18 @@ jerry_get_object_native_handle (const jerry_value_t obj_val, **See also** -- [jerry_create_object](#jerrycreateobject) -- [jerry_set_object_native_handle](#jerrysetobjectnativehandle) +- [jerry_create_object](#jerry_create_object) +- [jerry_set_object_native_handle](#jerry_set_object_native_handle) +- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) + ## jerry_set_object_native_handle **Summary** -Set native handle and an optional free callback for the specified object +**Deprecated: Please use jerry_set_object_native_pointer instead.** + +Set native handle and an optional free callback for the specified object. *Note*: If native handle was already set for the object, its value is updated. @@ -3267,8 +3429,152 @@ jerry_set_object_native_handle (const jerry_value_t obj_val, **See also** -- [jerry_create_object](#jerrycreateobject) -- [jerry_get_object_native_handle](#jerrygetobjectnativehandle) +- [jerry_create_object](#jerry_create_object) +- [jerry_get_object_native_handle](#jerry_get_object_native_handle) +- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) + + +## jerry_get_object_native_pointer + +**Summary** + +Get native pointer and its type information. +The pointer and the type information are previously associated with the object by jerry_set_object_native_pointer. + +*Note*: It is recommended to ensure that the `out_native_info_p` value pointer + is equal to the native info pointer that is expected, before casting + and accessing the `out_native_pointer_p`. + An example of when this is important: external functions that expect + `this` to have a native pointer of a certain C type. + It is possible in JavaScript to change `this` at will – using `call()`, + `apply()` or `bind()`. Therefore, it is possible that the native pointer + of `this` is not of the expected C type. To handle this safely and + securely, one must always add type checks to make sure that the + `out_native_pointer_p` is of the expected type, before casting + and dereferencing `out_native_pointer_p`. + +**Prototype** + +```c +bool +jerry_get_object_native_pointer (const jerry_value_t obj_val, + void **out_native_pointer_p, + const jerry_object_native_info_t **out_native_info_p) +``` + +- `obj_val` - object value to get native pointer from. +- `out_native_pointer_p` - native pointer (output parameter). +- `out_native_info_p` - native pointer's type infomation (output parameter). +- return value + - true, if there is native pointer associated with the object + - false, otherwise + +**Example** + +```c +typedef struct { + int foo; + bool bar; +} native_obj_t; + +static void native_freecb (void *native_p) +{ + ... // free the native pointer +} + +// NOTE: The address (!) of type_info acts as a way to uniquely "identify" the +// C type `native_obj_t *`. +static const jerry_object_native_info_t native_obj_type_info = +{ + .free_cb = native_freecb +}; + +// Function creating JS object that is "backed" by a native_obj_t *: +{ + ... + + // construct object and native_set value: + jerry_value_t object = ...; + native_obj_t *native_obj = malloc(sizeof(*native_obj)); + jerry_set_object_native_pointer (object, native_obj, &native_obj_type_info); + + ... +} + +// Native method, `this` is expected to be "backed" by a native_obj_t *: +{ + void *native_p; + const jerry_object_native_info_t *type_p; + bool has_p = jerry_get_object_native_pointer (this_val, &native_p, &type_p); + + if (has_p) + { + // The type_p pointer address itself is used to identify the type: + if (type_p == &native_obj_type_info) + { + // The type of this's native pointer matches what is expected. + // Only now is it safe to cast to native_obj_t * and dereference the + // pointer: + native_obj_t *native_obj = native_p; + native_obj->bar = ...; // Safe to access now! + } + else + { + // The type of this's native pointer is NOT what we expected! + // We should not cast to native_obj_t * and dereference because it's unsafe. + // Handle the error here, for example throw an error. + } + } + ... +} +``` + +**See also** + +- [jerry_create_object](#jerry_create_object) +- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) +- [jerry_object_native_info_t](#jerry_object_native_info_t) + + +## jerry_set_object_native_pointer + +**Summary** + +Set native pointer and an optional type information for the specified object. +You can get them by calling jerry_get_object_native_pointer later. + +*Note*: If native pointer was already set for the object, its value is updated. + +*Note*: If a non-NULL free callback is specified in the native type information, + it will be called by the garbage collector when the object is freed. + The type info is always overwrites the previous value, so passing + a NULL value deletes the current type info. + +**Prototype** + +```c +bool +jerry_set_object_native_pointer (const jerry_value_t obj_val, + void *native_p, + const jerry_object_native_info_t *info_p) +``` + +- `obj_val` - object to set native pointer in. +- `native_p` - native pointer. +- `info_p` - native pointer's type infomation or NULL. When used, this should + be a long-lived pointer, usually a pointer to a + `static const jerry_object_native_info_t` makes most sense. + +**Example** + +See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) for a +best-practice example. + +**See also** + +- [jerry_create_object](#jerry_create_object) +- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) +- [jerry_object_native_info_t](#jerry_object_native_info_t) ## jerry_foreach_object_property @@ -3320,7 +3626,7 @@ bool foreach_function (const jerry_value_t prop_name, **See also** -- [jerry_object_property_foreach_t](#jerryobjectpropertyforeacht) +- [jerry_object_property_foreach_t](#jerry_object_property_foreach_t) # Input validator functions @@ -3358,13 +3664,13 @@ jerry_is_valid_utf8_string (const jerry_char_t *utf8_buf_p, /**< UTF-8 string */ **See also** -- [jerry_run_simple](#jerryrunsimple) -- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) -- [jerry_create_string_sz_from_utf8](#jerrycreatestringszfromutf8) -- [jerry_get_utf8_string_size](#jerrygetutf8stringsize) -- [jerry_get_utf8_string_length](#jerrygetutf8stringlength) -- [jerry_string_to_utf8_char_buffer](#jerrystringtoutf8charbuffer) -- [jerry_substring_to_utf8_char_buffer](#jerrysubstringtoutf8charbuffer) +- [jerry_run_simple](#jerry_run_simple) +- [jerry_create_string_from_utf8](#jerry_create_string_from_utf8) +- [jerry_create_string_sz_from_utf8](#jerry_create_string_sz_from_utf8) +- [jerry_get_utf8_string_size](#jerry_get_utf8_string_size) +- [jerry_get_utf8_string_length](#jerry_get_utf8_string_length) +- [jerry_string_to_utf8_char_buffer](#jerry_string_to_utf8_char_buffer) +- [jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer) ## jerry_is_valid_cesu8_string @@ -3408,12 +3714,12 @@ jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, /**< CESU-8 string **See also** -- [jerry_create_string](#jerrycreatestring) -- [jerry_create_string_sz](#jerrycreatestringsz) -- [jerry_get_string_size](#jerrygetstringsize) -- [jerry_get_string_length](#jerrygetstringlength) -- [jerry_string_to_char_buffer](#jerrystringtocharbuffer) -- [jerry_substring_to_char_buffer](#jerrysubstringtocharbuffer) +- [jerry_create_string](#jerry_create_string) +- [jerry_create_string_sz](#jerry_create_string_sz) +- [jerry_get_string_size](#jerry_get_string_size) +- [jerry_get_string_length](#jerry_get_string_length) +- [jerry_string_to_char_buffer](#jerry_string_to_char_buffer) +- [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer) # Snapshot functions @@ -3470,9 +3776,9 @@ jerry_parse_and_save_snapshot (const jerry_char_t *source_p, **See also** -- [jerry_init](#jerryinit) -- [jerry_cleanup](#jerrycleanup) -- [jerry_exec_snapshot](#jerryexecsnapshot) +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_exec_snapshot](#jerry_exec_snapshot) ## jerry_exec_snapshot @@ -3481,7 +3787,7 @@ jerry_parse_and_save_snapshot (const jerry_char_t *source_p, Execute snapshot from the specified buffer. -*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. **Prototype** @@ -3532,9 +3838,9 @@ jerry_exec_snapshot (const uint32_t *snapshot_p, **See also** -- [jerry_init](#jerryinit) -- [jerry_cleanup](#jerrycleanup) -- [jerry_parse_and_save_snapshot](#jerryparseandsavesnapshot) +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot) ## jerry_parse_and_save_literals @@ -3596,6 +3902,6 @@ jerry_parse_and_save_literals (const jerry_char_t *source_p, **See also** -- [jerry_init](#jerryinit) -- [jerry_cleanup](#jerrycleanup) -- [jerry_register_magic_strings](#jerryregistermagicstrings) +- [jerry_init](#jerry_init) +- [jerry_cleanup](#jerry_cleanup) +- [jerry_register_magic_strings](#jerry_register_magic_strings) diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md index b4eb2ce3b..30a35bca3 100644 --- a/03.API-EXAMPLE.md +++ b/03.API-EXAMPLE.md @@ -186,7 +186,7 @@ The following example function will output a JavaScript value: #include #include "jerryscript.h" -#include "jerry-port.h" +#include "jerryscript-port.h" static void print_value (const jerry_value_t value) @@ -256,7 +256,7 @@ Shell operation can be described with the following loop: #include #include "jerryscript.h" -#include "jerry-port.h" +#include "jerryscript-port.h" static void print_value (const jerry_value_t); diff --git a/04.INTERNALS.md b/04.INTERNALS.md index c3f36613f..ed65274ff 100644 --- a/04.INTERNALS.md +++ b/04.INTERNALS.md @@ -266,7 +266,7 @@ Several references to single allocated number are not supported. Each reference ### String -Strings in JerryScript are not just character sequences, but can hold numbers and so-called magic ids too. For common character sequences there is a table in the read only memory that contains magic id and character sequence pairs. If a string is already in this table, the magic id of its string is stored, not the character sequence itself. Using numbers speeds up the property access. These techniques save memory. +Strings in JerryScript are not just character sequences, but can hold numbers and so-called magic ids too. For common character sequences (defined in `./jerry-core/lit/lit-magic-strings.ini`) there is a table in the read only memory that contains magic id and character sequence pairs. If a string is already in this table, the magic id of its string is stored, not the character sequence itself. Using numbers speeds up the property access. These techniques save memory. ### Object / Lexical Environment diff --git a/05.PORT-API.md b/05.PORT-API.md index 9dc7acc01..4af4c3212 100644 --- a/05.PORT-API.md +++ b/05.PORT-API.md @@ -125,7 +125,7 @@ This section describes a basic port implementation which was created for Unix ba ```c #include -#include "jerry-port.h" +#include "jerryscript-port.h" /** * Default implementation of jerry_port_fatal. @@ -140,7 +140,7 @@ void jerry_port_fatal (jerry_fatal_code_t code) ```c #include -#include "jerry-port.h" +#include "jerryscript-port.h" /** * Provide console message implementation for the engine. @@ -177,7 +177,7 @@ jerry_port_log (jerry_log_level_t level, /**< log level */ ```c #include -#include "jerry-port.h" +#include "jerryscript-port.h" /** * Default implementation of jerry_port_get_time_zone. diff --git a/06.REFERENCE-COUNTING.md b/06.REFERENCE-COUNTING.md index e8b6301c2..2b607820d 100644 --- a/06.REFERENCE-COUNTING.md +++ b/06.REFERENCE-COUNTING.md @@ -1,6 +1,6 @@ --- layout: page -title: Reference counting +title: Reference Counting permalink: /reference-counting/ --- diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md index d28a9da58..c8ad09d0f 100644 --- a/07.DEBUGGER.md +++ b/07.DEBUGGER.md @@ -139,7 +139,7 @@ jerry_debugger_stop (void) **See also** -- [jerry_debugger_continue](#jerrydebuggercontinue) +- [jerry_debugger_continue](#jerry_debugger_continue) ### jerry_debugger_continue @@ -148,7 +148,7 @@ jerry_debugger_stop (void) If the engine would stop at the next available breakpoint it cancels this effect. The engine will still stop at enabled breakpoints. This function effectively negates the effect of -[jerry_debugger_stop ()](#jerrydebuggerstop) calls or stop +[jerry_debugger_stop ()](#jerry_debugger_stop) calls or stop requests issued by the debugger client. **Prototype** @@ -170,7 +170,7 @@ jerry_debugger_continue (void) **See also** -- [jerry_debugger_stop](#jerrydebuggerstop) +- [jerry_debugger_stop](#jerry_debugger_stop) ### jerry_debugger_disable_stop_at_breakpoint diff --git a/08.CODING-STANDARDS.md b/08.CODING-STANDARDS.md new file mode 100644 index 000000000..7cb336ee7 --- /dev/null +++ b/08.CODING-STANDARDS.md @@ -0,0 +1,806 @@ +--- +layout: page +title: Coding Standards +permalink: /coding-standards/ +--- + +* toc +{:toc} + +# JerryScript Coding Standards + +This text is a brief overview of JerryScript Coding Standards. +Each rule starts with a short description followed by several +examples. We believe examples are better than long explanations. +Please follow these guidelines when you submit a patch for +review. + +## General rules + +* Indentation is two spaces. +* Tab characters are not allowed. +* Maximum line length is 120 characters (excluding newline). +* No trailing white space is allowed. +* Run `tools/run-tests.py --check-vera` to check several + of the coding conventions automatically. + +## Comments + +Only block comments (`/* */`) are allowed in JerryScript. +Comments should be complete sentences (e.g. start with an +upper case letter), except for return value, field and +argument descriptions (see the exceptions below). The +text part of a comment should focus on explaining *why* +the code is doing something rather than *what* the code +is doing. + +```diff ++++ Good +++ +``` + +```c + /* A perfect comment. */ + + /* A perfect multiline + * comment. Each line should + * start with an asterisk. */ +``` + +```diff +--- Bad --- +``` + +```c + // Double slash comments are not allowed. + + /* not a complete sentence */ + + /* A bad mulitiline + comment. */ +``` + +All types, constants and functions require a description in +JerryScript. These comments should start with `/**`. The starting +`/**` and ending `*/` must be on separate lines. + +```diff ++++ Good +++ +``` + +```c +/** + * A correct description. + */ +``` + +```diff +--- Bad --- +``` + +```c +/** An incorrect description. */ +``` + +## Preprocessor defines + +The name of a preprocessor macro must be an uppercase string +and these macros must be preceded by a description. +Abbreviations are allowed but not preferred in new code. + +```diff ++++ Good +++ +``` + +```c +/** + * Short description about the constant. + */ +#define JERRY_VALUE_SEVEN 7 + +/** + * Short description about the macro function. + */ +#define JERRY_ADD_TWO_NUMBERS(arg1, arg2) \ + ((arg1) + (arg2)) + +/** + * Although this is correct, a reviewer might request + * to change NUMS to NUMBERS. Hence it is recommended + * to use NUMBERS in the first place. + */ +#define JERRY_ADD_TWO_NUMS(arg1, arg2) \ + ((arg1) + (arg2)) +``` + +```diff +--- Bad --- +``` + +```c +#define JERRY_CONSTANT_WITHOUT_DESCRIPTION 5 + +#define JeRrY_mIxEd_CaSe_NaMe "str" +``` + +## Conditional preprocessor directives + +A comment is required after `#else` and `#endif` in JerryScript. +The defined keyword should be omitted from these comments. + +```diff ++++ Good +++ +``` + +```c +#ifdef JERRY_A + +#else /* !JERRY_A */ + +#endif /* JERRY_A */ + +#ifdef JERRY_A +#if defined JERRY_B && defined JERRY_C && (JERRY_C > 6) + +#else /* !(JERRY_B && JERRY_C && (JERRY_C > 6)) */ + +#endif /* JERRY_B && JERRY_C && (JERRY_C > 6) */ +#endif /* JERRY_A */ +``` + +```diff +--- Bad --- +``` + +```c +#ifdef JERRY_A + +#endif + +#ifdef JERRY_A + +#endif /* defined JERRY_A */ + +#ifdef JERRY_B + /* Missing comment after else. */ +#else + +#endif /* JERRY_B */ +``` + +## Code blocks + +Each code block must be enclosed in curly braces even +if it is a single line statement. These braces must +be on separate lines. There must be a single space +before the opening parenthesis of the expression +after if/while/switch keywords. + +```diff ++++ Good +++ +``` + +```c +if (value > 6) +{ + function_call (); +} + +if (value > 1) +{ + function_call_a (); +} +else +{ + function_call_b (); +} + +do +{ + function_call (); + value++; +} +while (value < 6); + +switch (value) +{ + case A: + { + /* FALLTHRU comment is allowed if a + * switch-case is not terminated by + * break/continue/return. */ + + /* FALLTHRU */ + } + case B: + case C: + { + break; + } + case D: + { + /* We can use continue if we are in a loop. */ + continue; + } + default: + { + return; + } +} +``` + +```diff +--- Bad --- +``` + +```c +if (value > 6) + function_call_a (); +else + function_call_b (); + +if (value > 6) { + function_call_a (); +} + +if (value > 6) function_call_a (); +else { function_call_b (); } + +if +(value > 6) +{ +} + +switch (value) { + case 0: break; + default: { + return 5; + } +} + +switch (value) +{ + case A: + { + if (value > 6) + { + CASE B: + { + /* This is allowed in C but + * not in JerryScript. */ + break; + } + } + } +} + +do + value++; +while (value < 5); + +do { + value++; +} while (value < 5); + +do +{ + value++; +} while (value < 5); +``` + +## Newlines + +A newline in JerryScript is a separator which separates different +parts of the source code. Its primary purpose is to improve +readability. Unlike other rules developers have some freedom +to add newlines to their code. However there are some rules. + +* Only a single newline separator is allowed. +* Source files must be terminated by a newline. +* Global declarations must be separated by a newline. +* Newlines are not allowed after an opening curly brace or before + a closing curly brace +* No newlines are allowed between control statements (if-else, while, + for, switch, etc.) and their code blocks. +* There should be a newline after the variable declarations + if they are the first statements of a block. + +```diff ++++ Good +++ +``` + +```c +if (a > 5) +{ + /* Newline must be present after the first + * variable declarations of a code block. */ + int j = a - 1; + int k = a * 2; + + return j + k; +} + +while (a < 5) +{ + a++; + + /* It is recommended to put a newline after + * intermediate variable declarations. */ + int i = a * 2; + + b = i - 3; +} + +/* It is a recommended to put newlines around asserts. */ +a = b + 5; + +JERRY_ASSERT (a < 20); + +c = a + 7; + +/* It is a good practice to put a newline after a multiline + * function call (see Function calls later). */ +f (a, + b, + c); + +a = 6; +``` + +```diff +--- Bad --- +``` + +```c +/* No newlines are allowed after an opening curly + * brace or before a closing curly brace */ + +while (a > 0) +{ + + a = 6; + +} + +if (a > 5) +{ + while (b < 6) + { + + b++; + } + +} + + +/* Two or more newlines are not allowed. */ +a = 6; + + +b = 7; + +/* No newlines are allowed between control staments + * and their code blocks. */ + +if (a > 6) + +{ +} + +else + +{ +} + +do + +{ +} + +while (a < 6); +``` + +## Expressions + +Spaces are required around binary operators. No space is +needed otherwise. + +```diff ++++ Good +++ +``` + +```c +a = b + c; +a = (b + c) << 3; +a = b = c + ~d; +a += ++c + d++; +call_function (a * (b + !!c) - d + (e % f)); +if (a) +{ +} +``` + +```diff +--- Bad --- +``` + +```c +a=b+c; +a = b+c; +a += c + ( d ); +/* Introduce temporary variables or macros + * if the expression is too long. Occures rarely.. */ +a = b + + c; +if ( a + b > 0 ) +{ +} +``` + +## Logical operators + +All expressions with && and || logical operators must be +enclosed in parentheses. A single and multiline form is +allowed for these expressions. In the latter case each +line must start with the logical operator and each line +must be aligned to the column right after the opening +parenthesis. + +```diff ++++ Good +++ +``` + +```c +/* Single line form. */ +a = ((c && d) || (e && f)); + +a = (c + && d); + +a = (c + && (d || e) + && f); + +do +{ +} +while (a + && b); + +/* This form is rarely used but it is ok. */ +if (a + && (b + || c + || d) + && e) +{ +} +``` + +```diff +--- Bad --- +``` + +```c +if (a || b || + c) +{ +} + +/* Parentheses are missing. */ +a = b || c; + +/* Misaligned &&. */ +if (a + && b) +{ +} +``` + +## Ternary conditional operators + +A special form of ternary conditional operators are allowed +in JerryScript where the ? and : operators are on separate +lines in the same column. + +```diff ++++ Good +++ +``` + +```c +a = (b ? c + : d); + +/* Single line form is accepted as well. */ +a = (b ? c : d); + +/* This form is rarely used but it is ok. */ +if (a ? b + : (c ? d + : e)) +{ +} +``` + +```diff +--- Bad --- +``` + +```c +a = b ? + c : d; + +while (a ? b + : c) +{ +} + +if (a + ? b + : c) +{ +} +``` + +## Function calls + +There must be a space after the function name. Each argument +must be in the same or separated lines. In the former case +there must be a space before the next argument and in the +latter case all arguments must be aligned to the same column. + +```diff ++++ Good +++ +``` + +```c +function_a (); +function_b (a); +function_c (a, b, c); + +function_c (a, + b, + c); + +function_c (a, + b, + function_c (a, + b, + c); +``` + +```diff +--- Bad --- +``` + +```c +/* No space before the opening parenthesis. */ +function_f(); + +function_f ( +); + +function_g(a); + +function_g + (a + ); + +/* Two arguments on the same line. */ +function_h (a, b, + c); + +function_h (a, + b, c); + +/* Misaligned arguments. */ +function_h (a, + b, + c); +``` + +## Variable declarations + +JerryScript is a pure C99 codebase so variable +declarations can be anywhere in the code including +inside for-loops. It is recommended to declare a +variable before the first use. + +```diff ++++ Good +++ +``` + +```c +for (int i = 0; i < 10; i++) +{ + int j = i + 1; + while (j < 10) + { + ++j; + } +} + +/* Multiline form of for loops. */ +for (int i = 0; + i < 10; + i++) +{ +} +``` + +## Type casting + +There must be a space after the closing parenthesis +of the type cast. Type casting has no multiline form +in JerryScript. + +```diff ++++ Good +++ +``` + +```c +int a = (int) double_variable; + +int a = (int) (long) (float) double_variable; +``` + +```diff +--- Bad --- +``` + +```c +/* Wrong spaces. */ +int a = ( int )double_variable; + +/* No multiline form. */ +int a = (int) + double_variable; +``` + +## Pointers and asterisk character + +Each pointer in JerryScript must be a lowercase string +which is ending with a `_p` suffix. Furthermore there +must be a space before the asterisk character. + +```diff ++++ Good +++ +``` + +```c + int *int_p; + + /* No need to add multiple _p-s for multiple indirections. + * It is recommended to avoid these constructs using typedef + * declarations. A reviewer might request such a change. */ + int ***int_p; + + /* This rule applies for type casting as well. */ + char = *(char *) type_p; +``` + +```diff +--- Bad --- +``` + +```c + /* No _p after the name. */ + int *ptr; + + /* Wrong asterisk position. */ + int* ptr_p; + + char_p = * (char*)type_p; +``` + +## Types + +Each type in JerryScript must be a lowercase string +which ends with a `_t` suffix. Furthermore each type +declaration must be preceded by a short description +of the type and each field must have a short description +as well. + +```diff ++++ Good +++ +``` + +```c +/** + * Short description of the following structure. + */ +typedef struct +{ + /* Field descriptions do not start with capital letters + * and there is no full stop at the end. */ + field1_t field1; /**< description of field 1 */ + field2_t field2; /**< description of field 1 */ + + field_n_t field_n; /**< description of field n */ +} structure_name_t; + +/** + * Another integer type. + */ +typedef int jerry_int; +``` + +```diff +--- Bad --- +``` + +```c +typedef struct +{ + field_t field_without_description; +} structure_without_description_t; + +typedef struct { int a; } single_line_struct; + +typedef +union { +} +wrong_newlines_t; + +/* + * Bad comment format. + */ +typedef +char wrong_newlines_again_t; +``` + +## Function declarations + +Function declarations in JerryScript are verbose but this format +reduces the maintenance cost and allows faster understanding of +the code. + +```diff ++++ Good +++ +``` + +```c +/** + * Short overview about the purpose of this function. + * + * A more detailed explanation if needed. + * + * Note: + * Extra notes if needed. + * + * @return short description about the value + * returned by the function + */ +return_value_type_t +function_name (argument1, /**< description of argument1 */ + argument2, /**< description of argument2 */ + ... + argument_n, /**< description of argument n */ +{ + + /* Function body. */ + +} /* function_name */ +``` + +```diff +--- Bad --- +``` + +```c +static int +print (char *text) /**< description of text argument */ +{ + /* Missing comment before the function. */ +} /* print */ + +/** + * Prints the text received by the function. + * + * @return number of characters printed by the function + */ +int print(char *text) +{ + /* No description of text argument. */ + /* Missing comment at the end of the function. */ +} +``` diff --git a/_includes/header.html b/_includes/header.html index 672759ab8..68f7d9a84 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -21,7 +21,7 @@