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

Update the webpage (#5127)

Browse Source 
The GitHub ribbon is also revived.

Related issue: #5125

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
This commit is contained in:
Zsolt Borbély
2024-02-07 06:07:21 +01:00
committed by GitHub
parent d0671c4ff1
commit 9192b862c9
14 changed files with 2732 additions and 3647 deletions
Download Patch File Download Diff File Expand all files Collapse all files
00.GETTING-STARTED.md
+6 -6
View File
@@ -21,11 +21,11 @@ Several scripts and tools help the building and development process, thus it is
- `bash` >= `4.3.11`
- `cppcheck` >= `1.61`
- `vera++` >= `1.2.1`
- `clang-format-10` >= `10.0.0`
- `python` >= `2.7.6`
```bash
sudo apt-get install gcc gcc-arm-none-eabi cmake cppcheck vera++ python
sudo apt-get install gcc gcc-arm-none-eabi cmake cppcheck clang-format-10 python
```
To make our scripts run correctly, several shell utilities should be available on the system:
@@ -61,10 +61,10 @@ tools/build.py --debug --logging=on --error-messages=on --line-info=on
python tools/build.py --cmake-param=CMAKE_PARAM
```
**Set a profile mode (ES.next, ES5.1, minimal)**
**Set a profile mode (es.next, minimal)**
```bash
python tools/build.py --profile=es.next|es5.1|minimal
python tools/build.py --profile=es.next|minimal
```
See also the related [README.md](https://github.com/jerryscript-project/jerryscript/blob/master/jerry-core/profiles/README.md).
@@ -183,10 +183,10 @@ python tools/run-tests.py --check-signed-off
python tools/run-tests.py --check-cppcheck
```
**To run vera check**
**To run format check**
```bash
python tools/run-tests.py --check-vera
python tools/run-tests.py --check-format
```
**To get a list of all the available test options**
01.CONFIGURATION.md
+5 -6
View File
@@ -54,7 +54,7 @@ that can be used by the debugger to identify the currently executed source conte
### Profiles
This option can be used to enable/disable available JavaScript language features by providing profile files. Profile files contain a list of C definitions that configure each individual feature.
The `path` value for CMake and Python arguments should be a file path to the profile file, or one of `es.next`, `es5.1`, or `minimal`, which are the pre-defined profiles.
The `path` value for CMake and Python arguments should be a file path to the profile file, or one of `es.next` or `minimal`, which are the pre-defined profiles.
To see how a profile file should be created, or what configuration options are available in C, see the profile [README](https://github.com/jerryscript-project/jerryscript/blob/master/jerry-core/profiles/README.md).
| Options | |
@@ -200,7 +200,7 @@ This option is enabled by default.
### Memory statistics
This option can be used to provide memory usage statistics either upon engine termination, or during runtime using the `jerry_get_memory_stats` jerry API function.
This option can be used to provide memory usage statistics either upon engine termination, or during runtime using the `jerry_heap_stats` jerry API function.
The feature can create a significant performance overhead, and should only be used for measurement purposes. This option is disabled by default.
| Options | |
@@ -309,7 +309,7 @@ in other projects. To achieve this, the following command can be executed to cre
into the `amalgam` directory:
```sh
$ python tools/amalgam.py --output-dir amalgam --jerry-core --jerry-port-default --jerry-math
$ python tools/amalgam.py --output-dir amalgam --jerry-core --jerry-port --jerry-math
```
(Note: In the example above, the command is executed from the project's root directory, but that is
@@ -320,8 +320,7 @@ The command creates the following files in the `amalgam` dir:
* `jerryscript.c`
* `jerryscript.h`
* `jerryscript-config.h`
* `jerryscript-port-default.c`
* `jerryscript-port-default.h`
* `jerryscript-port.c`
* `jerryscript-math.c`
* `math.h`
@@ -333,7 +332,7 @@ These files can be directly compiled with an application using the JerryScript A
E.g., using a command similar to the one below:
```sh
$ gcc -Wall -o demo_app demo_app.c amalgam/jerryscript.c amalgam/jerryscript-port-default.c amalgam/jerryscript-math.c -Iamalgam/
$ gcc -Wall -o demo_app demo_app.c amalgam/jerryscript.c amalgam/jerryscript-port.c amalgam/jerryscript-math.c -Iamalgam/
```
(Note: The headers must be available on the include path.)
02.API-REFERENCE.md
+2256 -2835
View File
File diff suppressed because it is too large Load Diff
03.API-EXAMPLE.md
+142 -175
View File
@@ -42,40 +42,7 @@ $ export PKG_CONFIG_PATH=$(pwd)/example_install/lib/pkgconfig/
Test if the `pkg-config` works for JerryScript:
```sh
$ pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-ext libjerry-math
```
## Example 1. Execute JavaScript from your application
The most basic example to test the engine is to create an `api-example-1.c` file containing the following code:
[doctest]: # ()
```c
#include "jerryscript.h"
int
main (void)
{
const jerry_char_t script[] = "var str = 'Hello, World!';";
bool ret_value = jerry_run_simple (script, sizeof (script) - 1, JERRY_INIT_EMPTY);
return (ret_value ? 0 : 1);
}
```
To compile it one can use the following command:
```sh
$ gcc api-example-1.c -o api-example-1 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math)
```
If everything is correct the application returns with a zero exit code:
```
$ ./api-example-1
$ echo $?
$ pkg-config --cflags --libs libjerry-core libjerry-port libjerry-ext libjerry-math
```
## Example 2. Split engine initialization and script execution.
@@ -83,9 +50,9 @@ $ echo $?
In this example the engine is initialized directly with the `jerry_init` method
and cleaned up with the `jerry_cleanup` method. The example JavaScript code
is directly parsed and executed via the `jerry_eval` method. Each `jerry_value_t`
returned by the API methods is freed with the `jerry_release_value` method.
returned by the API methods is freed with the `jerry_value_free` method.
To make sure that the code parsing and execution was ok, the `jerry_value_is_error`
To make sure that the code parsing and execution was ok, the `jerry_value_is_exception`
method is used to check for any errors.
Use the following code for the `api-example-2.c` file:
@@ -113,10 +80,10 @@ main (void)
JERRY_PARSE_NO_OPTS);
/* Check if there was any error (syntax or runtime) */
bool run_ok = !jerry_value_is_error (eval_ret);
bool run_ok = !jerry_value_is_exception (eval_ret);
/* Parsed source code must be freed */
jerry_release_value (eval_ret);
jerry_value_free (eval_ret);
/* Cleanup engine */
jerry_cleanup ();
@@ -128,7 +95,7 @@ main (void)
To compile it one can use the following command:
```sh
$ gcc api-example-2.c -o api-example-2 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math)
$ gcc api-example-2.c -o api-example-2 $(pkg-config --cflags --libs libjerry-core libjerry-port libjerry-math)
```
If everything is correct the application returns with a zero exit code:
@@ -166,20 +133,20 @@ main (void)
jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL);
/* Check if there is any JS code parse error */
if (!jerry_value_is_error (parsed_code))
if (!jerry_value_is_exception (parsed_code))
{
/* Execute the parsed source code in the Global scope */
jerry_value_t ret_value = jerry_run (parsed_code);
/* Check the execution return value if there is any error */
run_ok = !jerry_value_is_error (ret_value);
run_ok = !jerry_value_is_exception (ret_value);
/* Returned value must be freed */
jerry_release_value (ret_value);
jerry_value_free (ret_value);
}
/* Parsed source code must be freed */
jerry_release_value (parsed_code);
jerry_value_free (parsed_code);
/* Cleanup engine */
jerry_cleanup ();
@@ -191,7 +158,7 @@ main (void)
To compile it one can use the following command:
```sh
$ gcc api-example-3.c -o api-example-3 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math)
$ gcc api-example-3.c -o api-example-3 $(pkg-config --cflags --libs libjerry-core libjerry-port libjerry-math)
```
If everything is correct the application returns with a zero exit code:
@@ -210,10 +177,10 @@ In this example a very simple "print" method is added which prints out a static
This method will be implemented in C and will be called from the JavaScript code.
For this a few extra API methods are required:
- `jerry_get_global_object`
- `jerry_create_string`
- `jerry_set_property`
- `jerry_create_external_function`
- `jerry_current_realm`
- `jerry_string_sz`
- `jerry_object_set`
- `jerry_function_external`
The `api-example-4.c` file should contain the following code:
@@ -233,7 +200,7 @@ print_handler (const jerry_call_info_t *call_info_p,
printf ("Print handler was called\n");
/* Return an "undefined" value to the JavaScript engine */
return jerry_create_undefined ();
return jerry_undefined ();
}
int
@@ -248,40 +215,40 @@ main (void)
/* Add the "print" method for the JavaScript global object */
{
/* Get the "global" object */
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t global_object = jerry_current_realm ();
/* Create a "print" JS string */
jerry_value_t property_name_print = jerry_create_string ((const jerry_char_t *) "print");
jerry_value_t property_name_print = jerry_string_sz ("print");
/* Create a function from a native C method (this function will be called from JS) */
jerry_value_t property_value_func = jerry_create_external_function (print_handler);
jerry_value_t property_value_func = jerry_function_external (print_handler);
/* Add the "print" property with the function value to the "global" object */
jerry_value_t set_result = jerry_set_property (global_object, property_name_print, property_value_func);
jerry_value_t set_result = jerry_object_set (global_object, property_name_print, property_value_func);
/* Check if there was no error when adding the property (in this case it should never happen) */
if (jerry_value_is_error (set_result)) {
if (jerry_value_is_exception (set_result)) {
printf ("Failed to add the 'print' property\n");
}
/* Release all jerry_value_t-s */
jerry_release_value (set_result);
jerry_release_value (property_value_func);
jerry_release_value (property_name_print);
jerry_release_value (global_object);
jerry_value_free (set_result);
jerry_value_free (property_value_func);
jerry_value_free (property_name_print);
jerry_value_free (global_object);
}
/* Setup Global scope code */
jerry_value_t parsed_code = jerry_parse (script, script_size, NULL);
if (!jerry_value_is_error (parsed_code))
if (!jerry_value_is_exception (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);
jerry_value_free (ret_value);
}
/* Parsed source code must be freed */
jerry_release_value (parsed_code);
jerry_value_free (parsed_code);
/* Cleanup engine */
jerry_cleanup ();
@@ -294,7 +261,7 @@ main (void)
To compile it one can use the following command:
```sh
$ gcc api-example-4.c -o api-example-4 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math)
$ gcc api-example-4.c -o api-example-4 $(pkg-config --cflags --libs libjerry-core libjerry-port libjerry-math)
```
If everything is correct the application should print out the message present in the `print_handler` method:
@@ -314,7 +281,7 @@ argument (which probably comes from a JavaScript source) to a JS string and prin
New API methods used:
- `jerry_value_to_string`
- `jerry_string_to_utf8_char_buffer`
- `jerry_string_to_buffer`
The `api-example-5.c` file should contain the following code:
@@ -342,17 +309,17 @@ print_handler (const jerry_call_info_t *call_info_p,
* Please note that if the string does not fit into the buffer nothing will be copied.
* More details on the API reference page
*/
jerry_size_t copied_bytes = jerry_string_to_utf8_char_buffer (string_value, buffer, sizeof (buffer) - 1);
jerry_size_t copied_bytes = jerry_string_to_buffer (string_value, JERRY_ENCODING_UTF8, buffer, sizeof (buffer) - 1);
buffer[copied_bytes] = '\0';
/* Release the "toString" result */
jerry_release_value (string_value);
jerry_value_free (string_value);
printf ("%s\n", (const char *)buffer);
}
/* Return an "undefined" value to the JavaScript engine */
return jerry_create_undefined ();
return jerry_undefined ();
}
int
@@ -367,40 +334,40 @@ main (void)
/* Add the "print" method for the JavaScript global object */
{
/* Get the "global" object */
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t global_object = jerry_current_realm ();
/* Create a "print" JS string */
jerry_value_t property_name_print = jerry_create_string ((const jerry_char_t *) "print");
jerry_value_t property_name_print = jerry_string_sz ("print");
/* Create a function from a native C method (this function will be called from JS) */
jerry_value_t property_value_func = jerry_create_external_function (print_handler);
jerry_value_t property_value_func = jerry_function_external (print_handler);
/* Add the "print" property with the function value to the "global" object */
jerry_value_t set_result = jerry_set_property (global_object, property_name_print, property_value_func);
jerry_value_t set_result = jerry_object_set (global_object, property_name_print, property_value_func);
/* Check if there was no error when adding the property (in this case it should never happen) */
if (jerry_value_is_error (set_result)) {
if (jerry_value_is_exception (set_result)) {
printf ("Failed to add the 'print' property\n");
}
/* Release all jerry_value_t-s */
jerry_release_value (set_result);
jerry_release_value (property_value_func);
jerry_release_value (property_name_print);
jerry_release_value (global_object);
jerry_value_free (set_result);
jerry_value_free (property_value_func);
jerry_value_free (property_name_print);
jerry_value_free (global_object);
}
/* Setup Global scope code */
jerry_value_t parsed_code = jerry_parse (script, script_size, NULL);
if (!jerry_value_is_error (parsed_code))
if (!jerry_value_is_exception (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);
jerry_value_free (ret_value);
}
/* Parsed source code must be freed */
jerry_release_value (parsed_code);
jerry_value_free (parsed_code);
/* Cleanup engine */
jerry_cleanup ();
@@ -413,7 +380,7 @@ main (void)
To compile it one can use the following command:
```sh
$ gcc api-example-5.c -o api-example-5 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math)
$ gcc api-example-5.c -o api-example-5 $(pkg-config --cflags --libs libjerry-core libjerry-port libjerry-math)
```
If everything is correct the application should print out the string passed for the `print` method in the JS code:
@@ -431,14 +398,14 @@ can be used by other applications.
In this example the following extension methods are used:
- `jerryx_handler_register_global`
- `jerryx_register_global`
- `jerryx_handler_print`
In further examples this "print" handler will be used.
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
int
main (void)
@@ -450,23 +417,22 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
/* Register 'print' function from the extensions to the global object */
jerryx_handler_register_global ((const jerry_char_t *) "print",
jerryx_handler_print);
jerryx_register_global ("print", jerryx_handler_print);
/* Setup Global scope code */
jerry_value_t parsed_code = jerry_parse (script, script_size, NULL);
if (!jerry_value_is_error (parsed_code))
if (!jerry_value_is_exception (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);
jerry_value_free (ret_value);
}
/* Parsed source code must be freed */
jerry_release_value (parsed_code);
jerry_value_free (parsed_code);
/* Cleanup engine */
jerry_cleanup ();
@@ -478,10 +444,10 @@ main (void)
To compile it one can use the following command:
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call.
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port` entry for the `pkg-config` call.
```sh
$ gcc api-example-6.c -o api-example-6 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math)
$ gcc api-example-6.c -o api-example-6 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port libjerry-math)
```
If everything is correct the application should print out the string passed for the `print` method in the JS code:
@@ -500,8 +466,10 @@ Use the following code as the `api-example-7.c` file:
[doctest]: # ()
```c
#include <stdio.h>
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
#include "jerryscript-ext/properties.h"
int
main (void)
@@ -512,30 +480,29 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
/* Register 'print' function from the extensions */
jerryx_handler_register_global ((const jerry_char_t *) "print",
jerryx_handler_print);
jerryx_register_global ("print", jerryx_handler_print);
/* Getting pointer to the Global object */
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t global_object = jerry_current_realm ();
/* Constructing strings */
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_var");
jerry_value_t prop_value = jerry_create_string ((const jerry_char_t *) "Hello from C!");
jerry_value_t prop_name = jerry_string_sz ("my_var");
jerry_value_t prop_value = jerry_string_sz ("Hello from C!");
/* Setting the string value as a property of the Global object */
jerry_value_t set_result = jerry_set_property (global_object, prop_name, prop_value);
jerry_value_t set_result = jerry_object_set (global_object, prop_name, prop_value);
/* The 'set_result' should be checked if there was any error */
if (jerry_value_is_error (set_result)) {
if (jerry_value_is_exception (set_result)) {
printf ("Failed to add the 'my_var' property\n");
}
jerry_release_value (set_result);
jerry_value_free (set_result);
/* Releasing string values, as it is no longer necessary outside of engine */
jerry_release_value (prop_name);
jerry_release_value (prop_value);
jerry_value_free (prop_name);
jerry_value_free (prop_value);
/* Releasing the Global object */
jerry_release_value (global_object);
jerry_value_free (global_object);
/* Now starting script that would output value of just initialized field */
jerry_value_t eval_ret = jerry_eval (script,
@@ -543,7 +510,7 @@ main (void)
JERRY_PARSE_NO_OPTS);
/* Free JavaScript value, returned by eval */
jerry_release_value (eval_ret);
jerry_value_free (eval_ret);
/* Freeing engine */
jerry_cleanup ();
@@ -554,10 +521,10 @@ main (void)
To compile it one can use the following command:
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call.
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port` entry for the `pkg-config` call.
```sh
$ gcc api-example-7.c -o api-example-7 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math)
$ gcc api-example-7.c -o api-example-7 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port libjerry-math)
```
The sample will output 'Hello from C!'. However, now it is not just a part of the source script, but the value, dynamically supplied to the engine:
@@ -571,9 +538,9 @@ $ ./api-example-7
JerryScript value can be a boolean, number, null, object, string, undefined or some special type of objects (arraybuffer, symbols, etc).
There is a special "error" value which wraps another value. This "error" can be created by throwing a JavaScript value from JS code
or via API method(s). It is advised to check for this error with the `jerry_value_is_error` method as not all API methods
can process error values. To extract the value from the "error" the API method `jerry_get_value_from_error` should be used.
If an error object is created via API method (for example with `jerry_create_error`) the "error" value is automatically created.
or via API method(s). It is advised to check for this error with the `jerry_value_is_exception` method as not all API methods
can process error values. To extract the value from the "error" the API method `jerry_exception_value` should be used.
If an error object is created via API method (for example with `jerry_error`) the "error" value is automatically created.
Notice the difference between error value and error object:
- The error object is a object which was constructed via one of the `Error` objects (available from the global object or from API).
@@ -590,7 +557,7 @@ var error_object = new Error ("error message");
throw "message";
```
To check what type a given `jerry_value_t` is the `jerry_value_is_*` methods or the `jerry_value_get_type` could be used.
To check what type a given `jerry_value_t` is the `jerry_value_is_*` methods or the `jerry_value_type` could be used.
For example the following code snippet could print out a few types (not all types are checked):
[doctest]: # (test="compile")
@@ -605,14 +572,14 @@ print_value (const jerry_value_t jsvalue)
{
jerry_value_t value;
/* If there is an error extract the object from it */
if (jerry_value_is_error (jsvalue))
if (jerry_value_is_exception (jsvalue))
{
printf ("Error value detected: ");
value = jerry_get_value_from_error (jsvalue, false);
value = jerry_exception_value (jsvalue, false);
}
else
{
value = jerry_acquire_value (jsvalue);
value = jerry_value_copy (jsvalue);
}
if (jerry_value_is_undefined (value))
@@ -637,7 +604,7 @@ print_value (const jerry_value_t jsvalue)
/* Float value */
else if (jerry_value_is_number (value))
{
printf ("number: %lf", jerry_get_number_value (value));
printf ("number: %lf", jerry_value_as_number (value));
}
/* String value */
else if (jerry_value_is_string (value))
@@ -645,11 +612,11 @@ print_value (const jerry_value_t jsvalue)
jerry_char_t str_buf_p[256];
/* Determining required buffer size */
jerry_size_t req_sz = jerry_get_string_size (value);
jerry_size_t req_sz = jerry_string_size (value, JERRY_ENCODING_CESU8);
if (req_sz <= 255)
{
jerry_string_to_char_buffer (value, str_buf_p, req_sz);
jerry_string_to_buffer (value, JERRY_ENCODING_CESU8, str_buf_p, req_sz);
str_buf_p[req_sz] = '\0';
printf ("%s", (const char *) str_buf_p);
}
@@ -665,7 +632,7 @@ print_value (const jerry_value_t jsvalue)
}
printf ("\n");
jerry_release_value (value);
jerry_value_free (value);
}
```
@@ -692,21 +659,22 @@ See the following `api-example-8-shell.c` file:
#include <stdlib.h>
#include <string.h>
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
#include "jerryscript-ext/properties.h"
static void
print_value (const jerry_value_t jsvalue)
{
jerry_value_t value;
/* If there is an error extract the object from it */
if (jerry_value_is_error (jsvalue))
if (jerry_value_is_exception (jsvalue))
{
printf ("Error value detected: ");
value = jerry_get_value_from_error (jsvalue, false);
value = jerry_exception_value (jsvalue, false);
}
else
{
value = jerry_acquire_value (jsvalue);
value = jerry_value_copy (jsvalue);
}
if (jerry_value_is_undefined (value))
@@ -731,7 +699,7 @@ print_value (const jerry_value_t jsvalue)
/* Float value */
else if (jerry_value_is_number (value))
{
printf ("number: %lf", jerry_get_number_value (value));
printf ("number: %lf", jerry_value_as_number (value));
}
/* String value */
else if (jerry_value_is_string (value))
@@ -739,11 +707,11 @@ print_value (const jerry_value_t jsvalue)
jerry_char_t str_buf_p[256];
/* Determining required buffer size */
jerry_size_t req_sz = jerry_get_string_size (value);
jerry_size_t req_sz = jerry_string_size (value, JERRY_ENCODING_CESU8);
if (req_sz <= 255)
{
jerry_string_to_char_buffer (value, str_buf_p, req_sz);
jerry_string_to_buffer (value, JERRY_ENCODING_CESU8, str_buf_p, req_sz);
str_buf_p[req_sz] = '\0';
printf ("%s", (const char *) str_buf_p);
}
@@ -759,7 +727,7 @@ print_value (const jerry_value_t jsvalue)
}
printf ("\n");
jerry_release_value (value);
jerry_value_free (value);
}
int
@@ -771,8 +739,7 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
/* Register 'print' function from the extensions */
jerryx_handler_register_global ((const jerry_char_t *) "print",
jerryx_handler_print);
jerryx_register_global ("print", jerryx_handler_print);
while (!is_done)
{
@@ -815,7 +782,7 @@ main (void)
/* Print out the value */
print_value (ret_val);
jerry_release_value (ret_val);
jerry_value_free (ret_val);
}
/* Cleanup engine */
@@ -827,10 +794,10 @@ main (void)
To compile it one can use the following command:
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call.
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port` entry for the `pkg-config` call.
```sh
$ gcc api-example-8-shell.c -o api-example-8-shell $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math)
$ gcc api-example-8-shell.c -o api-example-8-shell $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port libjerry-math)
```
The application reads lines from standard input and evaluates them, one after another. To try out run:
@@ -848,7 +815,8 @@ In this example (`api-example-9.c`) an object with a native function is added to
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
#include "jerryscript-ext/properties.h"
struct my_struct
{
@@ -863,7 +831,7 @@ get_msg_handler (const jerry_call_info_t *call_info_p, /**< call information */
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);
return jerry_string_sz (my_struct.msg);
} /* get_msg_handler */
int
@@ -873,33 +841,32 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
/* Register 'print' function from the extensions */
jerryx_handler_register_global ((const jerry_char_t *) "print",
jerryx_handler_print);
jerryx_register_global ("print", jerryx_handler_print);
/* Do something with the native object */
my_struct.msg = "Hello, World!";
/* Create an empty JS object */
jerry_value_t object = jerry_create_object ();
jerry_value_t object = jerry_object ();
/* Create a JS function object and wrap into a jerry value */
jerry_value_t func_obj = jerry_create_external_function (get_msg_handler);
jerry_value_t func_obj = jerry_function_external (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_release_value (jerry_set_property (object, prop_name, func_obj));
jerry_release_value (prop_name);
jerry_release_value (func_obj);
jerry_value_t prop_name = jerry_string_sz ("myFunc");
jerry_value_free (jerry_object_set (object, prop_name, func_obj));
jerry_value_free (prop_name);
jerry_value_free (func_obj);
/* Wrap the JS object (not empty anymore) into a jerry api value */
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t global_object = jerry_current_realm ();
/* Add the JS object to the global context */
prop_name = jerry_create_string ((const jerry_char_t *) "MyObject");
jerry_release_value (jerry_set_property (global_object, prop_name, object));
jerry_release_value (prop_name);
jerry_release_value (object);
jerry_release_value (global_object);
prop_name = jerry_string_sz ("MyObject");
jerry_value_free (jerry_object_set (global_object, prop_name, object));
jerry_value_free (prop_name);
jerry_value_free (object);
jerry_value_free (global_object);
/* Now we have a "builtin" object called MyObject with a function called myFunc()
*
@@ -915,7 +882,7 @@ main (void)
jerry_value_t eval_ret = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
/* Free JavaScript value, returned by eval */
jerry_release_value (eval_ret);
jerry_value_free (eval_ret);
/* Cleanup engine */
jerry_cleanup ();
@@ -926,10 +893,10 @@ main (void)
To compile it one can use the following command:
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call.
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port` entry for the `pkg-config` call.
```sh
$ gcc api-example-9.c -o api-example-9 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math)
$ gcc api-example-9.c -o api-example-9 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port libjerry-math)
```
Execute the example with:
@@ -956,7 +923,8 @@ Use the following code for `api-example-10.c`:
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
#include "jerryscript-ext/properties.h"
/**
* Add param to 'this.x'
@@ -970,27 +938,27 @@ add_handler (const jerry_call_info_t *call_info_p, /**< call information */
/* Note: that the argument count check is ignored for the example's case */
/* Get 'this.x' */
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "x");
jerry_value_t x_val = jerry_get_property (call_info_p->this_value, prop_name);
jerry_value_t prop_name = jerry_string_sz ("x");
jerry_value_t x_val = jerry_object_get (call_info_p->this_value, prop_name);
if (!jerry_value_is_error (x_val))
if (!jerry_value_is_exception (x_val))
{
/* Convert Jerry API values to double */
double x = jerry_get_number_value (x_val);
double d = jerry_get_number_value (args_p[0]);
double x = jerry_value_as_number (x_val);
double d = jerry_value_as_number (args_p[0]);
/* Add the parameter to 'x' */
jerry_value_t res_val = jerry_create_number (x + d);
jerry_value_t res_val = jerry_number (x + d);
/* Set the new value of 'this.x' */
jerry_release_value (jerry_set_property (call_info_p->this_value, prop_name, res_val));
jerry_release_value (res_val);
jerry_value_free (jerry_object_set (call_info_p->this_value, prop_name, res_val));
jerry_value_free (res_val);
}
jerry_release_value (x_val);
jerry_release_value (prop_name);
jerry_value_free (x_val);
jerry_value_free (prop_name);
return jerry_create_undefined ();
return jerry_undefined ();
} /* add_handler */
int
@@ -1000,8 +968,7 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
/* Register 'print' function from the extensions */
jerryx_handler_register_global ((const jerry_char_t *) "print",
jerryx_handler_print);
jerryx_register_global ("print", jerryx_handler_print);
/* Create a JS object */
const jerry_char_t my_js_object[] = " \
@@ -1023,16 +990,16 @@ main (void)
JERRY_PARSE_NO_OPTS);
/* Create a JS function object and wrap into a jerry value */
jerry_value_t add_func_obj = jerry_create_external_function (add_handler);
jerry_value_t add_func_obj = jerry_function_external (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_release_value (jerry_set_property (my_js_obj_val, prop_name, add_func_obj));
jerry_release_value (add_func_obj);
jerry_release_value (prop_name);
jerry_value_t prop_name = jerry_string_sz ("add2x");
jerry_value_free (jerry_object_set (my_js_obj_val, prop_name, add_func_obj));
jerry_value_free (add_func_obj);
jerry_value_free (prop_name);
/* Free JavaScript value, returned by eval (my_js_object) */
jerry_release_value (my_js_obj_val);
jerry_value_free (my_js_obj_val);
const jerry_char_t script[] = " \
var str = MyObject.foo (); \
@@ -1045,7 +1012,7 @@ main (void)
jerry_value_t eval_ret = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
/* Free JavaScript value, returned by eval */
jerry_release_value (eval_ret);
jerry_value_free (eval_ret);
/* Cleanup engine */
jerry_cleanup ();
@@ -1056,10 +1023,10 @@ main (void)
To compile it one can use the following command:
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call.
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port` entry for the `pkg-config` call.
```sh
$ gcc api-example-10.c -o api-example-10 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math)
$ gcc api-example-10.c -o api-example-10 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port libjerry-math)
```
Execute the example with:
@@ -1076,7 +1043,7 @@ Value of x is 17
## Example 11. Changing the seed of pseudorandom generated numbers
If you want to change the seed of `Math.random()` generated numbers, you have to initialize the seed value with `srand`.
A recommended method is using `jerry_port_get_current_time()` or something based on a constantly changing value, therefore every run produces truly random numbers.
A recommended method is using `jerry_port_current_time()` or something based on a constantly changing value, therefore every run produces truly random numbers.
[doctest]: # ()
@@ -1084,13 +1051,14 @@ A recommended method is using `jerry_port_get_current_time()` or something based
#include <stdlib.h>
#include "jerryscript.h"
#include "jerryscript-port.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
#include "jerryscript-ext/properties.h"
int
main (void)
{
/* Initialize srand value */
union { double d; unsigned u; } now = { .d = jerry_port_get_current_time () };
union { double d; unsigned u; } now = { .d = jerry_port_current_time () };
srand (now.u);
/* Generate a random number, and print it */
@@ -1100,14 +1068,13 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
/* Register the print function */
jerryx_handler_register_global ((const jerry_char_t *) "print",
jerryx_handler_print);
jerryx_register_global ("print", jerryx_handler_print);
/* Evaluate the script */
jerry_value_t eval_ret = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
/* Free the JavaScript value returned by eval */
jerry_release_value (eval_ret);
jerry_value_free (eval_ret);
/* Cleanup the engine */
jerry_cleanup ();
05.PORT-API.md
+210 -319
View File
@@ -10,7 +10,7 @@ permalink: /port-api/
# Reference
## Termination
## Process management
It is questionable whether a library should be able to terminate an application. Any API function can signal an error (ex.: cannot allocate memory), so the engine use the termination approach with this port function.
@@ -34,202 +34,14 @@ Error codes
```c
typedef enum
{
ERR_OUT_OF_MEMORY = 10,
ERR_REF_COUNT_LIMIT = 12,
ERR_DISABLED_BYTE_CODE = 13,
ERR_FAILED_INTERNAL_ASSERTION = 120
JERRY_FATAL_OUT_OF_MEMORY = 10,
JERRY_FATAL_REF_COUNT_LIMIT = 12,
JERRY_FATAL_DISABLED_BYTE_CODE = 13,
JERRY_FATAL_UNTERMINATED_GC_LOOPS = 14,
JERRY_FATAL_FAILED_ASSERTION = 120
} jerry_fatal_code_t;
```
## I/O
These are the only I/O functions jerry calls.
```c
/**
* Jerry log levels. The levels are in severity order
* where the most serious levels come first.
*/
typedef enum
{
JERRY_LOG_LEVEL_ERROR, /**< the engine will terminate after the message is printed */
JERRY_LOG_LEVEL_WARNING, /**< a request is aborted, but the engine continues its operation */
JERRY_LOG_LEVEL_DEBUG, /**< debug messages from the engine, low volume */
JERRY_LOG_LEVEL_TRACE /**< detailed info about engine internals, potentially high volume */
} jerry_log_level_t;
/**
* Display or log a debug/error message, and sends it to the debugger client as well.
* The function should implement a printf-like interface, where the first argument
* specifies the log level and the second argument specifies a format string on how
* to stringify the rest of the parameter list.
*
* This function is only called with messages coming from the jerry engine as
* the result of some abnormal operation or describing its internal operations
* (e.g., data structure dumps or tracing info).
*
* It should be the port that decides whether error and debug messages are logged to
* the console, or saved to a database or to a file.
*
* Example: a libc-based port may implement this with vfprintf(stderr) or
* vfprintf(logfile), or both, depending on log level.
*
* Note:
* This port function is called by jerry-core when JERRY_LOGGING is
* enabled. It is also common practice though to use this function in
* application code.
*/
void jerry_port_log (jerry_log_level_t level, const char *fmt, ...);
```
The `jerry_port_print_char` is currently not used by the jerry-core directly.
However, it provides a port specific way for `jerry-ext` components to print
information.
```c
/**
* Print a character to stdout.
*/
void jerry_port_print_char (char c);
```
### Jerry Module system
The port API provides optional functions that can be used by the
user application to resolve modules. If no callback is provided
to `jerry_module_link`, the `jerry_port_module_resolve` function
is used for resolving modules.
```c
/**
* Opens file with the given path and reads its source.
* @return the source of the file
*/
uint8_t *
jerry_port_read_source (const char *file_name_p, /**< file name */
size_t *out_size_p) /**< [out] read bytes */
{
// open file from given path
// return its source
} /* jerry_port_read_source */
/**
* Release the previously opened file's content.
*/
void
jerry_port_release_source (uint8_t *buffer_p) /**< buffer to free */
{
free (buffer_p);
} /* jerry_port_release_source */
/**
* Default module resolver.
*
* @return a module object if resolving is successful, an error otherwise
*/
jerry_value_t
jerry_port_module_resolve (const jerry_value_t specifier, /**< module specifier string */
const jerry_value_t referrer, /**< parent module */
void *user_p) /**< user data */
{
// Resolves a module using the specifier string. If a referrer is a module,
// and specifier is a relative path, the base path should be the directory
// part extracted from the path of the referrer module.
// The callback function of jerry_module_link may call this function
// if it cannot resolve a module. Furthermore if the callback is NULL,
// this function is used for resolving modules.
// The default implementation only resolves ECMAScript modules, and does
// not (currently) use the user data.
} /* jerry_port_module_resolve */
/**
* Release known modules.
*/
void
jerry_port_module_release (const jerry_value_t realm) /**< if this argument is object, release only those modules,
* which realm value is equal to this argument. */
{
// This function releases the known modules, forcing their reload
// when resolved again later. The released modules can be filtered
// by realms. This function is only called by user applications.
} /* jerry_port_module_release */
```
## Date
```c
/**
* Get local time zone adjustment, in milliseconds, for the given timestamp.
* The timestamp can be specified in either UTC or local time, depending on
* the value of is_utc. Adding the value returned from this function to
* a timestamp in UTC time should result in local time for the current time
* zone, and subtracting it from a timestamp in local time should result in
* UTC time.
*
* Ideally, this function should satisfy the stipulations applied to LocalTZA
* in section 20.3.1.7 of the ECMAScript version 9.0 spec.
*
* See Also:
* ECMA-262 v9, 20.3.1.7
*
* Note:
* This port function is called by jerry-core when
* JERRY_BUILTIN_DATE is set to 1. Otherwise this function is
* not used.
*
* @param unix_ms The unix timestamp we want an offset for, given in
* millisecond precision (could be now, in the future,
* or in the past). As with all unix timestamps, 0 refers to
* 1970-01-01, a day is exactly 86 400 000 milliseconds, and
* leap seconds cause the same second to occur twice.
* @param is_utc Is the given timestamp in UTC time? If false, it is in local
* time.
*
* @return milliseconds between local time and UTC for the given timestamp,
* if available
*. 0 if not available / we are in UTC.
*/
double jerry_port_get_local_time_zone_adjustment (double unix_ms, bool is_utc);
/**
* Get system time
*
* Note:
* This port function is called by jerry-core when
* JERRY_BUILTIN_DATE is set to 1. It is also common practice
* in application code to use this function for the initialization of the
* random number generator.
*
* @return milliseconds since Unix epoch
*/
double jerry_port_get_current_time (void);
```
## External context
Allow user to provide external buffer for isolated engine contexts, so that user
can configure the heap size at runtime and run multiple JS applications
simultaneously.
```c
/**
* Get the current context of the engine. Each port should provide its own
* implementation of this interface.
*
* Note:
* This port function is called by jerry-core when
* JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not
* used.
*
* @return the pointer to the engine context.
*/
struct jerry_context_t *jerry_port_get_current_context (void);
```
## Sleep
```c
/**
* Makes the process sleep for a given time.
@@ -243,158 +55,237 @@ struct jerry_context_t *jerry_port_get_current_context (void);
void jerry_port_sleep (uint32_t sleep_time);
```
# How to port JerryScript
## External context
This section describes a basic port implementation which was created for Unix based systems.
## Termination
Allows the user to provide external buffer for isolated engine contexts, so that user
can configure the heap size at runtime and run multiple JS applications
simultaneously.
```c
#include <stdlib.h>
#include "jerryscript-port.h"
/**
* Default implementation of jerry_port_fatal.
* Allocate a new context for the engine.
*
* This port function is called by jerry_init when JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not
* used. The engine will pass the size required for the context structure. An implementation must make sure to
* allocate at least this amount.
*
* Excess allocated space will be used as the engine heap when jerryscript is configured to use it's internal allocator,
* this can be used to control the internal heap size.
*
* NOTE: The allocated memory must be pointer-aligned, otherwise the behavior is
* undefined.
*
* @param context_size: the size of the internal context structure
*
* @return total size of the allocated buffer
*/
void jerry_port_fatal (jerry_fatal_code_t code)
{
exit (code);
} /* jerry_port_fatal */
size_t jerry_port_context_alloc (size_t context_size);
```
```c
/**
* Get the currently active context of the engine.
*
* This port function is called by jerry-core when JERRY_EXTERNAL_CONTEXT is enabled.
* Otherwise this function is not used.
*
* @return the pointer to the currently used engine context.
*/
struct jerry_context_t *jerry_port_context_get (void);
```
```c
/**
* Free the currently used context.
*
* This port function is called by jerry_cleanup when JERRY_EXTERNAL_CONTEXT is enabled.
* Otherwise this function is not used.
*
* @return the pointer to the engine context.
*/
void jerry_port_context_free (void);
```
## I/O
```c
#include <stdarg.h>
#include "jerryscript-port.h"
/**
* Provide log message implementation for the engine.
* Display or log a debug/error message.
*
* Note:
* This example ignores the log level.
* The message is passed as a zero-terminated string. Messages may be logged in parts, which
* will result in multiple calls to this functions. The implementation should consider
* this before appending or prepending strings to the argument.
*
* This function is called with messages coming from the jerry engine as
* the result of some abnormal operation or describing its internal operations
* (e.g., data structure dumps or tracing info).
*
* The implementation can decide whether error and debug messages are logged to
* the console, or saved to a database or to a file.
*/
void
jerry_port_log (jerry_log_level_t level, /**< log level */
const char *format, /**< format string */
...) /**< parameters */
{
va_list args;
va_start (args, format);
vfprintf (stderr, format, args);
va_end (args);
} /* jerry_port_log */
void jerry_port_log (const char *message_p);
```
```c
/**
* Print a character to stdout with putchar.
* Print a single character to standard output.
*
* This port function is never called from jerry-core directly, it is only used by jerry-ext components to print
* information.
*
* @param byte: the byte to print.
*/
void
jerry_port_print_char (char c)
{
putchar (c);
} /* jerry_port_print_char */
void jerry_port_print_byte (jerry_char_t byte);
```
```c
/**
* Print a buffer to standard output
*
* This port function is never called from jerry-core directly, it is only used by jerry-ext components to print
* information.
*
* @param buffer_p: input buffer
* @param buffer_size: data size
*/
void jerry_port_print_buffer (const jerry_char_t *buffer_p, jerry_size_t buffer_size);
```
```c
/**
* Read a line from standard input.
*
* The implementation should allocate storage necessary for the string. The result string should include the ending line
* terminator character(s) and should be zero terminated.
*
* An implementation may return NULL to signal that the end of input is reached, or an error occured.
*
* When a non-NULL value is returned, the caller will pass the returned value to `jerry_port_line_free` when the line is
* no longer needed. This can be used to finalize dynamically allocated buffers if necessary.
*
* This port function is never called from jerry-core directly, it is only used by some jerry-ext components that
* require user input.
*
* @param out_size_p: size of the input string in bytes, excluding terminating zero byte
*
* @return pointer to the buffer storing the string,
* or NULL if end of input
*/
jerry_char_t *jerry_port_line_read (jerry_size_t *out_size_p);
```
```c
/**
* Free a line buffer allocated by jerry_port_line_read
*
* @param buffer_p: buffer returned by jerry_port_line_read
*/
void jerry_port_line_free (jerry_char_t *buffer_p);
```
## Filesystem
```
/**
* Canonicalize a file path.
*
* If possible, the implementation should resolve symbolic links and other directory references found in the input path,
* and create a fully canonicalized file path as the result.
*
* The function may return with NULL in case an error is encountered, in which case the calling operation will not
* proceed.
*
* The implementation should allocate storage for the result path as necessary. Non-NULL return values will be passed
* to `jerry_port_path_free` when the result is no longer needed by the caller, which can be used to finalize
* dynamically allocated buffers.
*
* NOTE: The implementation must not return directly with the input, as the input buffer is released after the call.
*
* @param path_p: zero-terminated string containing the input path
* @param path_size: size of the input path string in bytes, excluding terminating zero
*
* @return buffer with the normalized path if the operation is successful,
* NULL otherwise
*/
jerry_char_t *jerry_port_path_normalize (const jerry_char_t *path_p, jerry_size_t path_size);
```
```c
/**
* Free a path buffer returned by jerry_port_path_normalize.
*
* @param path_p: the path buffer to free
*/
void jerry_port_path_free (jerry_char_t *path_p);
```
```c
/**
* Get the offset of the basename component in the input path.
*
* The implementation should return the offset of the first character after the last path separator found in the path.
* This is used by the caller to split the path into a directory name and a file name.
*
* @param path_p: input zero-terminated path string
*
* @return offset of the basename component in the input path
*/
jerry_size_t jerry_port_path_base (const jerry_char_t *path_p);
```
```c
/**
* Open a source file and read its contents into a buffer.
*
* When the source file is no longer needed by the caller, the returned pointer will be passed to
* `jerry_port_source_free`, which can be used to finalize the buffer.
*
* @param file_name_p: Path that points to the source file in the filesystem.
* @param out_size_p: The opened file's size in bytes.
*
* @return pointer to the buffer which contains the content of the file.
*/
jerry_char_t *jerry_port_source_read (const char *file_name_p, jerry_size_t *out_size_p);
```
```c
/**
* Free a source file buffer.
*
* @param buffer_p: buffer returned by jerry_port_source_read
*/
void jerry_port_source_free (jerry_char_t *buffer_p);
```
## Date
```c
#include <time.h>
#include <sys/time.h>
#include "jerryscript-port.h"
/**
* Default implementation of jerry_port_get_local_time_zone_adjustment.
*/
double jerry_port_get_local_time_zone_adjustment (double unix_ms, /**< ms since unix epoch */
bool is_utc) /**< is the time above in UTC? */
{
struct tm tm;
time_t now = (time_t) (unix_ms / 1000);
localtime_r (&now, &tm);
if (!is_utc)
{
now -= tm.tm_gmtoff;
localtime_r (&now, &tm);
}
return ((double) tm.tm_gmtoff) * 1000;
} /* jerry_port_get_local_time_zone_adjustment */
/**
* Default implementation of jerry_port_get_current_time.
*/
double jerry_port_get_current_time (void)
{
struct timeval tv;
if (gettimeofday (&tv, NULL) != 0)
{
return 0;
}
return ((double) tv.tv_sec) * 1000.0 + ((double) tv.tv_usec) / 1000.0;
} /* jerry_port_get_current_time */
```
## External context
```c
#include "jerryscript-port.h"
#include "jerryscript-port-default.h"
/**
* Pointer to the current context.
* Note that it is a global variable, and is not a thread safe implementation.
*/
static jerry_context_t *current_context_p = NULL;
/**
* Set the current_context_p as the passed pointer.
*/
void
jerry_port_default_set_current_context (jerry_context_t *context_p) /**< points to the created context */
{
current_context_p = context_p;
} /* jerry_port_default_set_current_context */
/**
* Get the current context.
* Get local time zone adjustment in milliseconds for the given input time.
*
* @return the pointer to the current context
* The argument is a time value representing milliseconds since unix epoch.
*
* Ideally, this function should satisfy the stipulations applied to LocalTZA
* in section 21.4.1.7 of the ECMAScript version 12.0, as if called with isUTC true.
*
* This port function can be called by jerry-core when JERRY_BUILTIN_DATE is enabled.
* Otherwise this function is not used.
*
* @param unix_ms: time value in milliseconds since unix epoch
*
* @return local time offset in milliseconds applied to UTC for the given time value
*/
jerry_context_t *
jerry_port_get_current_context (void)
{
return current_context_p;
} /* jerry_port_get_current_context */
int32_t jerry_port_local_tza (double unix_ms);
```
## Sleep
```c
#include "jerryscript-port.h"
#include "jerryscript-port-default.h"
#ifdef HAVE_TIME_H
#include <time.h>
#elif defined (HAVE_UNISTD_H)
#include <unistd.h>
#endif /* HAVE_TIME_H */
#if defined (JERRY_DEBUGGER) && (JERRY_DEBUGGER == 1)
void jerry_port_sleep (uint32_t sleep_time)
{
#ifdef HAVE_TIME_H
nanosleep (&(const struct timespec)
{
(time_t) sleep_time / 1000, ((long int) sleep_time % 1000) * 1000000L /* Seconds, nanoseconds */
}
, NULL);
#elif defined (HAVE_UNISTD_H)
usleep ((useconds_t) sleep_time * 1000);
#endif /* HAVE_TIME_H */
(void) sleep_time;
} /* jerry_port_sleep */
#endif /* defined (JERRY_DEBUGGER) && (JERRY_DEBUGGER == 1) */
/**
* Get the current system time in UTC.
*
* This port function is called by jerry-core when JERRY_BUILTIN_DATE is enabled.
* It can also be used in the implementing application to initialize the random number generator.
*
* @return milliseconds since Unix epoch
*/
double jerry_port_current_time (void);
```
06.REFERENCE-COUNTING.md
+31 -31
View File
@@ -13,10 +13,10 @@ permalink: /reference-counting/
In JerryScript all `jerry_value_t` values are independent
references to internal objects. Values returned by JerryScript
API functions are always live references and must be released
by `jerry_release_value`.
by `jerry_value_free`.
```c
jerry_value_t global = jerry_get_global_object ();
jerry_value_t global = jerry_current_realm ();
/* The value stored in the 'global' variable contains a live
* reference to the global object. The system also keeps its
@@ -24,9 +24,9 @@ by `jerry_release_value`.
* are independent, and both must be destroyed before the global
* object can be freed. */
jerry_release_value (global);
jerry_value_free (global);
/* Without jerry_release_value() the global object will not
/* Without jerry_value_free() the global object will not
* be freed even by jerry_cleanup(). After the reference
* is released it becomes a dead reference and cannot be
* used anymore. */
@@ -36,15 +36,15 @@ Multiple references might refer to the same internal object
even though their `jerry_value_t` representation might be different.
```c
jerry_value_t pi_ref1 = jerry_create_number (3.14);
jerry_value_t pi_ref2 = jerry_acquire_value (pi_ref1);
jerry_value_t pi_ref1 = jerry_number (3.14);
jerry_value_t pi_ref2 = jerry_value_copy (pi_ref1);
/* Both pi_ref1 and pi_ref2 refer to the same 3.14 value
* although they might not be equal in C (pi_ref1 != pi_ref2). */
/* Both references must be released. */
jerry_release_value (pi_ref1);
jerry_release_value (pi_ref2);
jerry_value_free (pi_ref1);
jerry_value_free (pi_ref2);
```
Releasing the same `jerry_value_t` twice to release two live
@@ -52,8 +52,8 @@ references is not allowed and it might cause crashes. Hence the
following code is an **INCORRECT WAY** of releasing the 3.14 value.
```c
jerry_release_value (pi_ref1);
jerry_release_value (pi_ref1);
jerry_value_free (pi_ref1);
jerry_value_free (pi_ref1);
```
JerryScript API functions returning with a `jerry_value_t` always
@@ -63,7 +63,7 @@ stated in the documentation). The next example shows this
behaviour through property getting and setting.
```c
jerry_value_t prop_value = jerry_get_property (...);
jerry_value_t prop_value = jerry_object_get (...);
/* The prop_value must be released later because both the base
* object and the prop_value have an independent reference to
@@ -71,7 +71,7 @@ behaviour through property getting and setting.
* prop_value contains a live reference to an error object.
* This reference must be released as well. */
if (jerry_value_is_error (prop_value))
if (jerry_value_is_exception (prop_value))
{
/* Errors can be handled here. */
}
@@ -83,12 +83,12 @@ behaviour through property getting and setting.
}
/* The prop_value must be released. */
jerry_release_value (prop_value);
jerry_value_free (prop_value);
/* Property setting is the same. */
jerry_value_t new_prop_value = jerry_create_number (2.718);
jerry_value_t result = jerry_set_property (..., new_prop_value);
jerry_value_t new_prop_value = jerry_number (2.718);
jerry_value_t result = jerry_object_set (..., new_prop_value);
/* If the property set is successful, a new reference is created
* for the value referenced by new_prop_value. The new_prop_value
@@ -96,14 +96,14 @@ behaviour through property getting and setting.
* is successful. */
/* The new_prop_value can be passed to other JerryScript API
* functions before the jerry_release_value () call. */
* functions before the jerry_value_free () call. */
jerry_release_value (new_prop_value);
jerry_value_free (new_prop_value);
/* The reference stored in the 'result' variable is live whether
* the operation is successful or not, and must also be freed. */
if (jerry_value_is_error (result))
if (jerry_value_is_exception (result))
{
/* Errors can be handled here. */
}
@@ -112,7 +112,7 @@ behaviour through property getting and setting.
/* A reference to a true primitive value is returned. */
}
jerry_release_value (result);
jerry_value_free (result);
```
The simplest form of setting a property without error checking
@@ -120,8 +120,8 @@ is the following:
```c
/* There are no 'ifs' in this snippet. */
jerry_release_value (jerry_set_property (..., new_prop_value));
jerry_release_value (new_prop_value);
jerry_value_free (jerry_object_set (..., new_prop_value));
jerry_value_free (new_prop_value);
```
The reference returned by a `jerry_external_handler_t` callback
@@ -138,48 +138,48 @@ jerry_value_t my_external_handler (const jerry_value_t function_obj,
* these references are automatically released after the handler
* is returned. This approach reduces code size which is useful
* on embedded systems. However you can create other references
* to them by calling jerry_acquire_value () if needed. */
* to them by calling jerry_value_copy () if needed. */
/* Since the ownership of the reference is transferred to the
* caller the following snippet is valid. */
/* If the value to be returned is needed for other purposes the
* jerry_acquire_value () can be used to create new references. */
return jerry_create_string (...);
* jerry_value_copy () can be used to create new references. */
return jerry_string (...);
}
```
Duplicating a `jerry_value_t` in C does not create another live reference.
```c
jerry_value_t undef = jerry_create_undefined ();
jerry_value_t undef = jerry_undefined ();
jerry_value_t undef2 = undef;
/* Releasing either undef or undef2 is valid but not both.
* After the release both references become dead (invalid). */
jerry_release_value (undef2);
jerry_value_free (undef2);
/* Dead references can be reassigned again. */
undef = jerry_create_boolean (true);
undef = jerry_boolean (true);
```
References can be duplicated in C as long as only one of them is freed.
```c
jerry_value_t a = jerry_create_boolean (true);
jerry_value_t a = jerry_boolean (true);
jerry_value_t b = a;
jerry_value_t c = a;
/* A new reference is assigned to 'a'. */
a = jerry_create_boolean (false);
a = jerry_boolean (false);
[...]
jerry_release_value (a);
jerry_value_free (a);
/* The 'a' (boolean false) reference becomes dead (invalid). */
jerry_release_value (c);
jerry_value_free (c);
/* Both 'b' and 'c' (boolean true) references become dead. */
/* Since all references are released, no memory leak occurs. */
07.DEBUGGER.md
+18 -51
View File
@@ -84,8 +84,8 @@ Currently, `jerryx_debugger_rp_create ()` for raw packet transport layer and
`jerryx_debugger_serial_create (const char* config)` for serial protocol
are also available.)
The resource name provided to `jerry_parse ()` is used by the client
to identify the resource name of the source code. This resource name
The source name provided to `jerry_parse ()` is used by the client
to identify the source name of the source code. This source name
is usually a file name.
## JerryScript debugger C-API interface
@@ -107,14 +107,14 @@ when a source code is received successfully.
```c
typedef jerry_value_t
(*jerry_debugger_wait_for_source_callback_t) (const jerry_char_t *resource_name_p,
size_t resource_name_size,
(*jerry_debugger_wait_for_source_callback_t) (const jerry_char_t *source_name_p,
size_t source_name_size,
const jerry_char_t *source_p,
size_t source_size, void *user_p);
```
- `resource_name_p` - resource (usually a file) name of the source code
- `resource_name_size` - size of resource name
- `source_name_p` - source (usually a file) name of the source code
- `source_name_size` - size of source name
- `source_p` - source code character data
- `source_size` - size of source code
- `user_p` - custom pointer passed to [jerry_debugger_wait_for_client_source](#jerry_debugger_wait_for_client_source)
@@ -140,6 +140,8 @@ jerry_debugger_is_connected (void);
[doctest]: # (test="link")
```c
#include <stdio.h>
#include "jerryscript.h"
#include "jerryscript-ext/debugger.h"
@@ -316,8 +318,8 @@ jerry_debugger_wait_for_client_source (jerry_debugger_wait_for_source_callback_t
* Runs the source code received by jerry_debugger_wait_for_client_source.
*/
static jerry_value_t
wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource name */
size_t resource_name_size, /**< size of resource name */
wait_for_source_callback (const jerry_char_t *source_name_p, /**< source name */
size_t source_name_size, /**< size of source name */
const jerry_char_t *source_p, /**< source code */
size_t source_size, /**< source code size */
void *user_p /**< user pointer */)
@@ -325,19 +327,21 @@ wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource nam
(void) user_p;
jerry_parse_options_t parse_options;
parse_options.options = JERRY_PARSE_HAS_RESOURCE;
parse_options.resource_name = jerry_create_string ((const jerry_char_t *) resource_name_p);
parse_options.options = JERRY_PARSE_HAS_SOURCE_NAME;
parse_options.source_name = jerry_string ((const jerry_char_t *) source_name_p,
(jerry_size_t) source_name_size,
JERRY_ENCODING_UTF8);
jerry_value_t ret_val = jerry_parse (source_p,
source_size,
&parse_options);
jerry_release_value (parse_options.resource_name);
jerry_value_free (parse_options.source_name);
if (!jerry_value_is_error (ret_val))
if (!jerry_value_is_exception (ret_val))
{
jerry_value_t func_val = ret_val;
ret_val = jerry_run (func_val);
jerry_release_value (func_val);
jerry_value_free (func_val);
}
return ret_val;
@@ -365,7 +369,7 @@ main (void)
NULL,
&run_result);
jerry_release_value (run_result);
jerry_value_free (run_result);
}
while (receive_status == JERRY_DEBUGGER_SOURCE_RECEIVED);
@@ -417,40 +421,3 @@ main (void)
jerry_cleanup ();
}
```
### jerry_debugger_send_log
**Summary**
Sends the program's log to the debugger client.
**Prototype**
```c
void
jerry_debugger_send_log (jerry_log_level_t level, const jerry_char_t *buffer, jerry_size_t string_size)
```
**Example**
[doctest]: # (test="link")
```c
#include "jerryscript.h"
#include "jerryscript-ext/debugger.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
&& jerryx_debugger_ws_create ());
jerry_char_t my_log[] = "Custom diagnostics";
jerry_size_t my_log_size = sizeof (my_log);
jerry_debugger_send_log (JERRY_LOG_LEVEL_DEBUG, my_log, my_log_size);
jerry_cleanup ();
}
```
08.CODING-STANDARDS.md
+1 -1
View File
@@ -22,7 +22,7 @@ review.
* Tab characters are not allowed.
* Maximum line length is 120 characters (excluding newline).
* No trailing white space is allowed.
* Run `tools/run-tests.py --check-vera` to check several
* Run `tools/run-tests.py --check-format` to check several
of the coding conventions automatically.
## Comments
09.EXT-REFERENCE-ARG.md
+6 -6
View File
@@ -254,7 +254,7 @@ my_external_handler (const jerry_value_t function_obj,
mapping,
4);
if (jerry_value_is_error (rv))
if (jerry_value_is_exception (rv))
{
/* Handle error. */
return rv;
@@ -265,7 +265,7 @@ my_external_handler (const jerry_value_t function_obj,
* required_bool, required_str and optional_num can now be used.
*/
return jerry_create_undefined (); /* Or return something more meaningful. */
return jerry_undefined (); /* Or return something more meaningful. */
}
```
@@ -650,7 +650,7 @@ my_external_handler (const jerry_value_t function_obj,
mapping,
1);
if (jerry_value_is_error (rv))
if (jerry_value_is_exception (rv))
{
/* Handle error. */
return rv;
@@ -661,7 +661,7 @@ my_external_handler (const jerry_value_t function_obj,
* required_bool, required_num and optional_num can now be used.
*/
return jerry_create_undefined (); /* Or return something more meaningful. */
return jerry_undefined (); /* Or return something more meaningful. */
}
```
@@ -741,7 +741,7 @@ my_external_handler (const jerry_value_t function_obj,
mapping,
1);
if (jerry_value_is_error (rv))
if (jerry_value_is_exception (rv))
{
/* Handle error. */
return rv;
@@ -752,7 +752,7 @@ my_external_handler (const jerry_value_t function_obj,
* required_bool, required_num and optional_num can now be used.
*/
return jerry_create_undefined (); /* Or return something more meaningful. */
return jerry_undefined (); /* Or return something more meaningful. */
}
```
10.EXT-REFERENCE-HANDLER.md
+37 -197
View File
@@ -10,174 +10,9 @@ permalink: /ext-reference-handler/
# Common methods to handle properties
The `jerryscript-ext/handler.h` header defines a set of convenience methods
The `jerryscript-ext/properties.h` header defines a set of convenience methods
which makes the property access a bit straightforward.
## jerryx_set_property_str
**Summary**
Set a property on a target object with a given name.
*Note*:
- The property name must be a zero terminated UTF-8 string.
- There should be no '\0' (NULL) character in the name excluding the string terminator.
- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
jerry_value_t
jerryx_set_property_str (const jerry_value_t target_object,
const char *name,
const jerry_value_t value);
```
- `target_object` - the object where the property should be set
- `name` - name of the property
- `value` - property value to be set
- return value
- JS true value, if success
- thrown error, if there was a problem setting the property
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
int
main (int argc, char **argv)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t global = jerry_get_global_object ();
jerry_value_t value = jerry_create_number (3.3);
jerry_value_t result = jerryx_set_property_str (global, "value", value);
if (jerry_value_is_error (result))
{
/* The error type/reason can be extracted via the `jerry_get_value_from_error` method */
printf ("Error during property configuration\r\n");
}
jerry_release_value (result);
jerry_release_value (value);
jerry_release_value (global);
jerry_cleanup();
return 0;
}
```
## jerryx_get_property_str
**Summary**
Get the value of a property from the specified object with the given name.
*Notes*:
- The property name must be a zero terminated UTF-8 string.
- There should be no '\0' (NULL) character in the name excluding the string terminator.
- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```
jerry_value_t
jerryx_get_property_str (const jerry_value_t target_object,
const char *name);
```
- `target_object` - object on which the property name is accessed
- `name` - property name as an UTF-8 `char*`
- return value
- value of property, if success
- thrown error, if there was a problem accessing the property
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
int
main (int argc, char **argv)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t global = jerry_get_global_object ();
jerry_value_t math_object = jerryx_get_property_str (global, "Math");
/* use math_object */
jerry_release_value (math_object);
jerry_release_value (global);
jerry_cleanup();
return 0;
}
```
## jerryx_has_property_str
**Summary**
Check if a property exists on an object.
*Notes*:
- The operation performed is the same as what the `jerry_has_property` method.
- The property name must be a zero terminated UTF-8 string.
- There should be no '\0' (NULL) character in the name excluding the string terminator.
**Prototype**
```
bool
jerryx_has_property_str (const jerry_value_t target_object,
const char *name);
```
- `target_object` - object on which the property name is accessed
- `name` - property name as an UTF-8 `char*`
- return value
- true, if the given property name exists on the object
- false, if there is no such property name or there was an error accessing the property
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
int
main (int argc, char **argv)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t global = jerry_get_global_object ();
bool have_math = jerryx_has_property_str (global, "Math");
jerry_release_value (global);
jerry_cleanup();
return have_math ? 0 : 1;
}
```
# Utility to register multiple properties in bulk
In some cases it is useful to register multiple properties for a given object
@@ -273,8 +108,10 @@ jerryx_set_properties (const jerry_value_t target_object,
[doctest]: # ()
```c
#include <stdio.h>
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
#include "jerryscript-ext/properties.h"
static jerry_value_t
handler (const jerry_call_info_t *call_info_p,
@@ -283,7 +120,7 @@ handler (const jerry_call_info_t *call_info_p,
{
printf ("native handler called!\n");
return jerry_create_boolean (true);
return jerry_boolean (true);
}
int
@@ -293,24 +130,24 @@ main (int argc, char **argv)
jerryx_property_entry methods[] =
{
{ "demo", jerry_create_external_function (handler) },
{ "demo", jerry_function_external (handler) },
{ NULL, 0 },
};
jerry_value_t global = jerry_get_global_object ();
jerry_value_t global = jerry_current_realm ();
jerryx_register_result reg = jerryx_set_properties (global, methods);
/* if `reg.result` is undefined all methods are registered */
if (jerry_value_is_error (reg.result))
if (jerry_value_is_exception (reg.result))
{
printf ("Only registered %d properties\r\n", reg.registered);
/* clean up not registered property values */
jerryx_release_property_entry (methods, reg);
/* clean up the error */
jerry_release_value (reg.result);
jerry_value_free (reg.result);
}
jerry_release_value (global);
jerry_value_free (global);
jerry_cleanup();
@@ -324,8 +161,8 @@ To make property registration convenient, there are a set of macros to use
when setting a property entry:
* `JERRYX_PROPERTY_NUMBER(NAME, NUMBER)` - creates a number entry.
* `JERRYX_PROPERTY_STRING(NAME, STR)` - creates an UTF-8 string entry. This string must be zero terminated.
* `JERRYX_PROPERTY_STRING_SZ(NAME, STR, SIZE)` - creates an UTF-8 string entry using only `SIZE` bytes from the string.
* `JERRYX_PROPERTY_STRING(NAME, STR, SIZE)` - creates an UTF-8 string entry using `SIZE` bytes from the string.
* `JERRYX_PROPERTY_STRING_SZ(NAME, STR)` - creates an ASCII string entry. This string must be zero terminated.
* `JERRYX_PROPERTY_BOOLEAN(NAME, VALUE)` - creates a boolean entry.
* `JERRYX_PROPERTY_FUNCTION(NAME, NATIVE)` - creates a native C function entry.
* `JERRYX_PROPERTY_UNDEFINED(NAME)` - creates an undefined property entry.
@@ -336,8 +173,10 @@ when setting a property entry:
[doctest]: # ()
```c
#include <stdio.h>
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
#include "jerryscript-ext/properties.h"
static jerry_value_t
handler (const jerry_call_info_t *call_info_p,
@@ -346,7 +185,7 @@ handler (const jerry_call_info_t *call_info_p,
{
printf ("native handler called!\n");
return jerry_create_boolean (true);
return jerry_boolean (true);
}
int
@@ -367,20 +206,20 @@ main (int argc, char **argv)
JERRYX_PROPERTY_LIST_END(),
};
jerry_value_t global = jerry_get_global_object ();
jerry_value_t global = jerry_current_realm ();
jerryx_register_result reg = jerryx_set_properties (global, methods);
/* if `reg.result` is undefined all methods are registered */
if (jerry_value_is_error (reg.result))
if (jerry_value_is_exception (reg.result))
{
printf ("Only registered %d properties\r\n", reg.registered);
/* clean up not registered property values */
jerryx_release_property_entry (methods, reg);
/* clean up the error */
jerry_release_value (reg.result);
jerry_value_free (reg.result);
}
jerry_release_value (global);
jerry_value_free (global);
jerry_cleanup();
@@ -450,7 +289,7 @@ jerryx_handler_assert_fatal (const jerry_value_t func_obj_val, const jerry_value
**See also**
- [jerryx_handler_register_global](#jerryx_handler_register_global)
- [jerryx_register_global](#jerryx_register_global)
## jerryx_handler_assert_throw
@@ -476,7 +315,7 @@ jerryx_handler_assert_throw (const jerry_value_t func_obj_val, const jerry_value
**See also**
- [jerryx_handler_register_global](#jerryx_handler_register_global)
- [jerryx_register_global](#jerryx_register_global)
## jerryx_handler_assert
@@ -514,7 +353,7 @@ jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,
**See also**
- [jerryx_handler_register_global](#jerryx_handler_register_global)
- [jerryx_register_global](#jerryx_register_global)
## jerryx_handler_print
@@ -523,14 +362,14 @@ jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,
Provide a `print` implementation for scripts. The routine converts all of its
arguments to strings and outputs them char-by-char using
`jerry_port_print_char`. The NULL character is output as "\u0000",
`jerry_port_print_byte`. The NULL character is output as "\u0000",
other characters are output bytewise.
*Note*: This implementation does not use standard C `printf` to print its
output. This allows more flexibility but also extends the core JerryScript
engine port API. Applications that want to use `jerryx_handler_print` must
ensure that their port implementation also provides
`jerry_port_print_char`.
`jerry_port_print_byte`.
**Prototype**
@@ -549,26 +388,26 @@ jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this
**See also**
- [jerryx_handler_register_global](#jerryx_handler_register_global)
- [jerry_port_print_char](05.PORT-API.md#jerry_port_print_char)
- [jerryx_register_global](#jerryx_register_global)
- [jerry_port_print_byte](05.PORT-API.md#jerry_port_print_char)
# Handler registration helper
## jerryx_handler_register_global
## jerryx_register_global
**Summary**
Register a JavaScript function in the global object.
*Note*: Returned value must be freed with `jerry_release_value`, when it is no
*Note*: Returned value must be freed with `jerry_value_free`, when it is no
longer needed.
**Prototype**
```c
jerry_value_t
jerryx_handler_register_global (const jerry_char_t *name_p,
jerryx_register_global (const char *name_p,
jerry_external_handler_t handler_p);
```
@@ -583,7 +422,8 @@ jerryx_handler_register_global (const jerry_char_t *name_p,
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
#include "jerryscript-ext/properties.h"
static const struct {
const char *name_p;
@@ -599,14 +439,14 @@ static const struct {
static void
register_common_functions (void)
{
jerry_value_t ret = jerry_create_undefined ();
jerry_value_t ret = jerry_undefined ();
for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_is_error (ret); i++)
for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_is_exception (ret); i++)
{
ret = jerryx_handler_register_global ((const jerry_char_t *) common_functions[i].name_p,
common_functions[i].handler_p);
ret = jerryx_register_global (common_functions[i].name_p,
common_functions[i].handler_p);
}
jerry_release_value (ret);
jerry_value_free (ret);
}
```
11.EXT-REFERENCE-AUTORELEASE.md
+7 -7
View File
@@ -14,7 +14,7 @@ permalink: /ext-reference-autorelease/
**Summary**
Macro for `const jerry_value_t` for which jerry_release_value() is
Macro for `const jerry_value_t` for which jerry_value_free() is
automatically called when the variable goes out of scope.
*Note*: The macro depends on compiler support. For GCC and LLVM/clang, the macro is implemented
@@ -31,23 +31,23 @@ using the `__cleanup__` variable attribute. For other compilers, no support has
static void
foo (bool enable)
{
JERRYX_AR_VALUE_T bar = jerry_create_string ((const jerry_char_t *) "...");
JERRYX_AR_VALUE_T bar = jerry_string_sz ("...");
if (enable)
{
JERRYX_AR_VALUE_T baz = jerry_get_global_object ();
JERRYX_AR_VALUE_T baz = jerry_current_realm ();
/* bar and baz can now be used. */
/*
* jerry_release_value (baz) and jerry_release_value (bar) is called automatically before
* jerry_value_free (baz) and jerry_value_free (bar) is called automatically before
* returning, because `baz` and `bar` go out of scope.
*/
return;
}
/*
* jerry_release_value (bar) is called automatically when the function returns,
* jerry_value_free (bar) is called automatically when the function returns,
* because `bar` goes out of scope.
*/
}
@@ -56,5 +56,5 @@ foo (bool enable)
**See also**
- [jerry_value_t](../api-reference#jerry_value_t)
- [jerry_acquire_value](../api-reference#jerry_acquire_value)
- [jerry_release_value](../api-reference#jerry_release_value)
- [jerry_value_copy](../api-reference#jerry_value_copy)
- [jerry_value_free](../api-reference#jerry_value_free)
12.EXT-REFERENCE-MODULE.md
+6 -6
View File
@@ -47,8 +47,8 @@ resolved using the native JerryScript module resolver `jerryx_module_native_reso
`jerryx_module_resolve()`. Native modules are registered during application startup and by calling `dlopen()` by means
of library constructors, support for which can be turned on using the `FEATURE_INIT_FINI` build flag. In the absence of
such a flag, the module registration and unregistration functions are exposed as global symbols which can be called
explicitly. Note: `FEATURE_INIT_FINI` build flag isn't supported on Windows, because Microsoft Visual C/C++ Compiler
doesn't support library constructors and destructors.
explicitly. Note: On windows, `FEATURE_INIT_FINI` build flag only supported with GNU toolchain or Microsoft Visual C/C++ Compiler
2008 and upper.
## jerryx_module_resolve
@@ -174,9 +174,9 @@ load_and_evaluate_js_file (const jerry_value_t name, jerry_value_t *result)
char *js_file_contents = NULL;
int file_size = 0;
jerry_size_t name_size = jerry_get_utf8_string_size (name);
jerry_size_t name_size = jerry_string_size (name, JERRY_ENCODING_UTF8);
jerry_char_t name_string[name_size + 1];
jerry_string_to_utf8_char_buffer (name, name_string, name_size);
jerry_string_to_buffer (name, JERRY_ENCODING_UTF8, name_string, name_size);
name_string[name_size] = 0;
FILE *js_file = fopen (name_string, "r");
@@ -215,7 +215,7 @@ canonicalize_file_path (const jerry_value_t name)
/**
* Since a file on the file system can be referred to by multiple relative paths, but only by one absolute path, the
* absolute path becomes the canonical name for the module. Thus, to establish this canonical name, we must search
* name for "./" and "../", follow symlinks, etc., then create absolute_path via jerry_create_string () and return
* name for "./" and "../", follow symlinks, etc., then create absolute_path via jerry_string () and return
* it, because it is the canonical name for this module. Thus, we avoid loading the same JavaScript file twice.
*/
@@ -281,7 +281,7 @@ loaded.
static jerry_value_t
my_module_on_resolve (void)
{
return jerry_create_external_function (very_useful_function);
return jerry_function_external (very_useful_function);
} /* my_module_on_resolve */
/* Note that there is no semicolon at the end of the next line. This is how it must be. */
14.EXT-REFERENCE-HANDLE-SCOPE.md
+6 -6
View File
@@ -30,7 +30,7 @@ JerryScript only supports a single nested hierarchy of scopes. There is only one
static jerry_value_t
create_object (void)
{
jerry_value_t obj = jerry_create_object ();
jerry_value_t obj = jerry_object ();
return obj;
} /* create_object */
@@ -51,7 +51,7 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
test_handle_scope_val ();
jerry_gc (JERRY_GC_PRESSURE_LOW);
jerry_heap_gc (JERRY_GC_PRESSURE_LOW);
jerry_cleanup ();
} /* main */
@@ -76,7 +76,7 @@ create_object (void)
{
jerryx_escapable_handle_scope scope;
jerryx_open_escapable_handle_scope (&scope);
jerry_value_t obj = jerryx_create_handle (jerry_create_object ());
jerry_value_t obj = jerryx_create_handle (jerry_object ());
jerry_value_t escaped_obj;
jerryx_escape_handle(scope, obj, &escaped_obj);
@@ -103,7 +103,7 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
test_handle_scope_val ();
jerry_gc (JERRY_GC_PRESSURE_LOW);
jerry_heap_gc (JERRY_GC_PRESSURE_LOW);
jerry_cleanup ();
} /* main */
@@ -112,8 +112,8 @@ main (void)
**See also**
- [jerry_value_t](../api-reference#jerry_value_t)
- [jerry_acquire_value](../api-reference#jerry_acquire_value)
- [jerry_release_value](../api-reference#jerry_release_value)
- [jerry_value_copy](../api-reference#jerry_value_copy)
- [jerry_value_free](../api-reference#jerry_value_free)
## Pre-allocated list of handle scopes and handles
_includes/header.html
+1 -1
View File
@@ -44,4 +44,4 @@
</div><!--/.nav-collapse -->
</div>
</nav>
<a href="https://github.com/jerryscript-project/jerryscript"><img style="position: absolute; top: 50; right: 0; border: 0;" src="https://camo.githubusercontent.com/652c5b9acfaddf3a9c326fa6bde407b87f7be0f4/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f6f72616e67655f6666373630302e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png"></a>
<a href="https://github.com/jerryscript-project/jerryscript"><img style="position: absolute; top: 50; right: 0; border: 0;" src="https://github.blog/wp-content/uploads/2008/12/forkme_right_orange_ff7600.png" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png"></a>