mirror of
https://github.com/jerryscript-project/jerryscript.git
synced 2025-12-15 16:29:21 +00:00
abc29eee34
- fixed lists - image size correction - fixed code listings formats - capital letters are used in titles JerryScript-DCO-1.0-Signed-off-by: István Kádár ikadar@inf.u-szeged.hu
63 KiB
63 KiB
| layout | title | permalink |
|---|---|---|
| page | API | /API/ |
- toc {:toc}
jerry_run_simple
Summary
The simplest way to run JavaScript.
Prototype
jerry_completion_code_t
jerry_run_simple (const jerry_api_char_t *script_source,
size_t script_source_size,
jerry_flag_t flags);
script_source- source code;script_source_size- size of source code buffer, in bytes;- returned value - completion code that indicates whether run was performed successfully (
JERRY_COMPLETION_CODE_OK), or an unhandled JavaScript exception occurred (JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION).
Example
{
const jerry_api_char_t *script = "print ('Hello, World!');";
jerry_run_simple (script, strlen ((const char *) script), JERRY_FLAG_EMPTY);
}
See also
jerry_init
Summary
Initializes JerryScript engine, making possible to run JavaScript code and perform operations on JavaScript values.
Prototype
void
jerry_init (jerry_flag_t flags);
flags - combination of various engine configuration flags:
JERRY_FLAG_EMPTY- no flags, just initialize in default configuration;JERRY_FLAG_SHOW_OPCODES- print compiled byte-code;JERRY_FLAG_MEM_STATS- dump memory statistics;JERRY_FLAG_MEM_STATS_SEPARATE- dump memory statistics and reset peak values after parse;JERRY_FLAG_ENABLE_LOG- enable logging;
Example
{
jerry_init (JERRY_FLAG_ENABLE_LOG);
// ...
jerry_cleanup ();
}
See also
jerry_cleanup
Summary
Finish JavaScript engine execution, freeing memory and JavaScript values.
JavaScript values, received from engine, are inaccessible after the cleanup.
Prototype
void
jerry_cleanup (void);
See also
jerry_parse
Summary
Parse specified script to execute in Global scope.
Current API doesn't permit replacement or modification of Global scope's code without engine restart,
so jerry_parse could be invoked only once between jerry_init and jerry_cleanup.
Prototype
bool
jerry_parse (const jerry_api_char_t *source_p,
size_t source_size,
jerry_api_object_t **error_obj_p);
source_p- string, containing source code to parse;source_size- size of the string, in bytes.error_obj_p- error object (output parameter)
Example
{
jerry_init (JERRY_FLAG_EMPTY);
char script [] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
jerry_api_object_t *error_object_p = NULL;
if (!jerry_parse (script, script_size, &error_object_p))
{
/* Error object must be freed, if parsing failed */
jerry_api_release_object (error_object_p);
}
jerry_cleanup ();
}
See also
jerry_parse_and_save_snapshot
Summary
Generate snapshot from the specified source.
Prototype
size_t
jerry_parse_and_save_snapshot (const jerry_api_char_t *source_p,
size_t source_size,
bool is_for_global,
uint8_t *buffer_p,
size_t buffer_size);
source_p- script sourcesource_size- script source sizeis_for_global- snapshot would be executed as global (true) or eval (false)buffer_p- buffer to save snapshot tobuffer_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)
- 0 otherwise
Example
{
jerry_init (JERRY_FLAG_EMPTY);
static uint8_t global_mode_snapshot_buffer[1024];
const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_api_char_t *) code_to_snapshot_p,
strlen (code_to_snapshot_p),
true,
global_mode_snapshot_buffer,
sizeof (global_mode_snapshot_buffer));
}
See also
jerry_run
Summary
Run code of Global scope.
The code should be previously registered through jerry_parse.
Prototype
jerry_completion_code_t
jerry_run (jerry_api_value_t *error_value_p);
error_value_p- error value (output parameter)- returned value - completion code that indicates whether run performed successfully
JERRY_COMPLETION_CODE_OK- successful completionJERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION- an unhandled JavaScript exception occurredJERRY_COMPLETION_CODE_INVALID_SNAPSHOT_VERSION- snapshot version mismatchJERRY_COMPLETION_CODE_INVALID_SNAPSHOT_FORMAT- snapshot format is not valid
Example
{
const jerry_api_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
/* Initialize engine */
jerry_init (JERRY_FLAG_EMPTY);
/* Setup Global scope code */
jerry_api_object_t *error_object_p = NULL;
if (!jerry_parse (script, script_size, &error_object_p))
{
/* Error object must be freed, if parsing failed */
jerry_api_release_object (error_object_p);
}
else
{
/* Execute Global scope code
*
* Note:
* Initialization of 'error_value' is not mandatory here.
*/
jerry_api_value_t error_value = jerry_api_create_void_value ();
jerry_completion_code_t return_code = jerry_run (&error_value);
if (return_code == JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION)
{
/* Error value must be freed, if 'jerry_run' returns with an unhandled exception */
jerry_api_release_value (&error_value);
}
}
jerry_cleanup ();
}
See also
jerry_exec_snapshot
Summary
Execute snapshot from the specified buffer.
Prototype
jerry_completion_code_t
jerry_exec_snapshot (const void *snapshot_p,
size_t snapshot_size,
bool copy_bytecode,
jerry_api_value_t *retval_p);
snapshot_p- pointer to snapshotsnapshot_size- size of snapshotcopy_bytecode- flag, indicating whether the passed snapshot buffer should be copied to the engine's memory. If set the engine should not reference the buffer after the function returns (in this case, the passed buffer could be freed after the call). Otherwise (if the flag is not set) - the buffer could only be freed after the engine stops (i.e. after call to jerry_cleanup).retval_p- returned value (ECMA-262 'undefined' if code is executed as global scope code- return value - completion code
Example
{
bool is_ok;
jerry_api_value_t res;
static uint8_t global_mode_snapshot_buffer[1024];
const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
jerry_init (JERRY_FLAG_EMPTY);
size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_api_char_t *) code_to_snapshot_p,
strlen (code_to_snapshot_p),
true,
global_mode_snapshot_buffer,
sizeof (global_mode_snapshot_buffer));
jerry_cleanup ();
jerry_init (JERRY_FLAG_EMPTY);
is_ok = (jerry_exec_snapshot (global_mode_snapshot_buffer,
global_mode_snapshot_size,
false,
&res) == JERRY_COMPLETION_CODE_OK);
}
See also
jerry_get_memory_limits
Summary
Gets configured memory limits of JerryScript.
Prototype
void
jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p,
size_t *out_stack_limit_p);
out_data_bss_brk_limit_p- out parameter, that gives the maximum size of data + bss + brk sectionsout_stack_limit_p- out parameter, that gives the maximum size of the stack
Example
{
jerry_init (JERRY_FLAG_EMPTY);
size_t stack_limit;
size_t data_dss_brk_limit;
jerry_get_memory_limits (&stack_limit, &data_dss_brk_limit);
}
See also
jerry_api_gc
Summary
Performs garbage collection.
Prototype
void
jerry_api_gc (void);
Example
jerry_api_gc ();
jerry_api_eval
Summary
Perform JavaScript eval.
Prototype
jerry_completion_code_t
jerry_api_eval (const jerry_api_char_t *source_p,
size_t source_size,
bool is_direct,
bool is_strict,
jerry_api_value_t *retval_p);
source_p- source code to evaluatesource_size- length of the source codeis_direct- whether to performevalin "direct" mode (which means it is called as "eval" and not through some alias)is_strict- performevalas it is called from "strict mode" coderetval_p- value, returned byeval(output parameter)- returned value - completion code that indicates whether run performed successfully (
JERRY_COMPLETION_CODE_OK), or an unhandled JavaScript exception occurred (JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION)
Example
{
jerry_api_value_t ret_val;
jerry_completion_code_t status = jerry_api_eval (str_to_eval,
strlen (str_to_eval),
false, false,
&ret_val);
}
See also
jerry_api_create_undefined_value
Summary
Creates a jerry_api_value_t with type JERRY_API_DATA_TYPE_UNDEFINED representing an undefined value. The value have to be released by jerry_api_release_value.
Prototype
jerry_api_value_t
jerry_api_create_undefined_value (void);
- return value - a jerry_api_value_t with type JERRY_API_DATA_TYPE_UNDEFINED
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t undefined_value = jerry_api_create_undefined_value ();
... // usage of the value
jerry_api_release_value (&undefined_value);
}
See also
jerry_api_create_void_value
Summary
Creates a jerry_api_value_t with type JERRY_API_DATA_TYPE_VOID representing a void value. The value have to be released by jerry_api_release_value.
Prototype
jerry_api_value_t
jerry_api_create_void_value (void);
- return value - a jerry_api_value_t with type JERRY_API_DATA_TYPE_VOID
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t void_value = jerry_api_create_void_value ();
... // usage of the value
jerry_api_release_value (&void_value);
}
See also
jerry_api_create_null_value
Summary
Creates a jerry_api_value_t with type JERRY_API_DATA_TYPE_NULL represneting a null value. The value have to be released by jerry_api_release_value.
Prototype
jerry_api_value_t
jerry_api_create_null_value (void);
- return value - a jerry_api_value_t with type JERRY_API_DATA_TYPE_NULL
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t null_value = jerry_api_create_null_value ();
... // usage of the value
jerry_api_release_value (&null_value);
}
See also
jerry_api_create_boolean_value
Summary
Creates a JERRY_API_DATA_TYPE_BOOLEAN jerry_api_value_t from the given boolean parameter. The value have to be released by jerry_api_release_value.
Prototype
jerry_api_value_t
jerry_api_create_boolean_value (bool value);
value- bool value from which a jerry_api_value_t will be created- return value - a jerry_api_value_t created from the given boolean argument
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t boolean_value = jerry_api_create_boolean_value (true);
... // usage of the value
jerry_api_release_value (&boolean_value);
}
See also
jerry_api_create_number_value
Summary
Creates a jerry_api_value_t from the given double parameter. The v_float64 member will be set and the type will be JERRY_API_DATA_TYPE_FLOAT64. The value have to be released by jerry_api_release_value.
Prototype
jerry_api_value_t
jerry_api_create_number_value (double value);
value- double value from which a jerry_api_value_t will be created- return value - a jerry_api_value_t created from the given double argument
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t number_value = jerry_api_create_number_value (3.14);
... // usage of the value
jerry_api_release_value (&number_value);
}
See also
jerry_api_create_object_value
Summary
Creates a JERRY_API_DATA_TYPE_OBJECT type jerry_api_value_t from the given jerry_api_object_t parameter. The value have to be released by jerry_api_release_value when it becomes unnecessary.
Prototype
jerry_api_value_t
jerry_api_create_object_value (jerry_api_object_t *value);
value- jerry_api_object_t from which a value will be created- return value - a jerry_api_value_t created from the given jerry_api_object_t argument
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_object_t *object_p = jerry_api_create_object ();
jerry_api_value_t object_value = jerry_api_create_object_value (object_p);
... // usage of object_value
jerry_api_release_value (&object_value);
}
See also
jerry_api_create_string_sz
Summary
Creates a string. The caller should release the string with jerry_api_release_string when the value becomes unnecessary.
Prototype
jerry_api_string_t *
jerry_api_create_string_sz (const jerry_api_char_t *v,
jerry_api_size_t v_size)
v- string from which the result jerry_api_string_t will be createdv_size- size of the string- return value - a jerry_api_string_t* created from the given jerry_api_char_t* argument
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_char_t char_array[] = "a string";
jerry_api_string_t *string = jerry_api_create_string_sz (char_array,
lit_zt_utf8_string_size (char_array));
... // usage of string
jerry_api_release_string (string);
}
See also
jerry_api_create_string_value
Summary
Creates a JERRY_API_DATA_TYPE_STRING type jerry_api_value_t from the given jerry_api_string_t parameter. The value have to be released by jerry_api_release_value when it becomes unnecessary.
Prototype
jerry_api_value_t
jerry_api_create_string_value (jerry_api_string_t *value);
value- jerry_api_string_t from which a value will be created- return value - a jerry_api_value_t created from the given jerry_api_string_t argument
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_char_t char_array[] = "a string";
jerry_api_string_t *string = jerry_api_create_string_sz (char_array,
lit_zt_utf8_string_size (char_array));
jerry_api_value_t string_value = jerry_api_create_string_value (string);
... // usage of string_value
jerry_api_release_value (&string_value);
}
See also
jerry_api_create_error_sz
Summary
Creates an error object. Caller should release the object with jerry_api_release_object, just when the value becomes unnecessary.
Prototype
jerry_api_object_t *
jerry_api_create_error_sz (jerry_api_error_t error_type,
const jerry_api_char_t *message_p,
jerry_api_size_t message_size);
error_type- type of the errormessage_p- value of 'message' property of the constructed error objectmessage_size- size of the message in bytes- return value - pointer to created error object
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_char_t message[] = "error";
jerry_api_object_t *error_obj = jerry_api_create_error_sz (JERRY_API_ERROR_COMMON,
message,
lit_zt_utf8_string_size (char_array));
... // usage of error_obj
jerry_api_release_object (error_obj);
}
See also
jerry_api_get_boolean_value
Summary
Gets the raw bool value form a jerry_api_value_t value. If the given jerry_api_value_t structure has type other than JERRY_API_DATA_TYPE_BOOLEAN, JERRY_ASSERT fails.
Prototype
bool
jerry_api_get_boolean_value (const jerry_api_value_t *value_p);
value_p- pointer to an api value- return value - the boolean v_bool member of the given jerry_api_value_t structure
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_boolean (&value))
{
bool raw_value = jerry_api_get_boolean_value (&value);
... // usage of raw value
}
jerry_api_release_value (&value);
}
See also
jerry_api_get_number_value
Summary
Gets the number value of the given jerry_api_value_t structure as a raw double. If the given jerry_api_value_t structure has type JERRY_API_DATA_TYPE_UINT32 v_uint32 member will be returned as a double value. If the given jerry_api_value_t structure has type JERRY_API_DATA_TYPE_FLOAT32 v_float32 member will be returned as a double and if tpye is JERRY_API_DATA_TYPE_FLOAT64 the function returns the v_float64 member. As long as the type is none of the above, JERRY_ASSERT falis.
Prototype
double
jerry_api_get_number_value (const jerry_api_value_t *value_p);
value_p- pointer to an api value- return value - the number value of the given jerry_api_value_t structure as a raw double
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_number (&value))
{
double raw_value = jerry_api_get_number_value (&value);
... // usage of raw value
}
jerry_api_release_value (&value);
}
See also
jerry_api_get_object_value
Summary
Gets the v_object member of the given jerry_api_value_t structure. If the given jerry_api_value_t structure has type other than JERRY_API_DATA_TYPE_OBJECT, JERRY_ASSERT fails.
Prototype
jerry_api_object_t *
jerry_api_get_object_value (const jerry_api_value_t *value_p);
value_p- pointer to an api value- return value - the v_object member of the given jerry_api_value_t structure
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_object (&value))
{
jerry_api_object_t *raw_value = jerry_api_get_object_value (&value);
... // usage of raw value
}
jerry_api_release_value (&value);
}
See also
jerry_api_get_string_value
Summary
Gets the v_string member of the given jerry_api_value_t structure. If the given jerry_api_value_t structure has type other than JERRY_API_DATA_TYPE_STRING, JERRY_ASSERT fails.
Prototype
jerry_api_string_t *
jerry_api_get_string_value (const jerry_api_value_t *value_p);
value_p- pointer to an api value- return value - the v_string member of the given jerry_api_value_t structure
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_string (&value))
{
jerry_api_string_t *raw_value = jerry_api_get_string_value (&value);
... // usage of raw value
}
jerry_api_release_value (&value);
}
See also
jerry_api_get_string_size
Summary
Gets the length of a jerry_api_string_t.
Prototype
jerry_api_size_t
jerry_api_get_string_size (const jerry_api_string_t *str_p);
str_p- input string- return value - number of bytes in the buffer needed to represent the string
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_char_t char_array[] = "a string";
jerry_api_string_t *string = jerry_api_create_string (char_array);
jerry_api_size_t string_size = jerry_api_get_string_size ();
... // usage of string_size
jerry_api_release_string (string);
}
See also
jerry_api_get_string_length
Summary
Gets the length of a jerry_api_string_t.
Prototype
jerry_api_length_t
jerry_api_get_string_length (const jerry_api_string_t *str_p);
str_p- input string- return value - number of characters in the string
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_char_t char_array[] = "a string";
jerry_api_string_t *string = jerry_api_create_string (char_array);
jerry_api_length_t string_length = jerry_api_get_string_length (string);
... // usage of string_length
jerry_api_release_string (string);
}
See also
jerry_api_value_is_undefined
Summary
Returns whether the given jerry_api_value_t is an undefined value.
Prototype
bool
jerry_api_value_is_undefined (const jerry_api_value_t *value_p);
value_p- pointer to api an value- return value
- true, if the given jerry_api_value_t is an undefined value, more specifically, if it's type field equals JERRY_API_DATA_TYPE_UNDEFINED
- false, otherwise
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_undefined (&value))
{
...
}
jerry_api_release_value (&value);
}
See also
jerry_api_value_is_void
Summary
Returns whether the given jerry_api_value_t is a void value.
Prototype
bool
jerry_api_value_is_void (const jerry_api_value_t *value_p);
value_p- pointer to an api value- return value
- true, if the given jerry_api_value_t is a void value, more specifically, if it's type field equals JERRY_API_DATA_TYPE_VOID
- false, otherwise
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_void (&value))
{
...
}
jerry_api_release_value (&value);
}
See also
jerry_api_value_is_boolean
Summary
Returns whether the given jerry_api_value_t is a boolean value.
Prototype
bool
jerry_api_value_is_boolean (const jerry_api_value_t *value_p)
value_p- pointer to an api value- return value
- true, if the given jerry_api_value_t is a boolean value, more specifically, if it's type field equals JERRY_API_DATA_TYPE_BOOLEAN
- false, otherwise
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_boolean (&value))
{
...
}
jerry_api_release_value (&value);
}
See also
jerry_api_value_is_number
Summary
Returns whether the given jerry_api_value_t is a number value.
Prototype
bool
jerry_api_value_is_number (const jerry_api_value_t *value_p);
value_p- pointer to an api value- return value
- true, if the given jerry_api_value_t is a number value, more specifically, if it's type is JERRY_API_DATA_TYPE_FLOAT32, JERRY_API_DATA_TYPE_FLOAT64 or JERRY_API_DATA_TYPE_UINT32
- false, otherwise
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_number (&value))
{
...
}
jerry_api_release_value (&value);
}
See also
jerry_api_value_is_function
Summary
Returns whether the given jerry_api_value_t is a function object.
Prototype
bool
jerry_api_value_is_function (const jerry_api_value_t *value_p);
value_p- pointer to an api value- return value
- true, if the given jerry_api_value_t is a function object, more specifically, if it has JERRY_API_DATA_TYPE_OBJECT type and jerry_api_is_function () functiron return true for its v_object member
- false, otherwise
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_function (&value))
{
...
}
jerry_api_release_value (&value);
}
See also
jerry_api_value_is_null
Summary
Returns whether the given jerry_api_value_t is a null value.
Prototype
bool
jerry_api_value_is_null (const jerry_api_value_t *value_p);
value_p- pointer to an api value- return value
- true, if the given jerry_api_value_t is a null value, more specifically, if it's type is JERRY_API_DATA_TYPE_NULL
- false, otherwise
Example
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_null (&value))
{
...
}
jerry_api_release_value (&value);
See also
jerry_api_value_is_object
Summary
Returns whether the given jerry_api_value_t is an object.
Prototype
bool
jerry_api_value_is_object (const jerry_api_value_t *value_p);
value_p- pointer to an api value- return value
- true, if the given jerry_api_value_t is a null value, more specifically, if it's type is JERRY_API_DATA_TYPE_OBJECT
- false, otherwise
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_object (&value))
{
...
}
jerry_api_release_value (&value);
}
See also
jerry_api_value_is_string
Summary
Returns whether the given jerry_api_value_t is a string.
Prototype
bool
jerry_api_value_is_string (const jerry_api_value_t *value_p);
value_p- pointer to an api value- return value
- true, if the given jerry_api_value_t is a string, more specifically, if it's type is JERRY_API_DATA_TYPE_STRING
- false, otherwise
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t value;
... // create or acquire value
if (jerry_api_value_is_string (&value))
{
...
}
jerry_api_release_value (&value);
}
See also
jerry_api_acquire_value
Summary
Acquires the specified Jerry API value.
For values of string and object types this acquires the underlying data, for all other types it is a no-op. The acquired pointer have to be released by jerry_api_release_value.
Prototype
jerry_api_value_t *
jerry_api_acquire_value (jerry_api_value_t *value_p);
value_p- pointer to an API value- return value - pointer that may be used outside of the engine
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_object_t *object_p = jerry_api_create_object ();
jerry_api_value_t object_value = jerry_api_create_object_value (object_p);
jerry_api_value_t *acquired_object = jerry_api_acquire_value (&object_value);
jerry_api_release_value (acquired_object);
}
See also
jerry_api_release_value
Summary
Release specified pointer to the value.
Prototype
void
jerry_api_release_value (jerry_api_value_t *value_p);
value_p- pointer to the value.
Example
{
jerry_api_value_t val1;
jerry_api_value_t val2;
val1.type = JERRY_API_DATA_TYPE_OBJECT;
val1.u.v_object = jerry_api_create_object ();
val2.type = JERRY_API_DATA_TYPE_STRING;
val2.u.v_string = jerry_api_create_string ("abc");
... // usage of val1
jerry_api_release_value (&val1);
... // usage of val2
jerry_api_release_value (&val2);
}
jerry_api_create_string
Summary
Create new JavaScript string.
Upon the JavaScript string becomes unused, all pointers to it should be released using jerry_api_release_string.
Prototype
jerry_api_string_t *
jerry_api_create_string (const jerry_api_char_t *v);
v- value of string to create;- returned value is pointer to created string.
Example
{
jerry_api_string_t *string_p = jerry_api_create_string ("abc");
...
jerry_api_release_string (string_p);
}
See also
jerry_api_string_to_char_buffer
Summary
Copy string characters to specified buffer, append zero character at end of the buffer.
Prototype
jerry_api_size_t
jerry_api_string_to_char_buffer (const jerry_api_string_t *string_p,
jerry_api_char_t *buffer_p,
jerry_api_size_t buffer_size);
string_p- pointer to a string;buffer_p- pointer to output buffer (can be NULL, isbuffer_sizeis 0);buffer_size- size of the buffer;- returned value:
- number of bytes, actually copied to the buffer - if characters were copied successfully;
- otherwise (in case size of buffer is insufficient) - negative number, which is calculated as negation of buffer size, that is required to hold characters.
Example
{
jerry_api_object_t *obj_p = jerry_api_get_global ();
jerry_api_value_t val;
bool is_ok = jerry_api_get_object_field_value (obj_p,
"field_with_string_value",
&val);
if (is_ok)
{
bool is_string = (val.type == JERRY_API_DATA_TYPE_STRING);
if (is_string)
{
// neg_req_sz would be negative, as zero-size buffer is insufficient for any string
jerry_api_size_t req_sz = jerry_api_get_string_size (val.string_p);
jerry_api_char_t *str_buf_p = (jerry_api_char_t *) malloc (req_sz);
// sz would be -neg_req_sz
jerry_api_size_t sz = jerry_api_string_to_char_buffer (val.string_p,
str_buf_p,
req_sz);
printf ("%s", str_buf_p);
free (str_buf_p);
}
jerry_api_release_value (&val);
}
jerry_api_release_object (obj_p);
}
See also
jerry_api_acquire_string
Summary
Acquire new pointer to the string for usage outside of the engine.
The acquired pointer should be released with jerry_api_release_string.
Prototype
jerry_api_string_t *
jerry_api_acquire_string (jerry_api_string_t *string_p);
string_p- pointer to the string;- returned value - new pointer to the string.
Example
{
jerry_api_string_t *str_ptr1_p = jerry_api_create_string ("abc");
jerry_api_string_t *str_ptr2_p = jerry_api_acquire_string (str_ptr1_p);
... // usage of both pointers
jerry_api_release_string (str_ptr1_p);
... // usage of str_ptr2_p pointer
jerry_api_release_string (str_ptr2_p);
}
See also
jerry_api_release_string
Summary
Release specified pointer to the string.
Prototype
void
jerry_api_release_string (jerry_api_string_t *string_p);
string_p- pointer to the string.
Example
{
jerry_api_string_t *str_ptr1_p = jerry_api_create_string ("abc");
jerry_api_string_t *str_ptr2_p = jerry_api_acquire_string (str_ptr1_p);
... // usage of both pointers
jerry_api_release_string (str_ptr1_p);
... // usage of str_ptr2_p pointer
jerry_api_release_string (str_ptr2_p);
}
See also
jerry_api_create_object
Summary
Create new JavaScript object, like with new Object().
Upon the JavaScript object becomes unused, all pointers to it should be released using jerry_api_release_object.
Prototype
jerry_api_object_t *
jerry_api_create_object ();
- returned value is pointer to the created object.
Example
{
jerry_api_object_t *object_p = jerry_api_create_object ();
...
jerry_api_release_object (object_p);
}
See also
- jerry_api_acquire_object
- jerry_api_release_object
- jerry_api_add_object_field
- jerry_api_delete_object_field
- jerry_api_get_object_field_value
- jerry_api_set_object_field_value
- jerry_api_get_object_native_handle
- jerry_api_set_object_native_handle
jerry_api_acquire_object
Summary
Acquire new pointer to the object for usage outside of the engine.
The acquired pointer should be released with jerry_api_release_object.
Prototype
jerry_api_object_t *
jerry_api_acquire_object (jerry_api_object_t *object_p);
object_p- pointer to the object;- returned value - new pointer to the object.
Example
{
jerry_api_object_t *obj_ptr1_p = jerry_api_create_object ();
jerry_api_object_t *obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p);
... // usage of both pointers
jerry_api_release_object (obj_ptr1_p);
... // usage of obj_ptr2_p pointer
jerry_api_release_object (obj_ptr2_p);
}
See also
jerry_api_release_object
Summary
Release specified pointer to the object.
Prototype
void
jerry_api_release_object (jerry_api_object_t *object_p);
object_p- pointer to the object.
Example
{
jerry_api_object_t *obj_ptr1_p = jerry_api_create_object ();
jerry_api_object_t *obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p);
... // usage of both pointers
jerry_api_release_object (obj_ptr1_p);
... // usage of obj_ptr2_p pointer
jerry_api_release_object (obj_ptr2_p);
}
See also
jerry_api_get_global
Summary
Get the Global object.
Prototype
jerry_api_object_t *
jerry_api_get_global (void);
- returned value - pointer to the Global object.
Received pointer should be released with jerry_api_release_object, just when the value becomes unnecessary.
Example
{
jerry_api_object_t *glob_obj_p = jerry_api_get_global ();
jerry_api_value_t val;
bool is_ok = jerry_api_get_object_field_value (glob_obj_p, "some_field_name", &val);
if (is_ok)
{
... // usage of 'val'
jerry_api_release_value (&val);
}
jerry_api_release_object (glob_obj_p);
}
See also
- jerry_api_release_object
- jerry_api_add_object_field
- jerry_api_delete_object_field
- jerry_api_get_object_field_value
- jerry_api_set_object_field_value
jerry_api_add_object_field
Summary
Create field (named data property) in an object
Prototype
bool
jerry_api_add_object_field (jerry_api_object_t *object_p,
const jerry_api_char_t *field_name_p,
const jerry_api_value_t *field_value_p,
bool is_writable);
object_p- object to add field at;field_name_p- name of the field;field_value_p- value of the field;is_writable- flag indicating whether the created field should be writable.- returned value
- true, if field was created successfully, i.e. upon the call:
- there is no field with same name in the object;
- the object is extensible.
Example
{
jerry_api_object_t *obj_p = jerry_api_create_object ();
jerry_api_value_t val;
... // initialize val
// Make new constant field
jerry_api_add_object_field (obj_p, "some_field_name", &val, false);
}
See also
jerry_api_delete_object_field
Summary
Delete field (property) in the specified object
Prototype
bool
jerry_api_delete_object_field (jerry_api_object_t *object_p,
const jerry_api_char_t *field_name_p);
object_p- object to delete field at;field_name_p- name of the field.- returned value - true, if field was deleted successfully, i.e. upon the call:
- there is field with specified name in the object.
Example
{
jerry_api_object_t *obj_p;
... // receive or construct obj_p
jerry_api_delete_object_field (obj_p, "some_field_name");
}
See also
jerry_api_get_object_field_value
Summary
Get value of field (property) in the specified object, i.e. perform Get operation.
Prototype
bool
jerry_api_get_object_field_value (jerry_api_object_t *object_p,
const jerry_api_char_t *field_name_p,
jerry_api_value_t *field_value_p);
object_p- object;field_name_p- name of the field;field_value_p- retrieved field value (output parameter).- returned value - true, if field value was retrieved successfully, i.e. upon the call:
- there is field with specified name in the object.
If value was retrieved successfully, it should be freed with jerry_api_release_object just when it becomes unnecessary.
Example
{
jerry_api_object_t *obj_p;
... // receive or construct obj_p
jerry_api_value_t val;
bool is_ok = jerry_api_get_object_field_value (obj_p, "some_field_name", &val);
if (is_ok)
{
... // usage of 'val'
jerry_api_release_value (&val);
}
}
See also
jerry_api_get_object_field_value_sz
Summary
Gets the value of a field in the specified object. If the value was retrieved successfully, it should be freed with jerry_api_release_value when it becomes unnecessary.
Prototype
bool
jerry_api_get_object_field_value_sz (jerry_api_object_t *object_p,
const jerry_api_char_t *field_name_p,
jerry_api_size_t field_name_size,
jerry_api_value_t *field_value_p);
object_p- objectfield_name_p- name of the fieldfield_name_size- size of field name in bytesfield_value_p- Output parameter, that gives the value of the field if retrieved- return value
- true, if field value was retrieved successfully
- false, otherwise
Example
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_char_t field_name[] = "field";
jerry_api_value_t field_value = jerry_api_create_number_value (3.14);
jerry_api_object_t* object_p = jerry_api_create_object ();
jerry_api_add_object_field (object_p,
field_name,
lit_zt_utf8_string_size (field_name),
&field_value, true);
jerry_api_value_t retrieved_field_value = jerry_api_create_undefined_value ();
bool is_get_ok = jerry_api_get_object_field_value_sz (object_p,
field_name,
lit_zt_utf8_string_size (field_name),
&retrieved_field_value);
if (is_get_ok)
{
... // usage of the retrieved field
}
jerry_api_release_object (object_p);
}
See also
- jerry_init
- jerry_api_create_object
- jerry_api_release_object
- jerry_api_add_object_field
- jerry_api_get_object_field_value
- jerry_api_set_object_field_value
- jerry_api_set_object_field_value_sz
jerry_api_set_object_field_value
Summary
Set value of a field (property) in the specified object, i.e. perform Put operation.
Prototype
bool
jerry_api_set_object_field_value (jerry_api_object_t *object_p,
const jerry_api_char_t *field_name_p,
jerry_api_value_t *field_value_p);
object_p- object;field_name_p- name of the field;field_value_p- field value to set.- returned value - true, if field value was set successfully, i.e. upon the call:
- field value is writable.
Example
{
jerry_api_object_t *obj_p;
jerry_api_value_t val;
... // receive or construct obj_p and val
bool is_ok = jerry_api_set_object_field_value (obj_p, "some_field_name", &val);
}
See also
- jerry_api_create_object
- jerry_api_get_object_field_value
- jerry_api_get_object_field_value_sz
- jerry_api_set_object_field_value_sz
jerry_api_set_object_field_value_sz
Summary
Set value of field in the specified object.
Prototype
bool
jerry_api_set_object_field_value_sz (jerry_api_object_t *object_p,
const jerry_api_char_t *field_name_p,
jerry_api_size_t field_name_size,
const jerry_api_value_t *field_value_p);
object_p- objectfield_name_p- name of the fieldfield_name_size- size of field name in bytesfield_value_p- field value to set- return value
- true, if field value was set successfully
- false, otherwise
Example
{
jerry_api_object_t *obj_p;
jerry_api_char_t field_name[] = "some_field_name";
jerry_api_value_t val;
... // receive or construct obj_p and val
bool is_ok = jerry_api_set_object_field_value_sz (obj_p,
field_name,
lit_zt_utf8_string_size (field_name),
&val);
}
See also
- jerry_api_create_object
- jerry_api_get_object_field_value
- jerry_api_get_object_field_value_sz
- jerry_api_set_object_field_value
jerry_api_get_object_native_handle
Summary
Get native handle, previously associated with specified object.
Prototype
bool
jerry_api_get_object_native_handle (jerry_api_object_t *object_p,
uintptr_t *out_handle_p);
object_p- object to get handle from;out_handle_p- handle value (output parameter);- returned value - true, if there is handle associated with the object.
Example
{
jerry_api_object_t *obj_p;
uintptr_t handle_set;
... // receive or construct obj_p and handle_set value
jerry_api_set_object_native_handle (obj_p, handle_set, NULL);
...
uintptr_t handle_get;
bool is_there_associated_handle = jerry_api_get_object_native_handle (obj_p,
&handle_get);
}
See also
jerry_api_set_object_native_handle
Summary
Set native handle and, optionally, "free" callback for the specified object.
If native handle or "free" callback were already set for the object, corresponding value is updated.
Prototype
void
jerry_api_set_object_native_handle (jerry_api_object_t *object_p,
uintptr_t handle,
jerry_object_free_callback_t freecb_p);
object_p- object to set handle in;handle- handle value;freecb_p- pointer to "free" callback or NULL (if not NULL the callback would be called upon GC of the object).
Example
{
jerry_api_object_t *obj_p;
uintptr_t handle_set;
... // receive or construct obj_p and handle_set value
jerry_api_set_object_native_handle (obj_p, handle_set, NULL);
...
uintptr_t handle_get;
bool is_there_associated_handle = jerry_api_get_object_native_handle (obj_p,
&handle_get);
}
See also
jerry_api_is_function
Summary
Check whether the specified object is a function object.
Prototype
bool
jerry_api_is_function (const jerry_api_object_t *object_p);
object_p- object to check;- returned value - just boolean, indicating whether the specified object can be called as function.
Example
{
jerry_api_value_t val;
... // receiving val
if (val.type == JERRY_API_DATA_TYPE_OBJECT)
{
if (jerry_api_is_function (val.u.v_object))
{
// the object is function object
}
}
}
See also
jerry_api_is_constructor
Summary
Check whether the specified object is a constructor function object.
Prototype
bool
jerry_api_is_constructor (const jerry_api_object_t *object_p);
object_p- object to check;- returned value - just boolean, indicating whether the specified object can be called as constructor.
Example
{
jerry_api_value_t val;
... // receiving val
if (val.type == JERRY_API_DATA_TYPE_OBJECT)
{
if (jerry_api_is_constructor (val.u.v_object))
{
// the object is constructor function object
}
}
}
See also
jerry_api_call_function
Summary
Call function object.
Prototype
bool
jerry_api_call_function (jerry_api_object_t *function_object_p,
jerry_api_object_t *this_arg_p,
jerry_api_value_t *retval_p,
const jerry_api_value_t args_p[],
uint16_t args_count);
function_object_p- the function object to call;this_arg_p- object to use as 'this' during the invocation, or NULL - to set the Global object as 'this';retval_p- function's return value (output parameter);args_p,args_count- array of arguments and number of them;- returned value - true, if call was performed successfully, i.e.:
- specified object is a function object (see also jerry_api_is_function);
- no unhandled exceptions were thrown in connection with the call.
If call was performed successfully, returned value should be freed with jerry_api_release_object just when it becomes unnecessary.
Example
{
jerry_api_value_t val;
... // receiving val
if (val.type == JERRY_API_DATA_TYPE_OBJECT)
{
if (jerry_api_is_function (val.u.v_object))
{
jerry_api_value_t ret_val;
bool is_ok = jerry_api_call_function (val.u.v_object,
NULL,
&ret_val,
NULL, 0);
if (is_ok)
{
... // handle return value
jerry_api_release_value (&ret_val);
}
}
}
}
See also
jerry_api_construct_object
Summary
Construct object invoking specified function object as constructor.
Prototype
bool
jerry_api_construct_object (jerry_api_object_t *function_object_p,
jerry_api_value_t *retval_p,
const jerry_api_value_t args_p[],
uint16_t args_count);
function_object_p- the function object to invoke;retval_p- return value of function invoked as constructor, i.e. like with 'new' operator (output parameter);args_p,args_count- array of arguments and number of them;- returned value - true, if call was performed successfully, i.e.:
- specified object is a constructor function object;
- no unhandled exceptions were thrown in connection with the call.
If call was performed successfully, returned value should be freed with jerry_api_release_object just when it becomes unnecessary.
Example
{
jerry_api_value_t val;
... // receiving val
if (val.type == JERRY_API_DATA_TYPE_OBJECT)
{
if (jerry_api_is_constructor (val.u.v_object))
{
jerry_api_value_t ret_val;
bool is_ok = jerry_api_construct_object (val.u.v_object,
&ret_val,
NULL, 0);
if (is_ok)
{
... // handle return value
jerry_api_release_value (&ret_val);
}
}
}
}
See also
jerry_external_handler_t
Summary
The data type represents pointer to call handler of a native function object.
Structure
typedef bool (* jerry_external_handler_t) (const jerry_api_object_t *function_obj_p,
const jerry_api_value_t *this_p,
jerry_api_value_t *ret_val_p,
const jerry_api_value_t args_p[],
const uint16_t args_count);
See also
jerry_api_create_external_function
Summary
Create an external function object.
Prototype
jerry_api_object_t *
jerry_api_create_external_function (jerry_external_handler_t handler_p);
handler_p- pointer to native handler of the function object;- returned value - pointer to constructed external function object.
Received pointer should be released with jerry_api_release_object, just when the value becomes unnecessary.
Example
static bool
handler (const jerry_api_object_t *function_obj_p,
const jerry_api_value_t *this_p,
jerry_api_value_t *ret_val_p,
const jerry_api_value_t args_p[],
const uint16_t args_cnt)
{
printf ("native handler called!\n");
ret_val_p->type = JERRY_API_DATA_TYPE_BOOLEAN;
ret_val_p->u.v_bool = true;
}
{
jerry_api_object_t *obj_p = jerry_api_create_external_function (handler);
jerry_api_object_t *glob_obj_p = jerry_api_get_global ();
jerry_api_value_t val;
val.type = JERRY_API_DATA_TYPE_OBJECT;
val.u.v_object = obj_p;
// after this, script can invoke the native handler through "handler_field (1, 2, 3);"
jerry_api_set_object_field_value (glob_obj_p, "handler_field", &val);
jerry_api_release_object (glob_obj_p);
jerry_api_release_object (obj_p);
}
See also
jerry_api_create_array_object
Summary
Create new JavaScript array object.
Upon the JavaScript array object becomes unused, all pointers to it should be released using jerry_api_release_object.
Prototype
jerry_api_object_t *
jerry_api_create_array_object (jerry_api_size_t array_size);
array_size- size of array;- returned value is pointer to the created array object.
Example
{
jerry_api_object_t *array_object_p = jerry_api_create_array_object (10);
...
jerry_api_release_object (array_object_p);
}
See also
- jerry_api_acquire_object
- jerry_api_release_object
- jerry_api_set_array_index_value
- jerry_api_get_array_index_value
- jerry_api_add_object_field
- jerry_api_delete_object_field
- jerry_api_get_object_field_value
- jerry_api_set_object_field_value
- jerry_api_get_object_native_handle
- jerry_api_set_object_native_handle
jerry_api_set_array_index_value
Summary
Set value of an indexed element in the specified array object.
Prototype
bool
jerry_api_set_array_index_value (jerry_api_object_t *array_object_p,
jerry_api_length_t index,
jerry_api_value_t *value_p);
array_object_p- pointer to the array object;index- index of the array element;value_p- indexed value to set;- returned value - true, if value was set successfully.
Example
{
jerry_api_object_t *array_object_p = jerry_api_create_array_object (10);
jerry_api_value_t val;
... // receive or construct val
jerry_api_set_array_index_value (array_object_p, 5, &val);
jerry_api_release_object (array_object_p);
}
See also
jerry_api_get_array_index_value
Summary
Get value of an indexed element in the specified array object.
Prototype
bool
jerry_api_get_array_index_value (jerry_api_object_t *array_object_p,
jerry_api_length_t index,
jerry_api_value_t *value_p);
array_object_p- pointer to the array object;index- index of the array element;value_p- retrieved indexed value (output parameter);- returned value - true, if value was retrieved successfully.
Example
{
jerry_api_object_t *array_object_p;
... // receive or construct array_object_p
jerry_api_value_t val;
bool is_ok = jerry_api_get_array_index_value (array_object_p, 5, &val);
if (is_ok)
{
... // usage of 'val'
}
}
See also
jerry_api_create_error
Summary
Create new JavaScript error object. it should be throwed inside of handle attached to external function object.
Prototype
jerry_api_object_t *
jerry_api_create_error (jerry_api_error_t error_type,
const jerry_api_char_t *message_p);
error_type- error type of object;message_p- human-readable description of the error;- returned value is pointer to the created error object.
Example
static bool
handler (const jerry_api_object_t *function_obj_p,
const jerry_api_value_t *this_p,
jerry_api_value_t *ret_val_p,
const jerry_api_value_t args_p[],
const uint16_t args_cnt)
{
jerry_api_object_t *error_p = jerry_api_create_error (JERRY_API_ERROR_TYPE,
(jerry_api_char_t * ) "error");
jerry_api_acquire_object (error_p);
ret_val_p->type = JERRY_API_DATA_TYPE_OBJECT;
ret_val_p->u.v_object = error_p;
jerry_api_release_object (error_p);
return false;
}
{
jerry_api_object_t *throw_obj_p = jerry_api_create_external_function (handler);
jerry_api_object_t *glob_obj_p = jerry_api_get_global ();
jerry_api_value_t val;
val.type = JERRY_API_DATA_TYPE_OBJECT;
val.u.v_object = throw_obj_p;
// after this, script can invoke the native handler through "error_func ();"
// and "error_func" throw a error on called
jerry_api_set_object_field_value (glob_obj_p, "error_func", &val);
jerry_api_release_object (glob_obj_p);
jerry_api_release_object (throw_obj_p);
}
See also
- jerry_external_handler_t
- jerry_api_is_function
- jerry_api_call_function
- jerry_api_release_object
- jerry_api_create_external_function
jerry_register_external_magic_strings
Summary
Registers an external magic string array.
Prototype
void
jerry_register_external_magic_strings (const jerry_api_char_ptr_t *ex_str_items,
uint32_t count,
const jerry_api_length_t * str_lengths);
ex_str_items- character arrays, representing external magic strings' contentscount number- of the stringsstr_lengths- lengths of the strings
Example
{
jerry_init (JERRY_FLAG_EMPTY);
const jerry_api_char_ptr_t magic_string_items[] = {
(const jerry_api_char_ptr_t)"magicstring1",
(const jerry_api_char_ptr_t)"magicstring2",
(const jerry_api_char_ptr_t)"magicstring3"
};
uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_api_char_ptr_t));
const jerry_api_length_t magic_string_lengths[] = {
(jerry_api_length_t)strlen (magic_string_items[0]),
(jerry_api_length_t)strlen (magic_string_items[1]),
(jerry_api_length_t)strlen (magic_string_items[2])
};
jerry_register_external_magic_strings (magic_string_items,
num_magic_string_items,
magic_string_lengths);
}
See also
jerry_api_value_to_string
Summary
Creates the textual representation of an API value using the ToString ecma builtin operation.
Prototype
jerry_api_string_t *
jerry_api_value_to_string (const jerry_api_value_t *in_value_p);
in_value_p- input API value- return value - textual representation of the given API value
Example
{
jerry_api_value_t value;
... // receive or construct value
jerry_api_string_t *string_value = jerry_api_value_to_string (&value);
}
jerry_object_field_foreach_t
Summary
Function type applied for each fields of an object by API function jerry_api_foreach_object_field.
Definition
typedef bool (*jerry_object_field_foreach_t) (const jerry_api_string_t *field_name_p,
const jerry_api_value_t *field_value_p,
void *user_data_p);
field_name_p- name of the fieldfield_value_p- value of the fielduser_data_p- user data- return value
- true, if the operation executed successfully
- false, otherwise
See also
jerry_api_foreach_object_field
Summary
Applies the given function to every fields in the given objects.
Prototype
bool
jerry_api_foreach_object_field (jerry_api_object_t *object_p,
jerry_object_field_foreach_t foreach_p,
void *user_data_p);
object_p- objectforeach_p- foreach function, that will be apllied for each fieldsuser_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
- true, if object fields traversal was performed successfully, i.e.:
Example
bool foreach_function (const jerry_api_string_t *field_name_p,
const jerry_api_value_t *field_value_p,
void *user_data_p)
{
... // implementation of the foreach function
}
{
jerry_init (JERRY_FLAG_EMPTY);
jerry_api_object_t* object_p;
... // receive or construct object_p
double data = 3.14; // example data
jerry_api_foreach_object_field (object_p, foreach_function, &data);
}
See also