Update the webpage (#2499)

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

01.GETTING-STARTED.md

@@ -63,20 +63,20 @@ python tools/build.py --profile=es5.1|es2015-subset|minimal
 
 See also the related [README.md](https://github.com/jerryscript-project/jerryscript/blob/master/jerry-core/profiles/README.md).
 
-**Use (jerry, compiler-default, external) libc**
+**Use (compiler-default, external) libc**
 
-The default libc is jerry-libc, but you can use compiler-default libc or an external libc:
+The default libc is the compiler-default libc but you can use an external libc as well:
 
 - compiler-default libc:
 
 ```bash
-python tools/build.py --jerry-libc=off
+python tools/build.py
 ```
 
 - external libc:
 
 ```bash
-python tools/build.py --jerry-libc=off --compile-flag="-nostdlib -I/path/to/ext-libc/include" --link-lib="ext-c"
+python tools/build.py --compile-flag="-nostdlib -I/path/to/ext-libc/include" --link-lib="ext-c"
 ```
 
 **Add toolchain file**
@@ -96,7 +96,7 @@ python tools/build.py --toolchain=cmake/toolchain_linux_armv7l.cmake
 **Use system memory allocator**
 
 ```bash
-python tools/build.py --system-allocator=on --jerry-libc=off
+python tools/build.py --system-allocator=on
 ```
 
 *Note*: System allocator is only supported on 32 bit systems.

02.API-REFERENCE.md

@@ -23,16 +23,17 @@ Enum that contains the following elements:
 
 ## jerry_type_t
 
-Enum that contains a set of elements to represent JavaScript type:
+Enum that contains JerryScript API value types:
 
  - JERRY_TYPE_NONE - no type information
- - JERRY_TYPE_UNDEFINED - undefined value
+ - JERRY_TYPE_UNDEFINED - undefined type
- - JERRY_TYPE_NULL - null value
+ - JERRY_TYPE_NULL - null type
- - JERRY_TYPE_BOOLEAN - boolean value
+ - JERRY_TYPE_BOOLEAN - boolean type
- - JERRY_TYPE_NUMBER - number value
+ - JERRY_TYPE_NUMBER - number type
- - JERRY_TYPE_STRING - string value
+ - JERRY_TYPE_STRING - string type
- - JERRY_TYPE_OBJECT - object value
+ - JERRY_TYPE_OBJECT - object type
- - JERRY_TYPE_FUNCTION - function value
+ - JERRY_TYPE_FUNCTION - function type
+ - JERRY_TYPE_ERROR - error/abort type
 
 ## jerry_error_t
 
@@ -69,6 +70,7 @@ Possible compile time enabled feature types:
  - JERRY_FEATURE_DATE - Date support
  - JERRY_FEATURE_REGEXP - RegExp support
  - JERRY_FEATURE_LINE_INFO - line info available
+ - JERRY_FEATURE_LOGGING - logging
 
 ## jerry_parse_opts_t
 
@@ -78,6 +80,18 @@ Option bits for [jerry_parse](#jerry_parse) and
  - JERRY_PARSE_NO_OPTS - no options passed
  - JERRY_PARSE_STRICT_MODE - enable strict mode
 
+## jerry_gc_mode_t
+
+Set garbage collection operational mode
+
+ - JERRY_GC_SEVERITY_LOW - free unused objects
+ - JERRY_GC_SEVERITY_HIGH - free as much memory as possible
+
+The difference between `JERRY_GC_SEVERITY_LOW` and `JERRY_GC_SEVERITY_HIGH`
+is that the former keeps memory allocated for performance improvements such
+as property hash tables for large objects. The latter frees all possible
+memory blocks but the performance may drop after the garbage collection.
+
 ## jerry_generate_snapshot_opts_t
 
 Flags for [jerry_generate_snapshot](#jerry_generate_snapshot) and
@@ -139,18 +153,6 @@ 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**
@@ -246,6 +248,34 @@ typedef struct
 } jerry_context_data_manager_t;
 ```
 
+## jerry_instance_alloc_t
+
+**Summary**
+
+Function type for allocating buffer for JerryScript instance.
+
+**Prototype**
+
+```c
+typedef void *(*jerry_instance_alloc_t) (size_t size, void *cb_data_p);
+```
+
+- `size` - allocation size
+- `cb_data_p` - pointer to user data
+
+
+## jerry_instance_t
+
+**Summary**
+
+An opaque declaration of the JerryScript instance structure which is the header of the context space.
+
+**Prototype**
+
+```c
+typedef struct jerry_instance_t jerry_instance_t;
+```
+
 ## jerry_property_descriptor_t
 
 **Summary**
@@ -330,20 +360,6 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_
                                                    const jerry_length_t args_count);
 ```
 
-## jerry_object_free_callback_t
-
-**Summary**
-
-**Deprecated: Please use jerry_object_native_free_callback_t instead.**
-
-Native free callback of an object.
-
-**Prototype**
-
-```c
-typedef void (*jerry_object_free_callback_t) (const uintptr_t native_p);
-```
-
 ## jerry_object_native_free_callback_t
 
 **Summary**
@@ -360,7 +376,7 @@ typedef void (*jerry_object_native_free_callback_t) (void *native_p);
 
 **Summary**
 
-The type infomation of the native pointer.
+The type information of the native pointer.
 It includes the free callback that will be called when associated JavaScript object is garbage collected. It can be left NULL in case it is not needed.
 
 Typically, one would create a `static const jerry_object_native_info_t` for
@@ -628,7 +644,7 @@ Registers an external magic string array.
 
 ```c
 void
-jerry_register_magic_strings  (const jerry_char_ptr_t *ex_str_items_p,
+jerry_register_magic_strings  (const jerry_char_t **ex_str_items_p,
                                uint32_t count,
                                const jerry_length_t *str_lengths_p);
 ```
@@ -651,12 +667,12 @@ main (void)
 
   // 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[] = {
+  static const jerry_char_t *magic_string_items[] = {
-                                                         (const jerry_char_ptr_t) "magicstring1",
+                                                      (const jerry_char_t *) "magicstring1",
-                                                         (const jerry_char_ptr_t) "magicstring2",
+                                                      (const jerry_char_t *) "magicstring2",
-                                                         (const jerry_char_ptr_t) "magicstring3"
+                                                      (const jerry_char_t *) "magicstring3"
-                                                       };
+                                                    };
-  uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t));
+  uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_t *));
 
   // must be static, because 'jerry_register_magic_strings' does not copy
   static const jerry_length_t magic_string_lengths[] = {
@@ -715,13 +731,30 @@ Performs garbage collection.
 
 ```c
 void
-jerry_gc (void);
+jerry_gc (jerry_gc_mode_t mode);
 ```
 
+- `mode` - operational mode, see [jerry_gc_mode_t](#jerry_gc_mode_t)
+
 **Example**
 
+[doctest]: # ()
+
 ```c
-jerry_gc ();
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t object_value = jerry_create_object ();
+  jerry_release_value (object_value);
+
+  jerry_gc (JERRY_GC_SEVERITY_LOW);
+
+  jerry_cleanup ();
+}
 ```
 
 **See also**
@@ -950,12 +983,12 @@ Perform JavaScript `eval`.
 jerry_value_t
 jerry_eval (const jerry_char_t *source_p,
             size_t source_size,
-            bool is_strict);
+            uint32_t parse_opts);
 ```
 
 - `source_p` - source code to evaluate, it must be a valid utf8 string.
 - `source_size` - length of the source code
-- `is_strict` - perform `eval` as it is called from "strict mode" code.
+- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags.
 - return value - result of eval, may be error value.
 
 **Example**
@@ -964,7 +997,7 @@ jerry_eval (const jerry_char_t *source_p,
 {
   jerry_value_t ret_val = jerry_eval (str_to_eval,
                                       strlen (str_to_eval),
-                                      false);
+                                      JERRY_PARSE_NO_OPTS);
 }
 ```
 
@@ -1611,7 +1644,7 @@ jerry_value_is_undefined (const jerry_value_t value)
 Returns the JavaScript type
 for a given value as a [jerry_type_t](#jerry_type_t) enum value.
 
-This is a similar operation as the 'typeof' operator
+This is a similar operation to the 'typeof' operator
 in the standard with an exception that the 'null'
 value has its own enum value.
 
@@ -1677,6 +1710,125 @@ jerry_is_feature_enabled (const jerry_feature_t feature);
 
 # Error manipulation functions
 
+## jerry_create_abort_from_value
+
+**Summary**
+
+Create (api) abort from a value.
+
+This function creates an API abort value from an API value. The second argument defines
+whether the input value must be released or not. If it is set to `true`,
+then a [`jerry_release_value`](#jerry_release_value) function will be called
+for the first argument, so the api value won't be available after the call of
+`jerry_create_abort_from_value`. The second argument should be false if both value
+and created abort value are needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_abort_from_value (jerry_value_t value, bool release);
+```
+
+- `value` - api value
+- `release` - raw boolean, defines whether input value must be released
+- return value - abort (api) value
+
+**Example 1**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t abort = jerry_create_abort_from_value (value, true);
+  // using the 'value' variable after release is invalid.
+
+  jerry_release_value (abort);
+}
+```
+
+**Example 2**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t abort = jerry_create_abort_from_value (value, false);
+  // both 'abort' and 'value' can be used and must be released when they are no longer needed
+
+  jerry_release_value (abort);
+  jerry_release_value (value);
+}
+```
+
+**See also**
+
+- [jerry_value_t](#jerry_value_t)
+- [jerry_get_value_from_error](#jerry_get_value_from_error)
+- [jerry_create_error_from_value](#jerry_create_error_from_value)
+
+## jerry_create_error_from_value
+
+**Summary**
+
+Create (api) error from a value.
+
+This function creates an API error value from an API value. The second argument defines
+whether the input value must be released or not. If it is set to `true`,
+then a [`jerry_release_value`](#jerry_release_value) function will be called
+for the first argument, so the api value won't be available after the call of
+`jerry_create_error_from_value`. The second argument should be false if both value
+and created error value are needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_error_from_value (jerry_value_t value, bool release);
+```
+
+- `value` - api value
+- `release` - raw boolean, defines whether input value must be released
+- return value - error (api) value
+
+**Example 1**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t error = jerry_create_error_from_value (value, true);
+  // using the 'value' variable after release is invalid.
+
+
+  jerry_release_value (error);
+}
+```
+
+**Example 2**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t error = jerry_create_error_from_value (value, false);
+  // both 'error' and 'value' can be used and must be released when they are no longer needed
+
+  jerry_release_value (error);
+  jerry_release_value (value);
+}
+```
+
+**See also**
+
+- [jerry_value_t](#jerry_value_t)
+- [jerry_get_value_from_error](#jerry_get_value_from_error)
+- [jerry_create_abort_from_value](#jerry_create_abort_from_value
+
 ## jerry_get_error_type
 
 **Summary**
@@ -1732,7 +1884,7 @@ whether the input error value must be released or not. If it is set to `true`,
 then a [`jerry_release_value`](#jerry_release_value) function will be called
 for the first argument, so the error value won't be available after the call of
 `jerry_get_value_from_error`. The second argument should be false if both error
-and its represented value are needed. The first argument is returned unchanged if it is not an error.
+and its represented value are needed.
 
 *Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
 is no longer needed.
@@ -1752,14 +1904,14 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
 
 ```c
 {
-  jerry_value_t error;
+  jerry_value_t value;
   ... // create or acquire value
 
-  jerry_value_set_error_flag (&error);
+  jerry_value_t error = jerry_create_error_from_value (value, true);
-  jerry_value_t value = jerry_get_value_from_error (error, true);
+  jerry_value_t value_from_error = jerry_get_value_from_error (error, true);
   // using the 'error' variable after release is invalid.
 
-  jerry_release_value (value);
+  jerry_release_value (value_from_error);
 }
 ```
 
@@ -1767,14 +1919,14 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
 
 ```c
 {
-  jerry_value_t error;
+  jerry_value_t value;
   ... // create or acquire value
 
-  jerry_value_set_error_flag (&error);
+  jerry_value_t error = jerry_create_error_from_value (value, true);
-  jerry_value_t value = jerry_get_value_from_error (error, false);
+  jerry_value_t value_from_error = jerry_get_value_from_error (error, false);
-  // both 'error' and 'value' can be used and must be released when they are no longer needed
+  // both 'error' and 'value_from_error' can be used and must be released when they are no longer needed
 
-  jerry_release_value (value);
+  jerry_release_value (value_from_error);
   jerry_release_value (error);
 }
 ```
@@ -1782,78 +1934,8 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
 **See also**
 
 - [jerry_value_t](#jerry_value_t)
-- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
+- [jerry_create_error_from_value](#jerry_create_error_from_value)
-- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
+- [jerry_create_abort_from_value](#jerry_create_abort_from_value)
-
-## jerry_value_set_error_flag
-
-**Summary**
-
-Set the error flag.
-
-**Prototype**
-
-```c
-void
-jerry_value_set_error_flag (jerry_value_t *value_p);
-```
-
-- `value_p` - pointer to an api value
-
-**Example**
-
-```c
-{
-  jerry_value_t value;
-  ... // create or acquire value
-
-  jerry_value_set_error_flag (&value);
-
-  jerry_release_value (value);
-}
-```
-
-**See also**
-
-- [jerry_value_t](#jerry_value_t)
-- [jerry_get_value_from_error](#jerry_get_value_from_error)
-- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
-
-
-## jerry_value_set_abort_flag
-
-**Summary**
-
-Set both the error and abort flags.
-
-**Prototype**
-
-```c
-void
-jerry_value_set_abort_flag (jerry_value_t *value_p);
-```
-
-- `value_p` - pointer to an api value
-
-**Example**
-
-```c
-{
-  jerry_value_t value;
-  ... // create or acquire value
-
-  jerry_value_set_abort_flag (&value);
-
-  jerry_release_value (value);
-}
-```
-
-**See also**
-
-- [jerry_value_t](#jerry_value_t)
-- [jerry_get_value_from_error](#jerry_get_value_from_error)
-- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
-
 
 # Getter functions of 'jerry_value_t'
 
@@ -2890,7 +2972,7 @@ jerry_create_error (jerry_error_t error_type,
 
 - [jerry_value_is_error](#jerry_value_is_error)
 - [jerry_get_value_from_error](#jerry_get_value_from_error)
-- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
+- [jerry_create_error_from_value](#jerry_create_error_from_value)
 
 
 ## jerry_create_error_sz
@@ -4317,106 +4399,6 @@ jerry_set_prototype (const jerry_value_t obj_val,
 - [jerry_get_prototype](#jerry_get_prototype)
 
 
-## jerry_get_object_native_handle
-
-**Summary**
-
-**Deprecated: Please use jerry_get_object_native_pointer instead.**
-
-Get native handle, previously associated with specified object.
-
-**Prototype**
-
-```c
-bool
-jerry_get_object_native_handle (const jerry_value_t obj_val,
-                                uintptr_t *out_handle_p);
-```
-
-- `obj_val` - object value
-- `out_handle_p` - handle value (output parameter).
-- return value
-  - true, if there is handle associated with the object
-  - false, otherwise
-
-**Example**
-
-```c
-{
-  jerry_value_t object;
-  uintptr_t handle_set;
-
-  ... // receive or construct object and handle_set value
-
-  jerry_set_object_native_handle (object, handle_set, NULL);
-
-  ...
-
-  uintptr_t handle_get;
-  bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get);
-}
-```
-
-**See also**
-
-- [jerry_create_object](#jerry_create_object)
-- [jerry_set_object_native_handle](#jerry_set_object_native_handle)
-- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
-
-
-## jerry_set_object_native_handle
-
-**Summary**
-
-**Deprecated: Please use jerry_set_object_native_pointer instead.**
-
-Set native handle and an optional free callback for the specified object.
-
-*Note*: If native handle was already set for the object, its value is updated.
-
-*Note*: If a non-NULL free callback is specified, it will be called
-        by the garbage collector when the object is freed. The free
-        callback always overwrites the previous value, so passing
-        a NULL value deletes the current free callback.
-
-**Prototype**
-
-```c
-void
-jerry_set_object_native_handle (const jerry_value_t obj_val,
-                                uintptr_t handle_p,
-                                jerry_object_free_callback_t freecb_p);
-```
-
-- `obj_val` - object value to set handle in
-- `handle_p` - handle value
-- `freecb_p` - pointer to "free" callback or NULL
-
-**Example**
-
-```c
-{
-  jerry_value_t object;
-  uintptr_t handle_set;
-
-  ... // receive or construct object and handle_set value
-
-  jerry_set_object_native_handle (object, handle_set, NULL);
-
-  ...
-
-  uintptr_t handle_get;
-  bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get);
-}
-```
-
-**See also**
-
-- [jerry_create_object](#jerry_create_object)
-- [jerry_get_object_native_handle](#jerry_get_object_native_handle)
-- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
-
-
 ## jerry_get_object_native_pointer
 
 **Summary**
@@ -4437,7 +4419,7 @@ The pointer and the type information are previously associated with the object b
         and dereferencing `out_native_pointer_p`.
 
 *Note*: `out_native_pointer_p` and `out_native_info_p` can be NULL, and it means the
-        caller doesn't want to get the native_pointer or type infomation.
+        caller doesn't want to get the native_pointer or type information.
 
 **Prototype**
 
@@ -4450,7 +4432,7 @@ jerry_get_object_native_pointer (const jerry_value_t obj_val,
 
 - `obj_val` - object value to get native pointer from.
 - `out_native_pointer_p` - native pointer (output parameter).
-- `out_native_info_p` - native pointer's type infomation (output parameter).
+- `out_native_info_p` - native pointer's type information (output parameter).
 - return value
   - true, if there is native pointer associated with the object
   - false, otherwise
@@ -4547,7 +4529,7 @@ jerry_set_object_native_pointer (const jerry_value_t obj_val,
 
 - `obj_val` - object to set native pointer in.
 - `native_p` - native pointer.
-- `info_p` - native pointer's type infomation or NULL. When used, this should
+- `info_p` - native pointer's type information or NULL. When used, this should
              be a long-lived pointer, usually a pointer to a
              `static const jerry_object_native_info_t` makes most sense.
 
@@ -4705,7 +4687,7 @@ bool jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *nat
                                            void *user_data_p);
 ```
 
-- `native_info_p` - native pointer's type infomation.
+- `native_info_p` - native pointer's type information.
 - return value
   - `true`, if the search function terminated the traversal by returning `false`
   - `false`, if the end of the list of objects was reached
@@ -4903,6 +4885,105 @@ main (void)
 - [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer)
 
 
+# External context functions
+
+## jerry_create_instance
+
+**Summary**
+
+Creates a JerryScript instance for external context.
+
+**Prototype**
+
+```c
+jerry_instance_t *
+jerry_create_instance (uint32_t heap_size,
+                       jerry_instance_alloc_t alloc,
+                       void *cb_data_p);
+```
+
+- `heap_size` - requested heap size of the JerryScript instance
+- `alloc` - function for allocation
+- `cb_data_p` - user data
+- return value
+  - pointer to the newly created JerryScript instance if success
+  - NULL otherwise.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <stdlib.h>
+#include <pthread.h>
+
+#include "jerryscript.h"
+#include "jerryscript-port.h"
+
+/* A different Thread Local Storage variable for each jerry instance. */
+__thread jerry_instance_t *tls_instance;
+
+jerry_instance_t *
+jerry_port_get_current_instance (void)
+{
+  /* Returns the instance assigned to the thread. */
+  return tls_instance;
+}
+
+/* Allocate JerryScript heap for each thread. */
+static void *
+instance_alloc_fn (size_t size, void *cb_data)
+{
+  (void) cb_data;
+  return malloc (size);
+}
+
+static void *
+thread_function (void *param)
+{
+  tls_instance = jerry_create_instance (512 * 1024,
+                                        instance_alloc_fn,
+                                        NULL);
+  jerry_init (JERRY_INIT_EMPTY);
+  /* Run the JerryScript instance (e.g.: jerry_parse & jerry_run) */
+  jerry_cleanup ();
+
+  /* Deallocate JerryScript instance */
+  free (tls_instance);
+
+  return NULL;
+}
+
+#define NUM_OF_THREADS 8
+
+int
+main (void)
+{
+  pthread_t threads[NUM_OF_THREADS];
+
+  /* Create the threads. */
+  for (int i = 0; i < NUM_OF_THREADS; i++)
+  {
+    pthread_create (&threads[i], NULL, thread_function, (void *) (intptr_t) i);
+  }
+
+  /* Wait for the threads to complete, and release their resources. */
+  for (int i = 0; i < NUM_OF_THREADS; i++)
+  {
+    pthread_join (threads[i], NULL);
+  }
+
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_instance_t](#jerry_instance_t)
+- [jerry_instance_alloc_t](#jerry_instance_alloc_t)
+- [jerry_port_get_current_instance](05.PORT-API.md#jerry_port_get_current_instance)
+
+
 # Snapshot functions
 
 ## jerry_generate_snapshot

03.API-EXAMPLE.md

@@ -115,7 +115,7 @@ main (void)
   /* Evaluate script1 */
   eval_ret = jerry_eval (script_1,
                          strlen ((const char *) script_1),
-                         false);
+                         JERRY_PARSE_NO_OPTS);
 
   /* Free JavaScript value, returned by eval */
   jerry_release_value (eval_ret);
@@ -123,7 +123,7 @@ main (void)
   /* Evaluate script2 */
   eval_ret = jerry_eval (script_2,
                          strlen ((const char *) script_2),
-                         false);
+                         JERRY_PARSE_NO_OPTS);
 
   /* Free JavaScript value, returned by eval */
   jerry_release_value (eval_ret);
@@ -179,7 +179,7 @@ main (void)
   /* Now starting script that would output value of just initialized field */
   jerry_value_t eval_ret = jerry_eval (script,
                                        strlen ((const char *) script),
-                                       false);
+                                       JERRY_PARSE_NO_OPTS);
 
   /* Free JavaScript value, returned by eval */
   jerry_release_value (eval_ret);
@@ -332,7 +332,7 @@ main (void)
     /* Evaluate entered command */
     ret_val = jerry_eval ((const jerry_char_t *) cmd,
                           len,
-                          false);
+                          JERRY_PARSE_NO_OPTS);
 
     /* If command evaluated successfully, print value, returned by eval */
     if (jerry_value_is_error (ret_val))
@@ -430,7 +430,7 @@ main (void)
   size_t script_size = strlen ((const char *) script);
 
   /* Evaluate script */
-  jerry_value_t eval_ret = jerry_eval (script, script_size, false);
+  jerry_value_t eval_ret = jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS);
 
   /* Free JavaScript value, returned by eval */
   jerry_release_value (eval_ret);
@@ -519,7 +519,7 @@ main (void)
   /* Evaluate script */
   my_js_obj_val = jerry_eval (my_js_object,
                               strlen ((const char *) my_js_object),
-                              false);
+                              JERRY_PARSE_NO_OPTS);
 
   /* Create a JS function object and wrap into a jerry value */
   jerry_value_t add_func_obj = jerry_create_external_function (add_handler);
@@ -542,7 +542,7 @@ main (void)
   size_t script_size = strlen ((const char *) script);
 
   /* Evaluate script */
-  jerry_value_t eval_ret = jerry_eval (script, script_size, false);
+  jerry_value_t eval_ret = jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS);
 
   /* Free JavaScript value, returned by eval */
   jerry_release_value (eval_ret);
@@ -593,7 +593,7 @@ main (void)
                                   jerryx_handler_print);
 
   /* Evaluate the script */
-  jerry_value_t eval_ret = jerry_eval (script, script_size, false);
+  jerry_value_t eval_ret = jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS);
 
   /* Free the JavaScript value returned by eval */
   jerry_release_value (eval_ret);

05.PORT-API.md

@@ -73,6 +73,11 @@ typedef enum
  *
  * Example: a libc-based port may implement this with vfprintf(stderr) or
  * vfprintf(logfile), or both, depending on log level.
+ *
+ * Note:
+ *      This port function is called by jerry-core when JERRY_ENABLE_LOGGING is
+ *      defined. It is also common practice though to use this function in
+ *      application code.
  */
 void jerry_port_log (jerry_log_level_t level, const char *fmt, ...);
 ```

07.DEBUGGER.md

@@ -13,24 +13,23 @@ permalink: /debugger/
 JerryScript provides a remote debugger which allows debugging
 JavaScript programs. The debugger has two main components:
 a server which is part of the JerryScript binary and a
-separate client application. Currently two debugger clients
+separate client application. Currently a Python-based debugger
-are available in the /jerry-debugger subdirectory: an HTML
+client is available in the /jerry-debugger subdirectory.
-and a Python application. These simple applications demonstrate
+This simple application demonstrates the communication protocol
-the communication protocol between the client and server and can
+between the client and server, and can be reused by integrated
-be reused by integrated development environments.
+development environments.
 
 ## Setting up the debugger server
 
 The following arguments must be passed to `tools/build.py`:
 
-`--jerry-debugger=on --jerry-libc=off`
+`--jerry-debugger=on`
 
-At the moment only a Websocket-based implementation is provided
+The transport layer of the communication protocol is pluggable.
-by JerryScript which transmits messages over TCP/IP networks.
+At the moment, a WebSocket-based implementation is provided as a
-This implementation requires a socket API which is not yet
+JerryScript extension, which transmits messages over TCP/IP networks.
-supported by jerry-libc so the standard libc is used instead.
+If necessary/implemented, any reliable stream or datagram based
-In the future any reliable stream or datagram based protocol
+protocol can be used for transmitting debugger messages.
-can be used for transmitting debugger messages.
 
 ## Debugging JavaScript applications
 
@@ -59,8 +58,8 @@ the *Waiting for client connection* message:
 
 `--log-level 2`
 
-The HTML client can connect to the IP address of the server with
+The Python client can connect to the server by specifying its
-the `connect` command. The IP address can be localhost
+IP address on the command line. The address can be localhost
 if the server and the client are running on the same machine.
 
 After the connection is established the execution can be
@@ -75,9 +74,12 @@ All available commands of the client can be queried by the
 
 ## Integrating debugger support into applications using JerryScript
 
-The debugger can be enabled by calling the `jerry_debugger_init (uint16_t port)`
+When using the extension-provided WebSocket transport layer, the
-function after the `jerry_init ()` function. It initializes the debugger
+debugger can be enabled by calling `jerryx_debugger_after_connect
-and blocks until a client connects.
+(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.)
 
 The resource name provided to `jerry_parse ()` is used by the client
 to identify the resource name of the source code. This resource name
@@ -86,7 +88,7 @@ is usually a file name.
 ## JerryScript debugger C-API interface
 
 The following section describes the debugger functions
-available for the host application.
+available to the host application.
 
 ## JerryScript debugger types
 
@@ -117,36 +119,6 @@ typedef jerry_value_t
 
 ## JerryScript debugger functions
 
-### jerry_debugger_init
-
-**Summary**
-
-Debugger server initialization. Must be called after `jerry_init`.
-
-**Prototype**
-
-```c
-void
-jerry_debugger_init (uint16_t port);
-```
-
-- `port` - Server port number
-
-
-**Example**
-
-```c
-{
-  jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
-
-  // ...
-
-  jerry_cleanup ();
-}
-```
-
-
 ### jerry_debugger_is_connected
 
 **Summary**
@@ -162,10 +134,18 @@ jerry_debugger_is_connected (void);
 
 **Example**
 
+[doctest]: # (test="link")
+
 ```c
+#include "jerryscript.h"
+#include "jerryscript-ext/debugger.h"
+
+int
+main (void)
 {
   jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
 
   if (jerry_debugger_is_connected ())
   {
@@ -194,10 +174,18 @@ jerry_debugger_stop (void)
 
 **Example**
 
+[doctest]: # (test="link")
+
 ```c
+#include "jerryscript.h"
+#include "jerryscript-ext/debugger.h"
+
+int
+main (void)
 {
   jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
 
   jerry_debugger_stop ();
 
@@ -228,10 +216,18 @@ jerry_debugger_continue (void)
 
 **Example**
 
+[doctest]: # (test="link")
+
 ```c
+#include "jerryscript.h"
+#include "jerryscript-ext/debugger.h"
+
+int
+main (void)
 {
   jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
 
   jerry_debugger_continue ();
 
@@ -243,7 +239,7 @@ jerry_debugger_continue (void)
 
 - [jerry_debugger_stop](#jerry_debugger_stop)
 
-### jerry_debugger_disable_stop_at_breakpoint
+### jerry_debugger_stop_at_breakpoint
 
 **Summary**
 
@@ -262,15 +258,26 @@ jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint)
 
 **Example**
 
+[doctest]: # (test="link")
+
 ```c
+#include <string.h>
+#include "jerryscript.h"
+#include "jerryscript-ext/debugger.h"
+
+int
+main (void)
 {
   jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
 
   jerry_debugger_stop_at_breakpoint (true);
 
   // Protected execution of JavaScript code.
-  jerry_eval (...);
+  const jerry_char_t script[] = "42";
+  size_t script_size = strlen ((const char *) script);
+  jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS);
 
   jerry_debugger_stop_at_breakpoint (false);
 
@@ -298,7 +305,12 @@ jerry_debugger_wait_for_client_source (jerry_debugger_wait_for_source_callback_t
 
 **Example**
 
+[doctest]: # (test="link")
+
 ```c
+#include "jerryscript.h"
+#include "jerryscript-ext/debugger.h"
+
 /**
  * Runs the source code received by jerry_debugger_wait_for_client_source.
  */
@@ -325,20 +337,23 @@ wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource nam
   return ret_val;
 } /* wait_for_source_callback */
 
-int main ()
+int
+main (void)
 {
+  jerry_debugger_wait_for_source_status_t receive_status;
+
   do
   {
     /* Create a new JerryScript instance when a context reset is
      * received. Applications usually registers their core bindings
      * here as well (e.g. print, setTimeout). */
     jerry_init (JERRY_INIT_EMPTY);
-    jerry_debugger_init (5001);
+    jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                   && jerryx_debugger_ws_create ());
 
     do
     {
       jerry_value_t run_result;
-      jerry_debugger_wait_for_source_status_t receive_status;
 
       receive_status = jerry_debugger_wait_for_client_source (wait_for_source_callback,
                                                               NULL,
@@ -369,20 +384,67 @@ Sends the program's output to the debugger client.
 **Prototype**
 
 ```c
-  void
+void
-  jerry_debugger_send_output (jerry_char_t buffer[], jerry_size_t string_size, uint8_t type)
+jerry_debugger_send_output (const jerry_char_t *buffer, jerry_size_t string_size)
 ```
 
 **Example**
 
-```c
+[doctest]: # (test="link")
-  jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
 
-  jerry_char_t my_output = "Hey, this should be sent too!";
+```c
+#include "jerryscript.h"
+#include "jerryscript-ext/debugger.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
+
+  jerry_char_t my_output[] = "Hey, this should be sent too!";
   jerry_size_t my_output_size = sizeof (my_output);
 
-  jerry_debugger_send_output (my_output, my_output_size, JERRY_DEBUGGER_OUTPUT_OK);
+  jerry_debugger_send_output (my_output, my_output_size);
 
   jerry_cleanup ();
+}
+```
+
+### jerry_debugger_send_log
+
+**Summary**
+
+Sends the program's log to the debugger client.
+
+**Prototype**
+
+```c
+void
+jerry_debugger_send_log (jerry_log_level_t level, const jerry_char_t *buffer, jerry_size_t string_size)
+```
+
+**Example**
+
+[doctest]: # (test="link")
+
+```c
+#include "jerryscript.h"
+#include "jerryscript-ext/debugger.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
+
+  jerry_char_t my_log[] = "Custom diagnostics";
+  jerry_size_t my_log_size = sizeof (my_log);
+
+  jerry_debugger_send_log (JERRY_LOG_LEVEL_DEBUG, my_log, my_log_size);
+
+  jerry_cleanup ();
+}
 ```

10.EXT-REFERENCE-HANDLER.md

@@ -41,7 +41,9 @@ jerryx_handler_assert (const jerry_value_t func_obj_val, const jerry_value_t thi
 
 **Summary**
 
-Expose garbage collector to scripts.
+Expose garbage collector to scripts. If the first argument of the function
+is logical true, it performs a high severity gc. Otherwise a low severity
+gc is performed, which is also the default if no parameters passed.
 
 **Prototype**
 

12.EXT-REFERENCE-MODULE.md

@@ -192,7 +192,7 @@ load_and_evaluate_js_file (const jerry_value_t name, jerry_value_t *result)
     {
       /* We read the file into memory and call jerry_eval (), assigning the result to the out-parameter. */
       fread (js_file_contents, file_size, 1, js_file);
-      (*result) = jerry_eval (js_file_contents, file_size, false);
+      (*result) = jerry_eval (js_file_contents, file_size, JERRY_PARSE_NO_OPTS);
 
       /* We release the memory holding the contents of the file. */
       free (js_file_contents);

13.DEBUGGER-TRANSPORT.md

@@ -0,0 +1,258 @@
+---
+layout: page
+title: debugger transport
+category: documents
+permalink: /debugger-transport/
+---
+
+* toc
+{:toc}
+
+# JerryScript debugger transport interface
+
+The transport interface support allows dynamic selection of transportation
+layers which can encode/decode or send/receive messages transmitted between
+the debugger client and server.
+
+# Types
+
+## jerry_debugger_transport_receive_context_t
+
+**Summary**
+
+This context represents the current status of processing received data.
+The final state is returned by
+[jerry_debugger_transport_receive](#jerry_debugger_transport_receive)
+and must be passed to
+[jerry_debugger_transport_receive_completed](#jerry_debugger_transport_receive_completed)
+after the message is processed.
+
+**Prototype**
+
+```c
+typedef struct
+{
+  uint8_t *buffer_p; /**< buffer for storing the received data */
+  size_t received_length; /**< number of currently received bytes */
+  uint8_t *message_p; /**< start of the received message */
+  size_t message_length; /**< length of the received message */
+  size_t message_total_length; /**< total length for datagram protocols,
+                                *   0 for stream protocols */
+} jerry_debugger_transport_receive_context_t;
+```
+
+## jerry_debugger_transport_header_t
+
+**Summary**
+
+Shared header for each transport interface. It mostly contains callback functions
+used by the JerryScript debugger server.
+
+**Prototype**
+
+```c
+typedef struct jerry_debugger_transport_layer_t
+{
+  /* The following fields must be filled before calling jerry_debugger_transport_add(). */
+  jerry_debugger_transport_close_t close; /**< close connection callback */
+  jerry_debugger_transport_send_t send;  /**< send data callback */
+  jerry_debugger_transport_receive_t receive; /**< receive data callback */
+
+  /* The following fields are filled by jerry_debugger_transport_add(). */
+  struct jerry_debugger_transport_layer_t *next_p; /**< next transport layer */
+} jerry_debugger_transport_header_t;
+```
+
+## jerry_debugger_transport_close_t
+
+**Summary**
+
+Called when the connection is closed. Must release all resources (including the
+memory area for the transport interface) allocated for the transport interface.
+
+**Prototype**
+
+```c
+typedef void (*jerry_debugger_transport_close_t) (struct jerry_debugger_transport_interface_t *header_p);
+```
+
+## jerry_debugger_transport_send_t
+
+**Summary**
+
+Called when a message needs to be sent. Must either transmit the message or call
+the `header_p->next_p->send()` method.
+
+**Prototype**
+
+```c
+typedef bool (*jerry_debugger_transport_send_t) (struct jerry_debugger_transport_interface_t *header_p,
+                                                 uint8_t *message_p, size_t message_length);
+```
+
+## jerry_debugger_transport_receive_t
+
+**Summary**
+
+Called during message processing. If messages are available it must return with
+the next message.
+
+**Prototype**
+
+```c
+typedef bool (*jerry_debugger_transport_receive_t) (struct jerry_debugger_transport_interface_t *header_p,
+                                                    jerry_debugger_transport_receive_context_t *context_p);
+```
+
+# Transport interface API functions
+
+## jerry_debugger_transport_malloc
+
+**Summary**
+
+Allocates memory for the transport interface.
+
+**Prototype**
+
+```c
+void * jerry_debugger_transport_malloc (size_t size);
+```
+
+- `size`: size of the memory block.
+- return value: non-NULL pointer, if the memory is successfully allocated,
+                NULL otherwise.
+
+## jerry_debugger_transport_free
+
+**Summary**
+
+Free memory allocated by [jerry_debugger_transport_malloc](#jerry_debugger_transport_malloc)
+
+**Prototype**
+
+```c
+void jerry_debugger_transport_free (void *mem_p, size_t size);
+```
+
+- `header_p`: header of a transporation interface.
+- `size`: total size of the transportation interface.
+
+## jerry_debugger_transport_add
+
+**Summary**
+
+Add a new interface to the transporation interface chain. The interface
+will be the first item of the interface chain.
+
+**Prototype**
+
+```c
+void jerry_debugger_transport_add (jerry_debugger_transport_header_t *header_p,
+                                   size_t send_message_header_size, size_t max_send_message_size,
+                                   size_t receive_message_header_size, size_t max_receive_message_size);
+```
+
+- `header_p`: header of a transporation interface.
+- `send_message_header_size`: size of the outgoing message header, can be 0.
+- `max_send_message_size`: maximum outgoing message size supported by the interface.
+- `receive_message_header_size`: size of the incoming message header, can be 0.
+- `max_receive_message_size`: maximum incoming message size supported by the interface.
+
+## jerry_debugger_transport_start
+
+**Summary**
+
+Starts the communication to the debugger client. Must be called after the
+connection is successfully established.
+
+**Prototype**
+
+```c
+void jerry_debugger_transport_start (void);
+```
+
+## jerry_debugger_transport_is_connected
+
+**Summary**
+
+Tells whether a debugger client is connected to the debugger server.
+
+**Prototype**
+
+```c
+bool jerry_debugger_transport_is_connected (void);
+```
+
+- return value: `true`, if a client is connected, `false` otherwise.
+
+## jerry_debugger_transport_close
+
+**Summary**
+
+Disconnect from the current debugger client. It does nothing if a client is
+not connected, 
+
+**Prototype**
+
+```c
+void jerry_debugger_transport_close (void);
+```
+
+## jerry_debugger_transport_send
+
+**Summary**
+
+Send message to the client.
+
+**Prototype**
+
+```c
+bool jerry_debugger_transport_send (const uint8_t *message_p, size_t message_length);
+```
+
+- `message_p`: message to be sent.
+- `message_length`: message length in bytes.
+- return value: `true`, if a client is still connected, `false` otherwise.
+
+## jerry_debugger_transport_receive
+
+**Summary**
+
+Receive message from the client.
+
+**Prototype**
+
+```c
+bool jerry_debugger_transport_receive (jerry_debugger_transport_receive_context_t *context_p);
+```
+
+- `context_p`: an unused [jerry_debugger_transport_receive_context_t](#jerry_debugger_transport_receive_context_t).
+- return value: `true`, if a client is still connected, `false` otherwise.
+
+## jerry_debugger_transport_receive_completed
+
+**Summary**
+
+Must be called after [jerry_debugger_transport_receive](#jerry_debugger_transport_receive)
+returns with a valid message. Must not be called otherwise.
+
+**Prototype**
+
+```c
+void jerry_debugger_transport_receive_completed (jerry_debugger_transport_receive_context_t *context_p);
+```
+
+- `context_p`: a [jerry_debugger_transport_receive_context_t](#jerry_debugger_transport_receive_context_t)
+               passed to [jerry_debugger_transport_receive](#jerry_debugger_transport_receive).
+
+## jerry_debugger_transport_sleep
+
+**Summary**
+
+Can be used to wait for incoming messages. Currently the delay is 100ms.
+
+**Prototype**
+
+```c
+void jerry_debugger_transport_sleep (void);
+```