Merge jerry_get_value_without_error and jerry_value_clear_error_flag functions (#2350)

JerryScript-DCO-1.0-Signed-off-by: Istvan Miklos imiklos2@inf.u-szeged.hu

docs/02.API-REFERENCE.md

@@ -1710,41 +1710,71 @@ jerry_get_error_type (const jerry_value_t value);
 - [jerry_create_error](#jerry_create_error)
 - [jerry_value_is_error](#jerry_value_is_error)
 
-## jerry_value_clear_error_flag
+## jerry_get_value_from_error
 
 **Summary**
 
-Clear both the error and abort flags.
+Get the value from an error.
+
+Many API functions cannot be called with an error value.
+This function extracts the API value from an error. The second argument defines
+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.
+
+*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
 
 **Prototype**
 
 ```c
-void
+jerry_value_t
-jerry_value_clear_error_flag (jerry_value_t *value_p);
+jerry_get_value_from_error (jerry_value_t value, bool release)
 ```
 
-- `value_p` - pointer to an api value
+- `value` - error (api) value
+- `release` - raw boolean, defines whether input value must be released
+- return value - api value
 
-**Example**
+**Example 1**
 
 ```c
 {
-  jerry_value_t value;
+  jerry_value_t error;
   ... // create or acquire value
 
-  jerry_value_clear_error_flag (&value);
+  jerry_value_set_error_flag (&error);
+  jerry_value_t value = jerry_get_value_from_error (error, true);
+  // using the 'error' variable after release is invalid.
 
   jerry_release_value (value);
 }
 ```
 
+**Example 2**
+
+```c
+{
+  jerry_value_t error;
+  ... // create or acquire value
+
+  jerry_value_set_error_flag (&error);
+  jerry_value_t value = jerry_get_value_from_error (error, false);
+  // both 'error' and 'value' can be used and must be released when they are no longer needed
+
+  jerry_release_value (value);
+  jerry_release_value (error);
+}
+```
+
 **See also**
 
 - [jerry_value_t](#jerry_value_t)
 - [jerry_value_set_error_flag](#jerry_value_set_error_flag)
 - [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
 
-
 ## jerry_value_set_error_flag
 
 **Summary**
@@ -1776,7 +1806,7 @@ jerry_value_set_error_flag (jerry_value_t *value_p);
 **See also**
 
 - [jerry_value_t](#jerry_value_t)
-- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag)
+- [jerry_get_value_from_error](#jerry_get_value_from_error)
 - [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
 
 
@@ -1811,53 +1841,10 @@ jerry_value_set_abort_flag (jerry_value_t *value_p);
 **See also**
 
 - [jerry_value_t](#jerry_value_t)
-- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag)
+- [jerry_get_value_from_error](#jerry_get_value_from_error)
 - [jerry_value_set_error_flag](#jerry_value_set_error_flag)
 
 
-## jerry_get_value_without_error_flag
-
-**Summary**
-
-If the input value is an error value, then return a new reference to its referenced value.
-Otherwise, return a new reference to the value itself.
-
-*Note*: 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_value_without_error_flag (jerry_value_t value)
-```
-
-- `value` - api value
-
-**Example**
-
-```c
-{
-  jerry_value_t value;
-  ... // create or acquire value
-
-  jerry_value_set_error_flag (&value);
-
-  jerry_value_t real_value = jerry_get_value_without_error_flag (value);
-  ... // process the real_value. Different from `jerry_value_clear_error_flag`,
-      // the error `value` will not be automatically released after calling
-      // `jerry_get_value_without_error_flag`.
-
-  jerry_release_value (value);
-  jerry_release_value (real_value);
-}
-```
-
-**See also**
-
-- [jerry_acquire_value](#jerry_acquire_value)
-- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag)
-
 # Getter functions of 'jerry_value_t'
 
 Get raw data from API values.
@@ -2892,7 +2879,7 @@ jerry_create_error (jerry_error_t error_type,
 **See also**
 
 - [jerry_value_is_error](#jerry_value_is_error)
-- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag)
+- [jerry_get_value_from_error](#jerry_get_value_from_error)
 - [jerry_value_set_error_flag](#jerry_value_set_error_flag)
 
 

jerry-core/api/jerry.c

@@ -903,18 +903,35 @@ jerry_is_feature_enabled (const jerry_feature_t feature) /**< feature to check *
 } /* jerry_is_feature_enabled */
 
 /**
- * Clear the error flag
+ * Get the value from an error value.
+ *
+ * Extract the api value from an error. If the second argument is true
+ * it will release the input error value.
+ *
+ * Note:
+ *      returned value must be freed with jerry_release_value, when it is no longer needed.
+ *
+ * @return jerry_value_t value
  */
-void
+jerry_value_t
-jerry_value_clear_error_flag (jerry_value_t *value_p) /**< api value */
+jerry_get_value_from_error (jerry_value_t value, /**< api value */
+                            bool release) /**< release api value */
 {
   jerry_assert_api_available ();
 
-  if (ecma_is_value_error_reference (*value_p))
+  if (!ecma_is_value_error_reference (value))
   {
-    *value_p = ecma_clear_error_reference (*value_p, false);
+    return value;
   }
-} /* jerry_value_clear_error_flag */
+
+  jerry_value_t ret_val = jerry_acquire_value (ecma_get_error_reference_from_value (value)->value);
+
+  if (release)
+  {
+    jerry_release_value (value);
+  }
+  return ret_val;
+} /* jerry_get_value_from_error */
 
 /**
  * Set the error flag if the value is not an error reference.
@@ -932,8 +949,7 @@ jerry_value_set_error_flag (jerry_value_t *value_p) /**< api value */
     {
       return;
     }
-
+    *value_p = ecma_clear_error_reference (*value_p, false);
-    jerry_value_clear_error_flag (value_p);
   }
 
   *value_p = ecma_create_error_reference (*value_p, true);
@@ -955,27 +971,12 @@ jerry_value_set_abort_flag (jerry_value_t *value_p) /**< api value */
     {
       return;
     }
-
+    *value_p = ecma_clear_error_reference (*value_p, false);
-    jerry_value_clear_error_flag (value_p);
   }
 
   *value_p = ecma_create_error_reference (*value_p, false);
 } /* jerry_value_set_abort_flag */
 
-/**
- * If the input value is an error value, then return a new reference to its referenced value.
- * Otherwise, return a new reference to the value itself.
- *
- * Note:
- *      returned value must be freed with jerry_release_value, when it is no longer needed.
- *
- * @return the real value of the jerry_value
- */
-jerry_value_t jerry_get_value_without_error_flag (jerry_value_t value) /**< api value */
-{
-  return jerry_acquire_value (jerry_get_arg_value (value));
-} /* jerry_get_value_without_error_flag */
-
 /**
  * Return the type of the Error object if possible.
  *

jerry-core/include/jerryscript-core.h

@@ -368,10 +368,9 @@ bool jerry_is_feature_enabled (const jerry_feature_t feature);
 /**
  * Error manipulation functions.
  */
-void jerry_value_clear_error_flag (jerry_value_t *value_p);
+jerry_value_t jerry_get_value_from_error (jerry_value_t value, bool release);
 void jerry_value_set_error_flag (jerry_value_t *value_p);
 void jerry_value_set_abort_flag (jerry_value_t *value_p);
-jerry_value_t jerry_get_value_without_error_flag (jerry_value_t value);
 
 /**
  * Error object function(s).

jerry-main/main-unix-snapshot.c

@@ -320,7 +320,7 @@ process_generate (cli_state_t *cli_state_p, /**< cli state */
   {
     jerry_port_log (JERRY_LOG_LEVEL_ERROR, "Error: Generating snapshot failed!\n");
 
-    jerry_value_clear_error_flag (&snapshot_result);
+    snapshot_result = jerry_get_value_from_error (snapshot_result, true);
 
     print_unhandled_exception (snapshot_result);
 

jerry-main/main-unix.c

@@ -265,7 +265,7 @@ register_js_function (const char *name_p, /**< name of the function */
   if (jerry_value_is_error (result_val))
   {
     jerry_port_log (JERRY_LOG_LEVEL_WARNING, "Warning: failed to register '%s' method.", name_p);
-    jerry_value_clear_error_flag (&result_val);
+    result_val = jerry_get_value_from_error (result_val, true);
     print_unhandled_exception (result_val);
   }
 
@@ -772,13 +772,13 @@ main (int argc,
 
           if (jerry_value_is_error (ret_val_eval))
           {
-            jerry_value_clear_error_flag (&ret_val_eval);
+            ret_val_eval = jerry_get_value_from_error (ret_val_eval, true);
             print_unhandled_exception (ret_val_eval);
           }
         }
         else
         {
-          jerry_value_clear_error_flag (&ret_val_eval);
+          ret_val_eval = jerry_get_value_from_error (ret_val_eval, true);
           print_unhandled_exception (ret_val_eval);
         }
 
@@ -791,7 +791,7 @@ main (int argc,
 
   if (jerry_value_is_error (ret_value))
   {
-    jerry_value_clear_error_flag (&ret_value);
+    ret_value = jerry_get_value_from_error (ret_value, true);
     print_unhandled_exception (ret_value);
 
     ret_code = JERRY_STANDALONE_EXIT_CODE_FAIL;
@@ -803,7 +803,7 @@ main (int argc,
 
   if (jerry_value_is_error (ret_value))
   {
-    jerry_value_clear_error_flag (&ret_value);
+    ret_value = jerry_get_value_from_error (ret_value, true);
     print_unhandled_exception (ret_value);
     ret_code = JERRY_STANDALONE_EXIT_CODE_FAIL;
   }

targets/curie_bsp/jerry_app/quark/main.c

@@ -46,7 +46,7 @@ void jerry_resolve_error (jerry_value_t ret_value)
 {
   if (jerry_value_is_error (ret_value))
   {
-    jerry_value_clear_error_flag (&ret_value);
+    ret_value = jerry_get_value_from_error (ret_value, true);
     jerry_value_t err_str_val = jerry_value_to_string (ret_value);
     jerry_size_t err_str_size = jerry_get_string_size (err_str_val);
     jerry_char_t *err_str_buf = (jerry_char_t *) balloc (err_str_size, NULL);

targets/nuttx-stm32f4/jerry_main.c

@@ -152,7 +152,7 @@ print_unhandled_exception (jerry_value_t error_value, /**< error value */
 {
   assert (jerry_value_is_error (error_value));
 
-  error_value = jerry_get_value_without_error_flag (error_value);
+  error_value = jerry_get_value_from_error (error_value, false);
   jerry_value_t err_str_val = jerry_value_to_string (error_value);
   jerry_size_t err_str_size = jerry_get_string_size (err_str_val);
   jerry_char_t err_str_buf[256];

targets/tizenrt-artik053/apps/jerryscript/jerry_main.c

@@ -130,7 +130,7 @@ print_unhandled_exception (jerry_value_t error_value, /**< error value */
 {
   assert (jerry_value_is_error (error_value));
 
-  error_value = jerry_get_value_without_error_flag (error_value);
+  error_value = jerry_get_value_from_error (error_value, false);
   jerry_value_t err_str_val = jerry_value_to_string (error_value);
   jerry_size_t err_str_size = jerry_get_string_size (err_str_val);
   jerry_char_t err_str_buf[256];

targets/zephyr/src/main-zephyr.c

@@ -60,7 +60,7 @@ static int shell_cmd_handler (char *source_buffer)
     printf ("Error executing statement: ");
     /* Clear error flag, otherwise print call below won't produce any
        output. */
-    jerry_value_clear_error_flag (&ret_val);
+    ret_val = jerry_get_value_from_error (ret_val, true);
   }
 
   if (!jerry_value_is_error (print_function))

tests/unit-core/test-api-errortype.c

@@ -40,7 +40,7 @@ main (void)
     TEST_ASSERT (jerry_value_is_error (error_obj));
     TEST_ASSERT (jerry_get_error_type (error_obj) == errors[idx]);
 
-    jerry_value_clear_error_flag (&error_obj);
+    error_obj = jerry_get_value_from_error (error_obj, true);
 
     TEST_ASSERT (jerry_get_error_type (error_obj) == errors[idx]);
 

tests/unit-core/test-api-set-and-clear-error-flag.c

@@ -27,10 +27,11 @@ main (void)
   jerry_value_set_error_flag (&obj_val);
   jerry_value_t err_val = jerry_acquire_value (obj_val);
 
-  jerry_value_clear_error_flag (&obj_val);
+  obj_val = jerry_get_value_from_error (err_val, true);
-  jerry_release_value (obj_val);
 
+  JERRY_ASSERT (obj_val != err_val);
   jerry_release_value (err_val);
+  jerry_release_value (obj_val);
 
   jerry_cleanup ();
 } /* main */

tests/unit-core/test-api.c

@@ -1049,17 +1049,21 @@ main (void)
 
   TEST_ASSERT (test_api_is_free_callback_was_called);
 
-  /* Test: jerry_get_value_without_error_flag */
+  /* Test: jerry_get_value_from_error */
   {
     jerry_init (JERRY_INIT_EMPTY);
     jerry_value_t num_val = jerry_create_number (123);
     jerry_value_set_error_flag (&num_val);
     TEST_ASSERT (jerry_value_is_error (num_val));
-    jerry_value_t num2_val = jerry_get_value_without_error_flag (num_val);
+    jerry_value_t num2_val = jerry_get_value_from_error (num_val, false);
+    TEST_ASSERT (jerry_value_is_error (num_val));
     TEST_ASSERT (!jerry_value_is_error (num2_val));
     double num = jerry_get_number_value (num2_val);
     TEST_ASSERT (num == 123);
-    jerry_release_value (num_val);
+    num2_val = jerry_get_value_from_error (num_val, true);
+    TEST_ASSERT (!jerry_value_is_error (num2_val));
+    num = jerry_get_number_value (num2_val);
+    TEST_ASSERT (num == 123);
     jerry_release_value (num2_val);
     jerry_cleanup ();
   }
@@ -1076,7 +1080,7 @@ main (void)
                                    strlen (parser_err_src_p),
                                    JERRY_PARSE_NO_OPTS);
     TEST_ASSERT (jerry_value_is_error (parsed_code_val));
-    jerry_value_clear_error_flag (&parsed_code_val);
+    parsed_code_val = jerry_get_value_from_error (parsed_code_val, true);
     jerry_value_t err_str_val = jerry_value_to_string (parsed_code_val);
     jerry_size_t err_str_size = jerry_get_string_size (err_str_val);
     jerry_char_t err_str_buf[256];

tests/unit-core/test-backtrace.c

@@ -175,7 +175,7 @@ main (void)
 
   TEST_ASSERT (jerry_value_is_error (error));
 
-  jerry_value_clear_error_flag (&error);
+  error = jerry_get_value_from_error (error, true);
 
   TEST_ASSERT (jerry_value_is_object (error));