Update the webpage (#3319)

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
2019-11-14 20:43:11 +01:00
parent 3731fbf0af
commit 5b86cf113e
2 changed files with 302 additions and 13 deletions
@@ -326,6 +326,11 @@ Enum that contains the supported binary operation types
 - JERRY_BIN_OP_GREATER - greater relation (>)
 - JERRY_BIN_OP_GREATER_EQUAL - greater or equal relation (>=)
 - JERRY_BIN_OP_INSTANCEOF - instanceof operation
+ - JERRY_BIN_OP_ADD - addition operator (+)
+ - JERRY_BIN_OP_SUB - subtraction operator (-)
+ - JERRY_BIN_OP_MUL - multiplication operator (*)
+ - JERRY_BIN_OP_DIV - division operator (/)
+ - JERRY_BIN_OP_REM - remainder operator (%)

 *New in version 2.0*.

@@ -605,6 +610,22 @@ typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p);

 - [jerry_set_vm_exec_stop_callback](#jerry_set_vm_exec_stop_callback)

+## jerry_promise_state_t
+
+Enum which describes the state of a Promise.
+
+Possible values:
+
+ - JERRY_PROMISE_STATE_NONE - Invalid/Unknown state (possibly called on a non-promise object).
+ - JERRY_PROMISE_STATE_PENDING - Promise is in "Pending" state.
+ - JERRY_PROMISE_STATE_FULFILLED - Promise is in "Fulfilled" state.
+ - JERRY_PROMISE_STATE_REJECTED - Promise is in "Rejected" state.
+
+*New in version [NEXT VERSION]*.
+
+**See also**
+
+- [jerry_get_promise_result](#jerry_get_promise_result)

 ## jerry_typedarray_type_t

@@ -3241,6 +3262,144 @@ jerry_value_to_string (const jerry_value_t value);

 These APIs all depend on the ES2015-subset profile (or on some build options).

+## jerry_get_promise_result
+
+**Summary**
+
+The function returns the result of a Promise object.
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API depends on a build option (`JERRY_ES2015_BUILTIN_PROMISE`) and can be checked
+  in runtime with the `JERRY_FEATURE_PROMISE` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The ES2015-subset profile enables this by default.
+
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_get_promise_result (const jerry_value_t promise);
+```
+
+- `promise` - the input Promise object.
+- return
+  - The result of the Promise.
+  - If the Promise is not resolved yet the result is the 'undefined' value.
+  - A TypeError is returned if the input argument was not a Promise object or
+    the Promise support was not built into the library.
+
+*New in version [NEXT VERSION]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+
+static void
+example (void)
+{
+  // acquire/create a promise object.
+  jerry_value_t promise = jerry_create_promise ();
+  {
+    // prepare the argumnent for the resolve or reject.
+    jerry_value_t argument = jerry_create_number (33);
+
+    jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
+                                                           argument,
+                                                           true);
+    // 'is_ok' should be checked if it is an error or not.
+    // skipped in this example
+    jerry_release_value (is_ok);
+    jerry_release_value (argument);
+  }
+
+  jerry_value_t promise_result = jerry_get_promise_result (promise);
+  // 'promise_result' is now the number 33.
+
+  jerry_release_value (promise_result);
+  jerry_release_value (promise);
+}
+```
+
+**See also**
+
+- [jerry_create_promise](#jerry_create_promise)
+- [jerry_promise_state_t](#jerry_promise_state_t)
+
+## jerry_get_promise_state
+
+**Summary**
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API depends on a build option (`JERRY_ES2015_BUILTIN_PROMISE`) and can be checked
+  in runtime with the `JERRY_FEATURE_PROMISE` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The ES2015-subset profile enables this by default.
+
+
+**Prototype**
+
+```c
+jerry_promise_state_t
+jerry_get_promise_state (const jerry_value_t promise);
+```
+
+- `promise` - the input promise object.
+- return
+  - [jerry_promise_state_t](#jerry_promise_state_t)
+  - `JERRY_PROMISE_STATE_NONE` is returned if the input argument was not a promise object or
+    the Promise support was not built into the library.
+
+*New in version [NEXT VERSION]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+
+static void
+example (void)
+{
+  // acquire/create a promise object.
+  jerry_value_t promise = jerry_create_promise ();
+
+  jerry_promise_state_t start_state = jerry_get_promise_state (promise);
+  // a Promise have a default state of JERRY_PROMISE_STATE_PENDING
+
+  {
+    // prepare the argumnent for the resolve or reject.
+    jerry_value_t argument = jerry_create_number (33);
+
+    jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
+                                                           argument,
+                                                           true);
+    // 'is_ok' should be checked if it is an error or not.
+    // skipped in this example
+    jerry_release_value (is_ok);
+    jerry_release_value (argument);
+  }
+
+  jerry_promise_state_t current_state = jerry_get_promise_state (promise);
+  // at this point the Promise should be in the JERRY_PROMISE_STATE_FULFILLED state.
+
+  jerry_release_value (promise);
+}
+```
+
+**See also**
+
+- [jerry_create_promise](#jerry_create_promise)
+- [jerry_promise_state_t](#jerry_promise_state_t)
+
 ## jerry_resolve_or_reject_promise

 **Summary**
@@ -4078,7 +4237,7 @@ jerry_value_t
 jerry_create_string (const jerry_char_t *str_p);
 ```

- `str_p` - pointer to string
+- `str_p` - non-null pointer to string
 - return value - value of the created string

 **Example**
@@ -4117,7 +4276,7 @@ jerry_create_string_sz (const jerry_char_t *str_p,
                        jerry_size_t str_size)
 ```

- `str_p` - pointer to string
+- `str_p` - non-null pointer to string
 - `str_size` - size of the string
 - return value - value of the created string

@@ -4148,8 +4307,9 @@ jerry_create_string_sz (const jerry_char_t *str_p,

 Create string from a valid UTF8 string.

-*Note*: The difference from [jerry_create_string](#jerry_create_string) is that it accepts utf-8 string instead of cesu-8 string.
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+*Note*:
+ - The difference from [jerry_create_string](#jerry_create_string) is that it accepts utf-8 string instead of cesu-8 string.
+ - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
 is no longer needed.

 **Prototype**
@@ -4159,7 +4319,7 @@ jerry_value_t
 jerry_create_string_from_utf8 (const jerry_char_t *str_p);
 ```

- `str_p` - pointer to string
+- `str_p` - non-null pointer to string
 - return value - value of the created string

 *New in version 2.0*.
@@ -4189,19 +4349,20 @@ jerry_create_string_from_utf8 (const jerry_char_t *str_p);

 Create string from a valid UTF8 string.

-*Note*: The difference from [jerry_create_string_sz](#jerry_create_string_sz) is that it accepts utf-8 string instead of cesu-8 string.
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+*Note*:
+ - The difference from [jerry_create_string_sz](#jerry_create_string_sz) is that it accepts utf-8 string instead of cesu-8 string.
+ - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
 is no longer needed.

 **Prototype**

 ```c
 jerry_value_t
-jerry_create_string_sz (const jerry_char_t *str_p,
-                        jerry_size_t str_size)
+jerry_create_string_sz_from_utf8 (const jerry_char_t *str_p,
+                                  jerry_size_t str_size)
 ```

- `str_p` - pointer to string
+- `str_p` - non-null pointer to string
 - `str_size` - size of the string
 - return value - value of the created string

@@ -7405,6 +7566,105 @@ main (void)
 - [jerry_create_external_function](#jerry_create_external_function)


+## jerry_get_resource_name
+
+**Summary**
+
+Get the resource name (usually a file name) of the currently executed script or the given function object.
+
+This function is typically called from native callbacks.
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+- This feature depends on build option (`JERRY_LINE_INFO`) and can be checked
+  in runtime with the `JERRY_FEATURE_LINE_INFO` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_get_resource_name (jerry_value_t value);
+```
+- `value` - api value to obtain the resource name from
+- return string value constructed from
+  - the currently executed function object's resource name, if the given value is undefined
+  - resource name of the function object, if the given value is a function object
+  - "<anonymous>", otherwise
+
+**Example**
+
+[doctest]: # (name="02.API-REFERENCE-jsresourcename.c")
+
+```c
+#include <stdio.h>
+#include <string.h>
+#include "jerryscript.h"
+
+static jerry_value_t
+resource_name_handler (const jerry_value_t function_obj,
+                       const jerry_value_t this_val,
+                       const jerry_value_t args_p[],
+                       const jerry_length_t args_count)
+{
+  jerry_value_t undefined_value = jerry_create_undefined ();
+  jerry_value_t resource_name = jerry_get_resource_name (args_count > 0 ? args_p[0] : undefined_value);
+  jerry_release_value (undefined_value);
+
+  return resource_name;
+} /* resource_name_handler */
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t global = jerry_get_global_object ();
+
+  /* Register the "resourceName" method. */
+  {
+    jerry_value_t func = jerry_create_external_function (resource_name_handler);
+    jerry_value_t name = jerry_create_string ((const jerry_char_t *) "resourceName");
+    jerry_value_t result = jerry_set_property (global, name, func);
+    jerry_release_value (result);
+    jerry_release_value (name);
+    jerry_release_value (func);
+  }
+
+  jerry_release_value (global);
+
+  const jerry_char_t source[] = "function myFunction() { return resourceName() }; myFunction()";
+  const jerry_char_t resource[] = "demo.js";
+
+  jerry_value_t program = jerry_parse (resource,
+                                       sizeof (resource) - 1,
+                                       source,
+                                       sizeof (source) - 1,
+                                       JERRY_PARSE_NO_OPTS);
+
+  if (!jerry_value_is_error (program))
+  {
+    /* `run_result` contains "demo.js" */
+    jerry_value_t run_result = jerry_run (program);
+
+    /* usage of `run_result` */
+
+    jerry_release_value (run_result);
+  }
+
+  jerry_release_value (program);
+  jerry_cleanup ();
+
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_create_external_function](#jerry_create_external_function)
+
+
 # ArrayBuffer and TypedArray functions

 These APIs all depend on the ES2015-subset profile.
@@ -7642,7 +7902,7 @@ Get if the ArrayBuffer is detachable.
 **Prototype**

 ```c
-jerry_value_t 
+jerry_value_t
 jerry_is_arraybuffer_detachable (const jerry_value_t value);
 ```

@@ -7683,7 +7943,7 @@ This operation requires the ArrayBuffer to be external that created by
 **Prototype**

 ```c
-jerry_value_t 
+jerry_value_t
 jerry_detach_arraybuffer (const jerry_value_t value);
 ```