YourWishes/jerryscript
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update the webpage

Browse Source 
JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
This commit is contained in:
Zsolt Borbély
2016-08-26 16:38:24 +02:00
parent 0deac9f81c
commit 622f42e0a8
5 changed files with 336 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files
02.API-REFERENCE.md
+157 -68
View File
@@ -14,14 +14,15 @@ permalink: /api-reference/
Enum that contains the following elements:
- JERRY_INIT_EMPTY - empty flag set
- JERRY_INIT_ENABLE_LOG - enable logging
- JERRY_INIT_SHOW_OPCODES - dump byte-code to stdout after parse
- JERRY_INIT_SHOW_OPCODES - dump byte-code to log after parse
- JERRY_INIT_SHOW_REGEXP_OPCODES - dump regexp byte-code to log after compilation
- JERRY_INIT_MEM_STATS - dump memory statistics
- JERRY_INIT_MEM_STATS_SEPARATE - dump memory statistics and reset peak values after parse
## jerry_error_t
Possible types of an error:
- JERRY_ERROR_COMMON - common error
- JERRY_ERROR_EVAL - eval error
- JERRY_ERROR_RANGE - range error
@@ -42,6 +43,18 @@ Jerry's char value
typedef uint8_t jerry_char_t;
```
## jerry_char_ptr_t
**Summary**
Pointer to an array of character values
**Prototype**
```c
typedef jerry_char_t *jerry_char_ptr_t;
```
## jerry_size_t
**Summary**
@@ -139,7 +152,7 @@ Type of an external function handler
**Prototype**
```c
typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj_p,
typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj,
const jerry_value_t this_val,
const jerry_value_t args_p[],
const jerry_length_t args_count);
@@ -166,7 +179,7 @@ Function type applied for each data property of an object
**Prototype**
```c
typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name_p,
typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name,
const jerry_value_t property_value,
void *user_data_p);
```
@@ -190,8 +203,8 @@ jerry_init (jerry_init_flag_t flags)
`flags` - combination of various engine configuration flags:
- `JERRY_INIT_EMPTY` - no flags, just initialize in default configuration.
- `JERRY_INIT_ENABLE_LOG` - enable logging.
- `JERRY_INIT_SHOW_OPCODES` - print compiled byte-code.
- `JERRY_INIT_SHOW_REGEXP_OPCODES` - print compiled regexp byte-code.
- `JERRY_INIT_MEM_STATS` - dump memory statistics.
- `JERRY_INIT_MEM_STATS_SEPARATE` - dump memory statistics and reset peak values after parse.
@@ -199,7 +212,7 @@ jerry_init (jerry_init_flag_t flags)
```c
{
jerry_init (JERRY_INIT_SHOW_OPCODES | JERRY_INIT_ENABLE_LOG);
jerry_init (JERRY_INIT_SHOW_OPCODES | JERRY_INIT_SHOW_REGEXP_OPCODES);
// ...
@@ -242,14 +255,14 @@ Registers an external magic string array.
```c
void
jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items,
jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p,
uint32_t count,
const jerry_length_t *str_lengths);
const jerry_length_t *str_lengths_p);
```
- `ex_str_items` - character arrays, representing external magic strings' contents
- `ex_str_items_p` - character arrays, representing external magic strings' contents
- `count` - number of the strings
- `str_lengths` - lengths of the strings
- `str_lengths_p` - lengths of the strings
**Example**
@@ -305,8 +318,8 @@ jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p,
jerry_init (JERRY_INIT_EMPTY);
size_t stack_limit;
size_t data_dss_brk_limit;
jerry_get_memory_limits (&stack_limit, &data_dss_brk_limit);
size_t data_bss_brk_limit;
jerry_get_memory_limits (&stack_limit, &data_bss_brk_limit);
}
```
@@ -354,12 +367,12 @@ The simplest way to run JavaScript.
```c
bool
jerry_run_simple (const jerry_char_t *script_source,
jerry_run_simple (const jerry_char_t *script_source_p,
size_t script_source_size,
jerry_init_flag_t flags);
```
- `script_source` - source code, it must be a valid utf8 string.
- `script_source_p` - source code, it must be a valid utf8 string.
- `script_source_size` - size of source code buffer, in bytes.
- `jerry_init_flag_t` - combination of various engine configuration flags
- return value
@@ -388,7 +401,8 @@ jerry_run_simple (const jerry_char_t *script_source,
**Summary**
Parse specified script to execute in Global scope.
Parse script and construct an EcmaScript function. The
lexical environment is set to the global lexical environment.
*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it
is no longer needed.
@@ -415,7 +429,7 @@ jerry_parse (const jerry_char_t *source_p,
{
jerry_init (JERRY_INIT_EMPTY);
char script [] = "print ('Hello, World!');";
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
jerry_value_t parsed_code = jerry_parse (script, script_size, false);
@@ -434,7 +448,7 @@ jerry_parse (const jerry_char_t *source_p,
**Summary**
Run code in Global scope.
Run an EcmaScript function created by `jerry_parse`.
*Note*: The code should be previously parsed with `jerry_parse`.
@@ -442,7 +456,7 @@ Run code in Global scope.
```c
jerry_value_t
jerry_run (jerry_value_t func_val);
jerry_run (const jerry_value_t func_val);
```
- `func_val` - function to run
@@ -529,7 +543,7 @@ jerry_eval (const jerry_char_t *source_p,
Get the Global object.
*Note*: Returned value must be freed with [jerry_release_object](#jerryreleaseobject) when it
*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it
is no longer needed.
**Prototype**
@@ -555,7 +569,7 @@ jerry_get_global_object (void);
**See also**
- [jerry_release_object](#jerryreleaseobject)
- [jerry_release_value](#jerryreleasevalue)
- [jerry_define_own_property](#jerrydefineownproperty)
# Checker functions
@@ -566,6 +580,8 @@ Functions to check the type of an API value ([jerry_value_t](#jerryvaluet)).
**Summary**
Returns whether the given `jerry_value_t` is an array.
**Prototype**
```c
@@ -1026,7 +1042,7 @@ Get raw data from API values.
**Summary**
Gets the raw bool value form a `jerry_value_t`.
Gets the raw bool value from a `jerry_value_t`.
**Prototype**
@@ -1111,7 +1127,7 @@ jerry_get_number_value (const jerry_value_t value);
**Summary**
Get the size of a string. Returns zero, if the specified string is not a value.
Get the size of a string. Returns zero, if the value parameter is not a string.
**Prototype**
@@ -1126,7 +1142,7 @@ jerry_get_string_size (const jerry_value_t value);
```c
{
jerry_char_t char_array[] = "a string";
const jerry_char_t char_array[] = "a string";
jerry_value_t string = jerry_create_string (char_array);
jerry_size_t string_size = jerry_get_string_size (string);
@@ -1147,7 +1163,7 @@ jerry_get_string_size (const jerry_value_t value);
**Summary**
Get the length of a string. Returns zero, if the specified string is not a value.
Get the length of a string. Returns zero, if the value parameter is not a string.
**Prototype**
@@ -1163,7 +1179,7 @@ jerry_get_string_length (const jerry_value_t value);
```c
{
jerry_char_t char_array[] = "a string";
const jerry_char_t char_array[] = "a string";
jerry_value_t string = jerry_create_string (char_array);
jerry_length_t string_length = jerry_get_string_length (string);
@@ -1184,10 +1200,10 @@ jerry_get_string_length (const jerry_value_t value);
**Summary**
Copy string characters to specified buffer. It is the caller's responsibility to make sure that
the string fits in the buffer.
*Note*: '\0' could occur in characters.
Copy the characters of a string into a specified buffer. The
'\0' character could occur in character buffer. Returns 0,
if the value parameter is not a string or the buffer is
not large enough for the whole string.
**Prototype**
@@ -1263,7 +1279,7 @@ jerry_get_array_length (const jerry_value_t value);
# Converters of 'jerry_value_t'
Functions for convering API values to another value type.
Functions for converting API values to another value type.
## jerry_value_to_boolean
@@ -1437,7 +1453,7 @@ jerry_value_to_string (const jerry_value_t value);
- `value` - api value
- return value
- converted srting value, if success
- converted string value, if success
- thrown error, otherwise
**Example**
@@ -1459,7 +1475,7 @@ jerry_value_to_string (const jerry_value_t value);
- [jerry_value_to_primitive](#jerryvaluetoprimitive)
# Aquire and release API values
# Acquire and release API values
## jerry_acquire_value
@@ -1628,7 +1644,7 @@ jerry_create_error (jerry_error_t error_type,
```c
{
jerry_value_t error_obj = jerry_create_error (JERRY_ERROR_TYPE,
(jerry_char_t * ) "error");
(const jerry_char_t *) "error");
... // usage of error_obj
@@ -1668,10 +1684,10 @@ jerry_create_error_sz (jerry_error_t error_type,
```c
{
jerry_char_t message[] = "error";
const jerry_char_t *message = "error";
jerry_value_t error_obj = jerry_create_error_sz (JERRY_ERROR_COMMON,
message,
strlen ((char *) message));
strlen ((const char *) message));
... // usage of error_obj
@@ -1704,10 +1720,10 @@ jerry_create_external_function (jerry_external_handler_t handler_p);
```c
static jerry_value_t
handler (const jerry_value_t function_obj_p,
const jerry_value_t this_p,
handler (const jerry_value_t function_obj,
const jerry_value_t this_val,
const jerry_value_t args_p[],
const uint16_t args_cnt)
const jerry_length_t args_cnt)
{
printf ("native handler called!\n");
@@ -1719,7 +1735,7 @@ handler (const jerry_value_t function_obj_p,
jerry_value_t glob_obj = jerry_get_global_object ();
// after this, script can invoke the native handler through "handler_field (1, 2, 3);"
jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field");
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field");
jerry_set_property (glob_obj, prop_name, func_val);
jerry_release_value (prop_name);
@@ -1766,6 +1782,77 @@ jerry_create_number (double value);
**See also**
- [jerry_release_value](#jerryreleasevalue)
- [jerry_create_number_infinity](#jerrycreatenumberinfinity)
- [jerry_create_number_nan](#jerrycreatenumbernan)
## jerry_create_number_infinity
**Summary**
Creates a `jerry_value_t` representing a positive or negative infinity value.
**Prototype**
```c
jerry_value_t
jerry_create_number_infinity (bool sign);
```
- `sign` - true for negative Infinity and false for positive Infinity
- return value - a `jerry_value_t` representing the infinity value
**Example**
```c
{
jerry_value_t positive_inf_value = jerry_create_number_infinity (false);
... // usage of the positive_inf_value
jerry_release_value (positive_inf_value);
}
```
**See also**
- [jerry_release_value](#jerryreleasevalue)
- [jerry_create_number](#jerrycreatenumber)
- [jerry_create_number_nan](#jerrycreatenumbernan)
## jerry_create_number_nan
**Summary**
Creates a `jerry_value_t` representing a not-a-number value.
**Prototype**
```c
jerry_value_t
jerry_create_number_nan (void);
```
- return value - a `jerry_value_t` representing the not-a-number value
**Example**
```c
{
jerry_value_t nan_value = jerry_create_number_nan ();
... // usage of the nan_value
jerry_release_value (nan_value);
}
```
**See also**
- [jerry_release_value](#jerryreleasevalue)
- [jerry_create_number](#jerrycreatenumber)
- [jerry_create_number_infinity](#jerrycreatenumberinfinity)
## jerry_create_null
@@ -1890,7 +1977,7 @@ jerry_create_string_sz (const jerry_char_t *str_p,
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string_value = jerry_create_string_sz (char_array,
strlen ((char *) char_array));
strlen ((const char *) char_array));
... // usage of string_value
@@ -1901,14 +1988,14 @@ jerry_create_string_sz (const jerry_char_t *str_p,
**See also**
- [jerry_release_string](#jerryreleasestring)
- [jerry_create_string](#jerrycreatestring)
## jerry_create_undefined
**Summary**
Creates a jerry_value_t representing an undefined value.
Creates a `jerry_value_t` representing an undefined value.
**Prototype**
@@ -1942,7 +2029,7 @@ jerry_create_undefined (void);
**Summary**
Checks whether the object or it's prototype has the given property.
Checks whether the object or it's prototype objects have the given property.
**Prototype**
@@ -1963,7 +2050,7 @@ jerry_has_property (const jerry_value_t obj_val,
```c
{
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field");
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field");
bool has_prop = jerry_has_property (global_object, prop_name);
@@ -2003,7 +2090,7 @@ jerry_has_own_property (const jerry_value_t obj_val,
```c
{
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field");
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field");
bool has_prop = jerry_has_own_property (global_object, prop_name);
@@ -2043,7 +2130,7 @@ jerry_delete_property (const jerry_value_t obj_val,
```c
{
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "my_prop");
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop");
jerry_delete_property (global_object, prop_name);
@@ -2124,7 +2211,7 @@ jerry_get_property_by_index (const jerry_value_t obj_val,
```
- `obj_val` - object value
- index - index number
- `index` - index number
- return value
- stored value on the specified index, if success
- thrown exception, otherwise.
@@ -2190,7 +2277,7 @@ jerry_set_property (const jerry_value_t obj_val,
... // create or acquire value to set
jerry_value_t glob_obj = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "my_prop");
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop");
jerry_set_property (glob_obj, prop_name, value_to_set);
@@ -2232,7 +2319,7 @@ jerry_set_property_by_index (const jerry_value_t obj_val,
```
- `obj_val` - object value
- index - index number
- `index` - index number
- `value_to_set` - value to set
- return value
- true, if field value was set successfully
@@ -2445,7 +2532,8 @@ jerry_free_property_descriptor_fields (const jerry_property_descriptor_t *prop_d
**Summary**
Call function specified by a function value.
Call function specified by a function value. Error flag
must not be set for any arguments of this function.
*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it
is no longer needed.
@@ -2501,6 +2589,7 @@ jerry_call_function (const jerry_value_t func_obj_val,
**Summary**
Construct object, invoking specified function object as constructor.
Error flag must not be set for any arguments of this function.
*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it
is no longer needed.
@@ -2511,7 +2600,7 @@ is no longer needed.
jerry_value_t
jerry_construct_object (const jerry_value_t func_obj_val,
const jerry_value_t args_p[],
uint16_t args_count);
jerry_size_t args_count);
```
- `func_obj_val` - function object to call
@@ -2713,25 +2802,26 @@ jerry_get_object_native_handle (const jerry_value_t obj_val,
**Summary**
Set native handle and, optionally, free callback for the specified object
Set native handle and an optional free callback for the specified object
*Note*: If native handle was already set for the object, its value is updated.
*Note*: If free callback is specified, it is set to be called upon specified JS-object is freed (by GC).
Otherwise, if NULL is specified for free callback pointer, free callback is not created and, if
a free callback was added earlier for the object, it is removed.
*Note*: If a non-NULL free callback is specified, it will be called
by the garbage collector when the object is freed. The free
callback always overwrites the previous value, so passing
a NULL value deletes the current free callback.
**Prototype**
```c
void
jerry_set_object_native_handle (const jerry_value_t obj_val,
uintptr_t handle,
uintptr_t handle_p,
jerry_object_free_callback_t freecb_p);
```
- `obj_val` - object value to set handle in
- `handle` - handle value
- `handle_p` - handle value
- `freecb_p` - pointer to "free" callback or NULL
**Example**
@@ -2774,14 +2864,13 @@ jerry_foreach_object_property (jerry_value_t obj_val,
```
- `obj_val` - object value
- `foreach_p` - foreach function, that will be apllied for each property
- `foreach_p` - foreach function, that will be applied for each property
- `user_data_p` - user data for foreach function
- return value
- true, if object fields traversal was performed successfully, i.e.:
- no unhandled exceptions were thrown in object fields traversal
- object fields traversal was stopped on callback that returned false
- false, otherwise, if getter of field threw a exception or unhandled exceptions were thrown
during traversal
- false, otherwise
**Example**
@@ -2834,13 +2923,13 @@ jerry_parse_and_save_snapshot (const jerry_char_t *source_p,
- `source_p` - script source, it must be a valid utf8 string.
- `source_size` - script source size, in bytes.
- `is_for_global` - snapshot would be executed as global (true) or eval (false).
- `is_strict` - stric mode
- `is_strict` - strict mode
- `buffer_p` - buffer to save snapshot to.
- `buffer_size` - the buffer's size.
- return value
- the size of snapshot, if it was generated succesfully (i.e. there are no syntax errors in source
code, buffer size is sufficient, and snapshot support is enabled in current configuration through
JERRY_ENABLE_SNAPSHOT)
JERRY_ENABLE_SNAPSHOT_SAVE)
- 0 otherwise.
**Example**
@@ -2850,10 +2939,10 @@ jerry_parse_and_save_snapshot (const jerry_char_t *source_p,
jerry_init (JERRY_INIT_EMPTY);
static uint8_t global_mode_snapshot_buffer[1024];
const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
const jerry_char_t *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p,
strlen (code_to_snapshot_p),
size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p,
strlen ((const char *) code_to_snapshot_p),
true,
false,
global_mode_snapshot_buffer,
@@ -2904,11 +2993,11 @@ jerry_exec_snapshot (const void *snapshot_p,
{
jerry_value_t res;
static uint8_t global_mode_snapshot_buffer[1024];
const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
const jerry_char_t *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
jerry_init (JERRY_INIT_EMPTY);
size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p,
strlen (code_to_snapshot_p),
size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p,
strlen ((const char *) code_to_snapshot_p),
true,
global_mode_snapshot_buffer,
sizeof (global_mode_snapshot_buffer));