Update the webpage (#2835)

JerryScript-DCO-1.0-Signed-off-by: László Langó llango.u-szeged@partner.samsung.com

01.GETTING-STARTED.md

@@ -49,6 +49,12 @@ python tools/build.py --debug
 python tools/build.py --debug --lto=off
 ```
 
+**To enable more verbose outputs for debugging**
+
+```bash
+tools/build.py --debug --logging=on --error-messages=on --line-info=on
+```
+
 **Add custom arguments to CMake**
 
 ```bash

03.API-EXAMPLE.md

@@ -161,7 +161,7 @@ main (void)
   jerry_value_t prop_value = jerry_create_string (str);
 
   /* Setting the string value as a property of the Global object */
-  jerry_set_property (global_object, prop_name, prop_value);
+  jerry_release_value (jerry_set_property (global_object, prop_name, prop_value));
 
   /* Releasing string values, as it is no longer necessary outside of engine */
   jerry_release_value (prop_name);
@@ -396,7 +396,7 @@ main (void)
 
   /* Set the native function as a property of the empty JS object */
   jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "myFunc");
-  jerry_set_property (object, prop_name, func_obj);
+  jerry_release_value (jerry_set_property (object, prop_name, func_obj));
   jerry_release_value (prop_name);
   jerry_release_value (func_obj);
 
@@ -405,7 +405,7 @@ main (void)
 
   /* Add the JS object to the global context */
   prop_name = jerry_create_string ((const jerry_char_t *) "MyObject");
-  jerry_set_property (global_object, prop_name, object);
+  jerry_release_value (jerry_set_property (global_object, prop_name, object));
   jerry_release_value (prop_name);
   jerry_release_value (object);
   jerry_release_value (global_object);
@@ -472,7 +472,7 @@ add_handler (const jerry_value_t func_value, /**< function object */
     jerry_value_t res_val = jerry_create_number (x + d);
 
     /* Set the new value of 'this.x' */
-    jerry_set_property (this_val, prop_name, res_val);
+    jerry_release_value (jerry_set_property (this_val, prop_name, res_val));
     jerry_release_value (res_val);
   }
 
@@ -516,7 +516,7 @@ main (void)
 
   /* Set the native function as a property of previously created MyObject */
   jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "add2x");
-  jerry_set_property (my_js_obj_val, prop_name, add_func_obj);
+  jerry_release_value (jerry_set_property (my_js_obj_val, prop_name, add_func_obj));
   jerry_release_value (add_func_obj);
   jerry_release_value (prop_name);
 

05.PORT-API.md

@@ -82,6 +82,44 @@ typedef enum
 void jerry_port_log (jerry_log_level_t level, const char *fmt, ...);
 ```
 
+The `jerry_port_print_char` is currenlty not used by the jerry-core directly.
+However, it provides a port specifc way for `jerry-ext` components to print
+information.
+
+```c
+/**
+ * Print a character to stdout.
+ */
+void jerry_port_print_char (char c);
+```
+
+### ES2015 Module system helper functions
+
+The import statement requires two specific functions for opening and closing files (the modules) port specific.
+
+```c
+/**
+ * Opens file with the given path and reads its source.
+ * @return the source of the file
+ */
+uint8_t *
+jerry_port_read_source (const char *file_name_p, /**< file name */
+                        size_t *out_size_p) /**< [out] read bytes */
+{
+  // open file from given path
+  // return its source
+} /* jerry_port_read_source */
+
+/**
+ * Release the previously opened file's content.
+ */
+void
+jerry_port_release_source (uint8_t *buffer_p) /**< buffer to free */
+{
+  free (buffer_p);
+} /* jerry_port_release_source */
+```
+
 ## Date
 
 ```c
@@ -211,6 +249,17 @@ jerry_port_log (jerry_log_level_t level, /**< log level */
 } /* jerry_port_log */
 ```
 
+```c
+/**
+ * Print a character to stdout with putchar.
+ */
+void
+jerry_port_print_char (char c)
+{
+  putchar (c);
+} /* jerr_port_print_char */
+```
+
 ## Date
 
 ```c

07.DEBUGGER.md

@@ -78,8 +78,11 @@ When using the extension-provided WebSocket transport layer, the
 debugger can be enabled by calling `jerryx_debugger_after_connect
 (jerryx_debugger_tcp_create (debug_port) && jerryx_debugger_ws_create ())`
 after the `jerry_init ()` function. It initializes the debugger and
