Update the webpage (#1820)
* Add docs of extensions * Use `category` to distinct dropdown pages * Sort the documents alphabetical JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
This commit is contained in:
Zsolt Borbély
@@ -1,6 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: Getting Started
|
||||
category: navbar
|
||||
permalink: /getting-started/
|
||||
---
|
||||
|
||||
|
||||
+238
-2
@@ -1,6 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: API Reference
|
||||
category: navbar
|
||||
permalink: /api-reference/
|
||||
---
|
||||
|
||||
@@ -45,6 +46,7 @@ Possible compile time enabled feature types:
|
||||
- JERRY_FEATURE_SNAPSHOT_SAVE - saving snapshot files
|
||||
- JERRY_FEATURE_SNAPSHOT_EXEC - executing snapshot files
|
||||
- JERRY_FEATURE_DEBUGGER - debugging
|
||||
- JERRY_FEATURE_VM_EXEC_STOP - stopping ECMAScript execution
|
||||
|
||||
## jerry_char_t
|
||||
|
||||
@@ -243,6 +245,28 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na
|
||||
void *user_data_p);
|
||||
```
|
||||
|
||||
## jerry_vm_exec_stop_callback_t
|
||||
|
||||
**Summary**
|
||||
|
||||
Callback which tells whether the ECMAScript execution should be stopped.
|
||||
If it returns with undefined value the ECMAScript execution continues.
|
||||
Otherwise the result is thrown by the engine (if the error flag is not
|
||||
set for the returned value the engine automatically sets it). The
|
||||
callback function might be called again even if it threw an error.
|
||||
In this case the function must throw the same error again.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p);
|
||||
```
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_set_vm_exec_stop_callback](#jerry_set_vm_exec_stop_callback)
|
||||
|
||||
|
||||
# General engine functions
|
||||
|
||||
## jerry_init
|
||||
@@ -1058,6 +1082,47 @@ jerry_value_is_object (const jerry_value_t value)
|
||||
- [jerry_release_value](#jerry_release_value)
|
||||
|
||||
|
||||
## jerry_value_is_promise
|
||||
|
||||
**Summary**
|
||||
|
||||
Returns whether the given `jerry_value_t` is a promise value.
|
||||
|
||||
*Note*: This API depends on the ES2015-subset profile.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
bool
|
||||
jerry_value_is_promise (const jerry_value_t value)
|
||||
```
|
||||
|
||||
- `value` - api value
|
||||
- return value
|
||||
- true, if the given `jerry_value_t` is a promise
|
||||
- false, otherwise
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
... // create or acquire value
|
||||
|
||||
if (jerry_value_is_promise (value))
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_release_value](#jerry_release_value)
|
||||
|
||||
|
||||
## jerry_value_is_string
|
||||
|
||||
**Summary**
|
||||
@@ -1966,6 +2031,64 @@ jerry_value_to_string (const jerry_value_t value);
|
||||
- [jerry_value_to_primitive](#jerry_value_to_primitive)
|
||||
|
||||
|
||||
# Functions for promise objects
|
||||
|
||||
These APIs all depends on the ES2015-subset profile.
|
||||
|
||||
## jerry_resolve_or_reject_promise
|
||||
|
||||
**Summary**
|
||||
|
||||
Resolve or reject the promise with an argument.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
jerry_value_t
|
||||
jerry_resolve_or_reject_promise (jerry_value_t promise,
|
||||
jerry_value_t argument,
|
||||
bool is_resolve)
|
||||
```
|
||||
|
||||
- `promise` - the promise value
|
||||
- `argument` - the argument for resolve or reject
|
||||
- `is_resolve` - whether the promise should be resolved or rejected
|
||||
- return value
|
||||
- undefined jerry value - resolve or reject successed
|
||||
- jerry value with error flag - otherwise
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t promise = ... // acquire/create a promise object.
|
||||
|
||||
...
|
||||
|
||||
bool is_resolve = ... // whether the promise should be resolved or rejected
|
||||
jerry_value_t argument = ... // prepare the argumnent for the resolve or reject.
|
||||
|
||||
jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
|
||||
argument,
|
||||
is_resolve);
|
||||
|
||||
if (jerry_value_has_error_flag (is_ok))
|
||||
{
|
||||
// handle the error.
|
||||
}
|
||||
|
||||
jerry_release_value (is_ok);
|
||||
jerry_release_value (argument);
|
||||
jerry_release_value (promise);
|
||||
}
|
||||
```
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_release_value](#jerry_release_value)
|
||||
- [jerry_value_has_error_flag](#jerry_value_has_error_flag)
|
||||
|
||||
|
||||
# Acquire and release API values
|
||||
|
||||
## jerry_acquire_value
|
||||
@@ -2411,6 +2534,41 @@ jerry_create_object (void);
|
||||
- [jerry_release_value](#jerry_release_value)
|
||||
|
||||
|
||||
## jerry_create_promise
|
||||
|
||||
**Summary**
|
||||
|
||||
Create an empty promise object which can be resolved or rejected later
|
||||
by calling jerry_resolve_or_reject_promise.
|
||||
|
||||
*Note*: This API depends on the ES2015-subset profile.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
jerry_value_t
|
||||
jerry_create_promise (void)
|
||||
```
|
||||
|
||||
- return value - value of the newly created promise
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t p = jerry_create_promise ();
|
||||
|
||||
...// usage of the promise
|
||||
|
||||
jerry_release_value (p);
|
||||
}
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_resolve_or_reject_promise](#jerry_resolve_or_reject_promise)
|
||||
- [jerry_release_value](#jerry_release_value)
|
||||
|
||||
|
||||
## jerry_create_string
|
||||
|
||||
**Summary**
|
||||
@@ -3514,7 +3672,7 @@ static const jerry_object_native_info_t native_obj_type_info =
|
||||
{
|
||||
// The type of this's native pointer matches what is expected.
|
||||
// Only now is it safe to cast to native_obj_t * and dereference the
|
||||
// pointer:
|
||||
// pointer:
|
||||
native_obj_t *native_obj = native_p;
|
||||
native_obj->bar = ...; // Safe to access now!
|
||||
}
|
||||
@@ -3568,7 +3726,7 @@ jerry_set_object_native_pointer (const jerry_value_t obj_val,
|
||||
**Example**
|
||||
|
||||
See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) for a
|
||||
best-practice example.
|
||||
best-practice example.
|
||||
|
||||
**See also**
|
||||
|
||||
@@ -3905,3 +4063,81 @@ jerry_parse_and_save_literals (const jerry_char_t *source_p,
|
||||
- [jerry_init](#jerry_init)
|
||||
- [jerry_cleanup](#jerry_cleanup)
|
||||
- [jerry_register_magic_strings](#jerry_register_magic_strings)
|
||||
|
||||
|
||||
# Miscellaneous functions
|
||||
|
||||
## jerry_set_vm_exec_stop_callback
|
||||
|
||||
**Summary**
|
||||
|
||||
When JERRY_FEATURE_VM_EXEC_STOP is enabled a callback function can be
|
||||
specified by this function. This callback is periodically called when
|
||||
JerryScript executes an ECMAScript program.
|
||||
|
||||
If the callback returns with undefined value the ECMAScript execution
|
||||
continues. Otherwise the result is thrown by the engine (if the error
|
||||
flag is not set for the returned value the engine automatically sets
|
||||
it). The callback function might be called again even if it threw
|
||||
an error. In this case the function must throw the same error again.
|
||||
|
||||
To reduce the CPU overhead of constantly checking the termination
|
||||
condition the callback is called when a backward jump is executed
|
||||
or an exception is caught. Setting the `frequency` to a greater
|
||||
than `1` value reduces this overhead further. If its value is N
|
||||
only every Nth event (backward jump, etc.) trigger the next check.
|
||||
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
void
|
||||
jerry_set_vm_exec_stop_callback (jerry_vm_exec_stop_callback_t stop_cb,
|
||||
void *user_p,
|
||||
uint32_t frequency);
|
||||
```
|
||||
|
||||
- `stop_cb` - periodically called callback (passing NULL disables this feature)
|
||||
- `user_p` - user pointer passed to the `stop_cb` function
|
||||
- `frequency` - frequency of calling the `stop_cb` function
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
static jerry_value_t
|
||||
vm_exec_stop_callback (void *user_p)
|
||||
{
|
||||
static int countdown = 10;
|
||||
|
||||
while (countdown > 0)
|
||||
{
|
||||
countdown--;
|
||||
return jerry_create_undefined ();
|
||||
}
|
||||
|
||||
// The error flag is added automatically.
|
||||
return jerry_create_string ((const jerry_char_t *) "Abort script");
|
||||
}
|
||||
|
||||
{
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
jerry_set_vm_exec_stop_callback (vm_exec_stop_callback, &countdown, 16);
|
||||
|
||||
// Inifinte loop.
|
||||
const char *src_p = "while(true) {}";
|
||||
|
||||
jerry_value_t src = jerry_parse ((jerry_char_t *) src_p, strlen (src_p), false);
|
||||
jerry_release_value (jerry_run (src));
|
||||
jerry_release_value (src);
|
||||
jerry_cleanup ();
|
||||
}
|
||||
```
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerry_init](#jerry_init)
|
||||
- [jerry_cleanup](#jerry_cleanup)
|
||||
- [jerry_parse](#jerry_parse)
|
||||
- [jerry_run](#jerry_run)
|
||||
- [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t)
|
||||
|
||||
+13
-12
@@ -1,6 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: API Examples
|
||||
category: navbar
|
||||
permalink: /api-example/
|
||||
---
|
||||
|
||||
@@ -182,38 +183,38 @@ created by API functions has the error flag set.
|
||||
The following example function will output a JavaScript value:
|
||||
|
||||
```c
|
||||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
#include <string.h>
|
||||
|
||||
#include "jerryscript.h"
|
||||
#include "jerryscript-port.h"
|
||||
|
||||
static void
|
||||
print_value (const jerry_value_t value)
|
||||
{
|
||||
if (jerry_value_is_undefined (value))
|
||||
{
|
||||
jerry_port_console ("undefined");
|
||||
printf ("undefined");
|
||||
}
|
||||
else if (jerry_value_is_null (value))
|
||||
{
|
||||
jerry_port_console ("null");
|
||||
printf ("null");
|
||||
}
|
||||
else if (jerry_value_is_boolean (value))
|
||||
{
|
||||
if (jerry_get_boolean_value (value))
|
||||
{
|
||||
jerry_port_console ("true");
|
||||
printf ("true");
|
||||
}
|
||||
else
|
||||
{
|
||||
jerry_port_console ("false");
|
||||
printf ("false");
|
||||
}
|
||||
}
|
||||
/* Float value */
|
||||
else if (jerry_value_is_number (value))
|
||||
{
|
||||
jerry_port_console ("number");
|
||||
printf ("number");
|
||||
}
|
||||
/* String value */
|
||||
else if (jerry_value_is_string (value))
|
||||
@@ -225,15 +226,15 @@ print_value (const jerry_value_t value)
|
||||
jerry_string_to_char_buffer (value, str_buf_p, req_sz);
|
||||
str_buf_p[req_sz] = '\0';
|
||||
|
||||
jerry_port_console ("%s", (const char *) str_buf_p);
|
||||
printf ("%s", (const char *) str_buf_p);
|
||||
}
|
||||
/* Object reference */
|
||||
else if (jerry_value_is_object (value))
|
||||
{
|
||||
jerry_port_console ("[JS object]");
|
||||
printf ("[JS object]");
|
||||
}
|
||||
|
||||
jerry_port_console ("\n");
|
||||
printf ("\n");
|
||||
}
|
||||
```
|
||||
|
||||
@@ -252,11 +253,11 @@ Shell operation can be described with the following loop:
|
||||
- loop.
|
||||
|
||||
```c
|
||||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
#include <string.h>
|
||||
|
||||
#include "jerryscript.h"
|
||||
#include "jerryscript-port.h"
|
||||
|
||||
static void print_value (const jerry_value_t);
|
||||
|
||||
@@ -274,7 +275,7 @@ main (int argc, char *argv[])
|
||||
char *cmd_tail = cmd;
|
||||
size_t len = 0;
|
||||
|
||||
jerry_port_console ("> ");
|
||||
printf ("> ");
|
||||
|
||||
/* Read next command */
|
||||
while (true)
|
||||
@@ -311,7 +312,7 @@ main (int argc, char *argv[])
|
||||
{
|
||||
/* Evaluated JS code thrown an exception
|
||||
* and didn't handle it with try-catch-finally */
|
||||
jerry_port_console ("Unhandled JS exception occured: ");
|
||||
printf ("Unhandled JS exception occured: ");
|
||||
}
|
||||
|
||||
print_value (ret_val);
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: Internals
|
||||
category: documents
|
||||
permalink: /internals/
|
||||
---
|
||||
|
||||
|
||||
+1
-27
@@ -1,6 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: Port API
|
||||
category: documents
|
||||
permalink: /port-api/
|
||||
---
|
||||
|
||||
@@ -44,20 +45,6 @@ typedef enum
|
||||
These are the only I/O functions jerry calls.
|
||||
|
||||
```c
|
||||
/**
|
||||
* Print a string to the console. The function should implement a printf-like
|
||||
* interface, where the first argument specifies a format string on how to
|
||||
* stringify the rest of the parameter list.
|
||||
*
|
||||
* This function is only called with strings coming from the executed ECMAScript
|
||||
* wanting to print something as the result of its normal operation.
|
||||
*
|
||||
* It should be the port that decides what a "console" is.
|
||||
*
|
||||
* Example: a libc-based port may implement this with vprintf().
|
||||
*/
|
||||
void jerry_port_console (const char *fmt, ...);
|
||||
|
||||
/**
|
||||
* Jerry log levels. The levels are in severity order
|
||||
* where the most serious levels come first.
|
||||
@@ -142,19 +129,6 @@ void jerry_port_fatal (jerry_fatal_code_t code)
|
||||
#include <stdarg.h>
|
||||
#include "jerryscript-port.h"
|
||||
|
||||
/**
|
||||
* Provide console message implementation for the engine.
|
||||
*/
|
||||
void
|
||||
jerry_port_console (const char *format, /**< format string */
|
||||
...) /**< parameters */
|
||||
{
|
||||
va_list args;
|
||||
va_start (args, format);
|
||||
vfprintf (stdout, format, args);
|
||||
va_end (args);
|
||||
} /* jerry_port_console */
|
||||
|
||||
/**
|
||||
* Provide log message implementation for the engine.
|
||||
*
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: Reference Counting
|
||||
category: documents
|
||||
permalink: /reference-counting/
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: Debugger
|
||||
category: documents
|
||||
permalink: /debugger/
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: Coding Standards
|
||||
category: documents
|
||||
permalink: /coding-standards/
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,423 @@
|
||||
---
|
||||
layout: page
|
||||
title: 'Extension API: Argument Validation'
|
||||
category: documents
|
||||
permalink: /ext-reference-arg/
|
||||
---
|
||||
|
||||
* toc
|
||||
{:toc}
|
||||
|
||||
# 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_function](#jerryx_arg_function)
|
||||
- [jerryx_arg_native_pointer](#jerryx_arg_native_pointer)
|
||||
- [jerryx_arg_ignore](#jerryx_arg_ignore)
|
||||
|
||||
## 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)
|
||||
|
||||
# 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**
|
||||
|
||||
```c
|
||||
// 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,
|
||||
ARRAY_LENGTH (mapping));
|
||||
|
||||
if (jerry_value_has_error_flag (rv))
|
||||
{
|
||||
// Handle error
|
||||
return rv;
|
||||
}
|
||||
|
||||
// Validated and tranformed successfully!
|
||||
// required_bool, required_str and optional_num can now be used.
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**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_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)
|
||||
|
||||
|
||||
# Helpers for commonly used validations
|
||||
|
||||
## 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 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)
|
||||
|
||||
|
||||
## 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)
|
||||
|
||||
|
||||
# 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.
|
||||
@@ -0,0 +1,189 @@
|
||||
---
|
||||
layout: page
|
||||
title: 'Extension API: External Function Handlers'
|
||||
category: documents
|
||||
permalink: /ext-reference-handler/
|
||||
---
|
||||
|
||||
* toc
|
||||
{:toc}
|
||||
|
||||
# Common external function handlers
|
||||
|
||||
## jerryx_handler_assert
|
||||
|
||||
**Summary**
|
||||
|
||||
Assert for scripts. The routine calls `jerry_port_fatal` on assertion failure.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
jerry_value_t
|
||||
jerryx_handler_assert (const jerry_value_t func_obj_val, const jerry_value_t this_p,
|
||||
const jerry_value_t args_p[], const jerry_length_t args_cnt);
|
||||
```
|
||||
|
||||
- `func_obj_val` - the function object that was called (unused).
|
||||
- `this_p` - the `this` value of the call (unused).
|
||||
- `args_p` - the array of function arguments.
|
||||
- `args_cnt` - the number of function arguments.
|
||||
- return value - `jerry_value_t` representing boolean true, if only one argument
|
||||
was passed and that argument was a boolean true. Note that the function does
|
||||
not return otherwise.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerryx_handler_register_global](#jerryx_handler_register_global)
|
||||
|
||||
|
||||
## jerryx_handler_gc
|
||||
|
||||
**Summary**
|
||||
|
||||
Expose garbage collector to scripts.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
jerry_value_t
|
||||
jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,
|
||||
const jerry_value_t args_p[], const jerry_length_t args_cnt);
|
||||
```
|
||||
|
||||
- `func_obj_val` - the function object that was called (unused).
|
||||
- `this_p` - the `this` value of the call (unused).
|
||||
- `args_p` - the array of function arguments (unused).
|
||||
- `args_cnt` - the number of function arguments (unused).
|
||||
- return value - `jerry_value_t` representing `undefined`.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerryx_handler_register_global](#jerryx_handler_register_global)
|
||||
|
||||
|
||||
## jerryx_handler_print
|
||||
|
||||
**Summary**
|
||||
|
||||
Provide a `print` implementation for scripts. The routine converts all of its
|
||||
arguments to strings and outputs them char-by-char using
|
||||
`jerryx_port_handler_print_char`. The NUL character is output as "\u0000",
|
||||
other characters are output bytewise.
|
||||
|
||||
*Note*: This implementation does not use standard C `printf` to print its
|
||||
output. This allows more flexibility but also extends the core JerryScript
|
||||
engine port API. Applications that want to use `jerryx_handler_print` must
|
||||
ensure that their port implementation also provides
|
||||
`jerryx_port_handler_print_char`.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
jerry_value_t
|
||||
jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this_p,
|
||||
const jerry_value_t args_p[], const jerry_length_t args_cnt);
|
||||
```
|
||||
|
||||
- `func_obj_val` - the function object that was called (unused).
|
||||
- `this_p` - the `this` value of the call (unused).
|
||||
- `args_p` - the array of function arguments.
|
||||
- `args_cnt` - the number of function arguments.
|
||||
- return value - `jerry_value_t` representing `undefined` if all arguments could
|
||||
be converted to strings, an `Error` otherwise.
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerryx_handler_register_global](#jerryx_handler_register_global)
|
||||
- [jerryx_port_handler_print_char](#jerryx_port_handler_print_char)
|
||||
|
||||
|
||||
# Handler registration helper
|
||||
|
||||
## jerryx_handler_register_global
|
||||
|
||||
**Summary**
|
||||
|
||||
Register a JavaScript function in the global object.
|
||||
|
||||
*Note*: Returned value must be freed with `jerry_release_value`, when it is no
|
||||
longer needed.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
jerry_value_t
|
||||
jerryx_handler_register_global (const jerry_char_t *name_p,
|
||||
jerry_external_handler_t handler_p);
|
||||
```
|
||||
|
||||
- `name_p` - the name of the function to be registered.
|
||||
- `handler_p` - the address of the external function handler.
|
||||
- return value - `jerry_value_t` representing boolean true, if the operation was
|
||||
successful, an `Error` otherwise.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
#include "jerryscript.h"
|
||||
#include "jerryscript-ext/handler.h"
|
||||
|
||||
static const struct {
|
||||
const char *name_p;
|
||||
jerry_external_handler_t handler_p;
|
||||
} common_functions[] =
|
||||
{
|
||||
{ "assert", jerryx_handler_assert },
|
||||
{ "gc", jerryx_handler_gc },
|
||||
{ "print", jerryx_handler_print },
|
||||
{ NULL, NULL }
|
||||
};
|
||||
|
||||
static void register_common_functions ()
|
||||
{
|
||||
jerry_value_t ret = jerry_create_undefined ();
|
||||
|
||||
for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_has_error_flag (ret); i++)
|
||||
{
|
||||
ret = jerryx_handler_register_global ((const jerry_char_t *) common_functions[i].name_p,
|
||||
common_functions[i].handler_p);
|
||||
}
|
||||
|
||||
return ret;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
# Port API extension
|
||||
|
||||
## jerryx_port_handler_print_char
|
||||
|
||||
**Summary**
|
||||
|
||||
Print a single character.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
void
|
||||
jerryx_port_handler_print_char (char c);
|
||||
```
|
||||
|
||||
- `c` - the character to print.
|
||||
|
||||
**Example**
|
||||
|
||||
```c
|
||||
/**
|
||||
* Print a character to stdout with printf.
|
||||
*/
|
||||
void
|
||||
jerryx_port_handler_print_char (char c)
|
||||
{
|
||||
printf ("%c", c);
|
||||
} /* jerryx_port_handler_print_char */
|
||||
```
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerryx_handler_print](#jerryx_handler_print)
|
||||
@@ -21,7 +21,7 @@
|
||||
<ul class="nav navbar-nav navbar-right">
|
||||
{% for p in site.pages %}
|
||||
{% if p.title %}
|
||||
{% if p.url != "/coding-standards/" and p.url != "/debugger/" and p.url != "/internals/" and p.url != "/port-api/" and p.url != "/reference-counting/" %}
|
||||
{% if p.category == "navbar" %}
|
||||
{% if page.url == p.url %}
|
||||
<li class="active"><a href="{{ p.url | prepend: site.github.url }}" >{{ p.title }}</a></li>
|
||||
{% else %}
|
||||
@@ -32,11 +32,10 @@
|
||||
{% endfor %}
|
||||
<li class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">Documents <span class="caret"></span></a>
|
||||
<ul class="dropdown-menu">
|
||||
{% for p in site.pages %}
|
||||
{% if p.title %}
|
||||
{% if p.url == "/coding-standards/" or p.url == "/debugger/" or p.url == "/internals/" or p.url == "/port-api/" or p.url == "/reference-counting/" %}
|
||||
<li><a href="{{ p.url | prepend: site.github.url }}" >{{ p.title }}</a></li>
|
||||
{% endif %}
|
||||
{% assign doclist = site.pages | sort: 'title' %}
|
||||
{% for p in doclist %}
|
||||
{% if p.title and p.category == "documents" %}
|
||||
<li><a href="{{ p.url | prepend: site.github.url }}" >{{ p.title }}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
|
||||
Reference in New Issue
Block a user