# jerryx_arg types ## jerryx_arg_t **Summary** The structure defining a single validation/transformation step. *Note*: For commonly used validators, `arg.h` provides helpers to create the `jerryx_arg_t`s. For example, `jerryx_arg_number ()`, `jerryx_arg_boolean ()`, etc. **Prototype** ```c typedef struct { /** the transform function */ jerryx_arg_transform_func_t func; /** pointer to destination where func should store the result */ void *dest; /** extra information, specific to func */ uintptr_t extra_info; } jerryx_arg_t; ``` **See also** - [jerryx_arg_number](#jerryx_arg_number) - [jerryx_arg_boolean](#jerryx_arg_boolean) - [jerryx_arg_string](#jerryx_arg_string) - [jerryx_arg_utf8_string](#jerryx_arg_utf8_string) - [jerryx_arg_function](#jerryx_arg_function) - [jerryx_arg_native_pointer](#jerryx_arg_native_pointer) - [jerryx_arg_ignore](#jerryx_arg_ignore) - [jerryx_arg_object_properties](#jerryx_arg_object_properties) ## jerryx_arg_object_props_t **Summary** The structure is used in `jerryx_arg_object_properties`. It provides the properties' names, its corresponding JS-to-C mapping and other related information. **Prototype** ```c typedef struct { const jerry_char_t **name_p; /**< property name list of the JS object */ jerry_length_t name_cnt; /**< count of the name list */ 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_object_props_t; ``` **See also** - [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** Signature of the transform function. Users can create custom transformations by implementing a transform function and using `jerryx_arg_custom ()`. The function is expected to return `undefined` if it ran successfully or return an `Error` in case it failed. The function can use the iterator and the helpers `jerryx_arg_js_iterator_pop ()` and `jerryx_arg_js_iterator_peek ()` to get the next input value. *Note*: A transform function is allowed to consume any number of input values! This enables complex validation like handling different JS function signatures, mapping multiple input arguments to a C struct, etc. The function is expected to store the result of a successful transformation into `c_arg_p->dest`. In case the validation did not pass, the transform should not modify `c_arg_p->dest`. Additional parameters can be provided to the function through `c_arg_p->extra_info`. **Prototype** ```c typedef jerry_value_t (*jerryx_arg_transform_func_t) (jerryx_arg_js_iterator_t *js_arg_iter_p, const jerryx_arg_t *c_arg_p); ``` **See also** - [jerryx_arg_custom](#jerryx_arg_custom) - [jerryx_arg_js_iterator_pop](#jerryx_arg_js_iterator_pop) - [jerryx_arg_js_iterator_peek](#jerryx_arg_js_iterator_peek) ## jerryx_arg_coerce_t Enum that indicates whether an argument is allowed to be coerced into the expected JS type. - JERRYX_ARG_COERCE - the transform will invoke toNumber, toBoolean, toString, etc. - JERRYX_ARG_NO_COERCE - the type coercion is not allowed. The transform will fail if the type does not match the expectation. **See also** - [jerryx_arg_number](#jerryx_arg_number) - [jerryx_arg_boolean](#jerryx_arg_boolean) - [jerryx_arg_string](#jerryx_arg_string) ## jerryx_arg_optional_t Enum that indicates whether an argument is optional or required. - JERRYX_ARG_OPTIONAL - The argument is optional. If the argument is `undefined` the transform is successful and `c_arg_p->dest` remains untouched. - JERRYX_ARG_REQUIRED - The argument is required. If the argument is `undefined` the transform will fail and `c_arg_p->dest` remains untouched. **See also** - [jerryx_arg_number](#jerryx_arg_number) - [jerryx_arg_boolean](#jerryx_arg_boolean) - [jerryx_arg_string](#jerryx_arg_string) - [jerryx_arg_function](#jerryx_arg_function) - [jerryx_arg_native_pointer](#jerryx_arg_native_pointer) ## jerryx_arg_round_t Enum that indicates the rounding policy which will be chosen to transform an integer. - JERRYX_ARG_ROUND - use round() method. - JERRYX_ARG_FLOOR - use floor() method. - JERRYX_ARG_CEIL - use ceil() method. **See also** - [jerryx_arg_uint8](#jerryx_arg_uint8) - [jerryx_arg_uint16](#jerryx_arg_uint16) - [jerryx_arg_uint32](#jerryx_arg_uint32) - [jerryx_arg_int8](#jerryx_arg_int8) - [jerryx_arg_int16](#jerryx_arg_int16) - [jerryx_arg_int32](#jerryx_arg_int32) ## jerryx_arg_clamp_t Indicates the clamping policy which will be chosen to transform an integer. If the policy is NO_CLAMP, and the number is out of range, then the transformer will throw a range error. - JERRYX_ARG_CLAMP - clamp the number when it is out of range - JERRYX_ARG_NO_CLAMP - throw a range error **See also** - [jerryx_arg_uint8](#jerryx_arg_uint8) - [jerryx_arg_uint16](#jerryx_arg_uint16) - [jerryx_arg_uint32](#jerryx_arg_uint32) - [jerryx_arg_int8](#jerryx_arg_int8) - [jerryx_arg_int16](#jerryx_arg_int16) - [jerryx_arg_int32](#jerryx_arg_int32) # Main functions ## jerryx_arg_transform_this_and_args **Summary** 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`). **Prototype** ```c 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) ``` - `this_val` - `this` value. Note this is processed as the first value, before the array of arguments. - `js_arg_p` - points to the array with JS arguments. - `js_arg_cnt` - the count of the `js_arg_p` 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. **Example** [doctest]: # (test="compile") ```c #include "jerryscript.h" #include "jerryscript-ext/arg.h" /* JS signature: function (requiredBool, requiredString, optionalNumber) */ 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; char required_str[16]; double optional_num = 1234.567; // default value /* "mapping" defines the steps to transform input arguments to C variables. */ const jerryx_arg_t mapping[] = { /* `this` is the first value. No checking needed on `this` for this function. */ jerryx_arg_ignore (), jerryx_arg_boolean (&required_bool, JERRYX_ARG_NO_COERCE, JERRYX_ARG_REQUIRED), jerryx_arg_string (required_str, sizeof (required_str), JERRYX_ARG_NO_COERCE, JERRYX_ARG_REQUIRED), jerryx_arg_number (&optional_num, JERRYX_ARG_NO_COERCE, JERRYX_ARG_OPTIONAL), }; /* Validate and transform. */ const jerry_value_t rv = jerryx_arg_transform_this_and_args (this_val, args_p, args_count, mapping, 4); if (jerry_value_is_error (rv)) { /* Handle error. */ return rv; } /* * Validated and transformed successfully! * required_bool, required_str and optional_num can now be used. */ return jerry_create_undefined (); /* Or return something more meaningful. */ } ``` **See also** - [jerryx_arg_ignore](#jerryx_arg_ignore) - [jerryx_arg_number](#jerryx_arg_number) - [jerryx_arg_boolean](#jerryx_arg_boolean) - [jerryx_arg_string](#jerryx_arg_string) - [jerryx_arg_function](#jerryx_arg_function) - [jerryx_arg_native_pointer](#jerryx_arg_native_pointer) - [jerryx_arg_custom](#jerryx_arg_custom) - [jerryx_arg_object_properties](#jerryx_arg_object_properties) ## jerryx_arg_transform_args **Summary** Validate an array of `jerry_value_t` and assign them to the native arguments. **Prototype** ```c 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) ``` - `js_arg_p` - points to the array with JS arguments. - `js_arg_cnt` - the count of the `js_arg_p` 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_transform_this_and_args](#jerryx_arg_transform_this_and_args) ## jerryx_arg_transform_object_properties **Summary** Validate the properties of a JS object and assign them to the native arguments. *Note*: This function transforms properties of a single JS object into native C values. To transform multiple objects in one pass (for example when converting multiple arguments to an external handler), please use `jerryx_arg_object_properties` together with `jerryx_arg_transform_this_and_args` or `jerryx_arg_transform_args`. **Prototype** ```c jerry_value_t jerryx_arg_transform_object_properties (const jerry_value_t obj_val, const jerry_char_t **name_p, const jerry_length_t name_cnt, const jerryx_arg_t *c_arg_p, jerry_length_t c_arg_cnt); ``` - `obj_val` - the JS object. - `name_p` - points to the array of property names. - `name_cnt` - the count of the `name_p` 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_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 ## jerryx_arg_uint8 ## jerryx_arg_uint16 ## jerryx_arg_uint32 ## jerryx_arg_int8 ## jerryx_arg_int16 ## jerryx_arg_int32 **Summary** All above jerryx_arg_[u]intX functions are used to create a validation/transformation step (`jerryx_arg_t`) that expects to consume one `number` JS argument and stores it into a C integer (uint8, int8, uint16, ...) **Prototype** Take jerryx_arg_int32 as an example ```c static inline jerryx_arg_t jerryx_arg_int32 (int32_t *dest, jerryx_arg_round_t round_flag, jerryx_arg_clamp_t clamp_flag, jerryx_arg_coerce_t coerce_flag, jerryx_arg_optional_t opt_flag); ``` - return value - the created `jerryx_arg_t` instance. - `dest` - pointer to the `int32_t` where the result should be stored. - `round_flag` - the rounding policy. - `clamp_flag` - the clamping policy. - `coerce_flag` - whether type coercion is allowed. - `opt_flag` - whether the argument is optional. **See also** - [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) ## jerryx_arg_number **Summary** Create a validation/transformation step (`jerryx_arg_t`) that expects to consume one `number` JS argument and stores it into a C `double`. **Prototype** ```c static inline jerryx_arg_t jerryx_arg_number (double *dest, jerryx_arg_coerce_t coerce_flag, jerryx_arg_optional_t opt_flag) ``` - return value - the created `jerryx_arg_t` instance. - `dest` - pointer to the `double` where the result should be stored. - `coerce_flag` - whether type coercion is allowed. - `opt_flag` - whether the argument is optional. **See also** - [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) ## jerryx_arg_boolean **Summary** Create a validation/transformation step (`jerryx_arg_t`) that expects to consume one `boolean` JS argument and stores it into a C `bool`. **Prototype** ```c static inline jerryx_arg_t jerryx_arg_boolean (bool *dest, jerryx_arg_coerce_t coerce_flag, jerryx_arg_optional_t opt_flag) ``` - return value - the created `jerryx_arg_t` instance. - `dest` - pointer to the `bool` where the result should be stored. - `coerce_flag` - whether type coercion is allowed. - `opt_flag` - whether the argument is optional. **See also** - [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) ## jerryx_arg_string **Summary** Create a validation/transformation step (`jerryx_arg_t`) that expects to consume one `string` JS argument and stores it into a CESU-8 C `char` array. **Prototype** ```c static inline jerryx_arg_t jerryx_arg_string (char *dest, uint32_t size, jerryx_arg_coerce_t coerce_flag, jerryx_arg_optional_t opt_flag) ``` - return value - the created `jerryx_arg_t` instance. - `dest` - pointer to the native char array where the result should be stored. - `size` - the size of native char array. - `coerce_flag` - whether type coercion is allowed. - `opt_flag` - whether the argument is optional. **See also** - [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) - [jerry_arg_utf8_string](#jerry_arg_utf8_string) ## jerryx_arg_utf8_string **Summary** Create a validation/transformation step (`jerryx_arg_t`) that expects to consume one `string` JS argument and stores it into a UTF-8 C `char` array. **Prototype** ```c static inline jerryx_arg_t jerryx_arg_utf8_string (char *dest, uint32_t size, jerryx_arg_coerce_t coerce_flag, jerryx_arg_optional_t opt_flag) ``` - return value - the created `jerryx_arg_t` instance. - `dest` - pointer to the native char array where the result should be stored. - `size` - the size of native char array. - `coerce_flag` - whether type coercion is allowed. - `opt_flag` - whether the argument is optional. **See also** - [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) - [jerry_arg_string](#jerry_arg_string) ## jerryx_arg_function **Summary** 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`. **Prototype** ```c static inline jerryx_arg_t jerryx_arg_function (jerry_value_t *dest, jerryx_arg_optional_t opt_flag) ``` - return value - the created `jerryx_arg_t` instance. - `dest` - pointer to the `jerry_value_t` where the result should be stored. - `opt_flag` - whether the argument is optional. **See also** - [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) ## jerryx_arg_native_pointer **Summary** 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`. **Prototype** ```c 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) ``` - return value - the created `jerryx_arg_t` instance. - `dest` - pointer to where the resulting native pointer should be stored. - `info_p` - expected the type info. - `opt_flag` - whether the argument is optional. **See also** - [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) ## jerryx_arg_object_properties **Summary** Create a validation/transformation step (`jerryx_arg_t`) that expects to consume one `object` JS argument and call `jerryx_arg_transform_object_properties` inside to transform its properties to native arguments. User should prepare the `jerryx_arg_object_props_t` instance, and pass it to this function. **Prototype** ```c static inline jerryx_arg_t jerryx_arg_object_properties (const jerryx_arg_object_props_t *object_props_p, jerryx_arg_optional_t opt_flag); ``` - return value - the created `jerryx_arg_t` instance. - `object_props_p` - provides information for properties 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 object, which has 3 properties: * "enable": boolean * "data": number * "extra_data": 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 /* "prop_name_p" defines the name list of the expected properties' names. */ const char *prop_name_p[] = { "enable", "data", "extra_data" }; /* "prop_mapping" defines the steps to transform properties to C variables. */ const jerryx_arg_t prop_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_object_props_t instance. */ const jerryx_arg_object_props_t prop_info = { .name_p = (const jerry_char_t **) prop_name_p, .name_cnt = 3, .c_arg_p = prop_mapping, .c_arg_cnt = 3 }; /* It is the mapping used in the jerryx_arg_transform_args. */ const jerryx_arg_t mapping[] = { jerryx_arg_object_properties (&prop_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_is_error (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) ## 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_is_error (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 **Summary** Create a jerryx_arg_t instance with custom transform. **Prototype** ```c static inline jerryx_arg_t jerryx_arg_custom (void *dest, uintptr_t extra_info, jerryx_arg_transform_func_t func) ``` - return value - the created `jerryx_arg_t` instance. - `dest` - pointer to the native argument where the result should be stored. - `extra_info` - the extra parameter data, specific to the transform function. - `func` - the custom transform function. **See also** - [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) ## jerryx_arg_js_iterator_pop **Summary** Pop the current `jerry_value_t` argument from the iterator. It will change the `js_arg_idx` and `js_arg_p` value in the iterator. **Prototype** ```c jerry_value_t jerryx_arg_js_iterator_pop (jerryx_arg_js_iterator_t *js_arg_iter_p) ``` - return value - the `jerry_value_t` argument that was popped. - `js_arg_iter_p` - the JS arg iterator from which to pop. ## jerryx_arg_js_iterator_peek **Summary** Get the current JS argument from the iterator, without moving the iterator forward. *Note:* Unlike `jerryx_arg_js_iterator_pop ()`, it will not change `js_arg_idx` and `js_arg_p` value in the iterator. **Prototype** ```c jerry_value_t jerryx_arg_js_iterator_peek (jerryx_arg_js_iterator_t *js_arg_iter_p) ``` - return value - the current `jerry_value_t` argument. - `js_arg_iter_p` - the JS arg iterator from which to peek. ## jerryx_arg_js_iterator_index **Summary** Get the index of the current JS argument from the iterator. **Prototype** ```c jerry_length_t jerryx_arg_js_iterator_index (jerryx_arg_js_iterator_t *js_arg_iter_p) ``` - return value - the index of current JS argument. - `js_arg_iter_p` - the JS arg iterator from which to peek.