From 772d72c073b552366ef782bdd59b8388fe75f6ad Mon Sep 17 00:00:00 2001 From: Evgeny Gavrin Date: Fri, 26 Jun 2015 20:05:36 +0300 Subject: [PATCH] Fix style --- 02.how-to.md | 11 +- 03.api.md | 293 +++++++++++++++++++++++------------------------ 04.internals.md | 46 ++++---- 05.dev-guide.md | 21 ++-- css/block.css | 6 +- css/bytecode.css | 6 +- 6 files changed, 189 insertions(+), 194 deletions(-) diff --git a/02.how-to.md b/02.how-to.md index f582f6286..9e311634a 100644 --- a/02.how-to.md +++ b/02.how-to.md @@ -4,10 +4,9 @@ title: How To permalink: /how-to/ --- -* toc -{:toc} - # How to Get the Sources +This step should be simple: + {% highlight bash %} git clone https://github.com/Samsung/jerryscript.git cd jerryscript @@ -15,7 +14,7 @@ cd jerryscript # How to Setup Recommended Prerequisites -Currently, we are using Ubuntu Linux 14.04+ as our development environment, so this tutorial was written based on this assumption. Additionaly, it'd be useful to read [Prerequisites]({{ site.baseurl }}/wiki/Prerequisites) wiki page, also. +Currently, we are using Ubuntu Linux 14.04+ as our development environment, so this tutorial was written based on this assumption. Additionaly, it'll be useful to read [Prerequisites]({{ site.baseurl }}/wiki/Prerequisites) wiki page, also. There are dependencies, that should be installed manually. The following list is required for building: @@ -39,7 +38,7 @@ sudo apt-get install libpcre3 libpcre3-dev sudo apt-get install tcl8.6 tcl8.6-dev tk8.6-dev libboost-all-dev {% endhighlight %} -To make our scripts run correctly, several shell utilities should be available the system: +To make our scripts run correctly, several shell utilities should be available on the system: - `find` - `bc` @@ -68,7 +67,7 @@ It may take time, so go grab some coffee: Setting up prerequisites... (log file: ./build/prerequisites/prerequisites.log) {% endhighlight %} -# How to Build Debug Version +## How to Build Debug Version To build debug version for Linux: {% highlight bash %} diff --git a/03.api.md b/03.api.md index 5a16f48fd..c5d278e01 100644 --- a/03.api.md +++ b/03.api.md @@ -23,15 +23,7 @@ jerry_run_simple (const char * script_source, - `script_source` - source code; - `script_source_size` - size of source code buffer, in bytes; -- returned value - completion code that indicates whether run performed successfully (`JERRY_COMPLETION_CODE_OK`), or an unhandled JavaScript exception occurred (`JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION`). - - -**See also** - -- [jerry_init](#jerryinit) -- [jerry_cleanup](#jerrycleanup) -- [jerry_parse](#jerryparse) -- [jerry_run](#jerryrun) +- returned value - completion code that indicates whether run was performed successfully (`JERRY_COMPLETION_CODE_OK`), or an unhandled JavaScript exception occurred (`JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION`). **Example** @@ -43,6 +35,13 @@ jerry_run_simple (const char * script_source, } {% endhighlight %} +**See also** + +- [jerry_init](#jerryinit) +- [jerry_cleanup](#jerrycleanup) +- [jerry_parse](#jerryparse) +- [jerry_run](#jerryrun) + # jerry_init **Summary** @@ -63,10 +62,6 @@ jerry_init (jerry_flag_t flags); - `JERRY_FLAG_SHOW_OPCODES` - print compiled byte-code; - `JERRY_FLAG_EMPTY` - no flags, just initialize in default configuration. -**See also** - -- [jerry_cleanup](#jerrycleanup) - **Example** {% highlight cpp %} @@ -79,6 +74,10 @@ jerry_init (jerry_flag_t flags); } {% endhighlight %} +**See also** + +- [jerry_cleanup](#jerrycleanup) + # jerry_cleanup **Summary** @@ -115,10 +114,6 @@ jerry_parse (const char* source_p, size_t source_size); - `source_p` - string, containing source code to parse; - `source_size` - size of the string, in bytes. -**See also** - -- [jerry_run](#jerryrun) - **Example** {% highlight cpp %} @@ -134,6 +129,10 @@ jerry_parse (const char* source_p, size_t source_size); } {% endhighlight %} +**See also** + +- [jerry_run](#jerryrun) + # jerry_run **Summary** @@ -150,10 +149,6 @@ jerry_run (void); - returned value - completion code that indicates whether run performed successfully (`JERRY_COMPLETION_CODE_OK`), or an unhandled JavaScript exception occurred (`JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION`). -**See also** - -- [jerry_parse](#jerryparse) - **Example** {% highlight cpp %} @@ -169,10 +164,14 @@ jerry_run (void); } {% endhighlight %} +**See also** + +- [jerry_parse](#jerryparse) + # jerry_api_value_t **Summary** -The data type represents any JavaScript value that can be sent to / received from the engine. +The data type represents any JavaScript value that can be sent to or received from the engine. Type of value is identified by `jerry_api_value_t::type`, and can be one of the following: @@ -238,12 +237,6 @@ jerry_api_eval (const char * source_p, - `retval_p` - value, returned by `eval` (output parameter); - returned value - completion code that indicates whether run performed successfully (`JERRY_COMPLETION_CODE_OK`), or an unhandled JavaScript exception occurred (`JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION`). -**See also** - -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_external_function](#jerryapicreateexternalfunction) -- [jerry_external_handler_t](#jerryexternalhandlert) - **Example** {% highlight cpp %} @@ -257,6 +250,12 @@ jerry_api_eval (const char * source_p, } {% endhighlight %} +**See also** + +- [jerry_api_value_t](#jerryapivaluet) +- [jerry_api_create_external_function](#jerryapicreateexternalfunction) +- [jerry_external_handler_t](#jerryexternalhandlert) + # jerry_api_create_string **Summary** @@ -274,12 +273,6 @@ jerry_api_create_string (const char * v); - `v` - value of string to create; - returned value is pointer to created string. -**See also** - -- [jerry_api_acquire_string](#jerryapiacquirestring) -- [jerry_api_release_string](#jerryapireleasestring) -- [jerry_api_string_to_char_buffer](#jerryapistringtocharbuffer) - **Example** {% highlight cpp %} @@ -292,6 +285,12 @@ jerry_api_create_string (const char * v); } {% endhighlight %} +**See also** + +- [jerry_api_acquire_string](#jerryapiacquirestring) +- [jerry_api_release_string](#jerryapireleasestring) +- [jerry_api_string_to_char_buffer](#jerryapistringtocharbuffer) + # jerry_api_string_to_char_buffer **Summary** @@ -310,13 +309,8 @@ jerry_api_string_to_char_buffer (const jerry_api_string_t * string_p, - `buffer_p` - pointer to output buffer (can be NULL, is `buffer_size` is 0); - `buffer_size` - size of the buffer; - returned value: - - number of bytes, actually copied to the buffer - if characters were copied successfully; - - otherwise (in case size of buffer is insuficcient) - negative number, which is calculated as negation of buffer size, that is required to hold characters. - -**See also** - -- [jerry_api_create_string](#jerryapicreatestring) -- [jerry_api_value_t](#jerryapivaluet) + - number of bytes, actually copied to the buffer - if characters were copied successfully; + - otherwise (in case size of buffer is insuficcient) - negative number, which is calculated as negation of buffer size, that is required to hold characters. **Example** @@ -356,6 +350,11 @@ jerry_api_string_to_char_buffer (const jerry_api_string_t * string_p, } {% endhighlight %} +**See also** + +- [jerry_api_create_string](#jerryapicreatestring) +- [jerry_api_value_t](#jerryapivaluet) + # jerry_api_acquire_string **Summary** @@ -373,11 +372,6 @@ jerry_api_acquire_string (jerry_api_string_t * string_p); - `string_p` - pointer to the string; - returned value - new pointer to the string. -**See also** - -- [jerry_api_release_string](#jerryapireleasestring) -- [jerry_api_create_string](#jerryapicreatestring) - **Example** {% highlight cpp %} @@ -395,6 +389,11 @@ jerry_api_acquire_string (jerry_api_string_t * string_p); } {% endhighlight %} +**See also** + +- [jerry_api_release_string](#jerryapireleasestring) +- [jerry_api_create_string](#jerryapicreatestring) + # jerry_api_release_string **Summary** @@ -409,11 +408,6 @@ jerry_api_release_string (jerry_api_string_t * string_p); - `string_p` - pointer to the string. -**See also** - -- [jerry_api_acquire_string](#jerryapiacquirestring) -- [jerry_api_create_string](#jerryapicreatestring) - **Example** {% highlight cpp %} @@ -431,6 +425,11 @@ jerry_api_release_string (jerry_api_string_t * string_p); } {% endhighlight %} +**See also** + +- [jerry_api_acquire_string](#jerryapiacquirestring) +- [jerry_api_create_string](#jerryapicreatestring) + # jerry_api_create_object **Summary** @@ -446,19 +445,7 @@ jerry_api_create_object (const char * v); {% endhighlight %} - `v` - value of object to create; -- returned value is pointer to created object. - - -**See also** - -- [jerry_api_acquire_object](#jerryapiacquireobject) -- [jerry_api_release_object](#jerryapireleaseobject) -- [jerry_api_add_object_field](#jerryapiaddobjectfield) -- [jerry_api_delete_object_field](#jerryapideleteobjectfield) -- [jerry_api_get_object_field_value](#jerryapigetobjectfieldvalue) -- [jerry_api_set_object_field_value](#jerryapisetobjectfieldvalue) -- [jerry_api_get_object_native_handle](#jerryapigetobjectnativehandle) -- [jerry_api_set_object_native_handle](#jerryapisetobjectnativehandle) +- returned value is pointer to the created object. **Example** @@ -472,6 +459,17 @@ jerry_api_create_object (const char * v); } {% endhighlight %} +**See also** + +- [jerry_api_acquire_object](#jerryapiacquireobject) +- [jerry_api_release_object](#jerryapireleaseobject) +- [jerry_api_add_object_field](#jerryapiaddobjectfield) +- [jerry_api_delete_object_field](#jerryapideleteobjectfield) +- [jerry_api_get_object_field_value](#jerryapigetobjectfieldvalue) +- [jerry_api_set_object_field_value](#jerryapisetobjectfieldvalue) +- [jerry_api_get_object_native_handle](#jerryapigetobjectnativehandle) +- [jerry_api_set_object_native_handle](#jerryapisetobjectnativehandle) + # jerry_api_acquire_object **Summary** @@ -489,11 +487,6 @@ jerry_api_acquire_object (jerry_api_object_t * object_p); - `object_p` - pointer to the object; - returned value - new pointer to the object. -**See also** - -- [jerry_api_release_object](#jerryapireleaseobject) -- [jerry_api_create_object](#jerryapicreateobject) - **Example** {% highlight cpp %} @@ -511,6 +504,11 @@ jerry_api_acquire_object (jerry_api_object_t * object_p); } {% endhighlight %} +**See also** + +- [jerry_api_release_object](#jerryapireleaseobject) +- [jerry_api_create_object](#jerryapicreateobject) + # jerry_api_release_object **Summary** @@ -525,11 +523,6 @@ jerry_api_release_object (jerry_api_object_t * object_p); - `object_p` - pointer to the object. -**See also** - -- [jerry_api_acquire_object](#jerryapiacquireobject) -- [jerry_api_create_object](#jerryapicreateobject) - **Example** {% highlight cpp %} @@ -547,6 +540,11 @@ jerry_api_release_object (jerry_api_object_t * object_p); } {% endhighlight %} +**See also** + +- [jerry_api_acquire_object](#jerryapiacquireobject) +- [jerry_api_create_object](#jerryapicreateobject) + # jerry_api_get_global **Summary** @@ -563,14 +561,6 @@ jerry_api_get_global (void); Received pointer should be released with [jerry_api_release_object](#jerryapireleaseobject), just when the value becomes unnecessary. -**See also** - -- [jerry_api_release_object](#jerryapireleaseobject) -- [jerry_api_add_object_field](#jerryapiaddobjectfield) -- [jerry_api_delete_object_field](#jerryapideleteobjectfield) -- [jerry_api_get_object_field_value](#jerryapigetobjectfieldvalue) -- [jerry_api_set_object_field_value](#jerryapisetobjectfieldvalue) - **Example** {% highlight cpp %} @@ -590,6 +580,14 @@ Received pointer should be released with [jerry_api_release_object](#jerryapirel } {% endhighlight %} +**See also** + +- [jerry_api_release_object](#jerryapireleaseobject) +- [jerry_api_add_object_field](#jerryapiaddobjectfield) +- [jerry_api_delete_object_field](#jerryapideleteobjectfield) +- [jerry_api_get_object_field_value](#jerryapigetobjectfieldvalue) +- [jerry_api_set_object_field_value](#jerryapisetobjectfieldvalue) + # jerry_api_add_object_field **Summary** @@ -610,13 +608,8 @@ jerry_api_add_object_field (jerry_api_object_t * object_p, - `field_value_p` - value of the field; - `is_writable` - flag indicating whether the created field should be writable. - returned value - true, if field was created successfully, i.e. upon the call: - - there is no field with same name in the object; - - the object is extensible. - -**See also** - -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_object](#jerryapicreateobject) + - there is no field with same name in the object; + - the object is extensible. **Example** @@ -633,6 +626,12 @@ jerry_api_add_object_field (jerry_api_object_t * object_p, } {% endhighlight %} + +**See also** + +- [jerry_api_value_t](#jerryapivaluet) +- [jerry_api_create_object](#jerryapicreateobject) + # jerry_api_delete_object_field **Summary** @@ -649,12 +648,7 @@ jerry_api_delete_object_field (jerry_api_object_t * object_p, - `object_p` - object to delete field at; - `field_name_p` - name of the field. - returned value - true, if field was deleted successfully, i.e. upon the call: - - there is field with specified name in the object. - -**See also** - -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_object](#jerryapicreateobject) + - there is field with specified name in the object. **Example** @@ -667,6 +661,11 @@ jerry_api_delete_object_field (jerry_api_object_t * object_p, } {% endhighlight %} +**See also** + +- [jerry_api_value_t](#jerryapivaluet) +- [jerry_api_create_object](#jerryapicreateobject) + # jerry_api_get_object_field_value **Summary** @@ -685,15 +684,10 @@ jerry_api_get_object_field_value (jerry_api_object_t * object_p, - `field_name_p` - name of the field; - `field_value_p` - retrieved field value (output parameter). - returned value - true, if field value was retrieved successfully, i.e. upon the call: - - there is field with specified name in the object. + - there is field with specified name in the object. If value was retrieved successfully, it should be freed with [jerry_api_release_object](#jerryapireleaseobject) just when it becomes unnecessary. -**See also** - -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_object](#jerryapicreateobject) - **Example** {% highlight cpp %} @@ -712,6 +706,11 @@ If value was retrieved successfully, it should be freed with [jerry_api_release_ } {% endhighlight %} +**See also** + +- [jerry_api_value_t](#jerryapivaluet) +- [jerry_api_create_object](#jerryapicreateobject) + # jerry_api_set_object_field_value **Summary** @@ -730,12 +729,7 @@ jerry_api_set_object_field_value (jerry_api_object_t * object_p, - `field_name_p` - name of the field; - `field_value_p` - field value to set. - returned value - true, if field value was set successfully, i.e. upon the call: - - field value is writable. - -**See also** - -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_object](#jerryapicreateobject) + - field value is writable. **Example** @@ -750,6 +744,11 @@ jerry_api_set_object_field_value (jerry_api_object_t * object_p, } {% endhighlight %} +**See also** + +- [jerry_api_value_t](#jerryapivaluet) +- [jerry_api_create_object](#jerryapicreateobject) + # jerry_api_get_object_native_handle **Summary** @@ -768,11 +767,6 @@ jerry_api_get_object_native_handle (jerry_api_object_t * object_p, - `out_handle_p` - handle value (output parameter); - returned value - true, if there is handle associated with the object. -**See also** - -- [jerry_api_create_object](#jerryapicreateobject) -- [jerry_api_set_object_native_handle](#jerryapisetobjectnativehandle) - **Example** {% highlight cpp %} @@ -792,6 +786,11 @@ jerry_api_get_object_native_handle (jerry_api_object_t * object_p, } {% endhighlight %} +**See also** + +- [jerry_api_create_object](#jerryapicreateobject) +- [jerry_api_set_object_native_handle](#jerryapisetobjectnativehandle) + # jerry_api_set_object_native_handle **Summary** @@ -813,11 +812,6 @@ jerry_api_set_object_native_handle (jerry_api_object_t * object_p, - `handle` - handle value; - `freecb_p` - pointer to "free" callback or NULL (if not NULL the callback would be called upon GC of the object). -**See also** - -- [jerry_api_create_object](#jerryapicreateobject) -- [jerry_api_get_object_native_handle](#jerryapigetobjectnativehandle) - **Example** {% highlight cpp %} @@ -837,6 +831,11 @@ jerry_api_set_object_native_handle (jerry_api_object_t * object_p, } {% endhighlight %} +**See also** + +- [jerry_api_create_object](#jerryapicreateobject) +- [jerry_api_get_object_native_handle](#jerryapigetobjectnativehandle) + # jerry_api_is_function **Summary** @@ -852,12 +851,6 @@ jerry_api_is_function (const jerry_api_object_t* object_p); - `object_p` - object to check; - returned value - just boolean, indicating whether the specified object can be called as function. -**See also** - -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_is_constructor](#jerryapiisconstructor) -- [jerry_api_call_function](#jerryapicallfunction) - **Example** {% highlight cpp %} @@ -874,6 +867,12 @@ jerry_api_is_function (const jerry_api_object_t* object_p); } {% endhighlight %} +**See also** + +- [jerry_api_value_t](#jerryapivaluet) +- [jerry_api_is_constructor](#jerryapiisconstructor) +- [jerry_api_call_function](#jerryapicallfunction) + # jerry_api_is_constructor **Summary** @@ -889,12 +888,6 @@ jerry_api_is_constructor (const jerry_api_object_t* object_p); - `object_p` - object to check; - returned value - just boolean, indicating whether the specified object can be called as constructor. -**See also** - -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_is_function](#jerryapiisfunction) -- [jerry_api_construct_object](#jerryapiconstructobject) - **Example** {% highlight cpp %} @@ -911,6 +904,12 @@ jerry_api_is_constructor (const jerry_api_object_t* object_p); } {% endhighlight %} +**See also** + +- [jerry_api_value_t](#jerryapivaluet) +- [jerry_api_is_function](#jerryapiisfunction) +- [jerry_api_construct_object](#jerryapiconstructobject) + # jerry_api_call_function **Summary** @@ -937,12 +936,6 @@ jerry_api_call_function (jerry_api_object_t * function_object_p, If call was performed successfully, returned value should be freed with [jerry_api_release_object](#jerryapireleaseobject) just when it becomes unnecessary. -**See also** - -- [jerry_api_is_function](#jerryapiisfunction) -- [jerry_api_value_t](#jerryapivaluet) -- [jerry_api_create_external_function](#jerryapicreateexternalfunction) - **Example** {% highlight cpp %} @@ -970,6 +963,12 @@ jerry_api_call_function (jerry_api_object_t * function_object_p, } {% endhighlight %} +**See also** + +- [jerry_api_is_function](#jerryapiisfunction) +- [jerry_api_value_t](#jerryapivaluet) +- [jerry_api_create_external_function](#jerryapicreateexternalfunction) + # jerry_api_construct_object **Summary** @@ -994,11 +993,6 @@ jerry_api_construct_object (jerry_api_object_t * function_object_p, If call was performed successfully, returned value should be freed with [jerry_api_release_object](#jerryapireleaseobject) just when it becomes unnecessary. -**See also** - - - [jerry_api_is_constructor](#jerryapiisconstructor) - - [jerry_api_value_t](#jerryapivaluet) - **Example** {% highlight cpp %} @@ -1025,6 +1019,11 @@ If call was performed successfully, returned value should be freed with [jerry_a } {% endhighlight %} +**See also** + + - [jerry_api_is_constructor](#jerryapiisconstructor) + - [jerry_api_value_t](#jerryapivaluet) + # jerry_external_handler_t **Summary** @@ -1062,13 +1061,6 @@ jerry_api_create_external_function (jerry_external_handler_t handler_p); Received pointer should be released with [jerry_api_release_object](#jerryapireleaseobject), just when the value becomes unnecessary. -**See also** - -- [jerry_external_handler_t](#jerryexternalhandlert) -- [jerry_api_is_function](#jerryapiisfunction) -- [jerry_api_call_function](#jerryapicallfunction) -- [jerry_api_release_object](#jerryapireleaseobject) - **Example** {% highlight cpp %} @@ -1100,3 +1092,10 @@ handler (const jerry_api_object_t * function_obj_p, jerry_api_release_object (obj_p); } {% endhighlight %} + +**See also** + +- [jerry_external_handler_t](#jerryexternalhandlert) +- [jerry_api_is_function](#jerryapiisfunction) +- [jerry_api_call_function](#jerryapicallfunction) +- [jerry_api_release_object](#jerryapireleaseobject) diff --git a/04.internals.md b/04.internals.md index 5e597827e..f1c08443d 100644 --- a/04.internals.md +++ b/04.internals.md @@ -10,11 +10,11 @@ permalink: /internals/ # High-Level Design ![High-Level Design]({{ site.baseurl }}/img/engines_high_level_design.jpg){: class="thumbnail center-block img-responsive" } -On the diagram above is shown interaction of major components of software system: Parser and Runtime. Parser performs translation of input ECMAScript application into byte-code with specified format (refer to [Bytecode](/internals/#byte-code) and [Parser](/internals/#parser) page for details). Prepared bytecode is executed by Runtime engine that performs interpretation (refer to [Virtual Machine](/internals/#virtual-machine) and [ECMA](/internals/#ECMA) pages for details). +On the diagram above is shown interaction of major components of software system: Parser and Runtime. Parser performs translation of input ECMAScript application into the byte-code with the specified format (refer to [Bytecode](/internals/#byte-code) and [Parser](/internals/#parser) page for details). Prepared bytecode is executed by Runtime engine that performs interpretation (refer to [Virtual Machine](/internals/#virtual-machine) and [ECMA](/internals/#ECMA) pages for details). # Parser -The parser is implemented as recursive descent parser. The parser does not build any type of Abstract Syntax Tree. It converts source JavaScript code directly into byte-code. +The parser is implemented as recursive descent parser. The parser does not build any type of Abstract Syntax Tree. It converts the source JavaScript code directly into the byte-code. The parser consists of three major parts: - lexer @@ -25,7 +25,7 @@ The parser consists of three major parts: These four (except the parser itself) components are initialized during `parser_init` call (jerry-core/parser/js/parser.cpp). -This initializer requires two following subsystems to be initialized: memory allocator and serializer. The need for allocator is clear. The serializer resets internal bytecode_data structure(jerry-core/parser/js/bytecode-data.h). Currently bytecode_data is singleton. During parsing it is filled by data which is needed for further execution: +This initializer requires two following subsystems to be initialized: memory allocator and serializer. The need for allocator is clear. The serializer resets internal bytecode_data structure(jerry-core/parser/js/bytecode-data.h). Currently bytecode_data is singleton. During parsing it is filled by the data which is needed for the further execution: * Byte-code - array of opcodes (`bytecode_data.opcodes`). * Literals - array of literals (`bytecode_data.literals`). @@ -46,20 +46,20 @@ After initialization `parser_parse_program` (`./jerry-core/js/parser.cpp`) shoul 1. Initialize a scope. 2. Do pre-parser stage. -3. Parse scope code. +3. Parse the scope code. -After every scope is processed, parser merges all scopes into single byte-code array. +After every scope is processed, parser merges all scopes into the single byte-code array. Two new entities were introduced - scopes and pre-parser. -* There are two types of scopes in the parser: global scope and function declaration scope. Notice that function expressions do not create a new scope in terms of the parser. A reason why is described below. Parsing process starts on global scope. If a function declaration occurs string the process, new scope is created, this new scope is pushed to a stack of current scopes; then steps 1-3 of parsing are performed. Note, that only global scope parsing shall merge all scopes into a byte-code. All scopes are stored in a tree to represent a hierarchy of them. +* There are two types of scopes in the parser: global scope and function declaration scope. Notice that function expressions do not create a new scope in terms of the parser. The reason why is described below. Parsing process starts on global scope. If a function declaration occurs string the process, new scope is created, this new scope is pushed to a stack of current scopes; then steps 1-3 of parsing are performed. Note, that only global scope parsing shall merge all scopes into a byte-code. All scopes are stored in a tree to represent a hierarchy of them. * Pre-parser. This step performs hoisting of variable declarations. First, it dumps `reg_var_decl` opcodes. Then it goes through the script and looks for variable declaration lists. For every found variable in the scope (not in a sub-scope or function expression) it dumps var_decl opcode. After this step byte-code in the scope starts with optional `'use strict'` marker, then `reg_var_decl` and several (optional) `var_decls`. -Due to some limitations of the parser, some parsing functions take `this_arg` and/or `prop` as parameters. They are further used to dump `prop_setter` opcode. During parsing all necessary data is stored in either stacks or scope trees. After parsing of whole program, the parser merges all scopes into a single byte-code, hoisting function declarations in process. This task, so-called post-parser, is performed by `scopes_tree_raw_data` (jerry-core/js/scopes-tree.c) function. For further information about post-parser, check opcodes dumper section. +Due to some limitations of the parser, some parsing functions take `this_arg` and/or `prop` as parameters. They are further used to dump `prop_setter` opcode. During parsing all necessary data is stored in either stacks or scope trees. After parsing of the whole program, the parser merges all scopes into a single byte-code, hoisting function declarations in process. This task, so-called post-parser, is performed by `scopes_tree_raw_data` (jerry-core/js/scopes-tree.c) function. For the further information about post-parser, check opcodes dumper section. ### Lexer -The lexer splits input string on set of tokens. The token structure (`./jerry-core/parser/js/lexer.h`) consists of three elements: token type, location of the token and optional data: +The lexer splits input string into the set of tokens. The token structure (`./jerry-core/parser/js/lexer.h`) consists of three elements: token type, location of the token and optional data: {% highlight cpp %} typedef struct @@ -71,7 +71,7 @@ typedef struct token; {% endhighlight %} -Location of token (`locus`). It is just an index of first token's character at a string that represents the program. Token types are are listed in lexer.h header file (`token_type` enum). Depending on token type, token specific data (`uid` field) has the different meaning. +Location of token (`locus`). It is just an index of the first token's character at a string that represents the program. Token types are listed in lexer.h header file (`token_type` enum). Depending on token type, token specific data (`uid` field) has the different meaning.
@@ -84,11 +84,11 @@ Other (punctuators) | Not used.
-Token matching algorithm is straightforward - look at the first character of new token, recognize the type, and then just match the rest. Comments and space characters (except new line) are ignored, so they produce no token. The algorithm uses two pointers: buffer and token_start. The first one points to the next character of the input, the other one points to the first character of token, being matched, so-called current token. +Token matching algorithm is straightforward - look at the first character of the new token, recognize the type, and then just match the rest. Comments and space characters (except new line) are ignored, so they produce no token. The algorithm uses two pointers: buffer and token_start. The first one points to the next character of the input, the other one points to the first character of token, being matched, so-called current token. The lexer remembers two tokens during scan: current and previously seen. It also allows buffering one token to be rescanned (`lexer_save_token`) and setting scan position to any location in the file (`lexer_seek`). -The parser uses lexer two scan file two times - during pre-parsing and parsing stages. +The parser uses lexer to scan file two times - during pre-parsing and parsing stages. Currently the lexer does not support any encoding except ASCII. Also the lexer does not support regular expressions. @@ -110,7 +110,7 @@ The post-parser merges scopes into a single byte-code. For each scope it first d ### Serializer -Serializer dumps literals collected by the lexer to bytecode_data, is used by the dumper to dump or rewrite op_metas to a current scope. There is no much to say about this component. +Serializer dumps literals collected by the lexer to bytecode_data, is used by the dumper to dump or rewrite op_metas to a current scope. ### Syntax Errors Checker @@ -212,7 +212,7 @@ where ## Function call/Constructor call -Function/constructor call are utilized to perform calls to functions and constructors. Destination operand is encoded in `dst` field. Operand `name_idx` specifies the name of the function to call. Arguments are encoded the same way as in native call instruction. +Function/constructor call are utilized to perform calls to functions and constructors. Destination operand is encoded in `dst` field. Operand `name_idx` specifies the name of the function to call. Arguments are encoded the same way as in the native call instruction.
@@ -227,7 +227,7 @@ where ## Function declaration -Function declarations are represented by special kind of instructions. Function name and number of arguments are located in `name_idx` and `arg_list` fields respectively. +Function declarations are represented by the special kind of instructions. Function name and number of arguments are located in `name_idx` and `arg_list` fields respectively.
@@ -237,7 +237,7 @@ Function declarations are represented by special kind of instructions. Function where `name_idx` - literal idx -`arg_list` - namber of arguments +`arg_list` - number of arguments ## Function expression @@ -292,7 +292,7 @@ Meta instructions are usually utilized as continuations of other instructions. D ## Delete -JavaScript delete operator is modeled with delete instruction in the bytecode. There are two types of delete instruction, applied either to element of lexical environment or to object's property. +JavaScript delete operator is represented with delete instruction in the bytecode. There are two types of delete instruction, applied either to element of lexical environment or to object's property.
@@ -388,7 +388,7 @@ where ## Object declaration -Obect declaration instruction represents object literal in JavaScript specification. It consists of `op_obj_decl` instruction, followed by a list of `prop_data`, `prop_getter` and `prop_setter` meta instructions. A series of instructions which evaluate property values can precede meta instructions. Number of meta instructions, e.g. number of properties, is specified in the `prop_num` field. +Obect declaration instruction represents object literal in JavaScript specification. It consists of `op_obj_decl` instruction, followed by the list of `prop_data`, `prop_getter` and `prop_setter` meta instructions. A series of instructions which evaluate property values can precede meta instructions. Number of meta instructions, e.g. number of properties, is specified in the `prop_num` field.
@@ -446,7 +446,7 @@ Instruction can have up to three operands which are represented by `idx` values. - type of meta and corresponding arguments in `op_meta` - idx pair may represent opcode position -During execution every function of the source code has associated +During the execution every function of the source code has associated interpreter context, which consists of the following items: - current position (byte-code instruction to execute) @@ -467,7 +467,7 @@ Main routines of the virtual machine are: # ECMA -ECMA component of the engine is responsible for following notions: +ECMA component of the engine is responsible for the following notions: - Data representation - Runtime representation - GC @@ -559,11 +559,11 @@ Header occupies 8 bytes and consists of: - compressed pointer to the next chunk - number of elements -- rest space, aligned down to byte, is for first chunk of data in collection +- rest space, aligned down to byte, is for the first chunk of data in collection Chunk's layout is following: -- compressed pointer to next chunk +- compressed pointer to the next chunk - rest space, aligned down to byte, is for data stored in corresponding part of the collection ### Internal properties: @@ -576,7 +576,7 @@ Chunk's layout is following: - [[Code]] - where to find bytecode of the function - native code - where to find code of native unction - native handle - some uintptr_t assosiated with the objec -- [[FormalParameters]] - collection of pointers to ecma_string_t (the listof formal parameters of the function) +- [[FormalParameters]] - collection of pointers to ecma_string_t (the list of formal parameters of the function) - [[PrimitiveValue]] for String - for String object - [[PrimitiveValue]] for Number - for Number object - [[PrimitiveValue]] for Boolean - for Boolean object @@ -597,7 +597,7 @@ Entry of LCache has the following layout: - property name (pointer to string) - property pointer -Caches's row is defined by string's hash. When a property access occurs, all row's entries are searched by comparing object pointer and property name to according entry's fields, full comparison is used for property name. +Caches's row is defined by string's hash. When a property access occurs, all row's entries are searched by comparing object pointer and property name according entry's fields, full comparison is used for property name. If corresponding entry was found, its property pointer is returned (may be NULL - in case when there is no property with specified name in given object). Otherwise, object's property set is iterated fully and corresponding record is registered in LCache (with property pointer if it was found or NULL otherwise). diff --git a/05.dev-guide.md b/05.dev-guide.md index 592674889..bf8844d95 100644 --- a/05.dev-guide.md +++ b/05.dev-guide.md @@ -4,10 +4,7 @@ title: Development permalink: /dev-guide/ --- -The JerryScript Engine can be embedded into any application, providing way to run JavaScript in large range of environments - from desktops to low-memory microcontrollers. - -* toc -{:toc} +JerryScript Engine can be embedded into any application, providing the way to run JavaScript in a large range of environments - from desktops to low-memory microcontrollers. This guide is intended to introduce you to JerryScript embedding API through creation of simple JavaScript shell. @@ -149,13 +146,13 @@ main (int argc, char * argv[]) { } {% endhighlight %} -The sample would also output 'Hello, World!'. However, now it is not just part of source script, but value, dynamically supplied to the engine. +The sample will also output 'Hello, World!'. However, now it is not just a part of the source script, but the value, dynamically supplied to the engine. ## Step 5. Description of JavaScript value descriptors -Structure, used to put values to / receive values from engine is the following: +Structure, used to put values to or receive values from the engine is the following: -- `type` of value: +- `type` of the value: - JERRY_API_DATA_TYPE_UNDEFINED (undefined); - JERRY_API_DATA_TYPE_NULL (null); - JERRY_API_DATA_TYPE_BOOLEAN (true / false); @@ -167,11 +164,11 @@ Structure, used to put values to / receive values from engine is the following: - `v_string` (if JERRY_API_DATA_TYPE_STRING) - pointer to string; - `v_object` (if JERRY_API_DATA_TYPE_OBJECT) - pointer to object. -Abstract values, to be sent to / received from engine are described with the structure. +Abstract values, to be sent to or received from the engine are described with the structure. -Pointers to strings / objects and values should be released just when become unnecessary, using `jerry_api_release_string` / `jerry_api_release_object` and `jerry_api_release_value`, correspondingly. +Pointers to strings or objects and values should be released just when become unnecessary, using `jerry_api_release_string` or `jerry_api_release_object` and `jerry_api_release_value`, correspondingly. -The following example function would output a JavaScript value: +The following example function will output a JavaScript value: {% highlight cpp %} static void @@ -231,9 +228,9 @@ print_value (const jerry_api_value_t * value_p) ## Simple JavaScript shell -Now all build blocks, necessary to construct JavaScript shell, are ready. +Now all building blocks, necessary to construct JavaScript shell, are ready. -Shell operation can be described with following loop: +Shell operation can be described with the following loop: - read command; - if command is 'quit' diff --git a/css/block.css b/css/block.css index 768f0b4f7..56f69e690 100644 --- a/css/block.css +++ b/css/block.css @@ -1,7 +1,7 @@ .CSSTableGeneratorBlock { margin-left:35%;magin-right:35%;padding:0px; width:30%; - border:3px solid #0000ff; + border:3px solid #2388db; -moz-border-radius-bottomleft:0px; -webkit-border-bottom-left-radius:0px; @@ -53,7 +53,7 @@ background-color:#ffffff; - border:1px solid #0000ff; + border:1px solid #2388db; border-width:0px 3px 3px 0px; text-align:left; padding:6px; @@ -71,7 +71,7 @@ .CSSTableGeneratorBlock tr:first-child td{ background-color:#ffffff; - border:0px solid #0000ff; + border:0px solid #2388db; text-align:left; border-width:0px 0px 3px 3px; font-size:14px; diff --git a/css/bytecode.css b/css/bytecode.css index eeefcfac1..ff36c99a2 100644 --- a/css/bytecode.css +++ b/css/bytecode.css @@ -44,7 +44,7 @@ -webkit-border-bottom-left-radius:5px; border-bottom-left-radius:5px; }.CSSTableGeneratorByte tr:hover td{ - background-color:#f97777; + background-color:#b2b2b2; } @@ -70,7 +70,7 @@ } .CSSTableGeneratorByte tr:first-child td{ - background-color:#f97777; + background-color:#b2b2b2; border:0px solid #ffffff; text-align:center; border-width:0px 0px 1px 1px; @@ -82,7 +82,7 @@ .CSSTableGeneratorByte tr:first-child:hover td{ - background-color:#f97777; + background-color:#b2b2b2; } .CSSTableGeneratorByte tr:first-child td:first-child{ border-width:0px 0px 1px 0px;