-blocks until a client connects. (Custom transport layers may be
-implemented and initialized similarly.)
+blocks until a client connects.
+(Custom transport layers may be implemented and initialized similarly.
+Currently, `jerryx_debugger_rp_create ()` for raw packet transport layer and
+`jerryx_debugger_serial_create (const char* config)` for serial protocol
+are also available.)
 
 The resource name provided to `jerry_parse ()` is used by the client
 to identify the resource name of the source code. This resource name

10.EXT-REFERENCE-HANDLER.md

@@ -107,14 +107,14 @@ jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,
 
 Provide a `print` implementation for scripts. The routine converts all of its
 arguments to strings and outputs them char-by-char using
-`jerryx_port_handler_print_char`. The NUL character is output as "\u0000",
+`jerry_port_print_char`. The NUL character is output as "\u0000",
 other characters are output bytewise.
 
 *Note*: This implementation does not use standard C `printf` to print its
 output. This allows more flexibility but also extends the core JerryScript
 engine port API. Applications that want to use `jerryx_handler_print` must
 ensure that their port implementation also provides
-`jerryx_port_handler_print_char`.
+`jerry_port_print_char`.
 
 **Prototype**
 
@@ -134,7 +134,7 @@ jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this
 **See also**
 
 - [jerryx_handler_register_global](#jerryx_handler_register_global)
-- [jerryx_port_handler_print_char](#jerryx_port_handler_print_char)
+- [jerry_port_print_char](05.PORT-API.md#jerry_port_print_char)
 
 
 # Handler registration helper
@@ -194,38 +194,3 @@ register_common_functions (void)
   jerry_release_value (ret);
 }
 ```
-
-
-# Port API extension
-
-## jerryx_port_handler_print_char
-
-**Summary**
-
-Print a single character.
-
-**Prototype**
-
-```c
-void
-jerryx_port_handler_print_char (char c);
-```
-
-- `c` - the character to print.
-
-**Example**
-
-```c
-/**
- * Print a character to stdout with printf.
- */
-void
-jerryx_port_handler_print_char (char c)
-{
-  printf ("%c", c);
-} /* jerryx_port_handler_print_char */
-```
-
-**See also**
-
-- [jerryx_handler_print](#jerryx_handler_print)

14.EXT-REFERENCE-HANDLE-SCOPE.md

@@ -0,0 +1,122 @@
+---
+layout: page
+title: 'Extension API: Handle Scope'
+category: documents
+permalink: /ext-reference-handle-scope/
+---
+
+* toc
+{:toc}
+
+# Handle Scope
+
+## jerryx_handle_scope
+
+**Summary**
+It is often necessary to make the lifespan of handles shorter than the lifespan of a native method. Even though the native code could only use the most recent handle, all of the associated objects would also be kept alive since they all share the same scope.
+
+To handle this case, JerryScript HandleScope extension provides the ability to establish a new 'scope' to which newly created handles will be associated. Once those handles are no longer required, the scope can be 'closed' and any handles associated with the scope are invalidated. The methods available to open/close scopes are `jerryx_open_handle_scope` and `jerryx_close_handle_scope`.
+
+JerryScript only supports a single nested hierarchy of scopes. There is only one active scope at any time, and all new handles will be associated with that scope while it is active. Scopes must be closed in the reverse order from which they are opened. In addition, all scopes created within a native method must be closed before returning from that method.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+#include "jerryscript-ext/handle-scope.h"
+
+static jerry_value_t
+create_object (void)
+{
+  jerry_value_t obj = jerry_create_object ();
+  return obj;
+} /* create_object */
+
+static void
+test_handle_scope_val (void)
+{
+  jerryx_handle_scope scope;
+  jerryx_open_handle_scope (&scope);
+  jerry_value_t obj = jerryx_create_handle (create_object ());
+
+  jerryx_close_handle_scope (scope);
+  // now obj has been released
+} /* test_handle_scope_val */
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  test_handle_scope_val ();
+  jerry_gc (JERRY_GC_SEVERITY_LOW);
+
+  jerry_cleanup ();
+} /* main */
+```
+
+## jerryx_escapable_handle_scope
+
+**Summary**
+
+It is necessary in common cases that a handle has to be promote to outer scope and prevent from been garbage collected. To handle this case, a escapable handle scope has been proposed from which one object can be promoted to the outer scope. The method available to escape an object from been release at current scope is `jerryx_escape_handle`.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+#include "jerryscript-ext/handle-scope.h"
+
+static jerry_value_t
+create_object (void)
+{
+  jerryx_escapable_handle_scope scope;
+  jerryx_open_escapable_handle_scope (&scope);
+  jerry_value_t obj = jerryx_create_handle (jerry_create_object ());
+
+  jerry_value_t escaped_obj;
+  jerryx_escape_handle(scope, obj, &escaped_obj);
+  jerryx_close_handle_scope (scope);
+  // escaped_obj has now been escaped to outer scope, thus not released at this point
+
+  return escaped_obj;
+} /* create_object */
+
+static void
+test_handle_scope_val (void)
+{
+  jerryx_handle_scope scope;
+  jerryx_open_handle_scope (&scope);
+  jerry_value_t obj = create_object ();
+
+  jerryx_close_handle_scope (scope);
+  // now obj has been released
+} /* test_handle_scope_val */
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  test_handle_scope_val ();
+  jerry_gc (JERRY_GC_SEVERITY_LOW);
+
+  jerry_cleanup ();
+} /* main */
+```
+
+**See also**
+
+- [jerry_value_t](../api-reference#jerry_value_t)
+- [jerry_acquire_value](../api-reference#jerry_acquire_value)
+- [jerry_release_value](../api-reference#jerry_release_value)
+
+## Pre-allocated list of handle scopes and handles
+
+To prevent trapping into system calls frequently, a pre-allocated dedicated list mechanism has been introduced to the implementation of JerryX handle scope.
+
+To change the size of pre-allocation list, use build definition `JERRYX_HANDLE_PRELIST_SIZE` and `JERRYX_SCOPE_PRELIST_SIZE` to alter the default value of 20.

15.MODULE-SYSTEM.md

@@ -0,0 +1,142 @@
+---
+layout: page
+title: 'Module System (EcmaScript2015)'
+category: documents
+permalink: /module-system/
+---
+
+* toc
+{:toc}
+
+# ES6 module support for JerryScript
+
+The module system allows users to write import and export statements in scripts. Therefore the logic of the application could be separated in custom modules.
+The standard's relevant part can be found [here](https://www.ecma-international.org/ecma-262/6.0/#sec-modules).
+
+## General
+
+If the main script contains import statements, then Jerry opens and runs the appropriate scripts before the main script (as the standard says). The script's and the module's extension is `.js`, custom extensions are unnecessary.
+
+main.js
+
+```js
+import { secret_number } from "./module.js"
+
+print (secret_number);
+```
+
+module.js
+
+```js
+var secret_number = 42;
+
+export secret_number;
+```
+
+## Supported features
+
+* import variable or function
+  * add alias name to the imported variable (function)
+* export variable or function
+  * add alias name to the exported variable (function)
+
+### Example
+
+```js
+import {
+  engine,
+  version as v
+} from "./module.js"
+
+import { getFeatureDetails } from "./module_2.js"
+
+var version = "v3.1415";
+
+print("> main.js");
+
+print(">> Engine: " + engine);
+print(">> Version: " + v);
+
+print (">> " + getFeatureDetails());
+print (">> Script version: " + version);
+```
+
+```js
+// module.js
+var _engine = "JerryScript";
+export _engine as engine;
+
+export var version = "1.0 (e92ae0fb)";
+```
+
+```js
+// module_2.js
+var featureName = "EcmaScript 2015 modules";
+var year = 2018;
+
+export function getFeatureDetails() {
+  return "Feature name: " + featureName + " | developed in " + year;
+}
+```
+
+## Unsupported features
+
+* **snapshot**
+* errors from the imported scripts
+* redirection ( `export { a, b } from 'module.js'` )
+* default import and export
+  * `import b from 'module.js'`
+  * `export default b`,
+* whole module import statements
+  * `import * from 'module.js`
+  * `import { * as module } from 'module.js`
+* object freezing ( `Object.freeze (this)` )
+
+### Redirection
+
+An export statement can import variables from a custom module and export it directly from the current script. This statement is called redirection. In this case the `export { b } from 'module2.js'` works as the `b` was imported before then exported as a local variable.
+
+```js
+import { a, b } from 'module.js'
+
+print (a + b);
+```
+
+```js
+// module.js
+export var a = 2;
+export { b } from 'module2.js'
+```
+
+```js
+// module2.js
+export var b = 40;
+```
+
+### Default imports and exports
+
+TODO: This part is going to be written in the next part of the patch.
+
+### Import the whole module
+
+The whole module can be imported. In this case the `m` object would contain the exported parts of the module. If the import is not aliased, the `global object` would contain the exports.
+
+```js
+import { * as m } from "./module.js"
+
+print (m.secret_number);
+print (m.getPrettifiedNumber());
+print (m.api.version);
+```
+
+```js
+// module.js
+var secret_number = 42;
+export secret_number;
+
+export function getPrettifiedNumber() {
+  return "*** " + secret_number + " ***";
+}
+
+export { ble as api } from "./ble.js";
+```