1# jerryx_arg types 2 3## jerryx_arg_t 4 5**Summary** 6 7The structure defining a single validation/transformation step. 8 9*Note*: For commonly used validators, `arg.h` provides helpers to create the `jerryx_arg_t`s. 10For example, `jerryx_arg_number ()`, `jerryx_arg_boolean ()`, etc. 11 12**Prototype** 13 14```c 15typedef struct 16{ 17 /** the transform function */ 18 jerryx_arg_transform_func_t func; 19 /** pointer to destination where func should store the result */ 20 void *dest; 21 /** extra information, specific to func */ 22 uintptr_t extra_info; 23} jerryx_arg_t; 24``` 25 26**See also** 27 28- [jerryx_arg_number](#jerryx_arg_number) 29- [jerryx_arg_boolean](#jerryx_arg_boolean) 30- [jerryx_arg_string](#jerryx_arg_string) 31- [jerryx_arg_utf8_string](#jerryx_arg_utf8_string) 32- [jerryx_arg_function](#jerryx_arg_function) 33- [jerryx_arg_native_pointer](#jerryx_arg_native_pointer) 34- [jerryx_arg_ignore](#jerryx_arg_ignore) 35- [jerryx_arg_object_properties](#jerryx_arg_object_properties) 36 37## jerryx_arg_object_props_t 38 39**Summary** 40 41The structure is used in `jerryx_arg_object_properties`. It provides the properties' names, 42its corresponding JS-to-C mapping and other related information. 43 44**Prototype** 45 46```c 47typedef struct 48{ 49 const jerry_char_t **name_p; /**< property name list of the JS object */ 50 jerry_length_t name_cnt; /**< count of the name list */ 51 const jerryx_arg_t *c_arg_p; /**< points to the array of transformation steps */ 52 jerry_length_t c_arg_cnt; /**< the count of the `c_arg_p` array */ 53} jerryx_arg_object_props_t; 54``` 55 56**See also** 57 58- [jerryx_arg_object_properties](#jerryx_arg_object_properties) 59 60## jerryx_arg_array_items_t 61 62**Summary** 63 64The structure is used in `jerryx_arg_array`. It provides the array items' corresponding 65JS-to-C mappings and count. 66 67**Prototype** 68 69```c 70typedef struct 71{ 72 const jerryx_arg_t *c_arg_p; /**< points to the array of transformation steps */ 73 jerry_length_t c_arg_cnt; /**< the count of the `c_arg_p` array */ 74} jerryx_arg_array_items_t; 75``` 76 77**See also** 78 79- [jerryx_arg_array](#jerryx_arg_array) 80 81## jerryx_arg_transform_func_t 82 83**Summary** 84 85Signature of the transform function. 86 87Users can create custom transformations by implementing a transform function 88and using `jerryx_arg_custom ()`. 89 90The function is expected to return `undefined` if it ran successfully or 91return an `Error` in case it failed. The function can use the iterator and the 92helpers `jerryx_arg_js_iterator_pop ()` and `jerryx_arg_js_iterator_peek ()` to 93get the next input value. 94 95*Note*: A transform function is allowed to consume any number of input values! 96This enables complex validation like handling different JS function signatures, 97mapping multiple input arguments to a C struct, etc. 98 99The function is expected to store the result of 100a successful transformation into `c_arg_p->dest`. In case the validation did 101not pass, the transform should not modify `c_arg_p->dest`. 102 103Additional parameters can be provided to the function through `c_arg_p->extra_info`. 104 105**Prototype** 106 107```c 108typedef jerry_value_t (*jerryx_arg_transform_func_t) (jerryx_arg_js_iterator_t *js_arg_iter_p, 109 const jerryx_arg_t *c_arg_p); 110``` 111 112**See also** 113 114- [jerryx_arg_custom](#jerryx_arg_custom) 115- [jerryx_arg_js_iterator_pop](#jerryx_arg_js_iterator_pop) 116- [jerryx_arg_js_iterator_peek](#jerryx_arg_js_iterator_peek) 117 118 119## jerryx_arg_coerce_t 120 121Enum that indicates whether an argument is allowed to be coerced into the expected JS type. 122 123 - JERRYX_ARG_COERCE - the transform will invoke toNumber, toBoolean, toString, etc. 124 - JERRYX_ARG_NO_COERCE - the type coercion is not allowed. The transform will fail if the type does not match the expectation. 125 126**See also** 127 128- [jerryx_arg_number](#jerryx_arg_number) 129- [jerryx_arg_boolean](#jerryx_arg_boolean) 130- [jerryx_arg_string](#jerryx_arg_string) 131 132## jerryx_arg_optional_t 133 134Enum that indicates whether an argument is optional or required. 135 136 - JERRYX_ARG_OPTIONAL - The argument is optional. If the argument is `undefined` the transform is successful and `c_arg_p->dest` remains untouched. 137 - JERRYX_ARG_REQUIRED - The argument is required. If the argument is `undefined` the transform will fail and `c_arg_p->dest` remains untouched. 138 139**See also** 140 141- [jerryx_arg_number](#jerryx_arg_number) 142- [jerryx_arg_boolean](#jerryx_arg_boolean) 143- [jerryx_arg_string](#jerryx_arg_string) 144- [jerryx_arg_function](#jerryx_arg_function) 145- [jerryx_arg_native_pointer](#jerryx_arg_native_pointer) 146 147## jerryx_arg_round_t 148 149Enum that indicates the rounding policy which will be chosen to transform an integer. 150 151 - JERRYX_ARG_ROUND - use round() method. 152 - JERRYX_ARG_FLOOR - use floor() method. 153 - JERRYX_ARG_CEIL - use ceil() method. 154 155**See also** 156 157- [jerryx_arg_uint8](#jerryx_arg_uint8) 158- [jerryx_arg_uint16](#jerryx_arg_uint16) 159- [jerryx_arg_uint32](#jerryx_arg_uint32) 160- [jerryx_arg_int8](#jerryx_arg_int8) 161- [jerryx_arg_int16](#jerryx_arg_int16) 162- [jerryx_arg_int32](#jerryx_arg_int32) 163 164 165## jerryx_arg_clamp_t 166 167 Indicates the clamping policy which will be chosen to transform an integer. 168 If the policy is NO_CLAMP, and the number is out of range, 169 then the transformer will throw a range error. 170 171 - JERRYX_ARG_CLAMP - clamp the number when it is out of range 172 - JERRYX_ARG_NO_CLAMP - throw a range error 173 174**See also** 175 176- [jerryx_arg_uint8](#jerryx_arg_uint8) 177- [jerryx_arg_uint16](#jerryx_arg_uint16) 178- [jerryx_arg_uint32](#jerryx_arg_uint32) 179- [jerryx_arg_int8](#jerryx_arg_int8) 180- [jerryx_arg_int16](#jerryx_arg_int16) 181- [jerryx_arg_int32](#jerryx_arg_int32) 182 183# Main functions 184 185## jerryx_arg_transform_this_and_args 186 187**Summary** 188 189Validate the this value and the JS arguments, and assign them to the native arguments. 190This function is useful to perform input validation inside external function handlers (see `jerry_external_handler_t`). 191 192**Prototype** 193 194```c 195jerry_value_t 196jerryx_arg_transform_this_and_args (const jerry_value_t this_val, 197 const jerry_value_t *js_arg_p, 198 const jerry_length_t js_arg_cnt, 199 const jerryx_arg_t *c_arg_p, 200 jerry_length_t c_arg_cnt) 201``` 202 203 - `this_val` - `this` value. Note this is processed as the first value, before the array of arguments. 204 - `js_arg_p` - points to the array with JS arguments. 205 - `js_arg_cnt` - the count of the `js_arg_p` array. 206 - `c_arg_p` - points to the array of validation/transformation steps 207 - `c_arg_cnt` - the count of the `c_arg_p` array. 208 - return value - a `jerry_value_t` representing `undefined` if all validators passed or an `Error` if a validator failed. 209 210**Example** 211 212[doctest]: # (test="compile") 213 214```c 215#include "jerryscript.h" 216#include "jerryscript-ext/arg.h" 217 218/* JS signature: function (requiredBool, requiredString, optionalNumber) */ 219static jerry_value_t 220my_external_handler (const jerry_value_t function_obj, 221 const jerry_value_t this_val, 222 const jerry_value_t args_p[], 223 const jerry_length_t args_count) 224{ 225 bool required_bool; 226 char required_str[16]; 227 double optional_num = 1234.567; // default value 228 229 /* "mapping" defines the steps to transform input arguments to C variables. */ 230 const jerryx_arg_t mapping[] = 231 { 232 /* `this` is the first value. No checking needed on `this` for this function. */ 233 jerryx_arg_ignore (), 234 235 jerryx_arg_boolean (&required_bool, JERRYX_ARG_NO_COERCE, JERRYX_ARG_REQUIRED), 236 jerryx_arg_string (required_str, sizeof (required_str), JERRYX_ARG_NO_COERCE, JERRYX_ARG_REQUIRED), 237 jerryx_arg_number (&optional_num, JERRYX_ARG_NO_COERCE, JERRYX_ARG_OPTIONAL), 238 }; 239 240 /* Validate and transform. */ 241 const jerry_value_t rv = jerryx_arg_transform_this_and_args (this_val, 242 args_p, 243 args_count, 244 mapping, 245 4); 246 247 if (jerry_value_is_error (rv)) 248 { 249 /* Handle error. */ 250 return rv; 251 } 252 253 /* 254 * Validated and transformed successfully! 255 * required_bool, required_str and optional_num can now be used. 256 */ 257 258 return jerry_create_undefined (); /* Or return something more meaningful. */ 259} 260``` 261 262**See also** 263 264- [jerryx_arg_ignore](#jerryx_arg_ignore) 265- [jerryx_arg_number](#jerryx_arg_number) 266- [jerryx_arg_boolean](#jerryx_arg_boolean) 267- [jerryx_arg_string](#jerryx_arg_string) 268- [jerryx_arg_function](#jerryx_arg_function) 269- [jerryx_arg_native_pointer](#jerryx_arg_native_pointer) 270- [jerryx_arg_custom](#jerryx_arg_custom) 271- [jerryx_arg_object_properties](#jerryx_arg_object_properties) 272 273 274## jerryx_arg_transform_args 275 276**Summary** 277 278Validate an array of `jerry_value_t` and assign them to the native arguments. 279 280**Prototype** 281 282```c 283jerry_value_t 284jerryx_arg_transform_args (const jerry_value_t *js_arg_p, 285 const jerry_length_t js_arg_cnt, 286 const jerryx_arg_t *c_arg_p, 287 jerry_length_t c_arg_cnt) 288``` 289 290 - `js_arg_p` - points to the array with JS arguments. 291 - `js_arg_cnt` - the count of the `js_arg_p` array. 292 - `c_arg_p` - points to the array of validation/transformation steps 293 - `c_arg_cnt` - the count of the `c_arg_p` array. 294 - return value - a `jerry_value_t` representing `undefined` if all validators passed or an `Error` if a validator failed. 295 296**See also** 297 298- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) 299 300 301## jerryx_arg_transform_object_properties 302 303**Summary** 304 305Validate the properties of a JS object and assign them to the native arguments. 306 307*Note*: This function transforms properties of a single JS object into native C values. 308To transform multiple objects in one pass (for example when converting multiple arguments 309to an external handler), please use `jerryx_arg_object_properties` together with 310`jerryx_arg_transform_this_and_args` or `jerryx_arg_transform_args`. 311 312**Prototype** 313 314```c 315jerry_value_t 316jerryx_arg_transform_object_properties (const jerry_value_t obj_val, 317 const jerry_char_t **name_p, 318 const jerry_length_t name_cnt, 319 const jerryx_arg_t *c_arg_p, 320 jerry_length_t c_arg_cnt); 321 322``` 323 324 - `obj_val` - the JS object. 325 - `name_p` - points to the array of property names. 326 - `name_cnt` - the count of the `name_p` array. 327 - `c_arg_p` - points to the array of validation/transformation steps 328 - `c_arg_cnt` - the count of the `c_arg_p` array. 329 - return value - a `jerry_value_t` representing `undefined` if all validators passed or an `Error` if a validator failed. 330 331**See also** 332 333- [jerryx_arg_object_properties](#jerryx_arg_object_properties) 334 335## jerryx_arg_transform_array 336 337**Summary** 338 339Validate the JS array and assign its items to the native arguments. 340 341*Note*: This function transforms items of a single JS array into native C values. 342To transform multiple JS arguments in one pass, please use `jerryx_arg_array` together with 343`jerryx_arg_transform_this_and_args` or `jerryx_arg_transform_args`. 344 345**Prototype** 346 347```c 348jerry_value_t 349jerryx_arg_transform_array (const jerry_value_t array_val, 350 const jerryx_arg_t *c_arg_p, 351 jerry_length_t c_arg_cnt); 352 353``` 354 355 - `array_val` - the JS array. 356 - `c_arg_p` - points to the array of validation/transformation steps 357 - `c_arg_cnt` - the count of the `c_arg_p` array. 358 - return value - a `jerry_value_t` representing `undefined` if all validators passed or an `Error` if a validator failed. 359 360**See also** 361 362- [jerryx_arg_array](#jerryx_arg_array) 363 364 365# Helpers for commonly used validations 366 367## jerryx_arg_uint8 368 369## jerryx_arg_uint16 370 371## jerryx_arg_uint32 372 373## jerryx_arg_int8 374 375## jerryx_arg_int16 376 377## jerryx_arg_int32 378 379**Summary** 380 381All above jerryx_arg_[u]intX functions are used to create a validation/transformation step 382(`jerryx_arg_t`) that expects to consume one `number` JS argument 383and stores it into a C integer (uint8, int8, uint16, ...) 384 385**Prototype** 386 387Take jerryx_arg_int32 as an example 388 389```c 390static inline jerryx_arg_t 391jerryx_arg_int32 (int32_t *dest, 392 jerryx_arg_round_t round_flag, 393 jerryx_arg_clamp_t clamp_flag, 394 jerryx_arg_coerce_t coerce_flag, 395 jerryx_arg_optional_t opt_flag); 396``` 397 398 - return value - the created `jerryx_arg_t` instance. 399 - `dest` - pointer to the `int32_t` where the result should be stored. 400 - `round_flag` - the rounding policy. 401 - `clamp_flag` - the clamping policy. 402 - `coerce_flag` - whether type coercion is allowed. 403 - `opt_flag` - whether the argument is optional. 404 405**See also** 406 407- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) 408 409 410## jerryx_arg_number 411 412**Summary** 413 414Create a validation/transformation step (`jerryx_arg_t`) that expects to consume 415one `number` JS argument and stores it into a C `double`. 416 417**Prototype** 418 419```c 420static inline jerryx_arg_t 421jerryx_arg_number (double *dest, 422 jerryx_arg_coerce_t coerce_flag, 423 jerryx_arg_optional_t opt_flag) 424``` 425 426 - return value - the created `jerryx_arg_t` instance. 427 - `dest` - pointer to the `double` where the result should be stored. 428 - `coerce_flag` - whether type coercion is allowed. 429 - `opt_flag` - whether the argument is optional. 430 431**See also** 432 433- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) 434 435## jerryx_arg_boolean 436 437**Summary** 438 439Create a validation/transformation step (`jerryx_arg_t`) that expects to 440consume one `boolean` JS argument and stores it into a C `bool`. 441 442**Prototype** 443 444```c 445static inline jerryx_arg_t 446jerryx_arg_boolean (bool *dest, 447 jerryx_arg_coerce_t coerce_flag, 448 jerryx_arg_optional_t opt_flag) 449``` 450 - return value - the created `jerryx_arg_t` instance. 451 - `dest` - pointer to the `bool` where the result should be stored. 452 - `coerce_flag` - whether type coercion is allowed. 453 - `opt_flag` - whether the argument is optional. 454 455**See also** 456 457- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) 458 459 460## jerryx_arg_string 461 462**Summary** 463 464Create a validation/transformation step (`jerryx_arg_t`) that expects to 465consume one `string` JS argument and stores it into a CESU-8 C `char` array. 466 467**Prototype** 468 469```c 470static inline jerryx_arg_t 471jerryx_arg_string (char *dest, 472 uint32_t size, 473 jerryx_arg_coerce_t coerce_flag, 474 jerryx_arg_optional_t opt_flag) 475``` 476 477 - return value - the created `jerryx_arg_t` instance. 478 - `dest` - pointer to the native char array where the result should be stored. 479 - `size` - the size of native char array. 480 - `coerce_flag` - whether type coercion is allowed. 481 - `opt_flag` - whether the argument is optional. 482 483**See also** 484 485- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) 486- [jerry_arg_utf8_string](#jerry_arg_utf8_string) 487 488 489## jerryx_arg_utf8_string 490 491**Summary** 492 493Create a validation/transformation step (`jerryx_arg_t`) that expects to 494consume one `string` JS argument and stores it into a UTF-8 C `char` array. 495 496**Prototype** 497 498```c 499static inline jerryx_arg_t 500jerryx_arg_utf8_string (char *dest, 501 uint32_t size, 502 jerryx_arg_coerce_t coerce_flag, 503 jerryx_arg_optional_t opt_flag) 504``` 505 506 - return value - the created `jerryx_arg_t` instance. 507 - `dest` - pointer to the native char array where the result should be stored. 508 - `size` - the size of native char array. 509 - `coerce_flag` - whether type coercion is allowed. 510 - `opt_flag` - whether the argument is optional. 511 512**See also** 513 514- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) 515- [jerry_arg_string](#jerry_arg_string) 516 517 518## jerryx_arg_function 519 520**Summary** 521 522Create a validation/transformation step (`jerryx_arg_t`) that expects to 523consume one `function` JS argument and stores it into a C `jerry_value_t`. 524 525**Prototype** 526 527```c 528static inline jerryx_arg_t 529jerryx_arg_function (jerry_value_t *dest, 530 jerryx_arg_optional_t opt_flag) 531 532``` 533 - return value - the created `jerryx_arg_t` instance. 534 - `dest` - pointer to the `jerry_value_t` where the result should be stored. 535 - `opt_flag` - whether the argument is optional. 536 537**See also** 538 539- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) 540 541## jerryx_arg_native_pointer 542 543**Summary** 544 545Create a validation/transformation step (`jerryx_arg_t`) that expects to 546consume one `object` JS argument that is 'backed' with a native pointer with 547a given type info. In case the native pointer info matches, the transform 548will succeed and the object's native pointer will be assigned to `*dest`. 549 550**Prototype** 551 552```c 553static inline jerryx_arg_t 554jerryx_arg_native_pointer (void **dest, 555 const jerry_object_native_info_t *info_p, 556 jerryx_arg_optional_t opt_flag) 557``` 558 - return value - the created `jerryx_arg_t` instance. 559 - `dest` - pointer to where the resulting native pointer should be stored. 560 - `info_p` - expected the type info. 561 - `opt_flag` - whether the argument is optional. 562 563**See also** 564 565- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) 566 567## jerryx_arg_object_properties 568 569**Summary** 570 571Create a validation/transformation step (`jerryx_arg_t`) that expects to 572consume one `object` JS argument and call `jerryx_arg_transform_object_properties` inside 573to transform its properties to native arguments. 574User should prepare the `jerryx_arg_object_props_t` instance, and pass it to this function. 575 576**Prototype** 577 578```c 579static inline jerryx_arg_t 580jerryx_arg_object_properties (const jerryx_arg_object_props_t *object_props_p, 581 jerryx_arg_optional_t opt_flag); 582``` 583 - return value - the created `jerryx_arg_t` instance. 584 - `object_props_p` - provides information for properties transform. 585 - `opt_flag` - whether the argument is optional. 586 587**Example** 588 589[doctest]: # (test="compile") 590 591```c 592#include "jerryscript.h" 593#include "jerryscript-ext/arg.h" 594 595/** 596 * The binding function expects args_p[0] is an object, which has 3 properties: 597 * "enable": boolean 598 * "data": number 599 * "extra_data": number, optional 600 */ 601static jerry_value_t 602my_external_handler (const jerry_value_t function_obj, 603 const jerry_value_t this_val, 604 const jerry_value_t args_p[], 605 const jerry_length_t args_count) 606{ 607 bool required_bool; 608 double required_num; 609 double optional_num = 1234.567; // default value 610 611 /* "prop_name_p" defines the name list of the expected properties' names. */ 612 const char *prop_name_p[] = { "enable", "data", "extra_data" }; 613 614 /* "prop_mapping" defines the steps to transform properties to C variables. */ 615 const jerryx_arg_t prop_mapping[] = 616 { 617 jerryx_arg_boolean (&required_bool, JERRYX_ARG_COERCE, JERRYX_ARG_REQUIRED), 618 jerryx_arg_number (&required_num, JERRYX_ARG_COERCE, JERRYX_ARG_REQUIRED), 619 jerryx_arg_number (&optional_num, JERRYX_ARG_COERCE, JERRYX_ARG_OPTIONAL) 620 }; 621 622 /* Prepare the jerryx_arg_object_props_t instance. */ 623 const jerryx_arg_object_props_t prop_info = 624 { 625 .name_p = (const jerry_char_t **) prop_name_p, 626 .name_cnt = 3, 627 .c_arg_p = prop_mapping, 628 .c_arg_cnt = 3 629 }; 630 631 /* It is the mapping used in the jerryx_arg_transform_args. */ 632 const jerryx_arg_t mapping[] = 633 { 634 jerryx_arg_object_properties (&prop_info, JERRYX_ARG_REQUIRED) 635 }; 636 637 /* Validate and transform. */ 638 const jerry_value_t rv = jerryx_arg_transform_args (args_p, 639 args_count, 640 mapping, 641 1); 642 643 if (jerry_value_is_error (rv)) 644 { 645 /* Handle error. */ 646 return rv; 647 } 648 649 /* 650 * Validated and transformed successfully! 651 * required_bool, required_num and optional_num can now be used. 652 */ 653 654 return jerry_create_undefined (); /* Or return something more meaningful. */ 655} 656 657``` 658 659 **See also** 660 661- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) 662- [jerryx_arg_transform_object_properties](#jerryx_arg_transform_object_properties) 663 664## jerryx_arg_array 665 666**Summary** 667 668Create a validation/transformation step (`jerryx_arg_t`) that expects to 669consume one `array` JS argument and call `jerryx_arg_transform_array_items` inside 670to transform its items to native arguments. 671User should prepare the `jerryx_arg_array_items_t` instance, and pass it to this function. 672 673**Prototype** 674 675```c 676static inline jerryx_arg_t 677jerryx_arg_array (const jerryx_arg_array_items_t *array_items_p, jerryx_arg_optional_t opt_flag); 678``` 679 - return value - the created `jerryx_arg_t` instance. 680 - `array_items_p` - provides items information for transform. 681 - `opt_flag` - whether the argument is optional. 682 683**Example** 684 685[doctest]: # (test="compile") 686 687```c 688#include "jerryscript.h" 689#include "jerryscript-ext/arg.h" 690 691/** 692 * The binding function expects args_p[0] is an array, which has 3 items: 693 * first: boolean 694 * second: number 695 * third: number, optional 696 */ 697static jerry_value_t 698my_external_handler (const jerry_value_t function_obj, 699 const jerry_value_t this_val, 700 const jerry_value_t args_p[], 701 const jerry_length_t args_count) 702{ 703 bool required_bool; 704 double required_num; 705 double optional_num = 1234.567; // default value 706 707 /* "item_mapping" defines the steps to transform array items to C variables. */ 708 const jerryx_arg_t item_mapping[] = 709 { 710 jerryx_arg_boolean (&required_bool, JERRYX_ARG_COERCE, JERRYX_ARG_REQUIRED), 711 jerryx_arg_number (&required_num, JERRYX_ARG_COERCE, JERRYX_ARG_REQUIRED), 712 jerryx_arg_number (&optional_num, JERRYX_ARG_COERCE, JERRYX_ARG_OPTIONAL) 713 }; 714 715 /* Prepare the jerryx_arg_array_items_t instance. */ 716 const jerryx_arg_array_items_t array_info = 717 { 718 .c_arg_p = item_mapping, 719 .c_arg_cnt = 3 720 }; 721 722 /* It is the mapping used in the jerryx_arg_transform_args. */ 723 const jerryx_arg_t mapping[] = 724 { 725 jerryx_arg_array (&array_info, JERRYX_ARG_REQUIRED) 726 }; 727 728 /* Validate and transform. */ 729 const jerry_value_t rv = jerryx_arg_transform_args (args_p, 730 args_count, 731 mapping, 732 1); 733 734 if (jerry_value_is_error (rv)) 735 { 736 /* Handle error. */ 737 return rv; 738 } 739 740 /* 741 * Validated and transformed successfully! 742 * required_bool, required_num and optional_num can now be used. 743 */ 744 745 return jerry_create_undefined (); /* Or return something more meaningful. */ 746} 747 748``` 749 750 **See also** 751 752- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) 753- [jerryx_arg_transform_object_properties](#jerryx_arg_transform_object_properties) 754 755# Functions to create custom validations 756 757## jerryx_arg_custom 758 759**Summary** 760 761Create a jerryx_arg_t instance with custom transform. 762 763**Prototype** 764 765```c 766static inline jerryx_arg_t 767jerryx_arg_custom (void *dest, 768 uintptr_t extra_info, 769 jerryx_arg_transform_func_t func) 770 771``` 772 - return value - the created `jerryx_arg_t` instance. 773 - `dest` - pointer to the native argument where the result should be stored. 774 - `extra_info` - the extra parameter data, specific to the transform function. 775 - `func` - the custom transform function. 776 777**See also** 778 779- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args) 780 781 782 783## jerryx_arg_js_iterator_pop 784 785**Summary** 786 787Pop the current `jerry_value_t` argument from the iterator. 788It will change the `js_arg_idx` and `js_arg_p` value in the iterator. 789 790**Prototype** 791 792```c 793jerry_value_t 794jerryx_arg_js_iterator_pop (jerryx_arg_js_iterator_t *js_arg_iter_p) 795``` 796 - return value - the `jerry_value_t` argument that was popped. 797 - `js_arg_iter_p` - the JS arg iterator from which to pop. 798 799## jerryx_arg_js_iterator_peek 800 801**Summary** 802 803Get the current JS argument from the iterator, without moving the iterator forward. 804*Note:* Unlike `jerryx_arg_js_iterator_pop ()`, it will not change `js_arg_idx` and 805`js_arg_p` value in the iterator. 806 807**Prototype** 808 809```c 810jerry_value_t 811jerryx_arg_js_iterator_peek (jerryx_arg_js_iterator_t *js_arg_iter_p) 812``` 813 - return value - the current `jerry_value_t` argument. 814 - `js_arg_iter_p` - the JS arg iterator from which to peek. 815 816## jerryx_arg_js_iterator_restore 817 818**Summary** 819 820Restore the last item popped from the stack. This can be called as 821many times as there are arguments on the stack -- if called when the 822first element in the array is the current top of the stack, this 823function does nothing. 824 825*Note:* This function relies on the underlying implementation of the 826arg stack as an array, as its function is to simply back up the "top 827of stack" pointer to point to the previous element of the array. 828 829*Note:* Like `jerryx_arg_js_iterator_pop ()`, this function will 830change the `js_arg_idx` and `js_arg_p` values in the iterator. 831 832**Prototype** 833 834```c 835jerry_value_t 836jerryx_arg_js_iterator_restore (jerryx_arg_js_iterator_t *js_arg_iter_p) 837``` 838 - return value - the the new top of the stack. 839 - `js_arg_iter_p` - the JS arg iterator to restore. 840 841 842## jerryx_arg_js_iterator_index 843 844**Summary** 845 846Get the index of the current JS argument from the iterator. 847 848**Prototype** 849 850```c 851jerry_length_t 852jerryx_arg_js_iterator_index (jerryx_arg_js_iterator_t *js_arg_iter_p) 853``` 854 - return value - the index of current JS argument. 855 - `js_arg_iter_p` - the JS arg iterator from which to peek. 856