1 | /* Copyright JS Foundation and other contributors, http://js.foundation |
2 | * |
3 | * Licensed under the Apache License, Version 2.0 (the "License"); |
4 | * you may not use this file except in compliance with the License. |
5 | * You may obtain a copy of the License at |
6 | * |
7 | * http://www.apache.org/licenses/LICENSE-2.0 |
8 | * |
9 | * Unless required by applicable law or agreed to in writing, software |
10 | * distributed under the License is distributed on an "AS IS" BASIS |
11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
12 | * See the License for the specific language governing permissions and |
13 | * limitations under the License. |
14 | */ |
15 | |
16 | #ifndef JERRYX_ARG_H |
17 | #define JERRYX_ARG_H |
18 | |
19 | #include <stdbool.h> |
20 | #include <stddef.h> |
21 | #include <stdint.h> |
22 | #include "jerryscript.h" |
23 | |
24 | #ifdef __cplusplus |
25 | extern "C" |
26 | { |
27 | #endif /* __cplusplus */ |
28 | |
29 | /** |
30 | * The forward declaration of jerryx_arg_t. |
31 | */ |
32 | typedef struct jerryx_arg_t jerryx_arg_t; |
33 | |
34 | /** |
35 | * The forward declaration of jerryx_arg_js_iterator_t |
36 | */ |
37 | typedef struct jerryx_arg_js_iterator_t jerryx_arg_js_iterator_t; |
38 | |
39 | /** |
40 | * Signature of the transform function. |
41 | */ |
42 | typedef jerry_value_t (*jerryx_arg_transform_func_t) (jerryx_arg_js_iterator_t *js_arg_iter_p, /**< available JS args */ |
43 | const jerryx_arg_t *c_arg_p); /**< native arg */ |
44 | |
45 | /** |
46 | * The structure used in jerryx_arg_object_properties |
47 | */ |
48 | typedef struct |
49 | { |
50 | const jerry_char_t **name_p; /**< property name list of the JS object */ |
51 | jerry_length_t name_cnt; /**< count of the name list */ |
52 | const jerryx_arg_t *c_arg_p; /**< points to the array of transformation steps */ |
53 | jerry_length_t c_arg_cnt; /**< the count of the `c_arg_p` array */ |
54 | } jerryx_arg_object_props_t; |
55 | |
56 | /** |
57 | * The structure used in jerryx_arg_array |
58 | */ |
59 | typedef struct |
60 | { |
61 | const jerryx_arg_t *c_arg_p; /**< points to the array of transformation steps */ |
62 | jerry_length_t c_arg_cnt; /**< the count of the `c_arg_p` array */ |
63 | } jerryx_arg_array_items_t; |
64 | |
65 | /** |
66 | * The structure defining a single validation & transformation step. |
67 | */ |
68 | struct jerryx_arg_t |
69 | { |
70 | jerryx_arg_transform_func_t func; /**< the transform function */ |
71 | void *dest; /**< pointer to destination where func should store the result */ |
72 | uintptr_t ; /**< extra information, specific to func */ |
73 | }; |
74 | |
75 | jerry_value_t jerryx_arg_transform_this_and_args (const jerry_value_t this_val, |
76 | const jerry_value_t *js_arg_p, |
77 | const jerry_length_t js_arg_cnt, |
78 | const jerryx_arg_t *c_arg_p, |
79 | jerry_length_t c_arg_cnt); |
80 | |
81 | jerry_value_t jerryx_arg_transform_args (const jerry_value_t *js_arg_p, |
82 | const jerry_length_t js_arg_cnt, |
83 | const jerryx_arg_t *c_arg_p, |
84 | jerry_length_t c_arg_cnt); |
85 | |
86 | jerry_value_t jerryx_arg_transform_object_properties (const jerry_value_t obj_val, |
87 | const jerry_char_t **name_p, |
88 | const jerry_length_t name_cnt, |
89 | const jerryx_arg_t *c_arg_p, |
90 | jerry_length_t c_arg_cnt); |
91 | jerry_value_t jerryx_arg_transform_array (const jerry_value_t array_val, |
92 | const jerryx_arg_t *c_arg_p, |
93 | jerry_length_t c_arg_cnt); |
94 | |
95 | /** |
96 | * Indicates whether an argument is allowed to be coerced into the expected JS type. |
97 | */ |
98 | typedef enum |
99 | { |
100 | JERRYX_ARG_COERCE, /**< the transform inside will invoke toNumber, toBoolean or toString */ |
101 | JERRYX_ARG_NO_COERCE /**< the type coercion is not allowed. */ |
102 | } jerryx_arg_coerce_t; |
103 | |
104 | /** |
105 | * Indicates whether an argument is optional or required. |
106 | */ |
107 | typedef enum |
108 | { |
109 | /** |
110 | * The argument is optional. If the argument is `undefined` the transform is |
111 | * successful and `c_arg_p->dest` remains untouched. |
112 | */ |
113 | JERRYX_ARG_OPTIONAL, |
114 | /** |
115 | * The argument is required. If the argument is `undefined` the transform |
116 | * will fail and `c_arg_p->dest` remains untouched. |
117 | */ |
118 | JERRYX_ARG_REQUIRED |
119 | } jerryx_arg_optional_t; |
120 | |
121 | /** |
122 | * Indicates the rounding policy which will be chosen to transform an integer. |
123 | */ |
124 | typedef enum |
125 | { |
126 | JERRYX_ARG_ROUND, /**< round */ |
127 | JERRYX_ARG_FLOOR, /**< floor */ |
128 | JERRYX_ARG_CEIL /**< ceil */ |
129 | } jerryx_arg_round_t; |
130 | |
131 | /** |
132 | * Indicates the clamping policy which will be chosen to transform an integer. |
133 | * If the policy is NO_CLAMP, and the number is out of range, |
134 | * then the transformer will throw a range error. |
135 | */ |
136 | typedef enum |
137 | { |
138 | JERRYX_ARG_CLAMP,/**< clamp the number when it is out of range */ |
139 | JERRYX_ARG_NO_CLAMP /**< throw a range error */ |
140 | } jerryx_arg_clamp_t; |
141 | |
142 | /* Inline functions for initializing jerryx_arg_t */ |
143 | |
144 | #define JERRYX_ARG_INTEGER(type) \ |
145 | static inline jerryx_arg_t \ |
146 | jerryx_arg_ ## type (type ## _t *dest, \ |
147 | jerryx_arg_round_t round_flag, \ |
148 | jerryx_arg_clamp_t clamp_flag, \ |
149 | jerryx_arg_coerce_t coerce_flag, \ |
150 | jerryx_arg_optional_t opt_flag); |
151 | |
152 | JERRYX_ARG_INTEGER (uint8) |
153 | JERRYX_ARG_INTEGER (int8) |
154 | JERRYX_ARG_INTEGER (uint16) |
155 | JERRYX_ARG_INTEGER (int16) |
156 | JERRYX_ARG_INTEGER (uint32) |
157 | JERRYX_ARG_INTEGER (int32) |
158 | |
159 | #undef JERRYX_ARG_INTEGER |
160 | |
161 | static inline jerryx_arg_t |
162 | jerryx_arg_number (double *dest, jerryx_arg_coerce_t coerce_flag, jerryx_arg_optional_t opt_flag); |
163 | static inline jerryx_arg_t |
164 | jerryx_arg_boolean (bool *dest, jerryx_arg_coerce_t coerce_flag, jerryx_arg_optional_t opt_flag); |
165 | static inline jerryx_arg_t |
166 | jerryx_arg_string (char *dest, uint32_t size, jerryx_arg_coerce_t coerce_flag, jerryx_arg_optional_t opt_flag); |
167 | static inline jerryx_arg_t |
168 | jerryx_arg_utf8_string (char *dest, uint32_t size, jerryx_arg_coerce_t coerce_flag, jerryx_arg_optional_t opt_flag); |
169 | static inline jerryx_arg_t |
170 | jerryx_arg_function (jerry_value_t *dest, jerryx_arg_optional_t opt_flag); |
171 | static inline jerryx_arg_t |
172 | jerryx_arg_native_pointer (void **dest, const jerry_object_native_info_t *info_p, jerryx_arg_optional_t opt_flag); |
173 | static inline jerryx_arg_t |
174 | jerryx_arg_ignore (void); |
175 | static inline jerryx_arg_t |
176 | jerryx_arg_custom (void *dest, uintptr_t , jerryx_arg_transform_func_t func); |
177 | static inline jerryx_arg_t |
178 | jerryx_arg_object_properties (const jerryx_arg_object_props_t *object_props_p, jerryx_arg_optional_t opt_flag); |
179 | static inline jerryx_arg_t |
180 | jerryx_arg_array (const jerryx_arg_array_items_t *array_items_p, jerryx_arg_optional_t opt_flag); |
181 | |
182 | jerry_value_t |
183 | jerryx_arg_transform_optional (jerryx_arg_js_iterator_t *js_arg_iter_p, |
184 | const jerryx_arg_t *c_arg_p, |
185 | jerryx_arg_transform_func_t func); |
186 | |
187 | /* Helper functions for transform functions. */ |
188 | jerry_value_t jerryx_arg_js_iterator_pop (jerryx_arg_js_iterator_t *js_arg_iter_p); |
189 | jerry_value_t jerryx_arg_js_iterator_restore (jerryx_arg_js_iterator_t *js_arg_iter_p); |
190 | jerry_value_t jerryx_arg_js_iterator_peek (jerryx_arg_js_iterator_t *js_arg_iter_p); |
191 | jerry_length_t jerryx_arg_js_iterator_index (jerryx_arg_js_iterator_t *js_arg_iter_p); |
192 | |
193 | #include "arg.impl.h" |
194 | |
195 | #ifdef __cplusplus |
196 | } |
197 | #endif /* __cplusplus */ |
198 | #endif /* !JERRYX_ARG_H */ |
199 | |