Update the webpage (#3227)

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
2019-10-21 14:03:15 +02:00
parent 09af6e670e
commit 3731fbf0af
4 changed files with 349 additions and 14 deletions
@@ -204,7 +204,7 @@ The default value is 512.
 |---------|----------------------------------------------|
 | C:      | `-DJERRY_GLOBAL_HEAP_SIZE=(int)`             |
 | CMake:  | `--DJERRY_GLOBAL_HEAP_SIZE=(int)`            |
-| Python: | `--heap-size=(int)`                          |
+| Python: | `--mem-heap=(int)`                           |

 ### Garbage collection limit

@@ -451,6 +451,9 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_

 Native free callback of an object. It is used in `jerry_object_native_info_t` and for external Array buffers.

+*Note*:
+ - This callback method **must not** call any JerryScript API methods.
+
 **Prototype**

 ```c
@@ -4690,6 +4693,63 @@ main (void)
 - [jerry_delete_property](#jerry_delete_property)


+## jerry_has_internal_property
+
+**Summary**
+
+Checks whether the object has the given internal property.
+
+*Note*:
+ - Properties which were not created with [jerry_set_internal_property](#jerry_set_internal_property) are excluded
+   during the operation.
+ - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+
+**Prototype**
+
+```c
+bool
+jerry_has_internal_property (const jerry_value_t obj_val,
+                             const jerry_value_t prop_name_val);
+```
+
+- `obj_val` - object value
+- `prop_name_val` - property name
+- return value
+  - true, if the property exists
+  - false, otherwise
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t global_object = jerry_get_global_object ();
+  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property");
+
+  bool has_internal_js_prop = jerry_has_internal_property (global_object, prop_name);
+
+  jerry_release_value (prop_name);
+  jerry_release_value (global_object);
+
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_delete_internal_property](#jerry_delete_internal_property)
+- [jerry_get_internal_property](#jerry_get_internal_property)
+- [jerry_set_internal_property](#jerry_set_internal_property)
+
+
 ## jerry_delete_property

 **Summary**
@@ -4779,6 +4839,50 @@ jerry_delete_property_by_index (const jerry_value_t obj_val,
 - [jerry_get_property_by_index](#jerry_get_property_by_index)
 - [jerry_set_property_by_index](#jerry_set_property_by_index)

+## jerry_delete_internal_property
+
+**Summary**
+
+Delete an internal property from an object.
+
+*Note*: Properties which were not created with [jerry_set_internal_property](#jerry_set_internal_property) are excluded
+        during the operation.
+
+**Prototype**
+
+```c
+bool
+jerry_delete_internal_property (const jerry_value_t obj_val,
+                                const jerry_value_t prop_name_val);
+```
+
+- `obj_val` - object value
+- `prop_name_val` - property name
+- return value
+  - true, if property was deleted successfully
+  - false, otherwise
+
+**Example**
+
+```c
+{
+  jerry_value_t global_object = jerry_get_global_object ();
+  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property");
+
+  bool delete_result = jerry_delete_internal_property (global_object, prop_name);
+  /* use "delete_result" */
+
+  jerry_release_value (prop_name);
+  jerry_release_value (global_object);
+}
+```
+
+**See also**
+
+- [jerry_has_internal_property](#jerry_has_internal_property)
+- [jerry_get_internal_property](#jerry_get_internal_property)
+- [jerry_set_internal_property](#jerry_set_internal_property)
+

 ## jerry_get_property

@@ -4891,6 +4995,66 @@ jerry_get_property_by_index (const jerry_value_t obj_val,
 - [jerry_set_property](#jerry_set_property)
 - [jerry_set_property_by_index](#jerry_set_property_by_index)

+## jerry_get_internal_property
+
+**Summary**
+
+Get value of an internal property to the specified object with the given name.
+
+*Note*:
+ - Properties which were not created with [jerry_set_internal_property](#jerry_set_internal_property) are excluded
+   during the operation.
+ - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+   is no longer needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_get_internal_property (const jerry_value_t obj_val,
+                             const jerry_value_t prop_name_val);
+```
+
+- `obj_val` - object value
+- `prop_name_val` - property name
+- return value
+  - value of property, if the internal property exists
+  - undefined value, if the, if the internal does not property exists
+  - thrown error, otherwise
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t global_object = jerry_get_global_object ();
+  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property");
+
+  jerry_value_t prop_value = jerry_get_internal_property (global_object, prop_name);
+
+  /* use "prop_value" then release it. */
+
+  jerry_release_value (prop_value);
+  jerry_release_value (prop_name);
+  jerry_release_value (global_object);
+
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_has_internal_property](#jerry_has_internal_property)
+- [jerry_delete_internal_property](#jerry_delete_internal_property)
+- [jerry_set_internal_property](#jerry_set_internal_property)
+

 ## jerry_set_property

@@ -5008,6 +5172,68 @@ jerry_set_property_by_index (const jerry_value_t obj_val,
 - [jerry_get_property_by_index](#jerry_get_property_by_index)


+## jerry_set_internal_property
+
+**Summary**
+
+Set an internal property to the specified object with the given name.
+
+*Note*:
+ - The property cannot be accessed from the JavaScript context, only from the public API.
+ - It is different from [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) in that any jerry API value
+   can be hidden from the JavaScript context, not only native pointers.
+
+**Prototype**
+
+```c
+bool
+jerry_set_internal_property (const jerry_value_t obj_val,
+                             const jerry_value_t prop_name_val,
+                             const jerry_value_t value_to_set)
+```
+
+- `obj_val` - object value
+- `prop_name_val` - property name
+- `value_to_set` - value to set
+- return value
+  - true, if success
+  - thrown error, otherwise
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t global_object = jerry_get_global_object ();
+  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property");
+  jerry_value_t value_to_set = jerry_create_number (5);
+
+  bool set_result = jerry_set_internal_property (global_object, prop_name, value_to_set);
+
+  /* check the result of internal property set call */
+
+  jerry_release_value (value_to_set);
+  jerry_release_value (prop_name);
+  jerry_release_value (global_object);
+
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_has_internal_property](#jerry_has_internal_property)
+- [jerry_delete_internal_property](#jerry_delete_internal_property)
+- [jerry_get_internal_property](#jerry_get_internal_property)
+
+
 ## jerry_init_property_descriptor_fields

 **Summary**
@@ -5552,7 +5778,8 @@ jerry_set_prototype (const jerry_value_t obj_val,
 **Summary**

 Get native pointer by the given type information.
-The pointer and the type information are previously associated with the object by jerry_set_object_native_pointer.
+The pointer and the type information are previously associated with the object by
+[jerry_set_object_native_pointer](#jerry_set_object_native_pointer).

 *Note*: `out_native_pointer_p` can be NULL, and it means the
        caller doesn't want to get the native_pointer.
@@ -5759,15 +5986,18 @@ main (void)
 **Summary**

 Set native pointer and an optional type information for the specified object.
-You can get them by calling jerry_get_object_native_pointer later.
+You can get them by calling [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) later.

-*Note*: If native pointer was already set for the object, its value is updated.
+*Notes*:
+ - If a native pointer was already set for the object with the same type information, its value is updated.
+ - If a non-NULL free callback is specified in the native type information,
+   it will be called by the garbage collector when the object is freed.
+ - If the object is only referenced via the "global" object (or one of it's "child"),
+   the free callback will be invoked during the execution of `jerry_cleanup`.
+ - The free callback **must not** invoke API functions.

-*Note*: If a non-NULL free callback is specified in the native type information,
-        it will be called by the garbage collector when the object is freed.
-        This callback **must not** invoke API functions.
-        The type info always overwrites the previous value, so passing
-        a NULL value deletes the current type info.
+*Note*: If possible do not store API values in native pointers, rather check
+        [jerry_set_internal_property](#jerry_set_internal_property).

 **Prototype**

@@ -5802,10 +6032,12 @@ best-practice example.
 **Summary**

 Delete the native pointer of the specified object associated with the given native type info.
-You can get them by calling jerry_get_object_native_pointer later.

-*Note*:
+*Notes*:
 - If the specified object has no matching native pointer for the given native type info the operation has no effect.
+ - The method does not invoke the free callback specified in the type info.
+   If the native pointer should be freed then one must get the native pointer first and invoke the free callback manually
+   before calling this method.
 - This operation cannot throw an exception.

 **Prototype**
@@ -7401,6 +7633,85 @@ jerry_get_arraybuffer_pointer (const jerry_value_t value);

 - [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external)

+## jerry_is_arraybuffer_detachable
+
+**Summary**
+
+Get if the ArrayBuffer is detachable.
+
+**Prototype**
+
+```c
+jerry_value_t 
+jerry_is_arraybuffer_detachable (const jerry_value_t value);
+```
+
+- `value` - ArrayBuffer to be detached
+- return
+  - boolean value if success
+  - Error otherwise
+
+**Example**
+
+```c
+{
+  // create the ArrayBuffer
+  jerry_value_t buffer = jerry_create_arraybuffer (16);
+
+  jerry_value_t res = jerry_is_arraybuffer_detachable (buffer);
+  bool is_detachable = jerry_get_boolean_value (res);
+
+  // release buffer as it is not needed after this point
+  jerry_release_value (res);
+  jerry_release_value (buffer);
+}
+```
+
+**See also**
+
+- [jerry_detach_arraybuffer](#jerry_detach_arraybuffer)
+
+## jerry_detach_arraybuffer
+
+**Summary**
+
+Detach the underlying data block from ArrayBuffer and set its bytelength to 0.
+
+This operation requires the ArrayBuffer to be external that created by
+`jerry_create_arraybuffer_external`.
+
+**Prototype**
+
+```c
+jerry_value_t 
+jerry_detach_arraybuffer (const jerry_value_t value);
+```
+
+- `value` - ArrayBuffer to be detached
+- return
+  - null value if success
+  - Error otherwise
+
+**Example**
+
+```c
+{
+  uint8_t buf[1];
+  jerry_size_t length = 1;
+  // create the ArrayBuffer
+  jerry_value_t buffer = jerry_create_arraybuffer (length, buf, NULL);
+
+  jerry_value_t res = jerry_detach_arraybuffer (buffer);
+
+  // release buffer as it is not needed after this point
+  jerry_release_value (res);
+  jerry_release_value (buffer);
+}
+```
+
+**See also**
+
+- [jerry_is_arraybuffer_detachable](#jerry_is_arraybuffer_detachable)

 ## jerry_get_dataview_buffer

@@ -93,10 +93,14 @@ information.
 void jerry_port_print_char (char c);
 ```

-### ES2015 Module system helper functions
+### ES2015 Module system

-The module system requires two specific functions for opening and closing files.
-It also requires a platform specific way of normalizing file paths.
+The port API provides functions that can be used by the module system to open
+and close source files, and normalize file paths.
+The `jerry_port_get_native_module` port function can be used to provide native
+modules to the engine. This function will be called when an import/export
+statement is encountered with an unknown module specifier, which embedders can
+use to supply native module objects based on the module name argument.

 ```c
 /**
@@ -136,6 +140,25 @@ jerry_port_normalize_path (const char *in_path_p, /**< input file path */
  // write to out_buf_p the normalized path
  // return length of written path
 } /* jerry_port_normalize_path */
+
+/**
+ * Get the module object of a native module.
+ *
+ * Note:
+ *      This port function is called by jerry-core when ES2015_MODULE_SYSTEM
+ *      is enabled.
+ *
+ * @param name String value of the module specifier.
+ *
+ * @return Undefined, if 'name' is not a native module
+ *         jerry_value_t containing the module object, otherwise
+ */
+jerry_value_t
+jerry_port_get_native_module (jerry_value_t name) /**< module specifier */
+{
+  (void) name;
+  return jerry_create_undefined ();
+}
 ```

 ## Date
@@ -12,6 +12,7 @@ permalink: /module-system/

 The module system allows users to write import and export statements in scripts, which can be used to separate the logic of the application into custom modules.
 The standard's relevant part can be found [here](https://www.ecma-international.org/ecma-262/6.0/#sec-modules).
+Embedders wishing to use native builtin modules with ES6 imports can use the [Port API](05.PORT-API.md#es2015-module-system) to do so.

 ## General