From c0978d1a42db8a911794611cf554f989c3e62963 Mon Sep 17 00:00:00 2001 From: Istvan Kadar Date: Wed, 13 Jul 2016 13:33:46 +0200 Subject: [PATCH] Updated content on the JerryScript GitHub Pages site MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - API refenrece is updated. - API examples are updated. - How To page renamed to Getting Started. - Fixes in Internlas. JerryScript-DCO-1.0-Signed-off-by: István Kádár ikadar@inf.u-szeged.hu --- 01.GETTING-STARTED.md | 76 + 02.API-REFERENCE.md | 2931 ++++++++++++++++++++++++++++ 02.how-to.md | 100 - 03.API-EXAMPLE.md | 517 +++++ 03.api.md | 2725 -------------------------- 04.internals.md => 04.INTERNALS.md | 8 +- 05.dev-guide.md | 307 --- 7 files changed, 3529 insertions(+), 3135 deletions(-) create mode 100644 01.GETTING-STARTED.md create mode 100644 02.API-REFERENCE.md delete mode 100644 02.how-to.md create mode 100644 03.API-EXAMPLE.md delete mode 100644 03.api.md rename 04.internals.md => 04.INTERNALS.md (95%) delete mode 100644 05.dev-guide.md diff --git a/01.GETTING-STARTED.md b/01.GETTING-STARTED.md new file mode 100644 index 000000000..36f6e2db3 --- /dev/null +++ b/01.GETTING-STARTED.md @@ -0,0 +1,76 @@ +--- +layout: page +title: Getting Started +permalink: /getting-started/ +--- + +* toc +{:toc} + +### Setting Up Prerequisites + +Currently, only Ubuntu 14.04+ is officially supported as primary development environment. + +There are several dependencies, that should be installed manually. The following list is required for building: + +- `gcc` higher than `4.8.2` + - native + - arm-none-eabi +- `cmake` higher than `2.8.12.2` +- `make` higher than `3.81` +- `bash` higher than `4.3.11` +- `cppcheck` higher than 1.61 +- `vera++` higher than 1.2.1 + +```bash +sudo apt-get install gcc g++ gcc-arm-none-eabi cmake cppcheck vera++ +``` + +To make our scripts run correctly, several shell utilities should be available on the system: + +- `find` +- `bc` +- `awk` +- `sed` +- `sha256sum` +- `wget` + +Upon first build, `make` would try to setup prerequisites, required for further development and pre-commit testing: + +- STM32F3 and STM32F4 libraries + +```bash +make prerequisites -j +``` + +It may take time, so go grab some coffee: + +```bash +Setting up prerequisites... (log file: ./build/prerequisites/prerequisites.log) +``` + +### Building Debug Version + +To build debug version for Linux: + +```bash +make debug.linux -j +``` + +To build debug version for Linux without LTO (Link Time Optimization): + +```bash +LTO=OFF make debug.linux -j +``` + +### Checking Patch + +```bash +make precommit -j +``` + +If some style guidelines, build or test runs fail during precommit, then this is indicated with a message like this: + +``` +Build failed. See ./build/bin/unittests/make.log for details. +``` diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md new file mode 100644 index 000000000..ef09c0ffd --- /dev/null +++ b/02.API-REFERENCE.md @@ -0,0 +1,2931 @@ +--- +layout: page +title: API Reference +permalink: /api-reference/ +--- + +* toc +{:toc} + +# JerryScript types + +## jerry_init_flag_t + +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_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 + - JERRY_ERROR_REFERENCE - reference error + - JERRY_ERROR_SYNTAX - syntax error + - JERRY_ERROR_TYPE - type error + - JERRY_ERROR_URI - URI error + +## jerry_char_t + +**Summary** + +Jerry's char value + +**Prototype** + +```c +typedef uint8_t jerry_char_t; +``` + +## jerry_size_t + +**Summary** + +Jerry's size + +**Prototype** + +```c +typedef uint32_t jerry_size_t; +``` + +## jerry_length_t + +**Summary** + +Jerry's length + +**Prototype** + +```c +typedef uint32_t jerry_length_t; +``` + +## jerry_value_t + +**Summary** + +JerryScript value can be a boolean, number, null, object, string or undefined. The value has an error flag, +that indicates whether is an error or not. Every type has an error flag not only objects. The error flag should +be cleared before the value is passed as an argument, otherwise it can lead to a type error. The error objects +created by API functions has the error flag set. + +**Prototype** + +```c +typedef uint32_t jerry_value_t; +``` + +## jerry_property_descriptor_t + +**Summary** + +Description of ECMA property descriptor + +**Prototype** + +```c +typedef struct +{ + /** Is [[Value]] defined? */ + bool is_value_defined; + + /** Is [[Get]] defined? */ + bool is_get_defined; + + /** Is [[Set]] defined? */ + bool is_set_defined; + + /** Is [[Writable]] defined? */ + bool is_writable_defined; + + /** [[Writable]] */ + bool is_writable; + + /** Is [[Enumerable]] defined? */ + bool is_enumerable_defined; + + /** [[Enumerable]] */ + bool is_enumerable; + + /** Is [[Configurable]] defined? */ + bool is_configurable_defined; + + /** [[Configurable]] */ + bool is_configurable; + + /** [[Value]] */ + jerry_value_t value; + + /** [[Get]] */ + jerry_value_t getter; + + /** [[Set]] */ + jerry_value_t setter; +} jerry_property_descriptor_t; +``` + +## jerry_external_handler_t + +**Summary** + +Type of an external function handler + +**Prototype** + +```c +typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj_p, + const jerry_value_t this_val, + const jerry_value_t args_p[], + const jerry_length_t args_count); +``` + +## jerry_object_free_callback_t + +**Summary** + +Native free callback of an object + +**Prototype** + +```c +typedef void (*jerry_object_free_callback_t) (const uintptr_t native_p); +``` + +## jerry_object_property_foreach_t + +**Summary** + +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, + const jerry_value_t property_value, + void *user_data_p); +``` + +# General engine functions + +## jerry_init + +**Summary** + +Initializes the JerryScript engine, making possible to run JavaScript code and perform operations on +JavaScript values. + +**Prototype** + +```c +void +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_MEM_STATS` - dump memory statistics. +- `JERRY_INIT_MEM_STATS_SEPARATE` - dump memory statistics and reset peak values after parse. + +**Example** + +```c +{ + jerry_init (JERRY_INIT_SHOW_OPCODES | JERRY_INIT_ENABLE_LOG); + + // ... + + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_cleanup](#jerrycleanup) + + +## jerry_cleanup + +**Summary** + +Finish JavaScript engine execution, freeing memory and JavaScript values. + +*Note*: JavaScript values, received from engine, will be inaccessible after the cleanup. + +**Prototype** + +```c +void +jerry_cleanup (void); +``` + +**See also** + +- [jerry_init](#jerryinit) + + +## jerry_register_magic_strings + +**Summary** + +Registers an external magic string array. + +**Prototype** + +```c +void +jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items, + uint32_t count, + const jerry_length_t *str_lengths); +``` + +- `ex_str_items` - character arrays, representing external magic strings' contents +- `count` - number of the strings +- `str_lengths` - lengths of the strings + +**Example** + +```c +{ + jerry_init (JERRY_INIT_EMPTY); + + // must be static, because 'jerry_register_magic_strings' does not copy + static const jerry_char_ptr_t magic_string_items[] = { + (const jerry_char_ptr_t) "magicstring1", + (const jerry_char_ptr_t) "magicstring2", + (const jerry_char_ptr_t) "magicstring3" + }; + uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t)); + + // must be static, because 'jerry_register_magic_strings' does not copy + static const jerry_length_t magic_string_lengths[] = { + (jerry_length_t)strlen (magic_string_items[0]), + (jerry_length_t)strlen (magic_string_items[1]), + (jerry_length_t)strlen (magic_string_items[2]) + }; + jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths); +} +``` + +**See also** + +- [jerry_init](#jerryinit) +- [jerry_cleanup](#jerrycleanup) + + +## jerry_get_memory_limits + +**Summary** + +Gets configured memory limits of JerryScript. + +**Prototype** + +```c +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 sections. +- `out_stack_limit_p` - out parameter, that gives the maximum size of the stack. + +**Example** + +```c +{ + 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); +} +``` + +**See also** + +- [jerry_init](#jerryinit) +- [jerry_cleanup](#jerrycleanup) + + +## jerry_gc + +**Summary** + +Performs garbage collection. + +**Prototype** + +```c +void +jerry_gc (void); +``` + +**Example** + +```c +jerry_gc (); +``` + +**See also** + +- [jerry_init](#jerryinit) +- [jerry_cleanup](#jerrycleanup) + +# Parser and executor functions + +Functions to parse and run JavaScript source code. + +## jerry_run_simple + +**Summary** + +The simplest way to run JavaScript. + +**Prototype** + +```c +bool +jerry_run_simple (const jerry_char_t *script_source, + size_t script_source_size, + jerry_init_flag_t flags); +``` + +- `script_source` - 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 + - true, if run was successful + - false, otherwise + +**Example** + +```c +{ + const jerry_char_t *script = "print ('Hello, World!');"; + + jerry_run_simple (script, strlen ((const char *) script), JERRY_INIT_EMPTY); +} +``` + +**See also** + +- [jerry_init](#jerryinit) +- [jerry_cleanup](#jerrycleanup) +- [jerry_parse](#jerryparse) +- [jerry_run](#jerryrun) + + +## jerry_parse + +**Summary** + +Parse specified script to execute in Global scope. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_parse (const jerry_char_t *source_p, + size_t source_size, + bool is_strict); +``` + +- `source_p` - string, containing source code to parse. It must be a valid utf8 string. +- `source_size` - size of the string, in bytes. +- `is_strict` - defines strict mode. +- return value + - function object value, if script was parsed successfully, + - thrown error, otherwise + +**Example** + +```c +{ + jerry_init (JERRY_INIT_EMPTY); + + char script [] = "print ('Hello, World!');"; + size_t script_size = strlen ((const char *) script); + + jerry_value_t parsed_code = jerry_parse (script, script_size, false); + jerry_release_value (parsed_code); + + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_run](#jerryrun) + + +## jerry_run + +**Summary** + +Run code in Global scope. + +*Note*: The code should be previously parsed with `jerry_parse`. + +**Prototype** + +```c +jerry_value_t +jerry_run (jerry_value_t func_val); +``` + +- `func_val` - function to run +- return value + - result of bytecode, if run was successful + - thrown error, otherwise + +**Example** + +```c +{ + const jerry_char_t script[] = "print ('Hello, World!');"; + size_t script_size = strlen ((const char *) script); + + /* Initialize engine */ + jerry_init (JERRY_INIT_EMPTY); + + /* Setup Global scope code */ + jerry_value_t parsed_code = jerry_parse (script, script_size, false); + + if (!jerry_value_has_error_flag (parsed_code)) + { + /* Execute the parsed source code in the Global scope */ + jerry_value_t ret_value = jerry_run (parsed_code); + + /* Returned value must be freed */ + jerry_release_value (ret_value); + } + + /* Parsed source code must be freed */ + jerry_release_value (parsed_code); + + /* Cleanup engine */ + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_parse](#jerryparse) + + +## jerry_eval + +**Summary** + +Perform JavaScript `eval`. + +**Prototype** + +```c +jerry_value_t +jerry_eval (const jerry_char_t *source_p, + size_t source_size, + bool is_strict); +``` + +- `source_p` - source code to evaluate, it must be a valid utf8 string. +- `source_size` - length of the source code +- `is_strict` - perform `eval` as it is called from "strict mode" code. +- return value - result of eval, may be error value. + +**Example** + +```c +{ + jerry_value_t ret_val = jerry_eval (str_to_eval, + strlen (str_to_eval), + false); +} +``` + +**See also** + +- [jerry_create_external_function](#jerrycreateexternalfunction) +- [jerry_external_handler_t](#jerryexternalhandlert) + + +# Get the global context + +## jerry_get_global_object + +**Summary** + +Get the Global object. + +*Note*: Returned value must be freed with [jerry_release_object](#jerryreleaseobject) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_get_global_object (void); +``` + +- return value - api value of global object + +**Example** + +```c +{ + jerry_value_t glob_obj_val = jerry_get_global_object (); + + ... // Do something with global object, ex: add properties + + jerry_release_value (glob_obj_val); +} +``` + +**See also** + +- [jerry_release_object](#jerryreleaseobject) +- [jerry_define_own_property](#jerrydefineownproperty) + +# Checker functions + +Functions to check the type of an API value ([jerry_value_t](#jerryvaluet)). + +## jerry_value_is_array + +**Summary** + +**Prototype** + +```c +bool +jerry_value_is_array (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is an array + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_array (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_value_is_boolean + +**Summary** + +Returns whether the given `jerry_value_t` is a boolean value. + +**Prototype** + +```c +bool +jerry_value_is_boolean (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a boolean value + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_boolean (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_value_is_constructor + +**Summary** + +Returns whether the given `jerry_value_t` is a constructor function. + +**Prototype** + +```c +bool +jerry_value_is_constructor (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a constructor + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_constructor (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_value_is_function + +**Summary** + +Returns whether the given `jerry_value_t` is a function. + +**Prototype** + +```c +bool +jerry_value_is_function (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a function + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_function (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_value_is_number + +**Summary** + +Returns whether the given `jerry_value_t` is a number. + +**Prototype** + +```c +bool +jerry_value_is_function (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a number + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_number (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_value_is_null + +**Summary** + +Returns whether the given `jerry_value_t` is a null value. + +**Prototype** + +```c +bool +jerry_value_is_null (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a null + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_null (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_value_is_object + +**Summary** + +Returns whether the given `jerry_value_t` is an object value. + +**Prototype** + +```c +bool +jerry_value_is_object (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is an object + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_object (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_value_is_string + +**Summary** + +Returns whether the given `jerry_value_t` is a string value. + +**Prototype** + +```c +bool +jerry_value_is_string (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is a string + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_string (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_value_is_undefined + +**Summary** + +Returns whether the given `jerry_value_t` is an undefined value. + +**Prototype** + +```c +bool +jerry_value_is_undefined (const jerry_value_t value) +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` is an undefined value + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_undefined (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +# Error flag manipulation functions + +## jerry_value_has_error_flag + +**Summary** + +Returns whether the given `jerry_value_t` has the error flag set. + +**Prototype** + +```c +bool +jerry_value_has_error_flag (const jerry_value_t value); +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` has the error flag set + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_has_error_flag (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_t](#jerryvaluet) + + +## jerry_value_clear_error_flag + +**Summary** + +Clear the error flag. + +**Prototype** + +```c +void +jerry_value_clear_error_flag (jerry_value_t *value_p); +``` + +- `value_p` - pointer to an api value + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_clear_error_flag (&value); + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_t](#jerryvaluet) + + +## jerry_value_set_error_flag + +**Summary** + +Set the error flag. + +**Prototype** + +```c +void +jerry_value_set_error_flag (jerry_value_t *value_p); +``` + +- `value_p` - pointer to an api value + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_set_error_flag (&value); + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_t](#jerryvaluet) + + +# Getter functions of 'jerry_value_t' + +Get raw data from API values. + +## jerry_get_boolean_value + +**Summary** + +Gets the raw bool value form a `jerry_value_t`. + +**Prototype** + +```c +bool +jerry_get_boolean_value (const jerry_value_t value); +``` + +- `value` - api value +- return value - boolean value represented by the argument. + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_boolean (value)) + { + bool raw_value = jerry_get_boolean_value (value); + + ... // usage of raw value + + } + + jerry_release_value (value); +} + +``` + +**See also** + +- [jerry_value_is_boolean](#jerryvalueisboolean) +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_get_number_value + +**Summary** + +Gets the number value of the given `jerry_value_t` parameter as a raw double. + +**Prototype** + +```c +double +jerry_get_number_value (const jerry_value_t value); +``` + +- `value` - api value +- return value - the number value of the given `jerry_value_t` parameter as a raw double. + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_is_number (value)) + { + double raw_value = jerry_get_number_value (value); + + ... // usage of raw value + + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_is_number](#jerryvalueisnumber) +- [jerry_release_value](#jerryreleasevalue) + + +# Functions for string values + +## jerry_get_string_size + +**Summary** + +Get the size of a string. Returns zero, if the specified string is not a value. + +**Prototype** + +```c +jerry_size_t +jerry_get_string_size (const jerry_value_t value); +``` +- `value` - api value +- return value - number of bytes in the buffer needed to represent the string. + +**Example** + +```c +{ + 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); + + ... // usage of string_size + + jerry_release_value (string); +} +``` + +**See also** + +- [jerry_create_string](#jerrycreatestring) +- [jerry_get_string_length](#jerrygetstringlength) + + +## jerry_get_string_length + +**Summary** + +Get the length of a string. Returns zero, if the specified string is not a value. + +**Prototype** + +```c +jerry_length_t +jerry_get_string_length (const jerry_value_t value); +``` + +- `value` - api value +- return value - number of characters in the string + +**Example** + +```c +{ + 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); + + ... // usage of string_length + + jerry_release_value (string); +} +``` + +**See also** + +- [jerry_create_string](#jerrycreatestring) +- [jerry_get_string_size](#jerrygetstringsize) + + +## jerry_string_to_char_buffer + +**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. + +**Prototype** + +```c +jerry_size_t +jerry_string_to_char_buffer (const jerry_value_t value, + jerry_char_t *buffer_p, + jerry_size_t buffer_size); +``` + +- `value` - input string value +- `buffer_p` - pointer to output buffer +- `buffer_size` - size of the buffer +- return value - number of bytes, actually copied to the buffer + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_size_t req_sz = jerry_get_string_size (value); + jerry_char_t str_buf_p[req_sz]; + + jerry_string_to_char_buffer (value, str_buf_p, req_sz); + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_create_string](#jerrycreatestring) +- [jerry_get_string_size](#jerrygetstringsize) + + +# Functions for array object values + +## jerry_get_array_length + +**Summary** + +Get length of an array object. Returns zero, if the given parameter is not an array object. + +**Prototype** + +```c +uint32_t +jerry_get_array_length (const jerry_value_t value); +``` + +- `value` - input array value +- return value - length of the given array + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + uint32_t len = jerry_get_array_length (value); + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_create_array](#jerrycreatearray) + + +# Converters of 'jerry_value_t' + +Functions for convering API values to another value type. + +## jerry_value_to_boolean + +**Summary** + +Call ToBoolean operation on the api value. + +**Prototype** + +```c +bool +jerry_value_to_boolean (const jerry_value_t value); +``` + +- `value` - api value +- return value + - true, if the logical value is true + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + bool b = jerry_value_to_boolean (value); + + jerry_release_value (value); +} + +``` + +**See also** + +- [jerry_value_to_primitive](#jerryvaluetoprimitive) + +## jerry_value_to_number + +**Summary** + +Call ToNumber operation on the api value. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_value_to_number (const jerry_value_t value); +``` + +- `value` - api value +- return value + - converted number value, if success + - thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_t number_value = jerry_value_to_number (value); + + jerry_release_value (number_value); + jerry_release_value (value); +} + +``` + +**See also** + +- [jerry_value_to_primitive](#jerryvaluetoprimitive) + +## jerry_value_to_object + +**Summary** + +Call ToObject operation on the api value. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_value_to_object (const jerry_value_t value); +``` + +- `value` - api value +- return value + - converted object value, if success + - thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_t object_value = jerry_value_to_object (value); + + jerry_release_value (object_value); + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_to_primitive](#jerryvaluetoprimitive) + +## jerry_value_to_primitive + +**Summary** + +Call ToPrimitive operation on the api value. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_value_to_primitive (const jerry_value_t value); +``` + +- `value` - api value +- return value + - converted primitive value, if success + - thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_t prim_value = jerry_value_to_primitive (value); + + jerry_release_value (prim_value); + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_t](#jerryvaluet) + +## jerry_value_to_string + +**Summary** + +Call the ToString ecma builtin operation on the api value. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_value_to_string (const jerry_value_t value); +``` + +- `value` - api value +- return value + - converted srting value, if success + - thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_t string_value = jerry_value_to_string (value); + + jerry_release_value (string_value); + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_to_primitive](#jerryvaluetoprimitive) + + +# Aquire and release API values + +## jerry_acquire_value + +**Summary** + +Acquires the specified Jerry API value. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_acquire_value (jerry_value_t value); +``` + +- `value` - api value +- return value - acquired value that may be used outside of the engine + +**Example** + +```c +{ + jerry_value_t object_value = jerry_create_object (); + + jerry_value_t acquired_object = jerry_acquire_value (object_value); + + jerry_release_value (object_value); + + // acquired_object refers to the created object and makes it + // available after the release of 'object_value' + + jerry_release_value (acquired_object); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) +- [jerry_value_t](#jerryvaluet) + + +## jerry_release_value + +**Summary** + +Release specified Jerry API value. + +**Prototype** + +```c +void +jerry_release_value (jerry_value_t value); +``` + +- `value` - api value + +**Example** + +```c +{ + jerry_value_t object_value = jerry_create_object (); + + ... + + jerry_release_value (object_value); +} +``` + + +# Create API values + +Function for creating [API values](#jerryvaluet). + +*Note*: Every created API value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +## jerry_create_array + +**Summary** + +Create an array object value. + +**Prototype** + +```c +jerry_value_t +jerry_create_array (uint32_t size); +``` + + - `size` - size of array; + - return value - value of the constructed array object + + **Example** + +```c +{ + jerry_value_t array = jerry_create_array (10); + + ... + + jerry_release_value (array); +} +``` + +**See also** + +- [jerry_set_property_by_index](#jerrysetpropertybyindex) +- [jerry_get_property_by_index](#jerrygetpropertybyindex) + + +## jerry_create_boolean + +**Summary** + +Create a jerry_value_t representing a boolean value from the given boolean parameter. + +**Prototype** + +```c +jerry_value_t +jerry_create_boolean (bool value); +``` + +- `value` - raw boolean value. +- return value - a `jerry_value_t` created from the given boolean argument. + +**Example** + +```c +{ + jerry_value_t boolean_value = jerry_create_boolean (true); + + ... // usage of the value + + jerry_release_value (boolean_value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_create_error + +**Summary** + +Create new JavaScript error object. + +**Prototype** + +```c +jerry_value_t +jerry_create_error (jerry_error_t error_type, + const jerry_char_t *message_p); +``` + +- `error_type` - type of error +- `message_p` - value of 'message' property of constructed error object +- return value - value of the constructed error object + +**Example** + +```c +{ + jerry_value_t error_obj = jerry_create_error (JERRY_ERROR_TYPE, + (jerry_char_t * ) "error"); + + ... // usage of error_obj + + + jerry_release_value (error_obj); +} +``` + +**See also** + +- [jerry_value_has_error_flag](#jerryvaluehaserrorflag) +- [jerry_value_clear_error_flag](#jerryvalueclearerrorflag) +- [jerry_value_set_error_flag](#jerryvalueseterrorflag) + + +## jerry_create_error_sz + +**Summary** + +Create new JavaScript error object. + +**Prototype** + +```c +jerry_value_t +jerry_create_error_sz (jerry_error_t error_type, + const jerry_char_t *message_p, + jerry_size_t message_size); +``` + +- `error_type` - type of the error +- `message_p` - value of 'message' property of the constructed error object +- `message_size` - size of the message in bytes +- return value - value of the constructed error object + +**Example** + +```c +{ + jerry_char_t message[] = "error"; + jerry_value_t error_obj = jerry_create_error_sz (JERRY_ERROR_COMMON, + message, + strlen ((char *) message)); + + ... // usage of error_obj + + jerry_release_value (error_obj); +} +``` + +**See also** + +- [jerry_create_error](#jerrycreateerror) + + +## jerry_create_external_function + +**Summary** + +Create an external function object. + +**Prototype** + +```c +jerry_value_t +jerry_create_external_function (jerry_external_handler_t handler_p); +``` + +- `handler_p` - pointer to native handler of the function object +- return value - value of the constructed function object + +**Example** + +```c +static jerry_value_t +handler (const jerry_value_t function_obj_p, + const jerry_value_t this_p, + const jerry_value_t args_p[], + const uint16_t args_cnt) +{ + printf ("native handler called!\n"); + + return jerry_create_boolean (true); +} + +{ + jerry_value_t func_val = jerry_create_external_function (handler); + 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_set_property (glob_obj, prop_name, func_val); + jerry_release_value (prop_name); + + jerry_release_value (func_val); + jerry_release_value (glob_obj); +} +``` + +**See also** + +- [jerry_external_handler_t](#jerryexternalhandlert) +- [jerry_set_property](#jerrysetproperty) +- [jerry_call_function](#jerrycallfunction) + + +## jerry_create_number + +**Summary** + +Creates a `jerry_value_t` representing a number value. + +**Prototype** + +```c +jerry_value_t +jerry_create_number (double value); +``` + +- `value` - double value from which a `jerry_value_t` will be created +- return value - a `jerry_value_t` created from the given double argument + +**Example** + +```c +{ + jerry_value_t number_value = jerry_create_number (3.14); + + ... // usage of the value + + jerry_release_value (number_value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_create_null + +**Summary** + +Creates and returns a `jerry_value_t` with type null object. + +**Prototype** + +```c +jerry_value_t +jerry_create_null (void); +``` + +- return value - a `jerry_value_t` representing null. + +**Example** + +```c +{ + jerry_value_t null_value = jerry_create_null (); + + ... // usage of the value + + jerry_release_value (null_value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_create_object + +**Summary** + +Create new JavaScript object, like with new Object(). + +**Prototype** + +```c +jerry_value_t +jerry_create_object (void); +``` + +- return value - value of the created object + +**Example** + +```c +{ + jerry_value_t object_value = jerry_create_object (); + + ... // usage of object_value + + jerry_release_value (object_value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +## jerry_create_string + +**Summary** + +Create string from a valid CESU8 string. + +**Prototype** + +```c +jerry_value_t +jerry_create_string (const jerry_char_t *str_p); +``` + +- `str_p` - pointer to string +- return value - value of the created string + +**Example** + +```c +{ + const jerry_char_t char_array[] = "a string"; + jerry_value_t string_value = jerry_create_string (char_array); + + ... // usage of string_value + + jerry_release_value (string_value); +} +``` + +**See also** + +- [jerry_create_string_sz](#jerrycreatestringsz) + + +## jerry_create_string_sz + +**Summary** + +Create string from a valid CESU8 string. + +**Prototype** + +```c +jerry_value_t +jerry_create_string_sz (const jerry_char_t *str_p, + jerry_size_t str_size) +``` + +- `str_p` - pointer to string +- `str_size` - size of the string +- return value - value of the created string + +**Example** + +```c +{ + const jerry_char_t char_array[] = "a string"; + jerry_value_t string_value = jerry_create_string_sz (char_array, + strlen ((char *) char_array)); + + ... // usage of string_value + + jerry_release_value (string_value); +} + +``` + +**See also** + +- [jerry_release_string](#jerryreleasestring) + + +## jerry_create_undefined + +**Summary** + +Creates a jerry_value_t representing an undefined value. + +**Prototype** + +```c +jerry_value_t +jerry_create_undefined (void); +``` + +- return value - value of undefined + +**Example** + +```c +{ + jerry_value_t undefined_value = jerry_create_undefined (); + + ... // usage of the value + + jerry_release_value (undefined_value); +} +``` + +**See also** + +- [jerry_release_value](#jerryreleasevalue) + + +# General API functions of JS objects + +## jerry_has_property + +**Summary** + +Checks whether the object or it's prototype has the given property. + +**Prototype** + +```c +bool +jerry_has_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); +``` + +- `obj_val` - object value +- `prop_name_val` - property name +- return value + - true, if the property exists + - false, otherwise + +**Example** + +```c +{ + jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field"); + + bool has_prop = jerry_has_property (global_object, prop_name); + + jerry_release_value (prop_name); + jerry_release_value (global_object); +} +``` + +**See also** + +- [jerry_has_own_property](#jerryhasownproperty) +- [jerry_delete_property](#jerrydeleteproperty) + + +## jerry_has_own_property + +**Summary** + +Checks whether the object has the given property. + +**Prototype** + +```c +bool +jerry_has_own_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); +``` + +- `obj_val` - object value +- `prop_name_val` - property name +- return value + - true, if the property exists + - false, otherwise + +**Example** + +```c +{ + jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field"); + + bool has_prop = jerry_has_own_property (global_object, prop_name); + + jerry_release_value (prop_name); + jerry_release_value (global_object); +} +``` + +**See also** + +- [jerry_has_property](#jerryhasproperty) +- [jerry_delete_property](#jerrydeleteproperty) + + +## jerry_delete_property + +**Summary** + +Delete a property from an object. + +**Prototype** + +```c +bool +jerry_delete_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); +``` + +- `obj_val` - object value +- `prop_name_val` - property name +- return value + - true, if property was deleted successfully + - false, otherwise + +**Example** + +```c +{ + jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "my_prop"); + + jerry_delete_property (global_object, prop_name); + + jerry_release_value (prop_name); + jerry_release_value (global_object); +} +``` + +**See also** + +- [jerry_has_property](#jerryhasproperty) +- [jerry_has_own_property](#jerryhasownproperty) +- [jerry_get_property](#jerrygetproperty) + + +## jerry_get_property + +**Summary** + +Get value of a property to the specified object with the given name. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_get_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val); +``` + +- `obj_val` - object value +- `prop_name_val` - property name +- return value + - value of property, if success + - thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t global_object = jerry_get_global_object (); + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); + + jerry_value_t prop_value = jerry_get_property (obj_val, prop_name); + + jerry_release_value (prop_name); + jerry_release_value (global_object); +} +``` + +**See also** + +- [jerry_has_property](#jerryhasproperty) +- [jerry_has_own_property](#jerryhasownproperty) +- [jerry_delete_property](#jerrydeleteproperty) +- [jerry_set_property](#jerrysetproperty) +- [jerry_get_property_by_index](#jerrygetpropertybyindex) +- [jerry_set_property_by_index](#jerrysetpropertybyindex) + + +## jerry_get_property_by_index + +**Summary** + +Get value by an index from the specified object. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_get_property_by_index (const jerry_value_t obj_val, + uint32_t index); +``` + +- `obj_val` - object value +- index - index number +- return value + - stored value on the specified index, if success + - thrown exception, otherwise. + +**Example** + +```c +{ + jerry_value_t object; + + ... // create or acquire object + + jerry_value_t value = jerry_get_property_by_index (object, 5); + + ... + + jerry_release_value (value); + jerry_release_value (object); +} +``` + +**See also** + +- [jerry_has_property](#jerryhasproperty) +- [jerry_has_own_property](#jerryhasownproperty) +- [jerry_delete_property](#jerrydeleteproperty) +- [jerry_get_property](#jerrygetproperty) +- [jerry_set_property](#jerrysetproperty) +- [jerry_set_property_by_index](#jerrysetpropertybyindex) + + +## jerry_set_property + +**Summary** + +Set a property to the specified object with the given name. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_set_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + const jerry_value_t value_to_set) +``` + +- `obj_val` - object value +- `prop_name_val` - property name +- `value_to_set` - value to set +- return value + - true, if success + - thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t value_to_set; + + ... // 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_set_property (glob_obj, prop_name, value_to_set); + + jerry_release_value (prop_name); + + ... + + jerry_release_value (value_to_set); + jerry_release_value (glob_obj); +} +``` + +**See also** + +- [jerry_has_property](#jerryhasproperty) +- [jerry_has_own_property](#jerryhasownproperty) +- [jerry_delete_property](#jerrydeleteproperty) +- [jerry_get_property](#jerrygetproperty) +- [jerry_get_property_by_index](#jerrygetpropertybyindex) +- [jerry_set_property_by_index](#jerrysetpropertybyindex) + + +## jerry_set_property_by_index + +**Summary** + +Set indexed value in the specified object + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_set_property_by_index (const jerry_value_t obj_val, + uint32_t index, + const jerry_value_t value_to_set); +``` + +- `obj_val` - object value +- index - index number +- `value_to_set` - value to set +- return value + - true, if field value was set successfully + - thrown exception, otherwise + +**Example** + +```c +{ + jerry_value_t object; + jerry_value_t value_to_set; + + ... // create or acquire object and value to set + + jerry_value_t ret_val = jerry_set_property_by_index (object, 5, value_to_set); + + ... + + jerry_release_value (value_to_set); + jerry_release_value (ret_val); + jerry_release_value (object); +} +``` + +**See also** + +- [jerry_has_property](#jerryhasproperty) +- [jerry_has_own_property](#jerryhasownproperty) +- [jerry_delete_property](#jerrydeleteproperty) +- [jerry_get_property](#jerrygetproperty) +- [jerry_set_property](#jerrysetproperty) +- [jerry_get_property_by_index](#jerrygetpropertybyindex) + + +## jerry_init_property_descriptor_fields + +**Summary** + +Initialize property descriptor. + +**Prototype** + +```c +void +jerry_init_property_descriptor_fields (jerry_property_descriptor_t *prop_desc_p); +``` + +- `prop_desc_p` - pointer to property descriptor + +**Example** + +```c +{ + jerry_property_descriptor_t prop_desc; + jerry_init_property_descriptor_fields (&prop_desc); + + ... // usage of prop_desc + + jerry_free_property_descriptor_fields (&prop_desc); +} +``` + +**See also** + +- [jerry_define_own_property](#jerrydefineownproperty) +- [jerry_get_own_property_descriptor](#jerrygetownpropertydescriptor) +- [jerry_free_property_descriptor_fields](#jerryfreepropertydescriptorfields) + + +## jerry_define_own_property + +**Summary** + +Define a property to the specified object with the given name. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_define_own_property (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + const jerry_property_descriptor_t *prop_desc_p); +``` + +- `obj_val` - object value +- `prop_name_val` - property name +- `prop_desc_p` - pointer to property descriptor +- return value + - true, if success + - thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t global_obj_val = jerry_get_global_object (); + + jerry_property_descriptor_t prop_desc; + jerry_init_property_descriptor_fields (&prop_desc); + + jerry_value_t value_to_set; + + ... // create or acquire value to set + + prop_desc.is_value_defined = true; + prop_desc.value = value_to_set; + + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); + jerry_define_own_property (global_obj_val, prop_name, &prop_desc); + jerry_release_value (prop_name); + + jerry_free_property_descriptor_fields (&prop_desc); + jerry_release_value (global_obj_val); +} +``` + +**See also** + +- [jerry_init_property_descriptor_fields](#jerryinitpropertydescriptorfields) +- [jerry_get_own_property_descriptor](#jerrygetownpropertydescriptor) +- [jerry_free_property_descriptor_fields](#jerryfreepropertydescriptorfields) + + +## jerry_get_own_property_descriptor + +**Summary** + +Construct property descriptor from specified property. + +**Prototype** + +```c +bool +jerry_get_own_property_descriptor (const jerry_value_t obj_val, + const jerry_value_t prop_name_val, + jerry_property_descriptor_t *prop_desc_p); +``` + +- `obj_val` - object value +- `prop_name_val` - property name +- `prop_desc_p` - pointer to property descriptor +- return value + +**Example** + +```c +{ + jerry_value_t global_obj_val = jerry_get_global_object (); + + jerry_property_descriptor_t prop_desc; + jerry_init_property_descriptor_fields (&prop_desc); + + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop"); + jerry_get_own_property_descriptor (global_obj_val, prop_name, &prop_desc); + jerry_release_value (prop_name); + + ... // usage of property descriptor + + jerry_free_property_descriptor_fields (&prop_desc); + jerry_release_value (global_obj_val); +} +``` + +**See also** + +- [jerry_init_property_descriptor_fields](#jerryinitpropertydescriptorfields) +- [jerry_define_own_property](#jerrydefineownproperty) +- [jerry_free_property_descriptor_fields](#jerryfreepropertydescriptorfields) + + +## jerry_free_property_descriptor_fields + +**Summary** + +Free fields of property descriptor (setter, getter and value). + +**Prototype** + +```c +void +jerry_free_property_descriptor_fields (const jerry_property_descriptor_t *prop_desc_p); +``` + +- `prop_desc_p` - pointer to property descriptor + +**Example** + +```c +{ + jerry_property_descriptor_t prop_desc; + jerry_init_property_descriptor_fields (&prop_desc); + + ... // usage of property descriptor + + jerry_free_property_descriptor_fields (&prop_desc); +} +``` + +**See also** + +- [jerry_init_property_descriptor_fields](#jerryinitpropertydescriptorfields) +- [jerry_define_own_property](#jerrydefineownproperty) +- [jerry_get_own_property_descriptor](#jerrygetownpropertydescriptor) + + +## jerry_call_function + +**Summary** + +Call function specified by a function value. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_call_function (const jerry_value_t func_obj_val, + const jerry_value_t this_val, + const jerry_value_t args_p[], + jerry_size_t args_count); +``` + +- `func_obj_val` - the function object to call +- `this_val` - object for 'this' binding +- `args_p` - function's call arguments +- `args_count` - number of arguments +- return value - returned jerry value of the called function + +**Example** + +```c +{ + jerry_value_t val; + + ... // receiving val + + if (jerry_value_is_function (val)) + { + jerry_value_t this_val = jerry_create_undefined (); + jerry_value_t ret_val = jerry_call_function (val, this_val, NULL, 0); + + if (!jerry_value_has_error_flag (ret_val)) + { + ... // handle return value + } + + jerry_release_value (ret_val); + jerry_release_value (this_val); + } +} +``` + +**See also** + +- [jerry_is_function](#jerryisfunction) +- [jerry_create_external_function](#jerrycreateexternalfunction) + + +## jerry_construct_object + +**Summary** + +Construct object, invoking specified function object as constructor. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_construct_object (const jerry_value_t func_obj_val, + const jerry_value_t args_p[], + uint16_t args_count); +``` + +- `func_obj_val` - function object to call +- `args_p` - function's call arguments +- `args_count` - number of arguments +- return value - returned value of the invoked constructor + +**Example** + +```c +{ + jerry_value_t val; + + ... // receiving val + + if (jerry_is_constructor (val)) + { + jerry_value_t ret_val = jerry_construct_object (val, NULL, 0); + + if (!jerry_value_has_error_flag (ret_val)) + { + ... // handle return value + } + + jerry_release_value (ret_val); + } +} +``` + +**See also** + + - [jerry_is_constructor](#jerryisconstructor) + + +## jerry_get_object_keys + +**Summary** + +Get keys of the specified object value. + +**Prototype** + +```c +jerry_value_t +jerry_get_object_keys (const jerry_value_t obj_val); +``` + +- `obj_val` - object value +- return value + - array object value, if success + - thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t object; + ... // create or acquire object + + jerry_value_t keys_array = jerry_get_object_keys (object); + + ... // usage of keys_array + + jerry_release_value (keys_array); +} +``` + +**See also** + +- [jerry_get_property](#jerrygetproperty) +- [jerry_set_property](#jerrysetproperty) + + +## jerry_get_prototype + +**Summary** + +Get the prototype of the specified object. + +**Prototype** + +```c +jerry_value_t +jerry_get_prototype (const jerry_value_t obj_val); +``` + +- `obj_val` - object value +- return value + - object value, if success + - null or thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t object; + ... // create or acquire object + + jerry_value_t prototype = jerry_get_prototype (object); + + ... // usage of prototype object + + jerry_release_value (prototype); + jerry_release_value (object); +} +``` + +**See also** + +- [jerry_set_prototype](#jerrysetprototype) + + +## jerry_set_prototype + +**Summary** + +Set the prototype of the specified object. + +**Prototype** + +```c +jerry_value_t +jerry_get_prototype (const jerry_value_t obj_val, + const jerry_value_t proto_obj_val); +``` + +- `obj_val` - object value +- `proto_obj_val` - prototype object value +- return value + - true, if success + - thrown error, otherwise + +**Example** + +```c +{ + jerry_value_t object; + jerry_value_t prototype; + + ... // create or acquire object and prototype + + jerry_value_t ret_val = jerry_set_prototype (object, prototype); + + jerry_release_value (ret_val); + jerry_release_value (prototype); + jerry_release_value (object); +} +``` + +**See also** + +- [jerry_get_prototype](#jerrygetprototype) + + +## jerry_get_object_native_handle + +**Summary** + +Get native handle, previously associated with specified object. + +**Prototype** + +```c +bool +jerry_get_object_native_handle (const jerry_value_t obj_val, + uintptr_t *out_handle_p); +``` + +- `obj_val` - object value +- `out_handle_p` - handle value (output parameter). +- return value + - true, if there is handle associated with the object + - false, otherwise + +**Example** + +```c +{ + jerry_value_t object; + uintptr_t handle_set; + + ... // receive or construct object and handle_set value + + jerry_set_object_native_handle (object, handle_set, NULL); + + ... + + uintptr_t handle_get; + bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get); +} +``` + +**See also** + +- [jerry_create_object](#jerrycreateobject) +- [jerry_set_object_native_handle](#jerrysetobjectnativehandle) + +## jerry_set_object_native_handle + +**Summary** + +Set native handle and, optionally, 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. + +**Prototype** + +```c +void +jerry_set_object_native_handle (const jerry_value_t obj_val, + uintptr_t handle, + jerry_object_free_callback_t freecb_p); +``` + +- `obj_val` - object value to set handle in +- `handle` - handle value +- `freecb_p` - pointer to "free" callback or NULL + +**Example** + +```c +{ + jerry_value_t object; + uintptr_t handle_set; + + ... // receive or construct object and handle_set value + + jerry_set_object_native_handle (object, handle_set, NULL); + + ... + + uintptr_t handle_get; + bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get); +} +``` + +**See also** + +- [jerry_create_object](#jerrycreateobject) +- [jerry_get_object_native_handle](#jerrygetobjectnativehandle) + + +## jerry_foreach_object_property + +**Summary** + +Applies the given function to every property in the given object. + +**Prototype** + +```c +bool +jerry_foreach_object_property (jerry_value_t obj_val, + jerry_object_property_foreach_t foreach_p, + void *user_data_p); +``` + +- `obj_val` - object value +- `foreach_p` - foreach function, that will be apllied 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 + +**Example** + +```c +bool foreach_function (const jerry_value_t prop_name, + const jerry_value_t prop_value, + void *user_data_p) +{ + + ... // implementation of the foreach function + +} + +{ + jerry_value_t object; + ... // receive or construct object + + double data = 3.14; // example data + + jerry_foreach_object_property (object, foreach_function, &data); + +} +``` + +**See also** + +- [jerry_object_property_foreach_t](#jerryobjectpropertyforeacht) + + +# Snapshot functions + +## jerry_parse_and_save_snapshot + +**Summary** + +Generate snapshot from the specified source code. + +**Prototype** + +```c +size_t +jerry_parse_and_save_snapshot (const jerry_char_t *source_p, + size_t source_size, + bool is_for_global, + bool is_strict, + uint8_t *buffer_p, + size_t buffer_size); +``` + +- `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 +- `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) + - 0 otherwise. + +**Example** + +```c +{ + jerry_init (JERRY_INIT_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_char_t *) code_to_snapshot_p, + strlen (code_to_snapshot_p), + true, + false, + global_mode_snapshot_buffer, + sizeof (global_mode_snapshot_buffer)); + + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_init](#jerryinit) +- [jerry_cleanup](#jerrycleanup) +- [jerry_exec_snapshot](#jerryexecsnapshot) + + +## jerry_exec_snapshot + +**Summary** + +Execute snapshot from the specified buffer. + +*Note*: Returned value must be freed with [jerry_release_value](#jerryreleasevalue) when it +is no longer needed. + +**Prototype** + +```c +jerry_value_t +jerry_exec_snapshot (const void *snapshot_p, + size_t snapshot_size, + bool copy_bytecode); +``` + +- `snapshot_p` - pointer to snapshot +- `snapshot_size` - size of snapshot +- `copy_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). +- return value + - result of bytecode, if run was successful + - thrown error, otherwise + +**Example** + +```c +{ + jerry_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_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), + true, + global_mode_snapshot_buffer, + sizeof (global_mode_snapshot_buffer)); + jerry_cleanup (); + + jerry_init (JERRY_INIT_EMPTY); + + res = (jerry_exec_snapshot (global_mode_snapshot_buffer, + global_mode_snapshot_size, + false); + + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_init](#jerryinit) +- [jerry_cleanup](#jerrycleanup) +- [jerry_parse_and_save_snapshot](#jerryparseandsavesnapshot) diff --git a/02.how-to.md b/02.how-to.md deleted file mode 100644 index 0d8ab27e9..000000000 --- a/02.how-to.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -layout: page -title: How To -permalink: /how-to/ ---- - -* toc -{:toc} - -# How to Get the Sources -This step should be simple: - -{% highlight bash %} -git clone https://github.com/Samsung/jerryscript.git -cd jerryscript -{% endhighlight %} - -# How to Setup Recommended Prerequisites - -Currently, we are using Ubuntu Linux 14.04+ as our development environment, so this tutorial was written based on this assumption. Additionaly, it'll be useful to read [Prerequisites]({{ site.baseurl }}/wiki/Prerequisites) wiki page, also. - -There are dependencies, that should be installed manually. The following list is required for building: - -- `gcc` or `g++` higher than `4.8.2` - - native - - arm-none-eabi -- `cmake` higher than `2.8.12.2` -- `make` higher than `3.81` -- `bash` higher than `4.3.11` - -These tools are required for development: - -- `cppcheck` requires `libpcre` -- `vera++` requires `tcl`, `tk` and `boost` - -{% highlight bash %} -sudo apt-get install gcc g++ -sudo apt-get install gcc-arm-none-eabi -sudo apt-get install cmake -sudo apt-get install libpcre3 libpcre3-dev -sudo apt-get install tcl8.6 tcl8.6-dev tk8.6-dev libboost-all-dev -{% endhighlight %} - -To make our scripts run correctly, several shell utilities should be available on the system: - -- `find` -- `bc` -- `awk` -- `sed` -- `sha256sum` -- `wget` - -# How to Build - -After setting up prerequisites, let's built the engine: - -{% highlight bash %} -make -{% endhighlight %} - -Upon first build, `make` would try to setup prerequisites, required for further development and pre-commit testing: -- stm32f3 and stm32f4 libraries -- nuttx's headers -- cppcheck 1.66 -- vera++ 1.2.1 - -It may take time, so go grab some coffee: - -{% highlight bash %} -Setting up prerequisites... (log file: ./build/prerequisites/prerequisites.log) -{% endhighlight %} - -# How to Build Debug Version -To build debug version for Linux: - -{% highlight bash %} -make debug.linux -{% endhighlight %} - -To build debug version for Linux without LTO (Link Time Optimization): - -{% highlight bash %} -LTO=off make debug.linux -{% endhighlight %} - -# How to Run Unittests -{% highlight bash %} -make unittests -{% endhighlight %} - -# How to Check the Patch -{% highlight bash %} -make precommit -j -{% endhighlight %} - -Sometimes pre-commit testing fails, in that case you'll see message like that: - -{% highlight bash %} -Build failed. See ./build/bin/unittests/make.log for details. -{% endhighlight %} diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md new file mode 100644 index 000000000..90c71e10e --- /dev/null +++ b/03.API-EXAMPLE.md @@ -0,0 +1,517 @@ +--- +layout: page +title: API Examples +permalink: /api-example/ +--- + +* toc +{:toc} + +JerryScript Engine can be embedded into any application, providing the way to run JavaScript in a large range of environments - from desktops to low-memory microcontrollers. + +This guide is intended to introduce you to JerryScript embedding API through creation of simple JavaScript shell. + +## Step 1. Execute JavaScript from your application + +```c +#include +#include "jerry-api.h" + +int +main (int argc, char * argv[]) +{ + const jerry_char_t script[] = "print ('Hello, World!');"; + size_t script_size = strlen ((const char *) script); + + bool ret_value = jerry_run_simple (script, script_size, JERRY_INIT_EMPTY); + + return (ret_value ? 1 : 0); +} +``` + +The application will generate the following output: + +```bash +Hello, World! +``` + +## Step 2. Split engine initialization and script execution + +Here we perform the same actions, as `jerry_run_simple`, while splitting into several steps: + +- engine initialization +- script code setup +- script execution +- engine cleanup + + +```c +#include +#include "jerry-api.h" + +int +main (int argc, char * argv[]) +{ + const jerry_char_t script[] = "print ('Hello, World!');"; + size_t script_size = strlen ((const char *) script); + + /* Initialize engine */ + jerry_init (JERRY_INIT_EMPTY); + + /* Setup Global scope code */ + jerry_value_t parsed_code = jerry_parse (script, script_size, false); + + if (!jerry_value_has_error_flag (parsed_code)) + { + /* Execute the parsed source code in the Global scope */ + jerry_value_t ret_value = jerry_run (parsed_code); + + /* Returned value must be freed */ + jerry_release_value (ret_value); + } + + /* Parsed source code must be freed */ + jerry_release_value (parsed_code); + + /* Cleanup engine */ + jerry_cleanup (); + + return 0; +} +``` + +Our code is more complex now, but it introduces possibilities to interact with JerryScript step-by-step: setup native objects, call JavaScript functions, etc. + +## Step 3. Execution in 'eval'-mode + +```c +#include +#include "jerry-api.h" + +int +main (int argc, char * argv[]) +{ + const jerry_char_t script_1[] = "var s = 'Hello, World!';"; + const jerry_char_t script_2[] = "print (s);"; + + /* Initialize engine */ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t eval_ret; + + /* Evaluate script1 */ + eval_ret = jerry_eval (script_1, + strlen ((const char *) script_1), + false); + + /* Free JavaScript value, returned by eval */ + jerry_release_value (eval_ret); + + /* Evaluate script2 */ + eval_ret = jerry_eval (script_2, + strlen ((const char *) script_2), + false); + + /* Free JavaScript value, returned by eval */ + jerry_release_value (eval_ret); + + /* Cleanup engine */ + jerry_cleanup (); + + return 0; +} +``` + +This way, we execute two independent script parts in one execution environment. The first part initializes string variable, and the second outputs the variable. + +## Step 4. Interaction with JavaScript environment + +```c +#include +#include "jerry-api.h" + +int +main (int argc, char * argv[]) { + const jerry_char_t str[] = "Hello, World!"; + const jerry_char_t script[] = "print (s);"; + + /* Initializing JavaScript environment */ + jerry_init (JERRY_INIT_EMPTY); + + /* Getting pointer to the Global object */ + jerry_value_t global_object = jerry_get_global_object (); + + /* Constructing strings */ + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "s"); + jerry_value_t prop_value = jerry_create_string (str); + + /* Setting the string value as a property of the Global object */ + jerry_set_property (global_object, prop_name, prop_value); + + /* Releasing string values, as it is no longer necessary outside of engine */ + jerry_release_value (prop_name); + jerry_release_value (prop_value); + + /* Releasing the Global object */ + jerry_release_value (global_object); + + /* Now starting script that would output value of just initialized field */ + jerry_value_t eval_ret = jerry_eval (script, + strlen ((const char *) script), + false); + + /* Free JavaScript value, returned by eval */ + jerry_release_value (eval_ret); + + /* Freeing engine */ + jerry_cleanup (); + + return 0; +} +``` + +The sample will also output 'Hello, World!'. However, now it is not just a part of the source script, but the value, dynamically supplied to the engine. + +## Step 5. Description of JerryScript value descriptors + +JerryScript value can be a boolean, number, null, object, string or undefined. The value has an error flag, +that indicates whether is an error or not. Every type has an error flag not only objects. The error flag should +be cleared before the value is passed as an argument, otherwise it can lead to a type error. The error objects +created by API functions has the error flag set. + +The following example function will output a JavaScript value: + +```c +#include +#include + +#include "jerry-api.h" +#include "jerry-port.h" + +static void +print_value (const jerry_value_t value) +{ + if (jerry_value_is_undefined (value)) + { + jerry_port_logmsg (stdout, "undefined"); + } + else if (jerry_value_is_null (value)) + { + jerry_port_logmsg (stdout, "null"); + } + else if (jerry_value_is_boolean (value)) + { + if (jerry_get_boolean_value (value)) + { + jerry_port_logmsg (stdout, "true"); + } + else + { + jerry_port_logmsg (stdout, "false"); + } + } + /* Float value */ + else if (jerry_value_is_number (value)) + { + jerry_port_logmsg (stdout, "number"); + } + /* String value */ + else if (jerry_value_is_string (value)) + { + /* Determining required buffer size */ + jerry_size_t req_sz = jerry_get_string_size (value); + jerry_char_t str_buf_p[req_sz]; + + jerry_string_to_char_buffer (value, str_buf_p, req_sz); + + jerry_port_logmsg (stdout, "%s", (const char *) str_buf_p); + } + /* Object reference */ + else if (jerry_value_is_object (value)) + { + jerry_port_logmsg (stdout, "[JS object]"); + } + + jerry_port_logmsg (stdout, "\n"); +} +``` + +## Simple JavaScript shell + +Now all building blocks, necessary to construct JavaScript shell, are ready. + +Shell operation can be described with the following loop: + +- read command; +- if command is 'quit' + - exit loop; +- else + - eval (command); + - print result of eval; + - loop. + +```c +#include +#include + +#include "jerry-api.h" +#include "jerry-port.h" + +static void print_value (const jerry_api_value_t); + +int +main (int argc, char * argv[]) +{ + bool is_done = false; + + /* Initialize engine */ + jerry_init (JERRY_INIT_EMPTY); + + while (!is_done) + { + char cmd [256]; + char *cmd_tail = cmd; + size_t len = 0; + + jerry_port_logmsg (stdout, "> "); + + /* Read next command */ + while (true) + { + if (fread (cmd_tail, 1, 1, stdin) != 1 && len == 0) + { + is_done = true; + break; + } + if (*cmd_tail == '\n') + { + break; + } + + cmd_tail++; + len++; + } + + jerry_value_t ret_val; + + /* Evaluate entered command */ + ret_val = jerry_eval ((const jerry_char_t *) cmd, + len, + false); + + /* If command evaluated successfully, print value, returned by eval */ + if (jerry_value_has_error_flag (ret_val)) + { + /* Evaluated JS code thrown an exception + * and didn't handle it with try-catch-finally */ + jerry_port_errormsg ("Unhandled JS exception occured: "); + } + + print_value (ret_val); + jerry_release_value (ret_val); + } + + /* Cleanup engine */ + jerry_cleanup (); + + return 0; +} +``` + +The application inputs commands and evaluates them, one after another. + +## Step 6. Creating JS object in global context + +In this example we demonstrate how to use native function and structures in JavaScript. + +```c +#include +#include "jerry-api.h" + +struct my_struct +{ + const char *msg; +} my_struct; + +/** + * Get a string from a native object + */ +static jerry_value_t +get_msg_handler (const jerry_value_t func_value, /**< function object */ + const jerry_value_t this_value, /**< this arg */ + const jerry_value_t *args_p, /**< function arguments */ + const jerry_length_t args_cnt) /**< number of function arguments */ +{ + return jerry_create_string ((const jerry_char_t *) my_struct.msg); +} /* get_msg_handler */ + +int +main (int argc, char * argv[]) +{ + /* Initialize engine */ + jerry_init (JERRY_INIT_EMPTY); + + /* Do something with the native object */ + my_struct.msg = "Hello World"; + + /* Create an empty JS object */ + jerry_value_t object = jerry_create_object (); + + /* Create a JS function object and wrap into a jerry value */ + jerry_value_t func_obj = jerry_create_external_function (get_msg_handler); + + /* Set the native function as a property of the empty JS object */ + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "myFunc"); + jerry_set_property (object, prop_name, func_obj); + jerry_release_value (prop_name); + jerry_release_value (func_obj); + + /* Wrap the JS object (not empty anymore) into a jerry api value */ + jerry_value_t global_object = jerry_get_global_object (); + + /* Add the JS object to the global context */ + prop_name = jerry_create_string ((const jerry_char_t *) "MyObject"); + jerry_set_property (global_object, prop_name, object); + jerry_release_value (prop_name); + jerry_release_value (object); + jerry_release_value (global_object); + + /* Now we have a "builtin" object called MyObject with a function called myFunc() + * + * Equivalent JS code: + * var MyObject = { myFunc : function () { return "some string value"; } } + */ + const jerry_char_t script[] = " \ + var str = MyObject.myFunc (); \ + print (str); \ + "; + size_t script_size = strlen ((const char *) script); + + /* Evaluate script */ + jerry_value_t eval_ret = jerry_eval (script, script_size, false); + + /* Free JavaScript value, returned by eval */ + jerry_release_value (eval_ret); + + /* Cleanup engine */ + jerry_cleanup (); + + return 0; +} +``` + +The application will generate the following output: + +```bash +Hello World +``` + +## Step 7. Extending JS Objects with native functions + +Here we create a JS Object with `jerry_eval`, then extend it with a native function. This function shows how to get a property value from the object and how to manipulate it. + +```c +#include +#include "jerry-api.h" + +/** + * Add param to 'this.x' + */ +static jerry_value_t +add_handler (const jerry_value_t func_value, /**< function object */ + const jerry_value_t this_val, /**< this arg */ + const jerry_value_t *args_p, /**< function arguments */ + const jerry_length_t args_cnt) /**< number of function arguments */ +{ + /* Get 'this.x' */ + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "x"); + jerry_value_t x_val = jerry_get_property (this_val, prop_name); + + if (!jerry_value_has_error_flag (x_val)) + { + /* Convert Jerry API values to double */ + double x = jerry_get_number_value (x_val); + double d = jerry_get_number_value (*args_p); + + /* Add the parameter to 'x' */ + jerry_value_t res_val = jerry_create_number (x + d); + + /* Set the new value of 'this.x' */ + jerry_set_property (this_val, prop_name, res_val); + jerry_release_value (res_val); + } + + jerry_release_value (x_val); + jerry_release_value (prop_name); + + return jerry_create_undefined (); +} /* add_handler */ + +int +main (int argc, char * argv[]) +{ + /* Initialize engine */ + jerry_init (JERRY_INIT_EMPTY); + + /* Create a JS object */ + const jerry_char_t my_js_object[] = " \ + MyObject = \ + { x : 12, \ + y : 'Value of x is ', \ + foo: function () \ + { \ + return this.y + this.x; \ + } \ + } \ + "; + + jerry_value_t my_js_obj_val; + + /* Evaluate script */ + my_js_obj_val = jerry_eval (my_js_object, + strlen ((const char *) my_js_object), + false); + + /* Create a JS function object and wrap into a jerry value */ + jerry_value_t add_func_obj = jerry_create_external_function (add_handler); + + /* Set the native function as a property of previously created MyObject */ + jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "add2x"); + jerry_set_property (my_js_obj_val, prop_name, add_func_obj); + jerry_release_value (add_func_obj); + jerry_release_value (prop_name); + + /* Free JavaScript value, returned by eval (my_js_object) */ + jerry_release_value (my_js_obj_val); + + const jerry_char_t script[] = " \ + var str = MyObject.foo (); \ + print (str); \ + MyObject.add2x (5); \ + print (MyObject.foo ()); \ + "; + size_t script_size = strlen ((const char *) script); + + /* Evaluate script */ + jerry_value_t eval_ret = jerry_eval (script, script_size, false); + + /* Free JavaScript value, returned by eval */ + jerry_release_value (eval_ret); + + /* Cleanup engine */ + jerry_cleanup (); + + return 0; +} +``` + +The application will generate the following output: + +```bash +Value of x is 12 +Value of x is 17 +``` + +## Further steps + +For further API description, please visit [API Reference page](https://samsung.github.io/jerryscript/API/) on [JerryScript home page](https://samsung.github.io/jerryscript/). diff --git a/03.api.md b/03.api.md deleted file mode 100644 index a9799ea98..000000000 --- a/03.api.md +++ /dev/null @@ -1,2725 +0,0 @@ ---- -layout: page -title: API -permalink: /API/ ---- - -* toc -{:toc} - -# jerry_run_simple - -**Summary** - -The simplest way to run JavaScript. - -**Prototype** - -```c -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** - -```c -{ - const jerry_api_char_t *script = "print ('Hello, World!');"; - - jerry_run_simple (script, strlen ((const char *) script), JERRY_FLAG_EMPTY); -} -``` - -**See also** - -- [jerry_init](#jerry_init) -- [jerry_cleanup](#jerry_cleanup) -- [jerry_parse](#jerry_parse) -- [jerry_run](#jerry_run) - - -# jerry_init - -**Summary** - -Initializes JerryScript engine, making possible to run JavaScript code and perform operations on JavaScript values. - -**Prototype** - -```c -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** - -```c -{ - jerry_init (JERRY_FLAG_ENABLE_LOG); - - // ... - - jerry_cleanup (); -} -``` - -**See also** - -- [jerry_cleanup](#jerry_cleanup) - -# jerry_cleanup - -**Summary** - -Finish JavaScript engine execution, freeing memory and JavaScript values. - -JavaScript values, received from engine, are inaccessible after the cleanup. - -**Prototype** - -```c -void -jerry_cleanup (void); -``` - -**See also** - -- [jerry_init](#jerry_init) - - -# 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** - -```c -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** - -```c -{ - 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_run](#jerry_run) - - -# jerry_parse_and_save_snapshot - -**Summary** - -Generate snapshot from the specified source. - -**Prototype** - -```c -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 source -- `source_size` - script source size -- `is_for_global` - snapshot would be executed as global (true) or eval (false) -- `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) - - 0 otherwise - -**Example** - -```c -{ - 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_init](#jerry_init) -- [jerry_exec_snapshot](#jerry_exec_snapshot) - - -# jerry_run - -**Summary** - -Run code of Global scope. - -The code should be previously registered through `jerry_parse`. - -**Prototype** - -```c -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 completion - - `JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION` - an unhandled JavaScript exception occurred - - `JERRY_COMPLETION_CODE_INVALID_SNAPSHOT_VERSION` - snapshot version mismatch - - `JERRY_COMPLETION_CODE_INVALID_SNAPSHOT_FORMAT` - snapshot format is not valid - -**Example** - -```c -{ - 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_parse](#jerry_parse) - - -# jerry_exec_snapshot - -**Summary** - -Execute snapshot from the specified buffer. - -**Prototype** - -```c -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 snapshot -- `snapshot_size` - size of snapshot -- `copy_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** - -```c -{ - 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_init](#jerry_init) -- [jerry_cleanup](#jerry_cleanup) -- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot) - - -# jerry_get_memory_limits - -**Summary** - -Gets configured memory limits of JerryScript. - -**Prototype** - -```c -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 sections -- `out_stack_limit_p` - out parameter, that gives the maximum size of the stack - -**Example** - -```c -{ - 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_init](#jerry_init) - - -# jerry_api_gc - -**Summary** - -Performs garbage collection. - -**Prototype** - -```c -void -jerry_api_gc (void); -``` - -**Example** - -```c -jerry_api_gc (); -``` - - -# jerry_api_eval - -**Summary** - -Perform JavaScript `eval`. - -**Prototype** - -```c -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 evaluate -- `source_size` - length of the source code -- `is_direct` - whether to perform `eval` in "direct" mode (which means it is called as "eval" and not through some alias) -- `is_strict` - perform `eval` as it is called from "strict mode" code -- `retval_p` - value, returned by `eval` (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** - -```c -{ - 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_external_function](#jerry_api_create_external_function) -- [jerry_external_handler_t](#jerry_external_handler_t) - - -# 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](#jerry_api_release_value). - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# 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](#jerry_api_release_value). - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# 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](#jerry_api_release_value). - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# 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](#jerry_api_release_value). - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# 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](#jerry_api_release_value). - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# 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](#jerry_api_release_value) when it becomes unnecessary. - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# jerry_api_create_string_sz - -**Summary** - -Creates a string. The caller should release the string with [jerry_api_release_string](#jerry_api_release_string) when the value becomes unnecessary. - -**Prototype** - -```c -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 created -- `v_size` - size of the string -- return value - a jerry_api_string_t* created from the given jerry_api_char_t* argument - -**Example** - -```c -{ - 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_release_string](#jerry_api_release_string) - - -# 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](#jerry_api_release_value) when it becomes unnecessary. - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# 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** - -```c -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 error -- `message_p` - value of 'message' property of the constructed error object -- `message_size` - size of the message in bytes -- return value - pointer to created error object - -**Example** - -```c -{ - 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_create_error](#jerry_api_create_error) - - -# 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** - -```c -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** - -```c -{ - 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_value_is_boolean](#jerry_api_value_is_boolean) -- [jerry_api_release_value](#jerry_api_release_value) - - -# 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** - -```c -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** - -```c -{ - 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_value_is_number](#jerry_api_value_is_number) -- [jerry_api_release_value](#jerry_api_release_value) - - -# 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** - -```c -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** - -```c -{ - 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_value_is_object](#jerry_api_value_is_object) -- [jerry_api_release_value](#jerry_api_release_value) - - -# 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** - -```c -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** - -```c -{ - 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_value_is_string](#jerry_api_value_is_string) -- [jerry_api_release_value](#jerry_api_release_value) - - -# jerry_api_get_string_size - -**Summary** - -Gets the length of a jerry_api_string_t. - -**Prototype** - -```c -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** - -```c -{ - 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_create_string](#jerry_api_create_string) -- [jerry_api_release_string](#jerry_api_release_string) -- [jerry_api_get_string_length](#jerry_api_get_string_length) - - -# jerry_api_get_string_length - -**Summary** - -Gets the length of a jerry_api_string_t. - -**Prototype** - -```c -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** - -```c -{ - 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_create_string](#jerry_api_create_string) -- [jerry_api_release_string](#jerry_api_release_string) -- [jerry_api_get_string_size](#jerry_api_get_string_size) - - -# jerry_api_value_is_undefined - -**Summary** - -Returns whether the given jerry_api_value_t is an undefined value. - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# jerry_api_value_is_void - -**Summary** - -Returns whether the given jerry_api_value_t is a void value. - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# jerry_api_value_is_boolean - -**Summary** - -Returns whether the given jerry_api_value_t is a boolean value. - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# jerry_api_value_is_number - -**Summary** - -Returns whether the given jerry_api_value_t is a number value. - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# jerry_api_value_is_function - -**Summary** - -Returns whether the given jerry_api_value_t is a function object. - -**Prototype** - -```c -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** - -```c -{ - 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_is_function](#jerry_api_is_function) -- [jerry_api_release_value](#jerry_api_release_value) - - -# jerry_api_value_is_null - -**Summary** - -Returns whether the given jerry_api_value_t is a null value. - -**Prototype** - -```c -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** - -```c - 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_release_value](#jerry_api_release_value) - - -# jerry_api_value_is_object - -**Summary** - -Returns whether the given jerry_api_value_t is an object. - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# jerry_api_value_is_string - -**Summary** - -Returns whether the given jerry_api_value_t is a string. - -**Prototype** - -```c -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** - -```c -{ - 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_release_value](#jerry_api_release_value) - - -# 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](#jerry_api_release_value). - -**Prototype** - -```c -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** - -```c -{ - 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](#jerry_api_release_value) -- [jerry_api_acquire_string](#jerry_api_acquire_string) -- [jerry_api_acquire_object](#jerry_api_acquire_object) - - -# jerry_api_release_value - -**Summary** - -Release specified pointer to the value. - -**Prototype** - -```c -void -jerry_api_release_value (jerry_api_value_t *value_p); -``` - -- `value_p` - pointer to the value. - -**Example** -```c -{ - 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](#jerry_api_release_string). - -**Prototype** - -```c -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** - -```c -{ - jerry_api_string_t *string_p = jerry_api_create_string ("abc"); - - ... - - jerry_api_release_string (string_p); -} -``` - -**See also** - -- [jerry_api_acquire_string](#jerry_api_acquire_string) -- [jerry_api_release_string](#jerry_api_release_string) -- [jerry_api_string_to_char_buffer](#jerry_api_string_to_char_buffer) - - -# jerry_api_string_to_char_buffer - -**Summary** - -Copy string characters to specified buffer, append zero character at end of the buffer. - -**Prototype** - -```c -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, is `buffer_size` is 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** - -```c -{ - 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_create_string](#jerry_api_create_string) - - -# 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](#jerry_api_release_string). - -**Prototype** - -```c -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** - -```c -{ - 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](#jerry_api_release_string) -- [jerry_api_create_string](#jerry_api_create_string) - -# jerry_api_release_string - -**Summary** - -Release specified pointer to the string. - -**Prototype** - -```c -void -jerry_api_release_string (jerry_api_string_t *string_p); -``` - -- `string_p` - pointer to the string. - -**Example** - -```c -{ - 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_acquire_string](#jerry_api_acquire_string) -- [jerry_api_create_string](#jerry_api_create_string) - - -# 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](#jerry_api_release_object). - -**Prototype** - -```c -jerry_api_object_t * -jerry_api_create_object (); -``` - -- returned value is pointer to the created object. - -**Example** - -```c -{ - jerry_api_object_t *object_p = jerry_api_create_object (); - - ... - - jerry_api_release_object (object_p); -} -``` - -**See also** - -- [jerry_api_acquire_object](#jerry_api_acquire_object) -- [jerry_api_release_object](#jerry_api_release_object) -- [jerry_api_add_object_field](#jerry_api_add_object_field) -- [jerry_api_delete_object_field](#jerry_api_delete_object_field) -- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) -- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) -- [jerry_api_get_object_native_handle](#jerry_api_get_object_native_handle) -- [jerry_api_set_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](#jerry_api_release_object). - -**Prototype** - -```c -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** - -```c -{ - 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](#jerry_api_release_object) -- [jerry_api_create_object](#jerry_api_create_object) - - -# jerry_api_release_object - -**Summary** - -Release specified pointer to the object. - -**Prototype** - -```c -void -jerry_api_release_object (jerry_api_object_t *object_p); -``` - -- `object_p` - pointer to the object. - -**Example** - -```c -{ - 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_acquire_object](#jerry_api_acquire_object) -- [jerry_api_create_object](#jerry_api_create_object) - - -# jerry_api_get_global - -**Summary** - -Get the Global object. - -**Prototype** - -```c -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](#jerry_api_release_object), just when the value becomes unnecessary. - -**Example** - -```c -{ - 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_release_object) -- [jerry_api_add_object_field](#jerry_api_add_object_field) -- [jerry_api_delete_object_field](#jerry_api_delete_object_field) -- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) -- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) - - -# jerry_api_add_object_field - -**Summary** - -Create field (named data property) in an object - -**Prototype** - -```c -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** - -```c -{ - 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_create_object](#jerry_api_create_object) - - -# jerry_api_delete_object_field - -**Summary** - -Delete field (property) in the specified object - -**Prototype** - -```c -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** - -```c -{ - 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_create_object](#jerry_api_create_object) - - -# jerry_api_get_object_field_value - -**Summary** - -Get value of field (property) in the specified object, i.e. perform [[Get]] operation. - -**Prototype** - -```c -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](#jerry_api_release_object) just when it becomes unnecessary. - -**Example** - -```c -{ - 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_create_object](#jerry_api_create_object) -- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) -- [jerry_api_get_object_field_value_sz](#jerry_api_get_object_field_value_sz) - - -# 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** - -```c -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` - object -- `field_name_p` - name of the field -- `field_name_size` - size of field name in bytes -- `field_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** - -```c -{ - 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_init) -- [jerry_api_create_object](#jerry_api_create_object) -- [jerry_api_release_object](#jerry_api_release_object) -- [jerry_api_add_object_field](#jerry_api_add_object_field) -- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) -- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) -- [jerry_api_set_object_field_value_sz](#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** - -```c -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** - -```c -{ - 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_create_object) -- [jerry_api_get_object_field_value](#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](#jerry_api_set_object_field_value_sz) - - -# jerry_api_set_object_field_value_sz - -**Summary** - -Set value of field in the specified object. - -**Prototype** - -```c -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` - object -- `field_name_p` - name of the field -- `field_name_size` - size of field name in bytes -- `field_value_p` - field value to set -- return value - - true, if field value was set successfully - - false, otherwise - -**Example** - -```c -{ - 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_create_object) -- [jerry_api_get_object_field_value](#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](#jerry_api_set_object_field_value) - - -# jerry_api_get_object_native_handle - -**Summary** - -Get native handle, previously associated with specified object. - -**Prototype** - -```c -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** - -```c -{ - 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_create_object](#jerry_api_create_object) -- [jerry_api_set_object_native_handle](#jerry_api_set_object_native_handle) - -# 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** - -```c -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** - -```c -{ - 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_create_object](#jerry_api_create_object) -- [jerry_api_get_object_native_handle](#jerry_api_get_object_native_handle) - -# jerry_api_is_function - -**Summary** - -Check whether the specified object is a function object. - -**Prototype** - -```c -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** - -```c -{ - 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](#jerry_api_is_constructor) -- [jerry_api_call_function](#jerry_api_call_function) - - -# jerry_api_is_constructor - -**Summary** - -Check whether the specified object is a constructor function object. - -**Prototype** - -```c -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** - -```c -{ - 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_is_function](#jerry_api_is_function) -- [jerry_api_construct_object](#jerry_api_construct_object) - - -# jerry_api_call_function - -**Summary** - -Call function object. - -**Prototype** - -```c -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](#jerry_api_release_object) just when it becomes unnecessary. - -**Example** - -```c -{ - 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_is_function](#jerry_api_is_function) -- [jerry_api_create_external_function](#jerry_api_create_external_function) - - -# jerry_api_construct_object - -**Summary** - -Construct object invoking specified function object as constructor. - -**Prototype** - -```c -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](#jerry_api_release_object) just when it becomes unnecessary. - -**Example** - -```c -{ - 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_api_is_constructor](#jerry_api_is_constructor) - - -# jerry_external_handler_t - -**Summary** - -The data type represents pointer to call handler of a native function object. - -**Structure** - -```c -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](#jerry_api_create_external_function) - - -# jerry_api_create_external_function - -**Summary** - -Create an external function object. - -**Prototype** - -```c -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](#jerry_api_release_object), just when the value becomes unnecessary. - -**Example** - -```c -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_external_handler_t](#jerry_external_handler_t) -- [jerry_api_is_function](#jerry_api_is_function) -- [jerry_api_call_function](#jerry_api_call_function) -- [jerry_api_release_object](#jerry_api_release_object) - - -# 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](#jerry_api_release_object). - -**Prototype** - -```c -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** - -```c -{ - 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_acquire_object) -- [jerry_api_release_object](#jerry_api_release_object) -- [jerry_api_set_array_index_value](#jerry_api_set_array_index_value) -- [jerry_api_get_array_index_value](#jerry_api_get_array_index_value) -- [jerry_api_add_object_field](#jerry_api_add_object_field) -- [jerry_api_delete_object_field](#jerry_api_delete_object_field) -- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) -- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) -- [jerry_api_get_object_native_handle](#jerry_api_get_object_native_handle) -- [jerry_api_set_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** - -```c -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** - -```c -{ - 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_create_array_object](#jerry_api_create_array_object) - - -# jerry_api_get_array_index_value - -**Summary** - -Get value of an indexed element in the specified array object. - -**Prototype** - -```c -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** - -```c -{ - 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_array_object](#jerry_api_create_array_object) - - -# jerry_api_create_error - -**Summary** - -Create new JavaScript error object. -it should be throwed inside of handle attached to external function object. - -**Prototype** - -```c -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** - -```c -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_external_handler_t) -- [jerry_api_is_function](#jerry_api_is_function) -- [jerry_api_call_function](#jerry_api_call_function) -- [jerry_api_release_object](#jerry_api_release_object) -- [jerry_api_create_external_function](#jerry_api_create_external_function) - - -# jerry_register_external_magic_strings - -**Summary** - -Registers an external magic string array. - -**Prototype** - -```c -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' contents -- `count number` - of the strings -- `str_lengths` - lengths of the strings - -**Example** - -```c -{ - 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_init](#jerry_init) - - -# jerry_api_value_to_string - -**Summary** - -Creates the textual representation of an API value using the ToString ecma builtin operation. - -**Prototype** - -```c -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** - -```c -{ - 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](#jerry_api_foreach_object_field). - -**Definition** - -```c -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 field -- `field_value_p` - value of the field -- `user_data_p` - user data -- return value - - true, if the operation executed successfully - - false, otherwise - -**See also** - -- [jerry_api_foreach_object_field](#jerry_api_foreach_object_field) - - -# jerry_api_foreach_object_field - -**Summary** - -Applies the given function to every fields in the given objects. - -**Prototype** - -```c -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` - object -- `foreach_p` - foreach function, that will be apllied for each fields -- `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 - -**Example** - -```c -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** - -- [jerry_object_field_foreach_t](#jerry_object_field_foreach_t) diff --git a/04.internals.md b/04.INTERNALS.md similarity index 95% rename from 04.internals.md rename to 04.INTERNALS.md index 760751f8d..52f685279 100644 --- a/04.internals.md +++ b/04.INTERNALS.md @@ -10,7 +10,7 @@ permalink: /internals/ # High-Level Design ![High-Level Design]({{ site.baseurl }}/img/engines_high_level_design.png){: class="thumbnail center-block img-responsive" } -On the diagram above is shown interaction of major components of JerryScript: Parser and Virtual Machine (VM). Parser performs translation of input ECMAScript application into the byte-code with the specified format (refer to [Bytecode](#byte-code) and [Parser](#parser) page for details). Prepared bytecode is executed by the Virtual Machine that performs interpretation (refer to [Virtual Machine](#virtual-machine) and [ECMA](#ecma) pages for details). +The diagram above shows the interactions between the major components of JerryScript: Parser and Virtual Machine (VM). Parser performs translation of input ECMAScript application into the byte-code with the specified format (refer to [Bytecode](#byte-code) and [Parser](#parser) page for details). Prepared bytecode is executed by the Virtual Machine that performs interpretation (refer to [Virtual Machine](#virtual-machine) and [ECMA](#ecma) pages for details). # Parser @@ -134,7 +134,7 @@ Since most functions require less than 255 literal, small encoding provides a si ## Literal Store -JerryScript do not have a global string table for literals, but stores them into the Literal Store. During the parsing phase, when a new literal appears with the same identifier that already has occurred before, the string won't be stored once again, but the identifier in the Literal Store will be used. If a new literal is not in the Literal Store yet, it will be inserted. +JerryScript does not have a global string table for literals, but stores them into the Literal Store. During the parsing phase, when a new literal appears with the same identifier that has already occurred before, the string won't be stored once again, but the identifier in the Literal Store will be used. If a new literal is not in the Literal Store yet, it will be inserted. ## Byte-code Categories @@ -245,6 +245,7 @@ simple value is a pre-defined constant which can be: ### Compressed Pointers Compressed pointers were introduced to save heap space. + ![Compressed Pointer]({{ site.baseurl }}/img/ecma_compressed.png){: class="thumbnail center-block img-responsive" } These pointers are 8 byte alligned 16 bit long pointers which can address 512 Kb of memory which is also the maximum size of the JerryScript heap. @@ -283,6 +284,7 @@ The objects are represented as following structure: * type (function object, lexical environment, etc.) ### Properties of Objects + ![Object properties]({{ site.baseurl }}/img/ecma_object_property.png){: class="thumbnail center-block img-responsive" } Objects have a linked list that contains their properties. This list actually contains property pairs, in order to save memory described in the followings: @@ -314,7 +316,7 @@ Internal properties are special properties that carry meta-information that cann LCache is a hashmap for finding a property specified by an object and by a property name. The object-name-property layout of the LCache presents multiple times in a row as it is shown in the figure below. -![LCache]({{ site.baseurl }}/img/ecma_lcache.png){: class="thumbnail center-block img-responsive"} +![LCache]({{ site.baseurl }}/img/ecma_lcache.png){: class="thumbnail center-block img-responsive" } When a property access occurs, a hash value is extracted form the demanded property name and than this hash is used to index the LCache. After that, in the indexed row the specified object and property name will be searched. diff --git a/05.dev-guide.md b/05.dev-guide.md deleted file mode 100644 index d34a8a1c2..000000000 --- a/05.dev-guide.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -layout: page -title: Development -permalink: /dev-guide/ ---- - -* toc -{:toc} - -JerryScript Engine can be embedded into any application, providing the way to run JavaScript in a large range of environments - from desktops to low-memory microcontrollers. - -This guide is intended to introduce you to JerryScript embedding API through creation of simple JavaScript shell. - -## Step 1. Execute JavaScript from your application - -{% highlight cpp %} -#include -#include "jerry.h" - -int -main (int argc, char * argv[]) { - char script [] = "print ('Hello, World!');"; - - jerry_completion_code_t code = jerry_run_simple (script, - strlen (script), - JERRY_FLAG_EMPTY); -} -{% endhighlight %} - -The application will generate the following output: - -{% highlight bash %} -Hello, World! -{% endhighlight %} - -## Step 2. Split engine initialization and script execution - -Here we perform the same actions, as `jerry_run_simple`, while splitting into several steps: - -- engine initialization -- script code setup -- script execution -- engine cleanup - - -{% highlight cpp %} -#include -#include "jerry.h" - -int -main (int argc, char * argv[]) { - char script [] = "print ('Hello, World!');"; - - // Initialize engine - jerry_init (JERRY_FLAG_EMPTY); - - // Setup Global scope code - jerry_parse (script, strlen (script)); - - // Execute Global scope code - jerry_completion_code_t code = jerry_run (); - - // Cleanup engine - jerry_cleanup (); -} -{% endhighlight %} - -Our code is more complex now, but it introduces possibilities to interact with JerryScript step-by-step: setup native objects, call JavaScript functions, etc. - -## Step 3. Execution in 'eval'-mode - -{% highlight cpp %} -#include -#include "jerry.h" - -int -main (int argc, char * argv[]) { - char script1 [] = "var s = 'Hello, World!';"; - char script2 [] = "print (s);"; - - // Initialize engine - jerry_init (JERRY_FLAG_EMPTY); - - jerry_api_value_t eval_ret; - - // Evaluate script1 - jerry_api_eval (script1, strlen (script1), - false, false, &eval_ret); - // Free JavaScript value, returned by eval - jerry_api_release_value (&eval_ret); - - // Evaluate script2 - jerry_api_eval (script2, strlen (script2), - false, false, &eval_ret); - // Free JavaScript value, returned by eval - jerry_api_release_value (&eval_ret); - - // Cleanup engine - jerry_cleanup (); -} -{% endhighlight %} - -This way, we execute two independent script parts in one execution environment. The first part initializes string variable, and the second outputs the variable. - -## Step 4. Interaction with JavaScript environment - -{% highlight cpp %} -#include -#include "jerry.h" - -int -main (int argc, char * argv[]) { - char str [] = "Hello, World!"; - char var_name [] = "s"; - char script [] = "print (s);"; - - // Initializing JavaScript environment - jerry_init (JERRY_FLAG_EMPTY); - - // Getting pointer to the Global object - jerry_api_object_t *obj_p = jerry_api_get_global_object (); - - // Constructing string - jerry_api_string_t *str_val_p = jerry_api_create_string (str); - - // Constructing string value descriptor - jerry_api_value_t val; - val.type = JERRY_API_DATA_TYPE_STRING; - val.string_p = str_val_p; - - // Setting the string value to field of the Global object - jerry_api_set_object_field_value (obj_p, var_name, &val); - - // Releasing string value, as it is no longer necessary outside of engine - jerry_api_release_string (str_val_p); - - // Same for pointer to the Global object - jerry_api_release_object (obj_p); - - jerry_api_value_t eval_ret; - - // Now starting script that would output value of just initialized field - jerry_api_eval (script, strlen (script), - false, false, &eval_ret); - jerry_api_release_value (&eval_ret); - - // Freeing engine - jerry_cleanup (); -} -{% endhighlight %} - -The sample will also output 'Hello, World!'. However, now it is not just a part of the source script, but the value, dynamically supplied to the engine. - -## Step 5. Description of JavaScript value descriptors - -Structure, used to put values to or receive values from the engine is the following: - -- `type` of the value: - - JERRY_API_DATA_TYPE_UNDEFINED (undefined); - - JERRY_API_DATA_TYPE_NULL (null); - - JERRY_API_DATA_TYPE_BOOLEAN (true / false); - - JERRY_API_DATA_TYPE_FLOAT64 (number); - - JERRY_API_DATA_TYPE_STRING (string); - - JERRY_API_DATA_TYPE_OBJECT (object reference); -- `v_bool` (if JERRY_API_DATA_TYPE_BOOLEAN) - boolean value; -- `v_float64` (if JERRY_API_DATA_TYPE_FLOAT64) - number value; -- `v_string` (if JERRY_API_DATA_TYPE_STRING) - pointer to string; -- `v_object` (if JERRY_API_DATA_TYPE_OBJECT) - pointer to object. - -Abstract values, to be sent to or received from the engine are described with the structure. - -Pointers to strings or objects and values should be released just when become unnecessary, using `jerry_api_release_string` or `jerry_api_release_object` and `jerry_api_release_value`, correspondingly. - -The following example function will output a JavaScript value: - -{% highlight cpp %} -static void -print_value (const jerry_api_value_t * value_p) -{ - switch (value_p->type) - { - // Simple values: undefined, null, false, true - case JERRY_API_DATA_TYPE_UNDEFINED: - printf ("undefined"); - break; - case JERRY_API_DATA_TYPE_NULL: - printf ("null"); - break; - case JERRY_API_DATA_TYPE_BOOLEAN: - if (value_p->v_bool) - printf ("true"); - else - printf ("false"); - break; - - // Number value - case JERRY_API_DATA_TYPE_FLOAT64: - printf ("%lf", value_p->v_float64); - break; - - // String value - case JERRY_API_DATA_TYPE_STRING: - { - ssize_t neg_req_sz, sz; - // determining required buffer size - neg_req_sz = jerry_api_string_to_char_buffer (value_p->v_string, - NULL, - 0); - assert (neg_req_sz < 0); - char * str_buf_p = (char*) malloc (-neg_req_sz); - sz = jerry_api_string_to_char_buffer (value_p->v_string, - str_buf_p, - -neg_req_sz); - assert (sz == -neg_req_sz); - - printf ("%s", str_buf_p); - - free (str_buf_p); - break; - } - - // Object reference - case JERRY_API_DATA_TYPE_OBJECT: - printf ("[JS object]"); - break; - } - - printf ("\n"); -} -{% endhighlight %} - -## Simple JavaScript shell - -Now all building blocks, necessary to construct JavaScript shell, are ready. - -Shell operation can be described with the following loop: - -- read command; -- if command is 'quit' - - exit loop; -- else - - eval (command); - - print result of eval; - - loop. - -{% highlight cpp %} -#include -#include -#include -#include - -#include "jerry.h" - -static void -print_value (const jerry_api_value_t * value_p); - -int -main (int argc, char * argv[]) { - // Initialize engine - jerry_init (JERRY_FLAG_EMPTY); - - char cmd [256]; - while (true) { - printf ("> "); - - // Input next command - if (fgets (cmd, sizeof (cmd), stdin) == NULL - || strcmp (cmd, "quit\n") == 0) { - // If the command is 'quit', exit from loop - break; - } - - jerry_api_value_t ret_val; - - // Evaluate entered command - jerry_completion_code_t status = jerry_api_eval (cmd, strlen (cmd), - false, false, - &ret_val); - - // If command evaluated successfully, print value, returned by eval - if (status == JERRY_COMPLETION_CODE_OK) { - // 'eval' completed successfully - print_value (&ret_val); - jerry_api_release_value (&ret_val); - } else { - // evaluated JS code thrown an exception - // and didn't handle it with try-catch-finally - printf ("Unhandled JS exception occured\n"); - } - - printf ("\n"); - fflush (stdout); - } - - // Cleanup engine - jerry_cleanup (); - - return 0; -} -{% endhighlight %} - -The application inputs commands and evaluates them, one after another. - - -## Further steps - -For further API description, please look at [Embedding API](/API).