diff --git a/docs/01.GETTING-STARTED.md b/docs/01.GETTING-STARTED.md index b2bce19d2..534231e87 100644 --- a/docs/01.GETTING-STARTED.md +++ b/docs/01.GETTING-STARTED.md @@ -1,4 +1,4 @@ -### Setting Up Prerequisites +## Setting up prerequisites Currently, only Ubuntu 14.04+ is officially supported as primary development environment. @@ -19,38 +19,41 @@ sudo apt-get install gcc g++ gcc-arm-none-eabi cmake cppcheck vera++ python To make our scripts run correctly, several shell utilities should be available on the system: -- `find` - `awk` +- `bc` +- `find` +- `sed` -### Building Jerryscript +## Building JerryScript -##### To build debug version for Linux: +**To build debug version for Linux** ```bash python tools/build.py --debug ``` -##### To build debug version for Linux without LTO (Link Time Optimization): +**To build debug version for Linux without LTO (Link Time Optimization)** ```bash python tools/build.py --debug --lto=off ``` -##### Add custom arguments to CMake: +**Add custom arguments to CMake** ```bash python tools/build.py --cmake-param=CMAKE_PARAM ``` -##### Set a profile mode (full|minimal): +**Set a profile mode (full, minimal)** ```bash python tools/build.py --feature=full|minimal ``` -##### Use (jerry|compiler-default|external libc) libc: +**Use (jerry, compiler-default, external) libc** The default libc is jerry-libc, but you can use compiler-default libc or an external libc: + - compiler-default libc: ```bash @@ -63,7 +66,7 @@ python tools/build.py --jerry-libc=off --compiler-default-libc=on python tools/build.py --jerry-libc=off --compiler-default-libc=off --compile-flag="-I/path/to/libc/include" ``` -##### Add toolchain file: +**Add toolchain file** The ```cmake``` dir already contains some usable toolchain files, which you can use in the following format: @@ -77,72 +80,64 @@ For example the cross-compile to RaspberryPi 2 is something like this: python tools/build.py --toolchain=cmake/toolchain_linux_armv7l.cmake ``` -##### To get a list of all the available buildoptions for Linux: +**To get a list of all the available buildoptions for Linux** ```bash python tools/build.py --help ``` -### Checking patch +## Checking patch ```bash python tools/run-tests.py --precommit ``` +### Running only one type of test -#### Running only one type of test: - -##### To run build option tests: +**To run build option tests** ```bash python tools/run-tests.py --buildoption-test ``` -##### To run unittests: +**To run unittests** ```bash python tools/run-tests.py --unittests ``` -##### To run jerry-tests: +**To run jerry-tests** ```bash python tools/run-tests.py --jerry-tests ``` -##### To run jerry-test-suite: +**To run jerry-test-suite** ```bash python tools/run-tests.py --jerry-test-suite ``` -##### To run signed-off check: +**To run signed-off check** ```bash python tools/run-tests.py --check-signed-off ``` -##### To run cppcheck: +**To run cppcheck** ```bash python tools/run-tests.py --check-cppcheck ``` -##### To run vera check: +**To run vera check** ```bash python tools/run-tests.py --check-vera ``` -##### Use toolchain file: - -The cmake dir already contains some usable toolchain files, which you can use in the following format: - -python tools/run-tests.py --toolchain=TOOLCHAIN - -##### To get a list of all the available test options: +**To get a list of all the available test options** ```bash python tools/run-tests.py --help ``` - diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index 02c6ad305..510363e7c 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -13,6 +13,7 @@ Enum that contains the following elements: ## jerry_error_t Possible types of an error: + - JERRY_ERROR_COMMON - common error - JERRY_ERROR_EVAL - eval error - JERRY_ERROR_RANGE - range error @@ -33,6 +34,18 @@ Jerry's char value typedef uint8_t jerry_char_t; ``` +## jerry_char_ptr_t + +**Summary** + +Pointer to an array of character values + +**Prototype** + +```c +typedef jerry_char_t *jerry_char_ptr_t; +``` + ## jerry_size_t **Summary** @@ -130,7 +143,7 @@ Type of an external function handler **Prototype** ```c -typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj_p, +typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj, const jerry_value_t this_val, const jerry_value_t args_p[], const jerry_length_t args_count); @@ -157,7 +170,7 @@ Function type applied for each data property of an object **Prototype** ```c -typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name_p, +typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name, const jerry_value_t property_value, void *user_data_p); ``` @@ -233,14 +246,14 @@ Registers an external magic string array. ```c void -jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items, +jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p, uint32_t count, - const jerry_length_t *str_lengths); + const jerry_length_t *str_lengths_p); ``` -- `ex_str_items` - character arrays, representing external magic strings' contents +- `ex_str_items_p` - character arrays, representing external magic strings' contents - `count` - number of the strings -- `str_lengths` - lengths of the strings +- `str_lengths_p` - lengths of the strings **Example** @@ -296,8 +309,8 @@ jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p, jerry_init (JERRY_INIT_EMPTY); size_t stack_limit; - size_t data_dss_brk_limit; - jerry_get_memory_limits (&stack_limit, &data_dss_brk_limit); + size_t data_bss_brk_limit; + jerry_get_memory_limits (&stack_limit, &data_bss_brk_limit); } ``` @@ -345,12 +358,12 @@ The simplest way to run JavaScript. ```c bool -jerry_run_simple (const jerry_char_t *script_source, +jerry_run_simple (const jerry_char_t *script_source_p, size_t script_source_size, jerry_init_flag_t flags); ``` -- `script_source` - source code, it must be a valid utf8 string. +- `script_source_p` - source code, it must be a valid utf8 string. - `script_source_size` - size of source code buffer, in bytes. - `jerry_init_flag_t` - combination of various engine configuration flags - return value @@ -407,7 +420,7 @@ jerry_parse (const jerry_char_t *source_p, { jerry_init (JERRY_INIT_EMPTY); - char script [] = "print ('Hello, World!');"; + const jerry_char_t script[] = "print ('Hello, World!');"; size_t script_size = strlen ((const char *) script); jerry_value_t parsed_code = jerry_parse (script, script_size, false); @@ -426,7 +439,7 @@ jerry_parse (const jerry_char_t *source_p, **Summary** -Run an EcmaScript function created by jerry_parse. +Run an EcmaScript function created by `jerry_parse`. *Note*: The code should be previously parsed with `jerry_parse`. @@ -434,7 +447,7 @@ Run an EcmaScript function created by jerry_parse. ```c jerry_value_t -jerry_run (jerry_value_t func_val); +jerry_run (const jerry_value_t func_val); ``` - `func_val` - function to run @@ -558,6 +571,8 @@ Functions to check the type of an API value ([jerry_value_t](#jerry_value_t)). **Summary** +Returns whether the given `jerry_value_t` is an array. + **Prototype** ```c @@ -1018,7 +1033,7 @@ Get raw data from API values. **Summary** -Gets the raw bool value form a `jerry_value_t`. +Gets the raw bool value from a `jerry_value_t`. **Prototype** @@ -1118,7 +1133,7 @@ jerry_get_string_size (const jerry_value_t value); ```c { - jerry_char_t char_array[] = "a string"; + const jerry_char_t char_array[] = "a string"; jerry_value_t string = jerry_create_string (char_array); jerry_size_t string_size = jerry_get_string_size (string); @@ -1155,7 +1170,7 @@ jerry_get_string_length (const jerry_value_t value); ```c { - jerry_char_t char_array[] = "a string"; + const jerry_char_t char_array[] = "a string"; jerry_value_t string = jerry_create_string (char_array); jerry_length_t string_length = jerry_get_string_length (string); @@ -1255,7 +1270,7 @@ jerry_get_array_length (const jerry_value_t value); # Converters of 'jerry_value_t' -Functions for convering API values to another value type. +Functions for converting API values to another value type. ## jerry_value_to_boolean @@ -1429,7 +1444,7 @@ jerry_value_to_string (const jerry_value_t value); - `value` - api value - return value - - converted srting value, if success + - converted string value, if success - thrown error, otherwise **Example** @@ -1451,7 +1466,7 @@ jerry_value_to_string (const jerry_value_t value); - [jerry_value_to_primitive](#jerry_value_to_primitive) -# Aquire and release API values +# Acquire and release API values ## jerry_acquire_value @@ -1620,7 +1635,7 @@ jerry_create_error (jerry_error_t error_type, ```c { jerry_value_t error_obj = jerry_create_error (JERRY_ERROR_TYPE, - (jerry_char_t * ) "error"); + (const jerry_char_t *) "error"); ... // usage of error_obj @@ -1660,10 +1675,10 @@ jerry_create_error_sz (jerry_error_t error_type, ```c { - jerry_char_t message[] = "error"; + const jerry_char_t *message = "error"; jerry_value_t error_obj = jerry_create_error_sz (JERRY_ERROR_COMMON, message, - strlen ((char *) message)); + strlen ((const char *) message)); ... // usage of error_obj @@ -1696,10 +1711,10 @@ jerry_create_external_function (jerry_external_handler_t handler_p); ```c static jerry_value_t -handler (const jerry_value_t function_obj_p, - const jerry_value_t this_p, +handler (const jerry_value_t function_obj, + const jerry_value_t this_val, const jerry_value_t args_p[], - const uint16_t args_cnt) + const jerry_length_t args_cnt) { printf ("native handler called!\n"); @@ -1711,7 +1726,7 @@ handler (const jerry_value_t function_obj_p, jerry_value_t glob_obj = jerry_get_global_object (); // after this, script can invoke the native handler through "handler_field (1, 2, 3);" - jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field"); + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field"); jerry_set_property (glob_obj, prop_name, func_val); jerry_release_value (prop_name); @@ -1953,7 +1968,7 @@ jerry_create_string_sz (const jerry_char_t *str_p, { const jerry_char_t char_array[] = "a string"; jerry_value_t string_value = jerry_create_string_sz (char_array, - strlen ((char *) char_array)); + strlen ((const char *) char_array)); ... // usage of string_value @@ -1971,7 +1986,7 @@ jerry_create_string_sz (const jerry_char_t *str_p, **Summary** -Creates a jerry_value_t representing an undefined value. +Creates a `jerry_value_t` representing an undefined value. **Prototype** @@ -2026,7 +2041,7 @@ jerry_has_property (const jerry_value_t obj_val, ```c { jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field"); + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field"); bool has_prop = jerry_has_property (global_object, prop_name); @@ -2066,7 +2081,7 @@ jerry_has_own_property (const jerry_value_t obj_val, ```c { jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field"); + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field"); bool has_prop = jerry_has_own_property (global_object, prop_name); @@ -2106,7 +2121,7 @@ jerry_delete_property (const jerry_value_t obj_val, ```c { jerry_value_t global_object = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "my_prop"); + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); jerry_delete_property (global_object, prop_name); @@ -2187,7 +2202,7 @@ jerry_get_property_by_index (const jerry_value_t obj_val, ``` - `obj_val` - object value -- index - index number +- `index` - index number - return value - stored value on the specified index, if success - thrown exception, otherwise. @@ -2253,7 +2268,7 @@ jerry_set_property (const jerry_value_t obj_val, ... // create or acquire value to set jerry_value_t glob_obj = jerry_get_global_object (); - jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "my_prop"); + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); jerry_set_property (glob_obj, prop_name, value_to_set); @@ -2295,7 +2310,7 @@ jerry_set_property_by_index (const jerry_value_t obj_val, ``` - `obj_val` - object value -- index - index number +- `index` - index number - `value_to_set` - value to set - return value - true, if field value was set successfully @@ -2576,7 +2591,7 @@ is no longer needed. jerry_value_t jerry_construct_object (const jerry_value_t func_obj_val, const jerry_value_t args_p[], - uint16_t args_count); + jerry_size_t args_count); ``` - `func_obj_val` - function object to call @@ -2792,12 +2807,12 @@ Set native handle and an optional free callback for the specified object ```c void jerry_set_object_native_handle (const jerry_value_t obj_val, - uintptr_t handle, + uintptr_t handle_p, jerry_object_free_callback_t freecb_p); ``` - `obj_val` - object value to set handle in -- `handle` - handle value +- `handle_p` - handle value - `freecb_p` - pointer to "free" callback or NULL **Example** @@ -2840,14 +2855,13 @@ jerry_foreach_object_property (jerry_value_t obj_val, ``` - `obj_val` - object value -- `foreach_p` - foreach function, that will be apllied for each property +- `foreach_p` - foreach function, that will be applied for each property - `user_data_p` - user data for foreach function - return value - true, if object fields traversal was performed successfully, i.e.: - no unhandled exceptions were thrown in object fields traversal - object fields traversal was stopped on callback that returned false - - false, otherwise, if getter of field threw a exception or unhandled exceptions were thrown - during traversal + - false, otherwise **Example** @@ -2900,13 +2914,13 @@ jerry_parse_and_save_snapshot (const jerry_char_t *source_p, - `source_p` - script source, it must be a valid utf8 string. - `source_size` - script source size, in bytes. - `is_for_global` - snapshot would be executed as global (true) or eval (false). -- `is_strict` - stric mode +- `is_strict` - strict mode - `buffer_p` - buffer to save snapshot to. - `buffer_size` - the buffer's size. - return value - the size of snapshot, 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_ENABLE_SNAPSHOT) + JERRY_ENABLE_SNAPSHOT_SAVE) - 0 otherwise. **Example** @@ -2916,10 +2930,10 @@ jerry_parse_and_save_snapshot (const jerry_char_t *source_p, jerry_init (JERRY_INIT_EMPTY); static uint8_t global_mode_snapshot_buffer[1024]; - const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();"; + const jerry_char_t *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();"; - size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p, - strlen (code_to_snapshot_p), + size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p, + strlen ((const char *) code_to_snapshot_p), true, false, global_mode_snapshot_buffer, @@ -2970,11 +2984,11 @@ jerry_exec_snapshot (const void *snapshot_p, { jerry_value_t res; static uint8_t global_mode_snapshot_buffer[1024]; - const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();"; + const jerry_char_t *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();"; jerry_init (JERRY_INIT_EMPTY); - size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p, - strlen (code_to_snapshot_p), + size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p, + strlen ((const char *) code_to_snapshot_p), true, global_mode_snapshot_buffer, sizeof (global_mode_snapshot_buffer)); diff --git a/docs/03.API-EXAMPLE.md b/docs/03.API-EXAMPLE.md index 3a574f168..9bba81349 100644 --- a/docs/03.API-EXAMPLE.md +++ b/docs/03.API-EXAMPLE.md @@ -9,14 +9,14 @@ This guide is intended to introduce you to JerryScript embedding API through cre #include "jerry-api.h" int -main (int argc, char * argv[]) +main (int argc, char *argv[]) { const jerry_char_t script[] = "print ('Hello, World!');"; size_t script_size = strlen ((const char *) script); bool ret_value = jerry_run_simple (script, script_size, JERRY_INIT_EMPTY); - return (ret_value ? 1 : 0); + return (ret_value ? 0 : 1); } ``` @@ -41,7 +41,7 @@ Here we perform the same actions, as `jerry_run_simple`, while splitting into se #include "jerry-api.h" int -main (int argc, char * argv[]) +main (int argc, char *argv[]) { const jerry_char_t script[] = "print ('Hello, World!');"; size_t script_size = strlen ((const char *) script); @@ -80,7 +80,7 @@ Our code is more complex now, but it introduces possibilities to interact with J #include "jerry-api.h" int -main (int argc, char * argv[]) +main (int argc, char *argv[]) { const jerry_char_t script_1[] = "var s = 'Hello, World!';"; const jerry_char_t script_2[] = "print (s);"; @@ -122,7 +122,7 @@ This way, we execute two independent script parts in one execution environment. #include "jerry-api.h" int -main (int argc, char * argv[]) { +main (int argc, char *argv[]) { const jerry_char_t str[] = "Hello, World!"; const jerry_char_t script[] = "print (s);"; @@ -214,6 +214,7 @@ print_value (const jerry_value_t value) jerry_char_t str_buf_p[req_sz]; jerry_string_to_char_buffer (value, str_buf_p, req_sz); + str_buf_p[req_sz] = '\0'; jerry_port_console ("%s", (const char *) str_buf_p); } @@ -248,10 +249,10 @@ Shell operation can be described with the following loop: #include "jerry-api.h" #include "jerry-port.h" -static void print_value (const jerry_api_value_t); +static void print_value (const jerry_value_t); int -main (int argc, char * argv[]) +main (int argc, char *argv[]) { bool is_done = false; @@ -260,7 +261,7 @@ main (int argc, char * argv[]) while (!is_done) { - char cmd [256]; + char cmd[256] = {}; char *cmd_tail = cmd; size_t len = 0; @@ -283,6 +284,12 @@ main (int argc, char * argv[]) len++; } + /* If the command is "quit", break the loop */ + if (!strncmp (cmd, "quit\n", strlen ("quit\n"))) + { + break; + } + jerry_value_t ret_val; /* Evaluate entered command */ @@ -337,7 +344,7 @@ get_msg_handler (const jerry_value_t func_value, /**< function object */ } /* get_msg_handler */ int -main (int argc, char * argv[]) +main (int argc, char *argv[]) { /* Initialize engine */ jerry_init (JERRY_INIT_EMPTY); @@ -439,7 +446,7 @@ add_handler (const jerry_value_t func_value, /**< function object */ } /* add_handler */ int -main (int argc, char * argv[]) +main (int argc, char *argv[]) { /* Initialize engine */ jerry_init (JERRY_INIT_EMPTY); @@ -505,4 +512,4 @@ Value of x is 17 ## Further steps -For further API description, please visit [API Reference page](https://samsung.github.io/jerryscript/API/) on [JerryScript home page](https://samsung.github.io/jerryscript/). +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/). diff --git a/docs/04.INTERNALS.md b/docs/04.INTERNALS.md index 3389b86fc..7f5b9e70f 100644 --- a/docs/04.INTERNALS.md +++ b/docs/04.INTERNALS.md @@ -13,7 +13,7 @@ The lexer splits input string (ECMAScript program) into sequence of tokens. It i ## Scanner -Scanner (`./jerry-core/parser/js/js-parser-scanner.h`) pre-scans the input string to find certain tokens. For example, scanner determines whether the keyword `for` defines a general for or a for-in loop. Reading tokens in a while loop is not enough because a slash (`/`) can indicate the start of a regular expression or can be a division operator. +Scanner (`./jerry-core/parser/js/js-parser-scanner.c`) pre-scans the input string to find certain tokens. For example, scanner determines whether the keyword `for` defines a general for or a for-in loop. Reading tokens in a while loop is not enough because a slash (`/`) can indicate the start of a regular expression or can be a division operator. ## Expression Parser @@ -21,9 +21,9 @@ Expression parser is responsible for parsing JavaScript expressions. It is imple ## Statement Parser -JavaScript statements are parsed by this component. It uses the [Expression parser](#expression parser) to parse the constituent expressions. The implementation of Statement parser is located in `./jerry-core/parser/js/js-parser-statm.c`. +JavaScript statements are parsed by this component. It uses the [Expression parser](#expression-parser) to parse the constituent expressions. The implementation of Statement parser is located in `./jerry-core/parser/js/js-parser-statm.c`. -Function `parser_parse_source` carries out the parsing and compiling of the input EcmaScript source code. When a function appears in the source `parser_parse_source` calls `parser_parse_function` which is responsible for processing the source code of functions recursively including argument parsing and context handling. After the parsing, function `parser_post_processing` dumps the created opcodes and returns an ecma_compiled_code_t* that points to the compiled bytecode sequence. +Function `parser_parse_source` carries out the parsing and compiling of the input EcmaScript source code. When a function appears in the source `parser_parse_source` calls `parser_parse_function` which is responsible for processing the source code of functions recursively including argument parsing and context handling. After the parsing, function `parser_post_processing` dumps the created opcodes and returns an `ecma_compiled_code_t*` that points to the compiled bytecode sequence. The interactions between the major components shown on the following figure. @@ -61,9 +61,9 @@ There are three types of bytecode arguments in CBC: * __byte argument__: A value between 0 and 255, which often represents the argument count of call like opcodes (function call, new, eval, etc.). - * __literal argument__: An integer index which is greater or equal than zero and less than the `literal_end` field of the header. For further information see next section Literals (next). + * __literal argument__: An integer index which is greater or equal than zero and less than the `literal_end` field of the header. For further information see next section Literals (next). - * __relative branch__: An 1-3 byte long offset. The branch argument might also represent the end of an instruction range. For example the branch argument of `CBC_EXT_WITH_CREATE_CONTEXT` shows the end of a with statement. More precisely the position after the last instruction. + * __relative branch__: An 1-3 byte long offset. The branch argument might also represent the end of an instruction range. For example the branch argument of `CBC_EXT_WITH_CREATE_CONTEXT` shows the end of a `with` statement. More precisely the position after the last instruction. Argument combinations are limited to the following seven forms: @@ -92,30 +92,30 @@ There are two other sub-groups of identifiers. *Registers* are those identifiers There are two types of literal encoding in CBC. Both are variable length, where the length is one or two byte long. * __small__: maximum 511 literals can be encoded. - + One byte encoding for literals 0 - 254. - + ```c byte[0] = literal_index ``` Two byte encoding for literals 255 - 510. - + ```c byte[0] = 0xff byte[1] = literal_index - 0xff ``` * __full__: maximum 32767 literal can be encoded. - + One byte encoding for literals 0 - 127. - + ```c byte[0] = literal_index ``` Two byte encoding for literals 128 - 32767. - + ```c byte[0] = (literal_index >> 8) | 0x80 byte[1] = (literal_index & 0xff) @@ -135,66 +135,70 @@ Byte-codes can be placed into four main categories. Byte-codes of this category serve for placing objects onto the stack. As there are many instructions representing multiple atomic tasks in CBC, there are also many instructions for pushing objects onto the stack according to the number and the type of the arguments. The following table list a few of these opcodes with a brief description. -
+ -| byte-code | description | -| CBC_PUSH_LITERAL | Pushes the value of the given literal argument. | -| CBC_PUSH_TWO_LITERALS | Pushes the value of the given two literal arguments. | -| CBC_PUSH_UNDEFINED | Pushes an undefined value. | -| CBC_PUSH_TRUE | Pushes a logical true. | -| CBC_PUSH_PROP_LITERAL | Pushes a property whose base object is popped from the stack, and the property name is passed as a literal argument. | +| byte-code | description | +| --------------------- | ---------------------------------------------------- | +| CBC_PUSH_LITERAL | Pushes the value of the given literal argument. | +| CBC_PUSH_TWO_LITERALS | Pushes the value of the given two literal arguments. | +| CBC_PUSH_UNDEFINED | Pushes an undefined value. | +| CBC_PUSH_TRUE | Pushes a logical true. | +| CBC_PUSH_PROP_LITERAL | Pushes a property whose base object is popped from the stack, and the property name is passed as a literal argument. | -
+ ### Call Byte-codes The byte-codes of this category perform calls in different ways. -
+ -| byte-code | description | -| CBC_CALL0 | Calls a function without arguments. The return value won't be pushed onto the stack. | -| CBC_CALL1 | Calls a function with one argument. The return value won't be pushed onto the stack. | -| CBC_CALL | Calls a function with n arguments. n is passed as a byte argument. The return value won't be pushed onto the stack. | -| CBC_CALL0_PUSH_RESULT | Calls a function without arguments. The return value will be pushed onto the stack. | -| CBC_CALL1_PUSH_RESULT | Calls a function with one argument. The return value will be pushed onto the stack. | -| CBC_CALL2_PROP | Calls a property function with two arguments. The base object, the property name, and the two arguments are on the stack. | +| byte-code | description | +| --------------------- | ------------------------------------------------------------------------------------ | +| CBC_CALL0 | Calls a function without arguments. The return value won't be pushed onto the stack. | +| CBC_CALL1 | Calls a function with one argument. The return value won't be pushed onto the stack. | +| CBC_CALL | Calls a function with n arguments. n is passed as a byte argument. The return value won't be pushed onto the stack. | +| CBC_CALL0_PUSH_RESULT | Calls a function without arguments. The return value will be pushed onto the stack. | +| CBC_CALL1_PUSH_RESULT | Calls a function with one argument. The return value will be pushed onto the stack. | +| CBC_CALL2_PROP | Calls a property function with two arguments. The base object, the property name, and the two arguments are on the stack. | -
+ ### Arithmetic, Logical, Bitwise and Assignment Byte-codes -The opcodes of this category perform arithmetic, logical, bitwise and assignment operations according to the different +The opcodes of this category perform arithmetic, logical, bitwise and assignment operations. -
+ -| byte-code | description | -| CBC_LOGICAL_NOT | Negates the logical value that popped from the stack. The result is pushed onto the stack. | -| CBC_LOGICAL_NOT_LITERAL | Negates the logical value that given in literal argument. The result is pushed onto the stack. | -| CBC_ADD | Adds two values that are poped from the stack. The result is pushed onto the stack. | -| CBC_ADD_RIGHT_LITERAL | Adds two values. The left one popped from the stack, the right one is given as literal argument. | -| CBC_ADD_TWO_LITERALS | Adds two values. Both are given as literal arguments. | -| CBC_ASSIGN | Assigns a value to a property. It has three arguments: base object, property name, value to assign. | -| CBC_ASSIGN_PUSH_RESULT | Assigns a value to a property. It has three arguments: base object, property name, value to assign. The result will be pushed onto the stack. | +| byte-code | description | +| ----------------------- | --------------------------------------------------------------------------------------------------- | +| CBC_LOGICAL_NOT | Negates the logical value that popped from the stack. The result is pushed onto the stack. | +| CBC_LOGICAL_NOT_LITERAL | Negates the logical value that given in literal argument. The result is pushed onto the stack. | +| CBC_ADD | Adds two values that are popped from the stack. The result is pushed onto the stack. | +| CBC_ADD_RIGHT_LITERAL | Adds two values. The left one popped from the stack, the right one is given as literal argument. | +| CBC_ADD_TWO_LITERALS | Adds two values. Both are given as literal arguments. | +| CBC_ASSIGN | Assigns a value to a property. It has three arguments: base object, property name, value to assign. | +| CBC_ASSIGN_PUSH_RESULT | Assigns a value to a property. It has three arguments: base object, property name, value to assign. The result will be pushed onto the stack. | -
+ ### Branch Byte-codes Branch byte-codes are used to perform conditional and unconditional jumps in the byte-code. The arguments of these instructions are 1-3 byte long relative offsets. The number of bytes is part of the opcode, so each byte-code with a branch argument has three forms. The direction (forward, backward) is also defined by the opcode since the offset is an unsigned value. Thus, certain branch instructions has six forms. Some examples can be found in the following table. -
+ -| byte-code | description | -| CBC_JUMP_FORWARD | Jumps forward by the 1 byte long relative offset argument. | -| CBC_JUMP_FORWARD_2 | Jumps forward by the 2 byte long relative offset argument. | -| CBC_JUMP_FORWARD_3 | Jumps forward by the 3 byte long relative offset argument. | -| CBC_JUMP_BACKWARD | Jumps backward by the 1 byte long relative offset argument. | -| CBC_JUMP_BACKWARD_2 | Jumps backward by the 2 byte long relative offset argument. | -| CBC_JUMP_BACKWARD_3 | Jumps backward by the 3 byte long relative offset argument. | -| CBC_BRANCH_IF_TRUE_FORWARD | Jumps if the value on the top of the stack is true by the 1 byte long relative offset argument. | +| byte-code | description | +| -------------------------- | ----------------------------------------------------------- | +| CBC_JUMP_FORWARD | Jumps forward by the 1 byte long relative offset argument. | +| CBC_JUMP_FORWARD_2 | Jumps forward by the 2 byte long relative offset argument. | +| CBC_JUMP_FORWARD_3 | Jumps forward by the 3 byte long relative offset argument. | +| CBC_JUMP_BACKWARD | Jumps backward by the 1 byte long relative offset argument. | +| CBC_JUMP_BACKWARD_2 | Jumps backward by the 2 byte long relative offset argument. | +| CBC_JUMP_BACKWARD_3 | Jumps backward by the 3 byte long relative offset argument. | +| CBC_BRANCH_IF_TRUE_FORWARD | Jumps if the value on the top of the stack is true by the 1 byte long relative offset argument. | -
+ ## Snapshot @@ -239,7 +243,7 @@ Compressed pointers were introduced to save heap space. ![Compressed Pointer](img/ecma_compressed.png) -These pointers are 8 byte alligned 16 bit long pointers which can address 512 Kb of memory which is also the maximum size of the JerryScript heap. +These pointers are 8 byte aligned 16 bit long pointers which can address 512 Kb of memory which is also the maximum size of the JerryScript heap. ECMA data elements are allocated in pools (pools are allocated on heap) Chunk size of the pool is 8 bytes (reduces fragmentation). @@ -262,7 +266,7 @@ Strings in JerryScript are not just character sequences, but can hold numbers an An object can be a conventional data object or a lexical environment object. Unlike other data types, object can have references (called properties) to other data types. Because of circular references, reference counting is not always enough to determine dead objects. Hence a chain list is formed from all existing objects, which can be used to find unreferenced objects during garbage collection. The `gc-next` pointer of each object shows the next allocated object in the chain list. -Lexical environments (link) 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. +[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](img/ecma_object.png) @@ -282,13 +286,13 @@ A property is 7 bit long and its type field is 2 bit long which consumes 9 bit w #### Property Hashmap -If the number of property pairs reach a limit (currently this limit is defined to 16), a hash map (called [Property Hashmap](#Property Hashmap)) is inserted at the first position of the property pair list, in order to find a property using it, instead of finding it by iterating linearly over the property pairs. +If the number of property pairs reach a limit (currently this limit is defined to 16), a hash map (called [Property Hashmap](#property-hashmap)) is inserted at the first position of the property pair list, in order to find a property using it, instead of finding it by iterating linearly over the property pairs. Property hashmap contains 2n elements, where 2n is larger than the number of properties of the object. Each element can have tree types of value: * null, indicating an empty element * deleted, indicating a deleted property, or -* reference to the existing property +* reference to the existing property This hashmap is a must-return type cache, meaning that every property that the object have, can be found using it. @@ -308,7 +312,7 @@ LCache is a hashmap for finding a property specified by an object and by a prope ![LCache](img/ecma_lcache.png) -When a property access occurs, a hash value is extracted form the demanded property name and than this hash is used to index the LCache. After that, in the indexed row the specified object and property name will be searched. +When a property access occurs, a hash value is extracted from the demanded property name and than this hash is used to index the LCache. After that, in the indexed row the specified object and property name will be searched. It is important to note, that if the specified property is not found in the LCache, it does not mean that it does not exist (i.e. LCache is a may-return cache). If the property is not found, it will be searched in the property-list of the object, and if it is found there, the property will be placed into the LCache. diff --git a/jerry-core/jerry-api.h b/jerry-core/jerry-api.h index db417e621..378dfd36b 100644 --- a/jerry-core/jerry-api.h +++ b/jerry-core/jerry-api.h @@ -139,7 +139,7 @@ typedef struct /** * Type of an external function handler */ -typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj_p, +typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj, const jerry_value_t this_val, const jerry_value_t args_p[], const jerry_length_t args_count); @@ -152,7 +152,7 @@ typedef void (*jerry_object_free_callback_t) (const uintptr_t native_p); /** * Function type applied for each data property of an object */ -typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name_p, +typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name, const jerry_value_t property_value, void *user_data_p); @@ -231,7 +231,7 @@ jerry_value_t jerry_value_to_string (const jerry_value_t); jerry_value_t jerry_acquire_value (jerry_value_t); /** - * Relase the referenced values + * Release the referenced values */ void jerry_release_value (jerry_value_t); diff --git a/jerry-core/jerry.c b/jerry-core/jerry.c index c81db52c3..f0efd03bd 100644 --- a/jerry-core/jerry.c +++ b/jerry-core/jerry.c @@ -196,14 +196,14 @@ jerry_cleanup (void) * Register external magic string array */ void -jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items, /**< character arrays, representing - * external magic strings' contents */ +jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p, /**< character arrays, representing + * external magic strings' contents */ uint32_t count, /**< number of the strings */ - const jerry_length_t *str_lengths) /**< lengths of all strings */ + const jerry_length_t *str_lengths_p) /**< lengths of all strings */ { jerry_assert_api_available (); - lit_magic_strings_ex_set ((const lit_utf8_byte_t **) ex_str_items, count, (const lit_utf8_size_t *) str_lengths); + lit_magic_strings_ex_set ((const lit_utf8_byte_t **) ex_str_items_p, count, (const lit_utf8_size_t *) str_lengths_p); } /* jerry_register_magic_strings */ /** @@ -236,7 +236,7 @@ jerry_gc (void) * false - otherwise */ bool -jerry_run_simple (const jerry_char_t *script_source, /**< script source */ +jerry_run_simple (const jerry_char_t *script_source_p, /**< script source */ size_t script_source_size, /**< script source size */ jerry_init_flag_t flags) /**< combination of Jerry flags */ { @@ -244,7 +244,7 @@ jerry_run_simple (const jerry_char_t *script_source, /**< script source */ jerry_init (flags); - jerry_value_t parse_ret_val = jerry_parse (script_source, script_source_size, false); + jerry_value_t parse_ret_val = jerry_parse (script_source_p, script_source_size, false); if (!ECMA_IS_VALUE_ERROR (parse_ret_val)) { @@ -1695,7 +1695,7 @@ jerry_get_object_native_handle (const jerry_value_t obj_val, /**< object to get */ void jerry_set_object_native_handle (const jerry_value_t obj_val, /**< object to set handle in */ - uintptr_t handle, /**< handle value */ + uintptr_t handle_p, /**< handle value */ jerry_object_free_callback_t freecb_p) /**< object free callback or NULL */ { jerry_assert_api_available (); @@ -1704,7 +1704,7 @@ jerry_set_object_native_handle (const jerry_value_t obj_val, /**< object to set ecma_create_external_pointer_property (object_p, ECMA_INTERNAL_PROPERTY_NATIVE_HANDLE, - handle); + handle_p); if (freecb_p != NULL) { @@ -2051,7 +2051,7 @@ jerry_snapshot_set_offsets (uint8_t *buffer_p, /**< buffer */ * * @return size of snapshot, 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_ENABLE_SNAPSHOT), + * and snapshot support is enabled in current configuration through JERRY_ENABLE_SNAPSHOT_SAVE), * 0 - otherwise. */ size_t diff --git a/tools/update-webpage.sh b/tools/update-webpage.sh index 874547775..391dc6230 100755 --- a/tools/update-webpage.sh +++ b/tools/update-webpage.sh @@ -78,6 +78,13 @@ for docfile in $docs_dir/*.md; do sed -i -r -e 's/^!\[.*\]\(/&{{ site.baseurl }}\//' $gh_pages_dir/$docfile_base sed -i -r -e 's/^!\[.*\]\(\{\{ site\.baseurl \}\}\/img.*$/&{: class="thumbnail center-block img-responsive" }/' $gh_pages_dir/$docfile_base + # replace span tags to div + sed -i 's//<\/div>/g' $gh_pages_dir/$docfile_base + + # remove table header separators + sed -i '/^| ---/d' $gh_pages_dir/$docfile_base + # update images cp -Ru $docs_dir/img $gh_pages_dir done