A tool in jerry-ext: arg transformer for binding (#1740)

It provides some APIs for binding developers, so that
they can validate the type of the js argument and convert/assign them
to the native argument.

Related Issue: #1716

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

jerry-ext/arg/arg-internal.h

@@ -0,0 +1,31 @@
+/* Copyright JS Foundation and other contributors, http://js.foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef JERRYX_ARG_INTERNAL_H
+#define JERRYX_ARG_INTERNAL_H
+
+#include "jerryscript.h"
+
+/**
+ * The iterator structor for JS arguments.
+ */
+struct jerryx_arg_js_iterator_t
+{
+  const jerry_value_t *js_arg_p; /**< the JS arguments */
+  const jerry_length_t js_arg_cnt; /**< the total num of JS arguments */
+  jerry_length_t js_arg_idx; /**< current index of JS argument */
+};
+
+#endif /* !JERRYX_ARG_INTERNAL_H */

jerry-ext/arg/arg-js-iterator-helper.c

@@ -0,0 +1,58 @@
+/* Copyright JS Foundation and other contributors, http://js.foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "arg-internal.h"
+#include "jerryscript-ext/arg.h"
+#include "jerryscript.h"
+
+/**
+ * Pop the current JS argument from the iterator.
+ * It will change the index and js_arg_p value in the iterator.
+ *
+ * @return the current JS argument.
+ */
+jerry_value_t
+jerryx_arg_js_iterator_pop (jerryx_arg_js_iterator_t *js_arg_iter_p) /**< the JS arg iterator */
+{
+  return (js_arg_iter_p->js_arg_idx++ < js_arg_iter_p->js_arg_cnt ? *js_arg_iter_p->js_arg_p++
+                                                                  : jerry_create_undefined ());
+} /* jerryx_arg_js_iterator_pop */
+
+/**
+ * Get the current JS argument from the iterator.
+ *
+ * Note:
+ *     Unlike jerryx_arg_js_iterator_pop, it will not change index and
+ *     js_arg_p value in the iterator.
+ *
+ * @return the current JS argument.
+ */
+jerry_value_t
+jerryx_arg_js_iterator_peek (jerryx_arg_js_iterator_t *js_arg_iter_p) /**< the JS arg iterator */
+{
+  return (js_arg_iter_p->js_arg_idx < js_arg_iter_p->js_arg_cnt ? *js_arg_iter_p->js_arg_p
+                                                                : jerry_create_undefined ());
+} /* jerryx_arg_js_iterator_peek */
+
+/**
+ * Get the index of the current JS argument
+ *
+ * @return the index
+ */
+jerry_length_t
+jerryx_arg_js_iterator_index (jerryx_arg_js_iterator_t *js_arg_iter_p) /**< the JS arg iterator */
+{
+  return js_arg_iter_p->js_arg_idx;
+} /* jerryx_arg_js_iterator_index */

jerry-ext/arg/arg-transform-functions.c

@@ -0,0 +1,301 @@
+/* Copyright JS Foundation and other contributors, http://js.foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "jerryscript-ext/arg.h"
+#include "jerryscript.h"
+
+/**
+ * The common function to deal with optional arguments.
+ * The core transform function is provided by argument `func`.
+ *
+ * @return jerry undefined: the transformer passes,
+ *         jerry error: the transformer fails.
+ */
+jerry_value_t
+jerryx_arg_transform_optional (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */
+                               const jerryx_arg_t *c_arg_p, /**< native arg */
+                               jerryx_arg_transform_func_t func) /**< the core transform function */
+{
+  jerry_value_t js_arg = jerryx_arg_js_iterator_peek (js_arg_iter_p);
+
+  if (jerry_value_is_undefined (js_arg))
+  {
+    return js_arg;
+  }
+
+  return func (js_arg_iter_p, c_arg_p);
+} /* jerryx_arg_transform_optional */
+
+/**
+ * Tranform a JS argument to a double. Type coercion is not allowed.
+ *
+ * @return jerry undefined: the transformer passes,
+ *         jerry error: the transformer fails.
+ */
+jerry_value_t
+jerryx_arg_transform_number_strict (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */
+                                    const jerryx_arg_t *c_arg_p) /**< the native arg */
+{
+  jerry_value_t js_arg = jerryx_arg_js_iterator_pop (js_arg_iter_p);
+
+  if (!jerry_value_is_number (js_arg))
+  {
+    return jerry_create_error (JERRY_ERROR_TYPE,
+                               (jerry_char_t *) "It is not a number.");
+  }
+
+  double *dest = c_arg_p->dest;
+  *dest = jerry_get_number_value (js_arg);
+
+  return jerry_create_undefined ();
+} /* jerryx_arg_transform_number_strict */
+
+/**
+ * Tranform a JS argument to a double. Type coercion is allowed.
+ *
+ * @return jerry undefined: the transformer passes,
+ *         jerry error: the transformer fails.
+ */
+jerry_value_t
+jerryx_arg_transform_number (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */
+                             const jerryx_arg_t *c_arg_p) /**< the native arg */
+{
+  jerry_value_t js_arg = jerryx_arg_js_iterator_pop (js_arg_iter_p);
+
+  jerry_value_t to_number = jerry_value_to_number (js_arg);
+
+  if (jerry_value_has_error_flag (to_number))
+  {
+    jerry_release_value (to_number);
+
+    return jerry_create_error (JERRY_ERROR_TYPE,
+                               (jerry_char_t *) "It can not be converted to a number.");
+  }
+
+  double *dest = c_arg_p->dest;
+  *dest = jerry_get_number_value (to_number);
+  jerry_release_value (to_number);
+
+  return jerry_create_undefined ();
+} /* jerryx_arg_transform_number */
+
+/**
+ * Tranform a JS argument to a boolean. Type coercion is not allowed.
+ *
+ * @return jerry undefined: the transformer passes,
+ *         jerry error: the transformer fails.
+ */
+jerry_value_t
+jerryx_arg_transform_boolean_strict (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */
+                                     const jerryx_arg_t *c_arg_p) /**< the native arg */
+{
+  jerry_value_t js_arg = jerryx_arg_js_iterator_pop (js_arg_iter_p);
+
+  if (!jerry_value_is_boolean (js_arg))
+  {
+    return jerry_create_error (JERRY_ERROR_TYPE,
+                               (jerry_char_t *) "It is not a boolean.");
+  }
+
+  bool *dest = c_arg_p->dest;
+  *dest = jerry_get_boolean_value (js_arg);
+
+  return jerry_create_undefined ();
+} /* jerryx_arg_transform_boolean_strict */
+
+/**
+ * Tranform a JS argument to a boolean. Type coercion is allowed.
+ *
+ * @return jerry undefined: the transformer passes,
+ *         jerry error: the transformer fails.
+ */
+jerry_value_t
+jerryx_arg_transform_boolean (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */
+                              const jerryx_arg_t *c_arg_p) /**< the native arg */
+{
+  jerry_value_t js_arg = jerryx_arg_js_iterator_pop (js_arg_iter_p);
+
+  bool to_boolean = jerry_value_to_boolean (js_arg);
+
+  bool *dest = c_arg_p->dest;
+  *dest = to_boolean;
+
+  return jerry_create_undefined ();
+} /* jerryx_arg_transform_boolean */
+
+/**
+ * The common routine for string transformer.
+ *
+ * @return jerry undefined: the transformer passes,
+ *         jerry error: the transformer fails.
+ */
+static jerry_value_t
+jerryx_arg_string_common_routine (jerry_value_t js_arg, /**< JS arg */
+                                  const jerryx_arg_t *c_arg_p) /**< native arg */
+{
+  jerry_size_t size = jerry_string_to_char_buffer (js_arg,
+                                                   (jerry_char_t *) c_arg_p->dest,
+                                                   (jerry_size_t) c_arg_p->extra_info);
+
+  if (size == 0)
+  {
+    return jerry_create_error (JERRY_ERROR_TYPE,
+                               (jerry_char_t *) "The size of the buffer is not large enough.");
+  }
+
+  return jerry_create_undefined ();
+} /* jerryx_arg_string_common_routine */
+
+/**
+ * Tranform a JS argument to a char array. Type coercion is not allowed.
+ *
+ * @return jerry undefined: the transformer passes,
+ *         jerry error: the transformer fails.
+ */
+jerry_value_t
+jerryx_arg_transform_string_strict (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */
+                                    const jerryx_arg_t *c_arg_p) /**< the native arg */
+{
+  jerry_value_t js_arg = jerryx_arg_js_iterator_pop (js_arg_iter_p);
+
+  if (!jerry_value_is_string (js_arg))
+  {
+    return jerry_create_error (JERRY_ERROR_TYPE,
+                               (jerry_char_t *) "It is not a string.");
+  }
+
+  return jerryx_arg_string_common_routine (js_arg, c_arg_p);
+} /* jerryx_arg_transform_string_strict */
+
+/**
+ * Tranform a JS argument to a char array. Type coercion is allowed.
+ *
+ * @return jerry undefined: the transformer passes,
+ *         jerry error: the transformer fails.
+ */
+jerry_value_t
+jerryx_arg_transform_string (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */
+                             const jerryx_arg_t *c_arg_p) /**< the native arg */
+{
+  jerry_value_t js_arg = jerryx_arg_js_iterator_pop (js_arg_iter_p);
+
+  jerry_value_t to_string = jerry_value_to_string (js_arg);
+
+  if (jerry_value_has_error_flag (to_string))
+  {
+    jerry_release_value (to_string);
+
+    return jerry_create_error (JERRY_ERROR_TYPE,
+                               (jerry_char_t *) "It can not be converted to a string.");
+  }
+
+  jerry_value_t ret = jerryx_arg_string_common_routine (to_string, c_arg_p);
+  jerry_release_value (to_string);
+
+  return ret;
+} /* jerryx_arg_transform_string */
+
+/**
+ * Check whether the JS argument is jerry function, if so, assign to the native argument.
+ *
+ * @return jerry undefined: the transformer passes,
+ *         jerry error: the transformer fails.
+ */
+jerry_value_t
+jerryx_arg_transform_function (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */
+                               const jerryx_arg_t *c_arg_p) /**< the native arg */
+{
+  jerry_value_t js_arg = jerryx_arg_js_iterator_pop (js_arg_iter_p);
+
+  if (!jerry_value_is_function (js_arg))
+  {
+    return jerry_create_error (JERRY_ERROR_TYPE,
+                               (jerry_char_t *) "It is not a function.");
+  }
+
+  jerry_value_t *func_p = c_arg_p->dest;
+  *func_p = jerry_acquire_value (js_arg);
+
+  return jerry_create_undefined ();
+} /* jerryx_arg_transform_function */
+
+/**
+ * Check whether the native pointer has the expected type info.
+ * If so, assign it to the native argument.
+ *
+ * @return jerry undefined: the transformer passes,
+ *         jerry error: the transformer fails.
+ */
+jerry_value_t
+jerryx_arg_transform_native_pointer (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */
+                                     const jerryx_arg_t *c_arg_p) /**< the native arg */
+{
+  jerry_value_t js_arg = jerryx_arg_js_iterator_pop (js_arg_iter_p);
+
+  if (!jerry_value_is_object (js_arg))
+  {
+    return jerry_create_error (JERRY_ERROR_TYPE,
+                               (jerry_char_t *) "It is not a object.");
+  }
+
+  const jerry_object_native_info_t *expected_info_p;
+  const jerry_object_native_info_t *out_info_p;
+  expected_info_p = (const jerry_object_native_info_t *) c_arg_p->extra_info;
+  void **ptr_p = (void **) c_arg_p->dest;
+  bool is_ok = jerry_get_object_native_pointer (js_arg, ptr_p, &out_info_p);
+
+  if (!is_ok || out_info_p != expected_info_p)
+  {
+    return jerry_create_error (JERRY_ERROR_TYPE,
+                               (jerry_char_t *) "The object has no native pointer or type does not match.");
+  }
+
+  return jerry_create_undefined ();
+} /* jerryx_arg_transform_native_pointer */
+
+/**
+ * Define transformer for optional argument.
+ */
+#define JERRYX_ARG_TRANSFORM_OPTIONAL(type) \
+jerry_value_t \
+jerryx_arg_transform_ ## type ## _optional (jerryx_arg_js_iterator_t *js_arg_iter_p, \
+                                            const jerryx_arg_t *c_arg_p) \
+{ \
+  return jerryx_arg_transform_optional (js_arg_iter_p, c_arg_p, jerryx_arg_transform_ ## type); \
+}
+
+JERRYX_ARG_TRANSFORM_OPTIONAL (number)
+JERRYX_ARG_TRANSFORM_OPTIONAL (number_strict)
+JERRYX_ARG_TRANSFORM_OPTIONAL (boolean)
+JERRYX_ARG_TRANSFORM_OPTIONAL (boolean_strict)
+JERRYX_ARG_TRANSFORM_OPTIONAL (string)
+JERRYX_ARG_TRANSFORM_OPTIONAL (string_strict)
+JERRYX_ARG_TRANSFORM_OPTIONAL (function)
+JERRYX_ARG_TRANSFORM_OPTIONAL (native_pointer)
+
+/**
+ * Ignore the JS argument.
+ *
+ * @return jerry undefined
+ */
+jerry_value_t
+jerryx_arg_transform_ignore (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */
+                             const jerryx_arg_t *c_arg_p) /**< the native arg */
+{
+  (void) js_arg_iter_p; /* unused */
+  (void) c_arg_p; /* unused */
+
+  return jerry_create_undefined ();
+} /* jerryx_arg_transform_ignore */

jerry-ext/arg/arg.c

@@ -0,0 +1,88 @@
+/* Copyright JS Foundation and other contributors, http://js.foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "arg-internal.h"
+#include "jerryscript-ext/arg.h"
+#include "jerryscript.h"
+
+/**
+ * Validate the JS arguments and assign them to the native arguments.
+ *
+ * @return jerry undefined: all validators passed,
+ *         jerry error: a validator failed.
+ */
+jerry_value_t
+jerryx_arg_transform_args (const jerry_value_t *js_arg_p, /**< points to the array with JS arguments */
+                           const jerry_length_t js_arg_cnt, /**< the count of the `js_arg_p` array */
+                           const jerryx_arg_t *c_arg_p, /**< points to the array of validation/transformation steps */
+                           jerry_length_t c_arg_cnt) /**< the count of the `c_arg_p` array */
+{
+  jerry_value_t ret = jerry_create_undefined ();
+
+  jerryx_arg_js_iterator_t iterator =
+  {
+    .js_arg_p = js_arg_p,
+    .js_arg_cnt = js_arg_cnt,
+    .js_arg_idx = 0
+  };
+
+  for (; c_arg_cnt != 0 && !jerry_value_has_error_flag (ret); c_arg_cnt--, c_arg_p++)
+  {
+    ret = c_arg_p->func (&iterator, c_arg_p);
+  }
+
+  return ret;
+} /* jerryx_arg_transform_args */
+
+/**
+ * Validate the this value and the JS arguments,
+ * and assign them to the native arguments.
+ * This function is useful to perform input validation inside external
+ * function handlers (see jerry_external_handler_t).
+ * @note this_val is processed as the first value, before the array of arguments.
+ *
+ * @return jerry undefined: all validators passed,
+ *         jerry error: a validator failed.
+ */
+jerry_value_t
+jerryx_arg_transform_this_and_args (const jerry_value_t this_val, /**< the this_val for the external function */
+                                    const jerry_value_t *js_arg_p, /**< points to the array with JS arguments */
+                                    const jerry_length_t js_arg_cnt, /**< the count of the `js_arg_p` array */
+                                    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 */
+{
+  if (c_arg_cnt == 0)
+  {
+    return jerry_create_undefined ();
+  }
+
+  jerryx_arg_js_iterator_t iterator =
+  {
+    .js_arg_p = &this_val,
+    .js_arg_cnt = 1,
+    .js_arg_idx = 0
+  };
+
+  jerry_value_t ret = c_arg_p->func (&iterator, c_arg_p);
+
+  if (jerry_value_has_error_flag (ret))
+  {
+    jerry_release_value (ret);
+
+    return jerry_create_error (JERRY_ERROR_TYPE, (jerry_char_t *) "'this' validation failed");
+  }
+
+  return jerryx_arg_transform_args (js_arg_p, js_arg_cnt, c_arg_p + 1, c_arg_cnt - 1);
+} /* jerryx_arg_transform_this_and_args */