diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 4ae4d89be4..13225e784e 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -31,6 +31,19 @@ Possible types of an error: - JERRY_ERROR_TYPE - type error - JERRY_ERROR_URI - URI error +## jerry_feature_t + +Possible compile time enabled feature types: + + - JERRY_FEATURE_CPOINTER_32_BIT - 32 bit compressed pointers + - JERRY_FEATURE_ERROR_MESSAGES - error messages + - JERRY_FEATURE_JS_PARSER - js-parser + - JERRY_FEATURE_MEM_STATS - memory statistics + - JERRY_FEATURE_PARSER_DUMP - parser byte-code dumps + - JERRY_FEATURE_REGEXP_DUMP - regexp byte-code dumps + - JERRY_FEATURE_SNAPSHOT_SAVE - saving snapshot files + - JERRY_FEATURE_SNAPSHOT_EXEC - executing snapshot files + ## jerry_char_t **Summary** @@ -251,6 +264,8 @@ jerry_cleanup (void); Registers an external magic string array. +*Note*: The strings in the array must be sorted by size at first, then lexicographically. + **Prototype** ```c @@ -271,11 +286,12 @@ jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p, jerry_init (JERRY_INIT_EMPTY); // must be static, because 'jerry_register_magic_strings' does not copy + // the items must be sorted by size at first, then lexicographically static const jerry_char_ptr_t magic_string_items[] = { (const jerry_char_ptr_t) "magicstring1", (const jerry_char_ptr_t) "magicstring2", (const jerry_char_ptr_t) "magicstring3" - }; + }; uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t)); // must be static, because 'jerry_register_magic_strings' does not copy @@ -292,6 +308,7 @@ jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p, - [jerry_init](#jerryinit) - [jerry_cleanup](#jerrycleanup) +- [jerry_parse_and_save_literals](#jerryparseandsaveliterals) ## jerry_get_memory_limits @@ -926,6 +943,38 @@ jerry_value_is_undefined (const jerry_value_t value) - [jerry_release_value](#jerryreleasevalue) +## jerry_is_feature_enabled + +**Summary** + +Returns whether the specified compile time feature is enabled. + +**Prototype** + +```c +bool +jerry_is_feature_enabled (const jerry_feature_t feature); +``` + +- `feature` - jerry feature +- return value + - true, if the given `jerry_feature_t` is enabled + - false, otherwise + +**Example** + +```c +{ + ... + jerry_feature_t feature = JERRY_FEATURE_SNAPSHOT_SAVE; + + if (jerry_is_feature_enabled (feature)) + { + ... + } + +} +``` # Error flag manipulation functions @@ -1159,6 +1208,44 @@ jerry_get_string_size (const jerry_value_t value); - [jerry_get_string_length](#jerrygetstringlength) +## jerry_get_utf8_string_size + +**Summary** + +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 +instead of the cesu-8 string size. + +**Prototype** + +```c +jerry_size_t +jerry_get_utf8_string_size (const jerry_value_t value); +``` +- `value` - api value +- return value - number of bytes in the buffer needed to represent the utf8-encoded string. + +**Example** + +```c +{ + const jerry_char_t char_array[] = "a string"; + jerry_value_t string = jerry_create_string (char_array); + + jerry_size_t string_size = jerry_get_utf8_string_size (string); + + ... // usage of string_size + + jerry_release_value (string); +} +``` + +**See also** + +- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) +- [jerry_get_utf8_string_length](#jerrygetutf8stringlength) + ## jerry_get_string_length **Summary** @@ -1195,6 +1282,44 @@ jerry_get_string_length (const jerry_value_t value); - [jerry_create_string](#jerrycreatestring) - [jerry_get_string_size](#jerrygetstringsize) +## jerry_get_utf8_string_length + +**Summary** + +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 +returns with utf-8 string length instead of the cesu-8 string length. + +**Prototype** + +```c +jerry_length_t +jerry_get_utf8_string_length (const jerry_value_t value); +``` + +- `value` - input string value +- return value - number of characters in the string + +**Example** + +```c +{ + const jerry_char_t char_array[] = "a string"; + jerry_value_t string = jerry_create_string_from_utf8 (char_array); + + jerry_length_t string_length = jerry_get_utf8_string_length (string); + + ... // usage of string_length + + jerry_release_value (string); +} +``` + +**See also** + +- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) +- [jerry_get_utf8_string_size](#jerrygetutf8stringsize) ## jerry_string_to_char_buffer @@ -1240,6 +1365,49 @@ jerry_string_to_char_buffer (const jerry_value_t value, - [jerry_create_string](#jerrycreatestring) - [jerry_get_string_size](#jerrygetstringsize) +## jerry_string_to_utf8_char_buffer + +**Summary** + +Copy the characters of a string into a specified utf-8 buffer. +The '\0' character could occur in character buffer. Returns 0, +if the value parameter is not a string or the buffer isn't +large enough for the whole string. + +**Prototype** + +```c +jerry_size_t +jerry_string_to_utf8_char_buffer (const jerry_value_t value, + jerry_char_t *buffer_p, + jerry_size_t buffer_size); +``` + +- `value` - input string value +- `buffer_p` - pointer to output buffer +- `buffer_size` - size of the buffer +- return value - number of bytes, actually copied to the buffer + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_size_t req_sz = jerry_get_utf8_string_size (value); + jerry_char_t str_buf_p[req_sz]; + + jerry_string_to_utf8_char_buffer (value, str_buf_p, req_sz); + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) +- [jerry_get_utf8_string_size](#jerrygetutf8stringsize) # Functions for array object values @@ -1990,6 +2158,80 @@ jerry_create_string_sz (const jerry_char_t *str_p, - [jerry_create_string](#jerrycreatestring) +## jerry_create_string_from_utf8 + +**Summary** + +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. + +**Prototype** + +```c +jerry_value_t +jerry_create_string_from_utf8 (const jerry_char_t *str_p); +``` + +- `str_p` - pointer to string +- return value - value of the created string + +**Example** + +```c +{ + const jerry_char_t char_array[] = "a string"; + jerry_value_t string_value = jerry_create_string_from_utf8 (char_array); + + ... // usage of string_value + + jerry_release_value (string_value); +} +``` + +**See also** + +- [jerry_create_string_sz_from_utf8](#jerrycreatestringszfromutf8) + + +## jerry_create_string_sz_from_utf8 + +**Summary** + +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. + +**Prototype** + +```c +jerry_value_t +jerry_create_string_sz (const jerry_char_t *str_p, + jerry_size_t str_size) +``` + +- `str_p` - pointer to string +- `str_size` - size of the string +- return value - value of the created string + +**Example** + +```c +{ + const jerry_char_t char_array[] = "a string"; + jerry_value_t string_value = jerry_create_string_sz_from_utf8 (char_array, + strlen ((const char *) char_array)); + + ... // usage of string_value + + jerry_release_value (string_value); +} + +``` + +**See also** + +- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) ## jerry_create_undefined @@ -3018,3 +3260,67 @@ jerry_exec_snapshot (const void *snapshot_p, - [jerry_init](#jerryinit) - [jerry_cleanup](#jerrycleanup) - [jerry_parse_and_save_snapshot](#jerryparseandsavesnapshot) + + +## jerry_parse_and_save_literals + +**Summary** + +Collect the used literals from the given source code and save them into a specific file in a list or C format. +These literals are generated by the parser, they are valid identifiers and none of them are magic string. + +**Prototype** + +```c +size_t +jerry_parse_and_save_literals (const jerry_char_t *source_p, + size_t source_size, + bool is_strict, + uint8_t *buffer_p, + size_t buffer_size, + bool is_c_format); +``` + +- `source_p` - script source, it must be a valid utf8 string. +- `source_size` - script source size, in bytes. +- `is_strict` - strict mode. +- `buffer_p` - buffer to save literals to. +- `buffer_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, + and literal-save support is enabled in current configuration through JERRY_ENABLE_SNAPSHOT_SAVE) + - 0 otherwise. + +**Example** + +```c +{ + jerry_init (JERRY_INIT_EMPTY); + + static uint8_t save_literal_buffer[1024]; + const jerry_char_t *code_for_literal_save_p = "var obj = { a:'aa', bb:'Bb' }"; + + size_t literal_sizes = jerry_parse_and_save_literals (code_for_literal_save_p, + strlen ((const char *) code_for_literal_save_p), + false, + save_literal_buffer, + sizeof (save_literal_buffer), + true); + + if (literal_sizes != 0) + { + FILE *literal_file_p = fopen ("literals.txt", "w"); + fwrite (save_literal_buffer, sizeof (uint8_t), literal_sizes, literal_file_p); + fclose (literal_file_p); + } + + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_init](#jerryinit) +- [jerry_cleanup](#jerrycleanup) +- [jerry_register_magic_strings](#jerryregistermagicstrings) diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md index 87248986b3..535ed78cf4 100644 --- a/03.API-EXAMPLE.md +++ b/03.API-EXAMPLE.md @@ -521,4 +521,4 @@ Value of x is 17 ## Further steps -For further API description, please visit [API Reference page](https://samsung.github.io/jerryscript/api-reference/) on [JerryScript home page](https://samsung.github.io/jerryscript/). +For further API description, please visit [API Reference page](https://jerryscript-project.github.io/jerryscript/api-reference/) on [JerryScript home page](https://jerryscript-project.github.io/jerryscript/). diff --git a/_config.yml b/_config.yml index 02c01d680d..092cdbbef7 100644 --- a/_config.yml +++ b/_config.yml @@ -2,7 +2,7 @@ title: JerryScript Engine #email: your-email@domain.com description: > # this means to ignore newlines until "baseurl:" - JerryScript is a very lightweight JavaScript engine with capability to run on microcontrollers with less then 8KB of RAM. + JerryScript is a very lightweight JavaScript engine with capability to run on microcontrollers with less than 8KB of RAM. # baseurl: "/jerryscript" # the subpath of your site, e.g. /blog/ # url: "http://samsung.github.io" # the base hostname & protocol for your site #twitter_username: jekyllrb