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
2017-05-04 18:00:35 +08:00
parent ede13835b2
commit 90efdf9c8b
17 changed files with 1709 additions and 3 deletions
@@ -0,0 +1,124 @@
+/* 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_H
+#define JERRYX_ARG_H
+
+#include <assert.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include "jerryscript.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif /* __cplusplus */
+
+/**
+ * The forward declaration of jerryx_arg_t.
+ */
+typedef struct jerryx_arg_t jerryx_arg_t;
+
+/**
+ * The forward declaration of jerryx_arg_js_iterator_t
+ */
+typedef struct jerryx_arg_js_iterator_t jerryx_arg_js_iterator_t;
+
+/**
+ * Signature of the transform function.
+ */
+typedef jerry_value_t (*jerryx_arg_transform_func_t) (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */
+                                                      const jerryx_arg_t *c_arg_p); /**< native arg */
+
+/**
+ * The structure defining a single validation & transformation step.
+ */
+struct jerryx_arg_t
+{
+  jerryx_arg_transform_func_t func; /**< the transform function */
+  void *dest; /**< pointer to destination where func should store the result */
+  uintptr_t extra_info; /**< extra information, specific to func */
+};
+
+jerry_value_t jerryx_arg_transform_this_and_args (const jerry_value_t this_val,
+                                                  const jerry_value_t *js_arg_p,
+                                                  const jerry_length_t js_arg_cnt,
+                                                  const jerryx_arg_t *c_arg_p,
+                                                  jerry_length_t c_arg_cnt);
+
+jerry_value_t jerryx_arg_transform_args (const jerry_value_t *js_arg_p,
+                                         const jerry_length_t js_arg_cnt,
+                                         const jerryx_arg_t *c_arg_p,
+                                         jerry_length_t c_arg_cnt);
+
+/**
+ * Indicates whether an argument is allowed to be coerced into the expected JS type.
+ */
+typedef enum
+{
+  JERRYX_ARG_COERCE, /**< the transform inside will invoke toNumber, toBoolean or toString */
+  JERRYX_ARG_NO_COERCE /**< the type coercion is not allowed. */
+} jerryx_arg_coerce_t;
+
+/**
+ * Indicates whether an argument is optional or required.
+ */
+typedef enum
+{
+  /**
+   * The argument is optional. If the argument is `undefined` the transform is
+   * successful and `c_arg_p->dest` remains untouched.
+   */
+  JERRYX_ARG_OPTIONAL,
+  /**
+   * The argument is required. If the argument is `undefined` the transform
+   * will fail and `c_arg_p->dest` remains untouched.
+   */
+  JERRYX_ARG_REQUIRED
+} jerryx_arg_optional_t;
+
+/* Inline functions for initializing jerryx_arg_t */
+static inline jerryx_arg_t
+jerryx_arg_number (double *dest, jerryx_arg_coerce_t conv_flag, jerryx_arg_optional_t opt_flag);
+static inline jerryx_arg_t
+jerryx_arg_boolean (bool *dest, jerryx_arg_coerce_t conv_flag, jerryx_arg_optional_t opt_flag);
+static inline jerryx_arg_t
+jerryx_arg_string (char *dest, uint32_t size, jerryx_arg_coerce_t conv_flag, jerryx_arg_optional_t opt_flag);
+static inline jerryx_arg_t
+jerryx_arg_function (jerry_value_t *dest, jerryx_arg_optional_t opt_flag);
+static inline jerryx_arg_t
+jerryx_arg_native_pointer (void **dest, const jerry_object_native_info_t *info_p, jerryx_arg_optional_t opt_flag);
+static inline jerryx_arg_t
+jerryx_arg_ignore (void);
+static inline jerryx_arg_t
+jerryx_arg_custom (void *dest, uintptr_t extra_info, jerryx_arg_transform_func_t func);
+
+jerry_value_t
+jerryx_arg_transform_optional (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                               const jerryx_arg_t *c_arg_p,
+                               jerryx_arg_transform_func_t func);
+
+/* Helper functions for transform functions. */
+jerry_value_t jerryx_arg_js_iterator_pop (jerryx_arg_js_iterator_t *js_arg_iter_p);
+jerry_value_t jerryx_arg_js_iterator_peek (jerryx_arg_js_iterator_t *js_arg_iter_p);
+jerry_length_t jerryx_arg_js_iterator_index (jerryx_arg_js_iterator_t *js_arg_iter_p);
+
+#include "arg.impl.h"
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+#endif /* !JERRYX_ARG_H */
@@ -0,0 +1,278 @@
+/* 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_IMPL_H
+#define JERRYX_ARG_IMPL_H
+
+/* transform functions for each type. */
+jerry_value_t jerryx_arg_transform_number_strict (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                  const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_number_strict_optional (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                           const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_number_optional (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                    const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_number (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                           const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_boolean_strict (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                   const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_boolean_strict_optional (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                            const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_boolean_optional (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                     const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_boolean (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                            const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_string_strict (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                  const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_string_strict_optional (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                           const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_string_optional (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                    const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_string (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                           const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_function (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                             const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_function_optional (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                      const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_native_pointer (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                   const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_native_pointer_optional (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                                            const jerryx_arg_t *c_arg_p);
+jerry_value_t jerryx_arg_transform_ignore (jerryx_arg_js_iterator_t *js_arg_iter_p,
+                                           const jerryx_arg_t *c_arg_p);
+
+/**
+ * Create a validation/transformation step (`jerryx_arg_t`) that expects to
+ * consume one `number` JS argument and stores it into a C `double`.
+ *
+ * @return a jerryx_arg_t instance.
+ */
+static inline jerryx_arg_t
+jerryx_arg_number (double *dest, /**< pointer to the double where the result should be stored */
+                   jerryx_arg_coerce_t coerce_flag, /**< whether type coercion is allowed */
+                   jerryx_arg_optional_t opt_flag) /**< whether the argument is optional */
+{
+  jerryx_arg_transform_func_t func;
+
+  if (coerce_flag == JERRYX_ARG_NO_COERCE)
+  {
+    if (opt_flag == JERRYX_ARG_OPTIONAL)
+    {
+      func = jerryx_arg_transform_number_strict_optional;
+    }
+    else
+    {
+      func = jerryx_arg_transform_number_strict;
+    }
+  }
+  else
+  {
+    if (opt_flag == JERRYX_ARG_OPTIONAL)
+    {
+      func = jerryx_arg_transform_number_optional;
+    }
+    else
+    {
+      func = jerryx_arg_transform_number;
+    }
+  }
+
+  return (jerryx_arg_t)
+  {
+    .func = func,
+    .dest = (void *) dest
+  };
+} /* jerryx_arg_number */
+
+/**
+ * Create a validation/transformation step (`jerryx_arg_t`) that expects to
+ * consume one `boolean` JS argument and stores it into a C `bool`.
+ *
+ * @return a jerryx_arg_t instance.
+ */
+static inline jerryx_arg_t
+jerryx_arg_boolean (bool *dest, /**< points to the native bool */
+                    jerryx_arg_coerce_t coerce_flag, /**< whether type coercion is allowed */
+                    jerryx_arg_optional_t opt_flag) /**< whether the argument is optional */
+{
+  jerryx_arg_transform_func_t func;
+
+  if (coerce_flag == JERRYX_ARG_NO_COERCE)
+  {
+    if (opt_flag == JERRYX_ARG_OPTIONAL)
+    {
+      func = jerryx_arg_transform_boolean_strict_optional;
+    }
+    else
+    {
+      func = jerryx_arg_transform_boolean_strict;
+    }
+  }
+  else
+  {
+    if (opt_flag == JERRYX_ARG_OPTIONAL)
+    {
+      func = jerryx_arg_transform_boolean_optional;
+    }
+    else
+    {
+      func = jerryx_arg_transform_boolean;
+    }
+  }
+
+  return (jerryx_arg_t)
+  {
+    .func = func,
+    .dest = (void *) dest
+  };
+} /* jerryx_arg_boolean */
+
+/**
+ * Create a validation/transformation step (`jerryx_arg_t`) that expects to
+ * consume one `string` JS argument and stores it into a C `char` array.
+ *
+ * @return a jerryx_arg_t instance.
+ */
+static inline jerryx_arg_t
+jerryx_arg_string (char *dest, /**< pointer to the native char array where the result should be stored */
+                   uint32_t size, /**< the size of native char array */
+                   jerryx_arg_coerce_t coerce_flag, /**< whether type coercion is allowed */
+                   jerryx_arg_optional_t opt_flag) /**< whether the argument is optional */
+{
+  jerryx_arg_transform_func_t func;
+
+  if (coerce_flag == JERRYX_ARG_NO_COERCE)
+  {
+    if (opt_flag == JERRYX_ARG_OPTIONAL)
+    {
+      func = jerryx_arg_transform_string_strict_optional;
+    }
+    else
+    {
+      func = jerryx_arg_transform_string_strict;
+    }
+  }
+  else
+  {
+    if (opt_flag == JERRYX_ARG_OPTIONAL)
+    {
+      func = jerryx_arg_transform_string_optional;
+    }
+    else
+    {
+      func = jerryx_arg_transform_string;
+    }
+  }
+
+  return (jerryx_arg_t)
+  {
+    .func = func,
+    .dest = (void *) dest,
+    .extra_info = (uintptr_t) size
+  };
+} /* jerryx_arg_string */
+
+/**
+ * Create a validation/transformation step (`jerryx_arg_t`) that expects to
+ * consume one `function` JS argument and stores it into a C `jerry_value_t`.
+ *
+ * @return a jerryx_arg_t instance.
+ */
+static inline jerryx_arg_t
+jerryx_arg_function (jerry_value_t *dest, /**< pointer to the jerry_value_t where the result should be stored */
+                     jerryx_arg_optional_t opt_flag) /**< whether the argument is optional */
+{
+  jerryx_arg_transform_func_t func;
+
+  if (opt_flag == JERRYX_ARG_OPTIONAL)
+  {
+    func = jerryx_arg_transform_function_optional;
+  }
+  else
+  {
+    func = jerryx_arg_transform_function;
+  }
+
+  return (jerryx_arg_t)
+  {
+    .func = func,
+    .dest = (void *) dest
+  };
+} /* jerryx_arg_function */
+
+/**
+ * Create a validation/transformation step (`jerryx_arg_t`) that expects to
+ * consume one `Object` JS argument that is 'backed' with a native pointer with
+ * a given type info. In case the native pointer info matches, the transform
+ * will succeed and the object's native pointer will be assigned to *dest.
+ *
+ * @return a jerryx_arg_t instance.
+ */
+static inline jerryx_arg_t
+jerryx_arg_native_pointer (void **dest, /**< pointer to where the resulting native pointer should be stored */
+                           const jerry_object_native_info_t *info_p, /**< expected the type info */
+                           jerryx_arg_optional_t opt_flag) /**< whether the argument is optional */
+{
+  jerryx_arg_transform_func_t func;
+
+  if (opt_flag == JERRYX_ARG_OPTIONAL)
+  {
+    func = jerryx_arg_transform_native_pointer_optional;
+  }
+  else
+  {
+    func = jerryx_arg_transform_native_pointer;
+  }
+
+  return (jerryx_arg_t)
+  {
+    .func = func,
+    .dest = (void *) dest,
+    .extra_info = (uintptr_t) info_p
+  };
+} /* jerryx_arg_native_pointer */
+
+/**
+ * Create a jerryx_arg_t instance for ignored argument.
+ *
+ * @return a jerryx_arg_t instance.
+ */
+static inline jerryx_arg_t
+jerryx_arg_ignore (void)
+{
+  return (jerryx_arg_t)
+  {
+    .func = jerryx_arg_transform_ignore
+  };
+} /* jerryx_arg_ignore */
+
+/**
+ * Create a jerryx_arg_t instance with custom transform.
+ *
+ * @return a jerryx_arg_t instance.
+ */
+static inline jerryx_arg_t
+jerryx_arg_custom (void *dest, /**< pointer to the native argument where the result should be stored */
+                   uintptr_t extra_info, /**< the extra parameter, specific to the transform function */
+                   jerryx_arg_transform_func_t func) /**< the custom transform function */
+{
+  return (jerryx_arg_t)
+  {
+    .func = func,
+    .dest = dest,
+    .extra_info = extra_info
+  };
+} /* jerryx_arg_custom */
+
+#endif /* !JERRYX_ARG_IMPL_H */