jerryx: add jerryx_arg_array (#2052)

Related issue: #2046

JerryScript-DCO-1.0-Signed-off-by: Zidong Jiang zidong.jiang@intel.com

1 files changed, 141 insertions, 0 deletions

diff --git a/docs/09.EXT-REFERENCE-ARG.md b/docs/09.EXT-REFERENCE-ARG.md
index bd17f9c0..00136f20 100644
--- a/docs/09.EXT-REFERENCE-ARG.md
+++ b/docs/09.EXT-REFERENCE-ARG.md
@@ -56,6 +56,27 @@ typedef struct
 
 - [jerryx_arg_object_properties](#jerryx_arg_object_properties)
 
+## jerryx_arg_array_items_t
+
+**Summary**
+
+The structure is used in `jerryx_arg_array`. It provides the array items' corresponding 
+JS-to-C mappings and count.
+
+**Prototype**
+
+```c
+typedef struct
+{
+  const jerryx_arg_t *c_arg_p; /**< points to the array of transformation steps */
+  jerry_length_t c_arg_cnt; /**< the count of the `c_arg_p` array */
+} jerryx_arg_array_items_t;
+```
+
+**See also**
+
+- [jerryx_arg_array](#jerryx_arg_array)
+
 ## jerryx_arg_transform_func_t
 
 **Summary**
@@ -310,6 +331,35 @@ jerryx_arg_transform_object_properties (const jerry_value_t obj_val,
 
 - [jerryx_arg_object_properties](#jerryx_arg_object_properties)
 
+## jerryx_arg_transform_array
+
+**Summary**
+
+Validate the JS array and assign its items to the native arguments.
+
+*Note*: This function transforms items of a single JS array into native C values.
+To transform multiple JS arguments in one pass, please use `jerryx_arg_array` together with
+`jerryx_arg_transform_this_and_args` or `jerryx_arg_transform_args`.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerryx_arg_transform_array (const jerry_value_t array_val,
+                            const jerryx_arg_t *c_arg_p,
+                            jerry_length_t c_arg_cnt);
+
+```
+
+ - `array_val` - the JS array.
+ - `c_arg_p` - points to the array of validation/transformation steps
+ - `c_arg_cnt` - the count of the `c_arg_p` array.
+ - return value - a `jerry_value_t` representing `undefined` if all validators passed or an `Error` if a validator failed.
+
+**See also**
+
+- [jerryx_arg_array](#jerryx_arg_array)
+
 
 # Helpers for commonly used validations
 
@@ -580,6 +630,97 @@ my_external_handler (const jerry_value_t function_obj,
 - [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args)
 - [jerryx_arg_transform_object_properties](#jerryx_arg_transform_object_properties)
 
+## jerryx_arg_array
+
+**Summary**
+
+Create a validation/transformation step (`jerryx_arg_t`) that expects to
+consume one `array` JS argument and call `jerryx_arg_transform_array_items` inside
+to transform its items to native arguments.
+User should prepare the `jerryx_arg_array_items_t` instance, and pass it to this function.
+
+**Prototype**
+
+```c
+static inline jerryx_arg_t
+jerryx_arg_array (const jerryx_arg_array_items_t *array_items_p, jerryx_arg_optional_t opt_flag);
+```
+ - return value - the created `jerryx_arg_t` instance.
+ - `array_items_p` - provides items information for transform.
+ - `opt_flag` - whether the argument is optional.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+#include "jerryscript-ext/arg.h"
+
+/**
+ * The binding function expects args_p[0] is an array, which has 3 items:
+ *     first: boolean
+ *     second: number
+ *     third: number, optional
+ */
+static jerry_value_t
+my_external_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)
+{
+  bool required_bool;
+  double required_num;
+  double optional_num = 1234.567;  // default value
+
+  /* "item_mapping" defines the steps to transform array items to C variables. */
+  const jerryx_arg_t item_mapping[] =
+  {
+    jerryx_arg_boolean (&required_bool, JERRYX_ARG_COERCE, JERRYX_ARG_REQUIRED),
+    jerryx_arg_number (&required_num, JERRYX_ARG_COERCE, JERRYX_ARG_REQUIRED),
+    jerryx_arg_number (&optional_num, JERRYX_ARG_COERCE, JERRYX_ARG_OPTIONAL)
+  };
+
+  /* Prepare the jerryx_arg_array_items_t instance. */
+  const jerryx_arg_array_items_t array_info =
+  {
+    .c_arg_p = item_mapping,
+    .c_arg_cnt = 3
+  };
+
+  /* It is the mapping used in the jerryx_arg_transform_args. */
+  const jerryx_arg_t mapping[] =
+  {
+    jerryx_arg_array (&array_info, JERRYX_ARG_REQUIRED)
+  };
+
+  /* Validate and transform. */
+  const jerry_value_t rv = jerryx_arg_transform_args (args_p,
+                                                      args_count,
+                                                      mapping,
+                                                      1);
+
+  if (jerry_value_has_error_flag (rv))
+  {
+    /* Handle error. */
+    return rv;
+  }
+
+  /*
+   * Validated and transformed successfully!
+   * required_bool, required_num and optional_num can now be used.
+   */
+
+   return jerry_create_undefined (); /* Or return something more meaningful. */
+}
+
+```
+
+ **See also**
+
+- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args)
+- [jerryx_arg_transform_object_properties](#jerryx_arg_transform_object_properties)
+
 # Functions to create custom validations
 
 ## jerryx_arg_custom