Add soft assert handler to jerry-ext (#2516)

Allow developers to choose whether they want a hard or a soft
implementation behind `assert`, i.e., whether they want to kill
the whole engine in case of an assertion failure in the executed
script or just throw a JS error.

JerryScript-DCO-1.0-Signed-off-by: Akos Kiss akiss@inf.u-szeged.hu

docs/10.EXT-REFERENCE-HANDLER.md

@@ -1,17 +1,17 @@
 #  Common external function handlers
 
-## jerryx_handler_assert
+## jerryx_handler_assert_fatal
 
 **Summary**
 
-Assert for scripts. The routine calls `jerry_port_fatal` on assertion failure.
+Hard assert for scripts. The routine calls `jerry_port_fatal` on assertion failure.
 
 **Prototype**
 
 ```c
 jerry_value_t
-jerryx_handler_assert (const jerry_value_t func_obj_val, const jerry_value_t this_p,
+jerryx_handler_assert_fatal (const jerry_value_t func_obj_val, const jerry_value_t this_p,
-                       const jerry_value_t args_p[], const jerry_length_t args_cnt);
+                             const jerry_value_t args_p[], const jerry_length_t args_cnt);
 ```
 
 - `func_obj_val` - the function object that was called (unused).
@@ -27,6 +27,43 @@ jerryx_handler_assert (const jerry_value_t func_obj_val, const jerry_value_t thi
 - [jerryx_handler_register_global](#jerryx_handler_register_global)
 
 
+## jerryx_handler_assert_throw
+
+**Summary**
+
+Soft assert for scripts. The routine throws an error on assertion failure.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerryx_handler_assert_throw (const jerry_value_t func_obj_val, const jerry_value_t this_p,
+                             const jerry_value_t args_p[], const jerry_length_t args_cnt);
+```
+
+- `func_obj_val` - the function object that was called (unused).
+- `this_p` - the `this` value of the call (unused).
+- `args_p` - the array of function arguments.
+- `args_cnt` - the number of function arguments.
+- return value - `jerry_value_t` representing boolean true, if only one argument
+  was passed and that argument was a boolean true, an error otherwise.
+
+**See also**
+
+- [jerryx_handler_register_global](#jerryx_handler_register_global)
+
+
+## jerryx_handler_assert_fatal
+
+**Summary**
+
+An alias to `jerryx_handler_assert_fatal`.
+
+**See also**
+
+- [jerryx_handler_assert_fatal](#jerryx_handler_assert_fatal)
+
+
 ## jerryx_handler_gc
 
 **Summary**

jerry-ext/handler/handler-assert.c

@@ -17,16 +17,16 @@
 #include "jerryscript-port.h"
 
 /**
- * Assert for scripts. The routine calls jerry_port_fatal on assertion failure.
+ * Hard assert for scripts. The routine calls jerry_port_fatal on assertion failure.
  *
  * @return true - if only one argument was passed and that argument was a boolean true.
  *         Note that the function does not return otherwise.
  */
 jerry_value_t
-jerryx_handler_assert (const jerry_value_t func_obj_val, /**< function object */
+jerryx_handler_assert_fatal (const jerry_value_t func_obj_val, /**< function object */
-                       const jerry_value_t this_p, /**< this arg */
+                             const jerry_value_t this_p, /**< this arg */
-                       const jerry_value_t args_p[], /**< function arguments */
+                             const jerry_value_t args_p[], /**< function arguments */
-                       const jerry_length_t args_cnt) /**< number of function arguments */
+                             const jerry_length_t args_cnt) /**< number of function arguments */
 {
   (void) func_obj_val; /* unused */
   (void) this_p; /* unused */
@@ -37,9 +37,47 @@ jerryx_handler_assert (const jerry_value_t func_obj_val, /**< function object */
   {
     return jerry_create_boolean (true);
   }
-  else
+
+  jerry_port_log (JERRY_LOG_LEVEL_ERROR, "Script Error: assertion failed\n");
+  jerry_port_fatal (ERR_FAILED_INTERNAL_ASSERTION);
+} /* jerryx_handler_assert_fatal */
+
+/**
+ * Soft assert for scripts. The routine throws an error on assertion failure.
+ *
+ * @return true - if only one argument was passed and that argument was a boolean true.
+ *         error - otherwise.
+ */
+jerry_value_t
+jerryx_handler_assert_throw (const jerry_value_t func_obj_val, /**< function object */
+                             const jerry_value_t this_p, /**< this arg */
+                             const jerry_value_t args_p[], /**< function arguments */
+                             const jerry_length_t args_cnt) /**< number of function arguments */
+{
+  (void) func_obj_val; /* unused */
+  (void) this_p; /* unused */
+
+  if (args_cnt == 1
+      && jerry_value_is_boolean (args_p[0])
+      && jerry_get_boolean_value (args_p[0]))
   {
-    jerry_port_log (JERRY_LOG_LEVEL_ERROR, "Script Error: assertion failed\n");
+    return jerry_create_boolean (true);
-    jerry_port_fatal (ERR_FAILED_INTERNAL_ASSERTION);
   }
+
+  return jerry_create_error (JERRY_ERROR_COMMON, (jerry_char_t *) "assertion failed");
+} /* jerryx_handler_assert_throw */
+
+/**
+ * An alias to `jerryx_handler_assert_fatal`.
+ *
+ * @return true - if only one argument was passed and that argument was a boolean true.
+ *         Note that the function does not return otherwise.
+ */
+jerry_value_t
+jerryx_handler_assert (const jerry_value_t func_obj_val, /**< function object */
+                       const jerry_value_t this_p, /**< this arg */
+                       const jerry_value_t args_p[], /**< function arguments */
+                       const jerry_length_t args_cnt) /**< number of function arguments */
+{
+  return jerryx_handler_assert_fatal (func_obj_val, this_p, args_p, args_cnt);
 } /* jerryx_handler_assert */

jerry-ext/include/jerryscript-ext/handler.h

@@ -34,6 +34,10 @@ jerry_value_t jerryx_handler_register_global (const jerry_char_t *name_p,
  * Common external function handlers
  */
 
+jerry_value_t jerryx_handler_assert_fatal (const jerry_value_t func_obj_val, const jerry_value_t this_p,
+                                           const jerry_value_t args_p[], const jerry_length_t args_cnt);
+jerry_value_t jerryx_handler_assert_throw (const jerry_value_t func_obj_val, const jerry_value_t this_p,
+                                           const jerry_value_t args_p[], const jerry_length_t args_cnt);
 jerry_value_t jerryx_handler_assert (const jerry_value_t func_obj_val, const jerry_value_t this_p,
                                      const jerry_value_t args_p[], const jerry_length_t args_cnt);
 jerry_value_t jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,