Implement vm throw capture status management for API errors (#4783)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com

Author: zherczeg

docs/02.API-REFERENCE.md

@@ -3862,6 +3862,228 @@ void main(void)
 
 - [jerry_error_object_created_callback_t](#jerry_error_object_created_callback_t)
 
+## jerry_set_vm_throw_callback
+
+**Summary**
+
+The callback passed to this function is called when an error is thrown
+in ECMAScript code. The callback is not called again until the value is
+caught. See: [jerry_vm_throw_callback_t](#jerry_vm_throw_callback_t).
+
+*Notes*:
+- This API depends on a build option (`JERRY_VM_THROW`) and can be checked
+  in runtime with the `JERRY_FEATURE_VM_THROW` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+void
+jerry_set_vm_throw_callback (jerry_vm_throw_callback_t throw_cb,
+                             void *user_p);
+```
+
+- `throw_cb` - callback which is called on throws (passing NULL disables this feature)
+- `user_p` - user pointer passed to the `throw_cb` function
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+
+static void
+vm_throw_callback (const jerry_value_t error_value, /**< captured error */
+                   void *user_p) /**< user pointer */
+{
+  (void) error_value;
+
+  /* Counts the number of throws. */
+  int *counter_p = (int *) user_p;
+  (*counter_p)++;
+}
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  int counter = 0;
+  jerry_set_vm_throw_callback (vm_throw_callback, &counter);
+
+  const jerry_char_t script[] = "try { throw new Error('1') } catch (e) { throw new Error('2') }";
+
+  jerry_release_value (jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS));
+
+  /* The counter contains 2. */
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_vm_throw_callback_t](#jerry_vm_throw_callback_t)
+- [jerry_error_is_throw_captured](#jerry_error_is_throw_captured)
+- [jerry_error_set_throw_capture](#jerry_error_set_throw_capture)
+
+## jerry_error_is_throw_captured
+
+**Summary**
+
+Checks whether the callback set by [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback)
+captured the error.
+
+*Notes*:
+- This API depends on a build option (`JERRY_VM_THROW`) and can be checked
+  in runtime with the `JERRY_FEATURE_VM_THROW` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+bool jerry_error_is_throw_captured (jerry_value_t value);
+```
+
+- `value` - api value (should be an error reference)
+- return value
+  - true, if the vm throw callback captured the error
+  - false, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+
+static void
+vm_throw_callback (const jerry_value_t error_value, /**< captured error */
+                   void *user_p) /**< user pointer */
+{
+  (void) error_value;
+  (void) user_p;
+}
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  int counter = 0;
+  jerry_set_vm_throw_callback (vm_throw_callback, &counter);
+
+  const jerry_char_t script[] = "throw new Error()";
+  jerry_value_t result_value = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
+
+  if (jerry_error_is_throw_captured (result_value))
+  {
+    /* Code enters here, because the vm_throw_callback function is called. */
+  }
+
+  jerry_release_value (result_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback)
+- [jerry_error_set_throw_capture](#jerry_error_set_throw_capture)
+
+## jerry_error_set_throw_capture
+
+**Summary**
+
+Sets whether the callback set by [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback)
+should capture the error or not.
+
+*Notes*:
+- This API depends on a build option (`JERRY_VM_THROW`) and can be checked
+  in runtime with the `JERRY_FEATURE_VM_THROW` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+void jerry_error_set_throw_capture (jerry_value_t value, bool should_capture);
+```
+
+- `value` - api value (should be an error reference)
+- `should_capture` - callback should capture this error
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+
+static void
+vm_throw_callback (const jerry_value_t error_value, /**< captured error */
+                   void *user_p) /**< user pointer */
+{
+  (void) error_value;
+  (void) user_p;
+}
+
+static jerry_value_t
+throw_exception (const jerry_call_info_t *call_info_p, /**< call info */
+                 const jerry_value_t argv[], /**< argument list */
+                 const jerry_length_t argc) /**< argument count */
+{
+  (void) call_info_p;
+  (void) argv;
+  (void) argc;
+
+  jerry_value_t result_value = jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Error!");
+
+  /* Ignore calling the vm_throw_callback function. */
+  jerry_error_set_throw_capture (result_value, false);
+  return result_value;
+}
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  int counter = 0;
+  jerry_set_vm_throw_callback (vm_throw_callback, &counter);
+
+  jerry_value_t global_object_value = jerry_get_global_object ();
+  jerry_value_t function_value = jerry_create_external_function (throw_exception);
+  jerry_value_t function_name_value = jerry_create_string ((const jerry_char_t *) "throw_exception");
+
+  jerry_release_value (jerry_set_property (global_object_value, function_name_value, function_value));
+  jerry_release_value (function_name_value);
+  jerry_release_value (function_value);
+  jerry_release_value (global_object_value);
+
+  const jerry_char_t script[] = "throw_exception()";
+  jerry_release_value (jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS));
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback)
+- [jerry_error_is_throw_captured](#jerry_error_is_throw_captured)
+
+
 # Getter functions of 'jerry_value_t'
 
 Get raw data from API values.
@@ -11680,75 +11902,6 @@ main (void)
 
 - [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t)
 
-## jerry_set_vm_throw_callback
-
-**Summary**
-
-The callback passed to this function is called when an error is thrown
-in ECMAScript code. The callback is not called again until the value is
-caught. See: [jerry_vm_throw_callback_t](#jerry_vm_throw_callback_t).
-
-*Notes*:
-- This API depends on a build option (`JERRY_VM_THROW`) and can be checked
-  in runtime with the `JERRY_FEATURE_VM_THROW` feature enum value,
-  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
-
-**Prototype**
-
-```c
-void
-jerry_set_vm_throw_callback (jerry_vm_throw_callback_t throw_cb,
-                             void *user_p);
-```
-
-- `throw_cb` - callback which is called on throws (passing NULL disables this feature)
-- `user_p` - user pointer passed to the `throw_cb` function
-
-*New in version [[NEXT_RELEASE]]*.
-
-**Example**
-
-[doctest]: # (test="compile")
-
-```c
-#include "jerryscript.h"
-
-static void
-vm_throw_callback (const jerry_value_t error_value, /**< captured error */
-                   void *user_p) /**< user pointer */
-{
-  (void) error_value;
-
-  /* Counts the number of throws. */
-  int *counter_p = (int *) user_p;
-  (*counter_p)++;
-}
-
-int
-main (void)
-{
-  jerry_init (JERRY_INIT_EMPTY);
-
-  int counter = 0;
-  jerry_set_vm_throw_callback (vm_throw_callback, &counter);
-
-  const jerry_char_t script[] = "try { throw new Error('1') } catch (e) { throw new Error('2') }";
-
-  jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL);
-  jerry_release_value (jerry_run (parsed_code));
-  jerry_release_value (parsed_code);
-
-  /* The counter contains 2. */
-
-  jerry_cleanup ();
-  return 0;
-}
-```
-
-**See also**
-
-- [jerry_vm_throw_callback_t](#jerry_vm_throw_callback_t)
-
 ## jerry_get_resource_name
 
 **Summary**