Update the webpage (#2991)
JerryScript-DCO-1.0-Signed-off-by: Dániel Bátyai dbatyai@inf.u-szeged.hu
This commit is contained in:
Dániel Bátyai
committed by
László Langó
László Langó
parent
22babb1718
commit
93509a57e3
@@ -67,7 +67,7 @@ python tools/build.py --cmake-param=CMAKE_PARAM
|
||||
python tools/build.py --profile=es5.1|es2015-subset|minimal
|
||||
```
|
||||
|
||||
See also the related [README.md](https://github.com/pando-project/jerryscript/blob/master/jerry-core/profiles/README.md).
|
||||
See also the related [README.md](https://github.com/jerryscript-project/jerryscript/blob/master/jerry-core/profiles/README.md).
|
||||
|
||||
**Use (compiler-default, external) libc**
|
||||
|
||||
@@ -130,6 +130,15 @@ python tools/build.py --cpointer-32bit=on --mem-heap=1024
|
||||
*Note*: The heap size will be allocated statically at compile time, when JerryScript memory
|
||||
allocator is used.
|
||||
|
||||
**To build with libfuzzer support**
|
||||
|
||||
```bash
|
||||
CC=clang python tools/build.py --libfuzzer=on --compile-flag=-fsanitize=address --lto=off
|
||||
```
|
||||
|
||||
Check the documentation of libfuzzer to get the runtime settings of the created fuzzer
|
||||
binary: https://llvm.org/docs/LibFuzzer.html.
|
||||
|
||||
**To get a list of all the available buildoptions for Linux**
|
||||
|
||||
```bash
|
||||
@@ -0,0 +1,299 @@
|
||||
---
|
||||
layout: page
|
||||
title: Configuration
|
||||
category: navbar
|
||||
permalink: /configuration/
|
||||
---
|
||||
|
||||
* toc
|
||||
{:toc}
|
||||
|
||||
# Configuration
|
||||
|
||||
JerryScript provides a large number of configuration options which can be used to enable or disable specific features, allowing users to fine tune the engine to best suit their needs.
|
||||
A configuration option's value can be changed either by providing specific C preprocessor definitions, by adding CMake defininitions, or by using the arguments of the `tools/build.py` script.
|
||||
This document lists the available configuration options, shows the configuration name for C, CMake, and python, and provides a brief description that explains the effect of the options.
|
||||
|
||||
|
||||
### All-in-one build
|
||||
|
||||
Enables the All-in-one build process, which aggregates the contents of each source file, and uses this combined file to compile the JerryScript library.
|
||||
This process can provide comparable results to link time optimization, and can be useful when LTO is not available otherwise.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `<none>` |
|
||||
| CMake: | `-DENABLE_ALL_IN_ONE=ON/OFF` |
|
||||
| Python: | `--all-in-one=ON/OFF` |
|
||||
|
||||
### Jerry debugger
|
||||
|
||||
Enables debugger support in the engine, which can be used to debug running JavaScript code. For more information on using the debugger see [Debugger](07.DEBUGGER.md).
|
||||
The debugger is disabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_DEBUGGER=0/1` |
|
||||
| CMake: | `-DJERRY_DEBUGGER=ON/OFF` |
|
||||
| Python: | `--jerry-debugger=ON/OFF` |
|
||||
|
||||
### Line information
|
||||
|
||||
By default, all source code information is discarded after parsing is complete. This option can be used to augment the created bytecode to provide line information during runtime,
|
||||
that can be used by the debugger to identify the currently executed source context. See [Debugger](07.DEBUGGER.md).
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_LINE_INFO=0/1` |
|
||||
| CMake: | `-DJERRY_LINE_INFO=ON/OFF` |
|
||||
| Python: | `--line-info=ON/OFF` |
|
||||
|
||||
### 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 `es2015-subset`, `es5.1`, 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 | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `<see description>` |
|
||||
| CMake: | `-DJERRY_PROFILE="path"` |
|
||||
| Python: | `--profile="path"` |
|
||||
|
||||
### External context
|
||||
|
||||
Enables external context support in the engine. By default, JerryScript uses a statically allocated context to store the current state of the engine internals.
|
||||
When this option is enabled, an externally allocated memory region can be provided through the port API to the engine, to be used as the context.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_EXTERNAL_CONTEXT=0/1` |
|
||||
| CMake: | `-DJERRY_EXTERNAL_CONTEXT=ON/OFF` |
|
||||
| Python: | `--external-context=ON/OFF` |
|
||||
|
||||
### Snapshot execution
|
||||
|
||||
This option can be used to enable snapshot execution in the engine.
|
||||
This option is disabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_SNAPSHOT_EXEC=0/1` |
|
||||
| CMake: | `-DJERRY_SNAPSHOT_EXEC=ON/OFF` |
|
||||
| Python: | `--snapshot-exec=ON/OFF` |
|
||||
|
||||
### Snapshot saving
|
||||
|
||||
This option can be used to enable snapshot saving in the engine.
|
||||
This option is disabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_SNAPSHOT_SAVE=0/1` |
|
||||
| CMake: | `-DJERRY_SNAPSHOT_SAVE=ON/OFF` |
|
||||
| Python: | `--snapshot-save=ON/OFF` |
|
||||
|
||||
### Jerry parser
|
||||
|
||||
This option can be used to enable or disable the parser. When the parser is disabled all features that depend on source parsing are unavailable (eg. `jerry_parse`, `eval`, Function constructor).
|
||||
This option can be useful in combination with the snapshot feature. The parser is enabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_PARSER=0/1` |
|
||||
| CMake: | `-DJERRY_PARSER=ON/OFF` |
|
||||
| Python: | `--js-parser=ON/OFF` |
|
||||
|
||||
### Dump bytecode
|
||||
|
||||
This option can be used to display created bytecode in a human readable format. See [Internals](04.INTERNALS.md#byte-code) for more details.
|
||||
This option is disabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_PARSER_DUMP_BYTE_CODE=0/1` |
|
||||
| CMake: | `-DJERRY_PARSER_DUMP_BYTE_CODE=ON/OFF` |
|
||||
| Python: | `--show-opcodes=ON/OFF` |
|
||||
|
||||
### Dump RegExp bytecode
|
||||
|
||||
This option can be used to display created RegExp bytecode in a human readable format. The RegExp bytecode is different from the bytecode used by the virtual machine.
|
||||
This option is disabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_REGEXP_DUMP_BYTE_CODE=0/1` |
|
||||
| CMake: | `-DJERRY_REGEXP_DUMP_BYTE_CODE=ON/OFF` |
|
||||
| Python: | `--show-regexp-opcodes=ON/OFF` |
|
||||
|
||||
### Strict RegExp
|
||||
|
||||
This option can be used to enable strict RegExp mode. The standard RegExp syntax is a lot stricter than what is common in current JavaScript implementations.
|
||||
When enabled, this flag disables all of the non-standard, quality-of-life RegExp features, that are implemented to provide compatibility with other commonly used engines.
|
||||
This option is disabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_REGEXP_STRICT_MODE=0/1` |
|
||||
| CMake: | `-DJERRY_REGEXP_STRICT_MODE=ON/OFF` |
|
||||
| Python: | `--regexp-strict-mode=ON/OFF` |
|
||||
|
||||
### Error messages
|
||||
|
||||
Enables error messages for thrown Error objects. By default, error messages are omitted to reduce memory usage.
|
||||
Enabling this feature provides detailed error messages where available, like line information for Syntax errors, variable names for Reference errors, Type/Range error messages for built-in routines, etc.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_ERROR_MESSAGES=0/1` |
|
||||
| CMake: | `--DJERRY_ERROR_MESSAGES=ON/OFF` |
|
||||
| Python: | `--error-messages=ON/OFF` |
|
||||
|
||||
### Logging
|
||||
|
||||
This option can be used to enable log messages during runtime. When enabled the engine will use the `jerry_port_log` port API function to print relevant log messages.
|
||||
This feature is disabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_LOGGING=0/1` |
|
||||
| CMake: | `-DJERRY_LOGGING=ON/OFF` |
|
||||
| Python: | `--logging=ON/OFF` |
|
||||
|
||||
### LCache
|
||||
|
||||
This option enables the LCache, allowing faster access to object properties. The LCache usases a statically allocated hash-map, which increases memory consumption.
|
||||
See [Internals](04.INTERNALS.md#lcache) for further details.
|
||||
This option is enabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_LCACHE=0/1` |
|
||||
| CMake: | `<none>` |
|
||||
| Python: | `<none>` |
|
||||
|
||||
### Property hashmaps
|
||||
|
||||
This option enables the creation of hashmaps for object properties, which allows faster property access, at the cost of increased memory consumption.
|
||||
See [Internals](04.INTERNALS.md#property-hashmap) for further details.
|
||||
This option is enabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_PROPRETY_HASHMAP=0/1` |
|
||||
| CMake: | `<none>` |
|
||||
| Python: | `<none>` |
|
||||
|
||||
### 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.
|
||||
The feature can create a significant performance overhead, and should only be used for measurement purposes. This option is disabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_MEM_STATS=0/1` |
|
||||
| CMake: | `-DJERRY_MEM_STATS=ON/OFF` |
|
||||
| Python: | `--mem-stats=ON/OFF` |
|
||||
|
||||
### Heap size
|
||||
|
||||
This option can be used to adjust the size of the internal heap, represented in kilobytes. The provided value should be an integer. Values larger than 512 require 32-bit compressed pointers to be enabled.
|
||||
The default value is 512.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_GLOBAL_HEAP_SIZE=(int)` |
|
||||
| CMake: | `--DJERRY_GLOBAL_HEAP_SIZE=(int)` |
|
||||
| Python: | `--heap-size=(int)` |
|
||||
|
||||
### Stack limit
|
||||
|
||||
This option can be used to cap the stack usage of the engine, and prevent stack overflows due to recursion. The provided value should be an integer, which represents the allowed stack usage in kilobytes.
|
||||
The default value is 0 (unlimited).
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_STACK_LIMIT=(int)` |
|
||||
| CMake: | `-DJERRY_STACK_LIMIT=(int)` |
|
||||
| Python: | `--stack-limit=(int)` |
|
||||
|
||||
### 32-bit compressed pointers
|
||||
|
||||
Enables 32-bit pointers instead of the default 16-bit compressed pointers. This allows the engine to use a much larger heap, but also comes with slightly increased memory usage, as objects can't be packed as tightly.
|
||||
This option must be enabled when using the system allocator.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_CPOINTER_32_BIT=0/1` |
|
||||
| CMake: | `-DJERRY_CPOINTER_32_BIT=ON/OFF` |
|
||||
| Python: | `--cpointer-32bit=ON/OFF` |
|
||||
|
||||
### System allocator
|
||||
|
||||
This option enables the use of malloc/free instead of the internal JerryScript allocator. This feature requires 32-bit compressed pointers, and is unsupported on 64-bit architectures.
|
||||
This option is disabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_SYSTEM_ALLOCATOR=0/1` |
|
||||
| CMake: | `-DJERRY_SYSTEM_ALLOCATOR=ON/OFF` |
|
||||
| Python: | `--system-allocator=ON/OFF` |
|
||||
|
||||
### Valgrind support
|
||||
|
||||
This option enables valgrind support for the internal allocator. When enabled, valgrind will be able to properly identify allocated memory regions, and report leaks or out-of-bounds memory accesses.
|
||||
This option is disabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_VALGRIND=0/1` |
|
||||
| CMake: | `-DJERRY_VALGRIND=ON/OFF` |
|
||||
| Python: | `--valgrind=ON/OFF` |
|
||||
|
||||
### Memory stress test
|
||||
|
||||
This option can be used to stress test memory management, by running garbage collection before every allocation attempt.
|
||||
This option is disabled by default.
|
||||
|
||||
| Options | |
|
||||
|---------|----------------------------------------------|
|
||||
| C: | `-DJERRY_MEM_GC_BEFORE_EACH_ALLOC=0/1` |
|
||||
| CMake: | `-DJERRY_MEM_GC_BEFORE_EACH_ALLOC=ON/OFF` |
|
||||
| Python: | `--mem-stress-test=ON/OFF` |
|
||||
|
||||
|
||||
# Single source build mode
|
||||
|
||||
There is a special mode to use/"build" JerryScript. That is generating a single C file which can be
|
||||
included into projects quickly. To achive this the following command can be executed to create
|
||||
a set of files into the `gen_src` directory (Note that the command is executed in the jerryscript root directory
|
||||
but can be adapted to run outside of the project root dir):
|
||||
|
||||
```sh
|
||||
$ python tools/srcgenerator.py --output-dir gen_src --jerry-core --jerry-port-default --jerry-libm
|
||||
```
|
||||
|
||||
The command creates the following files in the `gen_src` dir:
|
||||
|
||||
* `jerryscript.c`
|
||||
* `jerryscript.h`
|
||||
* `jerryscript-config.h`
|
||||
* `jerryscript-port-default.c`
|
||||
* `jerryscript-port-default.h`
|
||||
* `jerryscript-libm.c`
|
||||
* `math.h`
|
||||
|
||||
**Important**: the `jerryscript-config.h` contains the configurations mentioned above and
|
||||
should be adapted to the required use-case. See the file contents for more details and for the
|
||||
default configuration. (Note: This config file is created from the the `jerry-core/config.h` file.)
|
||||
|
||||
These files can be directly compiled with an application using the JerryScript API.
|
||||
For example with the following command:
|
||||
|
||||
```sh
|
||||
$ gcc -Wall -o demo_app demo_app.c gen_src/jerryscript.c gen_src/jerryscript-port-default.c jerryscript-libm.c -Igen_src/
|
||||
```
|
||||
|
||||
Please note that the headers must be available on the include path.
|
||||
|
||||
In addition there is a `-DENABLE_ALL_IN_ONE_SOURCE=ON` CMake option to use this kind of sources during the build.
|
||||
+1048
-157
File diff suppressed because it is too large
Load Diff
+587
-73
@@ -10,9 +10,44 @@ permalink: /api-example/
|
||||
|
||||
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.
|
||||
This guide is intended to introduce you to JerryScript embedding API and to create a minimal JavaScript shell.
|
||||
The examples are not using all API methods please also check out the API reference document which contains additional examples.
|
||||
|
||||
## Step 1. Execute JavaScript from your application
|
||||
|
||||
## Before trying out the examples: Get and build JerryScript library
|
||||
|
||||
Before getting started using the JerryScript library it should be cloned and built for a target os/device.
|
||||
|
||||
There are quite a few configuration options but for these examples the JerryScript is built
|
||||
**with default configuration** and installed to a user directory on a Linux system.
|
||||
This is done by the following commands:
|
||||
|
||||
```sh
|
||||
$ mkdir jerry
|
||||
$ cd jerry
|
||||
$ git clone https://github.com/jerryscript-project/jerryscript.git
|
||||
$ jerryscript/tools/build.py --builddir=$(pwd)/example_build --cmake-param="-DCMAKE_INSTALL_PREFIX=$(pwd)/example_install/"
|
||||
$ make -C $(pwd)/example_build install
|
||||
```
|
||||
|
||||
With this the JerryScript library is installed into the `$(pwd)/example_install/{include,lib}` directories.
|
||||
|
||||
In this guide we will use `pkg-config` to ease the usage of headers and libraries.
|
||||
In order to do so, the following export is required (executed from the jerry directory):
|
||||
|
||||
```sh
|
||||
$ 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-libm
|
||||
```
|
||||
|
||||
## 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]: # ()
|
||||
|
||||
@@ -30,39 +65,213 @@ main (void)
|
||||
}
|
||||
```
|
||||
|
||||
The application will return with zero exit code.
|
||||
To compile it one can use the following command:
|
||||
|
||||
## Step 2. Split engine initialization and script execution
|
||||
```sh
|
||||
$ gcc api-example-1.c -o api-example-1 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-libm)
|
||||
```
|
||||
|
||||
Here we perform the same actions, as `jerry_run_simple`, while splitting into several steps:
|
||||
If everything is correct the application returns with a zero exit code:
|
||||
|
||||
- engine initialization
|
||||
- script code setup
|
||||
- script execution
|
||||
- engine cleanup
|
||||
```
|
||||
$ ./api-example-1
|
||||
$ echo $?
|
||||
```
|
||||
|
||||
## Example 2. Split engine initialization and script execution.
|
||||
|
||||
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.
|
||||
|
||||
To make sure that the code parsing and execution was ok, the `jerry_value_is_error`
|
||||
method is used to check for any errors.
|
||||
|
||||
Use the following code for the `api-example-2.c` file:
|
||||
|
||||
[doctest]: # ()
|
||||
|
||||
```c
|
||||
#include "jerryscript.h"
|
||||
#include "jerryscript-ext/handler.h"
|
||||
|
||||
int
|
||||
main (void)
|
||||
{
|
||||
const jerry_char_t script[] = "print ('Hello, World!');";
|
||||
const jerry_char_t script[] = "var str = 'Hello, World!';";
|
||||
const jerry_length_t script_size = sizeof (script) - 1;
|
||||
/* Note: sizeof can be used here only because the compiler knows the static character arrays's size.
|
||||
* If this is not the case, strlen should be used instead.
|
||||
*/
|
||||
|
||||
/* Initialize engine */
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
/* Register 'print' function from the extensions */
|
||||
jerryx_handler_register_global ((const jerry_char_t *) "print",
|
||||
jerryx_handler_print);
|
||||
/* Run the demo script with 'eval' */
|
||||
jerry_value_t eval_ret = jerry_eval (script,
|
||||
script_size,
|
||||
JERRY_PARSE_NO_OPTS);
|
||||
|
||||
/* Check if there was any error (syntax or runtime) */
|
||||
bool run_ok = !jerry_value_is_error (eval_ret);
|
||||
|
||||
/* Parsed source code must be freed */
|
||||
jerry_release_value (eval_ret);
|
||||
|
||||
/* Cleanup engine */
|
||||
jerry_cleanup ();
|
||||
|
||||
return (run_ok ? 0 : 1);
|
||||
}
|
||||
```
|
||||
|
||||
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-libm)
|
||||
```
|
||||
|
||||
If everything is correct the application returns with a zero exit code:
|
||||
|
||||
```
|
||||
$ ./api-example-2
|
||||
$ echo $?
|
||||
```
|
||||
|
||||
## Example 3. Split JavaScript parsing and script execution
|
||||
|
||||
In this example the `jerry_eval` is replaced with a more common API calls:
|
||||
|
||||
- script code setup - `jerry_parse`.
|
||||
- script execution - `jerry_run`.
|
||||
|
||||
The `api-example-3.c` file should contain the following code:
|
||||
|
||||
[doctest]: # ()
|
||||
|
||||
```c
|
||||
#include "jerryscript.h"
|
||||
|
||||
int
|
||||
main (void)
|
||||
{
|
||||
bool run_ok = false;
|
||||
|
||||
const jerry_char_t script[] = "var str = 'Hello, World!';";
|
||||
|
||||
/* Initialize engine */
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
/* Setup Global scope code */
|
||||
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
|
||||
|
||||
/* Check if there is any JS code parse error */
|
||||
if (!jerry_value_is_error (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);
|
||||
|
||||
/* 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 (run_ok ? 0 : 1);
|
||||
}
|
||||
```
|
||||
|
||||
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-libm)
|
||||
```
|
||||
|
||||
If everything is correct the application returns with a zero exit code:
|
||||
|
||||
```
|
||||
$ ./api-example-3
|
||||
$ echo $?
|
||||
```
|
||||
|
||||
## Example 4. Adding a C method for JavaScript
|
||||
|
||||
The previous examples were not that eye catching as there were no visual output by the JavaScript code
|
||||
and C program.
|
||||
|
||||
In this example a very simple "print" method is added which prints out a static string.
|
||||
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`
|
||||
|
||||
The `api-example-4.c` file should contain the following code:
|
||||
|
||||
[doctest]: # ()
|
||||
|
||||
```c
|
||||
#include <stdio.h>
|
||||
#include "jerryscript.h"
|
||||
|
||||
static jerry_value_t
|
||||
print_handler (const jerry_value_t function_object,
|
||||
const jerry_value_t function_this,
|
||||
const jerry_value_t arguments[],
|
||||
const jerry_length_t argument_count)
|
||||
{
|
||||
/* No arguments are used in this example */
|
||||
/* Print out a static string */
|
||||
printf ("Print handler was called\n");
|
||||
|
||||
/* Return an "undefined" value to the JavaScript engine */
|
||||
return jerry_create_undefined ();
|
||||
}
|
||||
|
||||
int
|
||||
main (void)
|
||||
{
|
||||
const jerry_char_t script[] = "print ();";
|
||||
const jerry_length_t script_size = sizeof (script) - 1;
|
||||
|
||||
/* Initialize engine */
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
/* Add the "print" method for the JavaScript global object */
|
||||
{
|
||||
/* Get the "global" object */
|
||||
jerry_value_t global_object = jerry_get_global_object ();
|
||||
/* Create a "print" JS string */
|
||||
jerry_value_t property_name_print = jerry_create_string ((const jerry_char_t *) "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);
|
||||
/* 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);
|
||||
|
||||
/* Check if there was no error when adding the property (in this case it should never happen) */
|
||||
if (jerry_value_is_error (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);
|
||||
}
|
||||
|
||||
/* Setup Global scope code */
|
||||
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
|
||||
|
||||
if (!jerry_value_is_error (parsed_code))
|
||||
{
|
||||
/* Execute the parsed source code in the Global scope */
|
||||
@@ -82,46 +291,118 @@ main (void)
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
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-libm)
|
||||
```
|
||||
|
||||
If everything is correct the application should print out the message present in the `print_handler` method:
|
||||
|
||||
```
|
||||
$ ./api-example-4
|
||||
```
|
||||
|
||||
## Example 5. Passing and processing arguments for native C code
|
||||
|
||||
In the previous example the `print_handler` simply wrote a static string to the standard output.
|
||||
However in most cases this is not useful, ideally the method's argument(s) should be printed.
|
||||
|
||||
In this example the `print_handler` is extended to convert the first
|
||||
argument (which probably comes from a JavaScript source) to a JS string and prints it out to the standard output.
|
||||
|
||||
New API methods used:
|
||||
|
||||
- `jerry_value_to_string`
|
||||
- `jerry_string_to_utf8_char_buffer`
|
||||
|
||||
The `api-example-5.c` file should contain the following code:
|
||||
|
||||
[doctest]: # ()
|
||||
|
||||
```c
|
||||
#include <stdio.h>
|
||||
#include "jerryscript.h"
|
||||
#include "jerryscript-ext/handler.h"
|
||||
|
||||
static jerry_value_t
|
||||
print_handler (const jerry_value_t function_object,
|
||||
const jerry_value_t function_this,
|
||||
const jerry_value_t arguments[],
|
||||
const jerry_length_t arguments_count)
|
||||
{
|
||||
/* There should be at least one argument */
|
||||
if (arguments_count > 0)
|
||||
{
|
||||
/* Convert the first argument to a string (JS "toString" operation) */
|
||||
jerry_value_t string_value = jerry_value_to_string (arguments[0]);
|
||||
|
||||
/* A naive allocation of buffer for the string */
|
||||
jerry_char_t buffer[256];
|
||||
|
||||
/* Copy the whole string to the buffer, without a null termination character,
|
||||
* 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);
|
||||
buffer[copied_bytes] = '\0';
|
||||
|
||||
/* Release the "toString" result */
|
||||
jerry_release_value (string_value);
|
||||
|
||||
printf ("%s\n", (const char *)buffer);
|
||||
}
|
||||
|
||||
/* Return an "undefined" value to the JavaScript engine */
|
||||
return jerry_create_undefined ();
|
||||
}
|
||||
|
||||
int
|
||||
main (void)
|
||||
{
|
||||
const jerry_char_t script_1[] = "var s = 'Hello, World!';";
|
||||
const jerry_char_t script_2[] = "print (s);";
|
||||
const jerry_char_t script[] = "print ('Hello from JS!');";
|
||||
const jerry_length_t script_size = sizeof (script) - 1;
|
||||
|
||||
/* Initialize engine */
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
/* Register 'print' function from the extensions */
|
||||
jerryx_handler_register_global ((const jerry_char_t *) "print",
|
||||
jerryx_handler_print);
|
||||
/* Add the "print" method for the JavaScript global object */
|
||||
{
|
||||
/* Get the "global" object */
|
||||
jerry_value_t global_object = jerry_get_global_object ();
|
||||
/* Create a "print" JS string */
|
||||
jerry_value_t property_name_print = jerry_create_string ((const jerry_char_t *) "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);
|
||||
/* 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 eval_ret;
|
||||
/* Check if there was no error when adding the property (in this case it should never happen) */
|
||||
if (jerry_value_is_error (set_result)) {
|
||||
printf ("Failed to add the 'print' property\n");
|
||||
}
|
||||
|
||||
/* Evaluate script1 */
|
||||
eval_ret = jerry_eval (script_1,
|
||||
sizeof (script_1) - 1,
|
||||
JERRY_PARSE_NO_OPTS);
|
||||
/* 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);
|
||||
}
|
||||
|
||||
/* Free JavaScript value, returned by eval */
|
||||
jerry_release_value (eval_ret);
|
||||
/* Setup Global scope code */
|
||||
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
|
||||
|
||||
/* Evaluate script2 */
|
||||
eval_ret = jerry_eval (script_2,
|
||||
sizeof (script_2) - 1,
|
||||
JERRY_PARSE_NO_OPTS);
|
||||
if (!jerry_value_is_error (parsed_code))
|
||||
{
|
||||
/* Execute the parsed source code in the Global scope */
|
||||
jerry_value_t ret_value = jerry_run (parsed_code);
|
||||
|
||||
/* Free JavaScript value, returned by eval */
|
||||
jerry_release_value (eval_ret);
|
||||
/* 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 ();
|
||||
@@ -130,9 +411,93 @@ main (void)
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
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-libm)
|
||||
```
|
||||
|
||||
If everything is correct the application should print out the string passed for the `print` method in the JS code:
|
||||
|
||||
```
|
||||
$ ./api-example-5
|
||||
```
|
||||
|
||||
|
||||
## Example 6. Using JerryScript Extensions
|
||||
|
||||
Some of the previous examples used a "print" method to write data out to the standard output.
|
||||
For convenience JerryScript provides an extension to add a simple "print" handler which
|
||||
can be used by other applications.
|
||||
|
||||
In this example the following extension methods are used:
|
||||
|
||||
- `jerryx_handler_register_global`
|
||||
- `jerryx_handler_print`
|
||||
|
||||
In further examples this "print" handler will be used.
|
||||
|
||||
```c
|
||||
#include "jerryscript.h"
|
||||
#include "jerryscript-ext/handler.h"
|
||||
|
||||
int
|
||||
main (void)
|
||||
{
|
||||
const jerry_char_t script[] = "print ('Hello from JS with ext!');";
|
||||
const jerry_length_t script_size = sizeof (script) - 1;
|
||||
|
||||
/* Initialize engine */
|
||||
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);
|
||||
|
||||
/* Setup Global scope code */
|
||||
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
|
||||
|
||||
if (!jerry_value_is_error (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;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
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.
|
||||
|
||||
```sh
|
||||
$ gcc api-example-6.c -o api-example-6 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-libm)
|
||||
```
|
||||
|
||||
If everything is correct the application should print out the string passed for the `print` method in the JS code:
|
||||
|
||||
```
|
||||
$ ./api-example-6
|
||||
```
|
||||
|
||||
## Example 7. Interaction with JavaScript environment - adding a string property
|
||||
|
||||
Previously a C method was registered for the global object, now this examples show how one can add a string
|
||||
property.
|
||||
|
||||
Use the following code as the `api-example-7.c` file:
|
||||
|
||||
[doctest]: # ()
|
||||
|
||||
@@ -143,8 +508,7 @@ This way, we execute two independent script parts in one execution environment.
|
||||
int
|
||||
main (void)
|
||||
{
|
||||
const jerry_char_t str[] = "Hello, World!";
|
||||
const jerry_char_t script[] = "print (s);";
|
||||
const jerry_char_t script[] = "print (my_var);";
|
||||
|
||||
/* Initializing JavaScript environment */
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
@@ -157,11 +521,16 @@ main (void)
|
||||
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);
|
||||
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!");
|
||||
|
||||
/* Setting the string value as a property of the Global object */
|
||||
jerry_release_value (jerry_set_property (global_object, prop_name, prop_value));
|
||||
jerry_value_t set_result = jerry_set_property (global_object, prop_name, prop_value);
|
||||
/* The 'set_result' should be checked if there was any error */
|
||||
if (jerry_value_is_error (set_result)) {
|
||||
printf ("Failed to add the 'my_var' property\n");
|
||||
}
|
||||
jerry_release_value (set_result);
|
||||
|
||||
/* Releasing string values, as it is no longer necessary outside of engine */
|
||||
jerry_release_value (prop_name);
|
||||
@@ -185,16 +554,46 @@ main (void)
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
To compile it one can use the following command:
|
||||
|
||||
## Step 5. Description of JerryScript value descriptors
|
||||
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call.
|
||||
|
||||
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.
|
||||
```sh
|
||||
$ gcc api-example-7.c -o api-example-7 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-libm)
|
||||
```
|
||||
|
||||
The following example function will output a JavaScript value:
|
||||
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:
|
||||
|
||||
```
|
||||
$ ./api-example-7
|
||||
```
|
||||
|
||||
## Example 8. Description of JerryScript value descriptors
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
For example in JS such object be created with the following code example:
|
||||
|
||||
```js
|
||||
var error_object = new Error ("error message");
|
||||
```
|
||||
|
||||
- The error value is not an object on its own. This is the exception raised/thrown either via API methods or from JS.
|
||||
For example, creating such error value in JS would look like this:
|
||||
|
||||
```js
|
||||
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.
|
||||
For example the following code snippet could print out a few types (not all types are checked):
|
||||
|
||||
[doctest]: # (test="compile")
|
||||
|
||||
@@ -204,8 +603,20 @@ The following example function will output a JavaScript value:
|
||||
#include "jerryscript.h"
|
||||
|
||||
static void
|
||||
print_value (const jerry_value_t value)
|
||||
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))
|
||||
{
|
||||
printf ("Error value detected: ");
|
||||
value = jerry_get_value_from_error (jsvalue, false);
|
||||
}
|
||||
else
|
||||
{
|
||||
value = jerry_acquire_value (jsvalue);
|
||||
}
|
||||
|
||||
if (jerry_value_is_undefined (value))
|
||||
{
|
||||
printf ("undefined");
|
||||
@@ -228,7 +639,7 @@ print_value (const jerry_value_t value)
|
||||
/* Float value */
|
||||
else if (jerry_value_is_number (value))
|
||||
{
|
||||
printf ("number");
|
||||
printf ("number: %lf", jerry_get_number_value (value));
|
||||
}
|
||||
/* String value */
|
||||
else if (jerry_value_is_string (value))
|
||||
@@ -249,10 +660,11 @@ print_value (const jerry_value_t value)
|
||||
}
|
||||
|
||||
printf ("\n");
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
## Simple JavaScript shell
|
||||
## Example 8: Simple JavaScript shell
|
||||
|
||||
Now all building blocks, necessary to construct JavaScript shell, are ready.
|
||||
|
||||
@@ -266,7 +678,9 @@ Shell operation can be described with the following loop:
|
||||
- print result of eval;
|
||||
- loop.
|
||||
|
||||
[doctest]: # (test="compile")
|
||||
See the following `api-example-8-shell.c` file:
|
||||
|
||||
[doctest]: # (test="link")
|
||||
|
||||
```c
|
||||
#include <stdio.h>
|
||||
@@ -275,7 +689,67 @@ Shell operation can be described with the following loop:
|
||||
#include "jerryscript.h"
|
||||
#include "jerryscript-ext/handler.h"
|
||||
|
||||
void print_value (const jerry_value_t);
|
||||
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))
|
||||
{
|
||||
printf ("Error value detected: ");
|
||||
value = jerry_get_value_from_error (jsvalue, false);
|
||||
}
|
||||
else
|
||||
{
|
||||
value = jerry_acquire_value (jsvalue);
|
||||
}
|
||||
|
||||
if (jerry_value_is_undefined (value))
|
||||
{
|
||||
printf ("undefined");
|
||||
}
|
||||
else if (jerry_value_is_null (value))
|
||||
{
|
||||
printf ("null");
|
||||
}
|
||||
else if (jerry_value_is_boolean (value))
|
||||
{
|
||||
if (jerry_get_boolean_value (value))
|
||||
{
|
||||
printf ("true");
|
||||
}
|
||||
else
|
||||
{
|
||||
printf ("false");
|
||||
}
|
||||
}
|
||||
/* Float value */
|
||||
else if (jerry_value_is_number (value))
|
||||
{
|
||||
printf ("number: %lf", jerry_get_number_value (value));
|
||||
}
|
||||
/* 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 + 1];
|
||||
|
||||
jerry_string_to_char_buffer (value, str_buf_p, req_sz);
|
||||
str_buf_p[req_sz] = '\0';
|
||||
|
||||
printf ("%s", (const char *) str_buf_p);
|
||||
}
|
||||
/* Object reference */
|
||||
else if (jerry_value_is_object (value))
|
||||
{
|
||||
printf ("[JS object]");
|
||||
}
|
||||
|
||||
printf ("\n");
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
|
||||
int
|
||||
main (void)
|
||||
@@ -327,15 +801,9 @@ main (void)
|
||||
len,
|
||||
JERRY_PARSE_NO_OPTS);
|
||||
|
||||
/* If command evaluated successfully, print value, returned by eval */
|
||||
if (jerry_value_is_error (ret_val))
|
||||
{
|
||||
/* Evaluated JS code thrown an exception
|
||||
* and didn't handle it with try-catch-finally */
|
||||
printf ("Unhandled JS exception occurred: ");
|
||||
}
|
||||
|
||||
/* Print out the value */
|
||||
print_value (ret_val);
|
||||
|
||||
jerry_release_value (ret_val);
|
||||
}
|
||||
|
||||
@@ -346,11 +814,24 @@ main (void)
|
||||
}
|
||||
```
|
||||
|
||||
The application inputs commands and evaluates them, one after another.
|
||||
To compile it one can use the following command:
|
||||
|
||||
## Step 6. Creating JS object in global context
|
||||
(**Note** that the `libjerry-ext` was added **before** the `libjerry-port-default` entry for the `pkg-config` call.
|
||||
|
||||
In this example we demonstrate how to use native function and structures in JavaScript.
|
||||
```sh
|
||||
$ gcc api-example-8-shell.c -o api-example-8-shell $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-libm)
|
||||
```
|
||||
|
||||
The application reads lines from standard input and evaluates them, one after another. To try out run:
|
||||
|
||||
```
|
||||
$ ./api-example-8-shell
|
||||
```
|
||||
|
||||
|
||||
## Example 9. Creating JS object in global context
|
||||
|
||||
In this example (`api-example-9.c`) an object with a native function is added to the global object.
|
||||
|
||||
[doctest]: # ()
|
||||
|
||||
@@ -433,15 +914,33 @@ 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.
|
||||
|
||||
```sh
|
||||
$ gcc api-example-9.c -o api-example-9 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-libm)
|
||||
```
|
||||
|
||||
Execute the example with:
|
||||
|
||||
```
|
||||
$ ./api-example-9
|
||||
```
|
||||
|
||||
The application will generate the following output:
|
||||
|
||||
```bash
|
||||
Hello World
|
||||
Hello, World
|
||||
```
|
||||
|
||||
## Step 7. Extending JS Objects with native functions
|
||||
## Example 10. 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.
|
||||
The example creates a JS Object with `jerry_eval`, then it is extended from C with a native function.
|
||||
In addition this native function shows how to get a property value from the object and how to manipulate it.
|
||||
|
||||
|
||||
Use the following code for `api-example-10.c`:
|
||||
|
||||
[doctest]: # ()
|
||||
|
||||
@@ -455,9 +954,12 @@ Here we create a JS Object with `jerry_eval`, then extend it with a native funct
|
||||
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_value_t args_p[], /**< function arguments */
|
||||
const jerry_length_t args_cnt) /**< number of function arguments */
|
||||
{
|
||||
/* The the 'this_val' is the 'MyObject' from the JS code below */
|
||||
/* 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 (this_val, prop_name);
|
||||
@@ -466,7 +968,7 @@ add_handler (const jerry_value_t func_value, /**< function object */
|
||||
{
|
||||
/* Convert Jerry API values to double */
|
||||
double x = jerry_get_number_value (x_val);
|
||||
double d = jerry_get_number_value (*args_p);
|
||||
double d = jerry_get_number_value (args_p[0]);
|
||||
|
||||
/* Add the parameter to 'x' */
|
||||
jerry_value_t res_val = jerry_create_number (x + d);
|
||||
@@ -543,14 +1045,26 @@ main (void)
|
||||
}
|
||||
```
|
||||
|
||||
The application will generate the following output:
|
||||
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.
|
||||
|
||||
```sh
|
||||
$ gcc api-example-10.c -o api-example-10 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-libm)
|
||||
```
|
||||
|
||||
Execute the example with:
|
||||
|
||||
```
|
||||
$ ./api-example-10
|
||||
```
|
||||
|
||||
```bash
|
||||
Value of x is 12
|
||||
Value of x is 17
|
||||
```
|
||||
|
||||
## Step 8. Changing the seed of pseudorandom generated numbers
|
||||
## 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.
|
||||
@@ -594,4 +1108,4 @@ main (void)
|
||||
|
||||
## Further steps
|
||||
|
||||
For further API description, please visit [API Reference page](https://pando-project.github.io/jerryscript/api-reference/) on [JerryScript home page](https://pando-project.github.io/jerryscript/).
|
||||
For further API description, please visit [API Reference page](https://jerryscript-project.github.io/jerryscript/api-reference/) on [JerryScript home page](https://jerryscript-project.github.io/jerryscript/).
|
||||
|
||||
+18
-17
@@ -33,7 +33,7 @@ Expression parser is responsible for parsing JavaScript expressions. It is imple
|
||||
|
||||
JavaScript statements are parsed by this component. It uses the [Expression parser](#expression-parser) to parse the constituent expressions. The implementation of Statement parser is located in `./jerry-core/parser/js/js-parser-statm.c`.
|
||||
|
||||
Function `parser_parse_source` carries out the parsing and compiling of the input EcmaScript source code. When a function appears in the source `parser_parse_source` calls `parser_parse_function` which is responsible for processing the source code of functions recursively including argument parsing and context handling. After the parsing, function `parser_post_processing` dumps the created opcodes and returns an `ecma_compiled_code_t*` that points to the compiled bytecode sequence.
|
||||
Function `parser_parse_source` carries out the parsing and compiling of the input ECMAScript source code. When a function appears in the source `parser_parse_source` calls `parser_parse_function` which is responsible for processing the source code of functions recursively including argument parsing and context handling. After the parsing, function `parser_post_processing` dumps the created opcodes and returns an `ecma_compiled_code_t*` that points to the compiled bytecode sequence.
|
||||
|
||||
The interactions between the major components shown on the following figure.
|
||||
|
||||
@@ -43,19 +43,19 @@ The interactions between the major components shown on the following figure.
|
||||
|
||||
This section describes the compact byte-code (CBC) representation. The key focus is reducing memory consumption of the byte-code representation without sacrificing considerable performance. Other byte-code representations often focus on performance only so inventing this representation is an original research.
|
||||
|
||||
CBC is a CISC like instruction set which assigns shorter instructions for frequent operations. Many instructions represent multiple atomic tasks which reduces the byte code size. This technique is basically a data compression method.
|
||||
CBC is a CISC like instruction set which assigns shorter instructions for frequent operations. Many instructions represent multiple atomic tasks which reduces the bytecode size. This technique is basically a data compression method.
|
||||
|
||||
## Compiled Code Format
|
||||
|
||||
The memory layout of the compiled byte code is the following.
|
||||
The memory layout of the compiled bytecode is the following.
|
||||
|
||||
{: class="thumbnail center-block img-responsive" }
|
||||
|
||||
The header is a `cbc_compiled_code` structure with several fields. These fields contain the key properties of the compiled code.
|
||||
|
||||
The literals part is an array of ecma values. These values can contain any EcmaScript value types, e.g. strings, numbers, function and regexp templates. The number of literals is stored in the `literal_end` field of the header.
|
||||
The literals part is an array of ecma values. These values can contain any ECMAScript value types, e.g. strings, numbers, functions and regexp templates. The number of literals is stored in the `literal_end` field of the header.
|
||||
|
||||
CBC instruction list is a sequence of byte code instructions which represents the compiled code.
|
||||
CBC instruction list is a sequence of bytecode instructions which represents the compiled code.
|
||||
|
||||
## Byte-code Format
|
||||
|
||||
@@ -65,7 +65,7 @@ The memory layout of a byte-code is the following:
|
||||
|
||||
Each byte-code starts with an opcode. The opcode is one byte long for frequent and two byte long for rare instructions. The first byte of the rare instructions is always zero (`CBC_EXT_OPCODE`), and the second byte represents the extended opcode. The name of common and rare instructions start with `CBC_` and `CBC_EXT_` prefix respectively.
|
||||
|
||||
The maximum number of opcodes is 511, since 255 common (zero value excluded) and 256 rare instructions can be defined. Currently around 230 frequent and 120 rare instructions are available.
|
||||
The maximum number of opcodes is 511, since 255 common (zero value excluded) and 256 rare instructions can be defined. Currently around 215 frequent and 70 rare instructions are available.
|
||||
|
||||
There are three types of bytecode arguments in CBC:
|
||||
|
||||
@@ -73,7 +73,7 @@ There are three types of bytecode arguments in CBC:
|
||||
|
||||
* __literal argument__: An integer index which is greater or equal than zero and less than the `literal_end` field of the header. For further information see next section Literals (next).
|
||||
|
||||
* __relative branch__: An 1-3 byte long offset. The branch argument might also represent the end of an instruction range. For example the branch argument of `CBC_EXT_WITH_CREATE_CONTEXT` shows the end of a `with` statement. More precisely the position after the last instruction.
|
||||
* __relative branch__: An 1-3 byte long offset. The branch argument might also represent the end of an instruction range. For example the branch argument of `CBC_EXT_WITH_CREATE_CONTEXT` shows the end of a `with` statement. More precisely the position after the last instruction in the with clause.
|
||||
|
||||
Argument combinations are limited to the following seven forms:
|
||||
|
||||
@@ -147,11 +147,11 @@ Byte-codes of this category serve for placing objects onto the stack. As there a
|
||||
|
||||
<div class="CSSTableGenerator" markdown="block">
|
||||
|
||||
| byte-code | description |
|
||||
| CBC_PUSH_LITERAL | Pushes the value of the given literal argument. |
|
||||
| CBC_PUSH_TWO_LITERALS | Pushes the value of the given two literal arguments. |
|
||||
| CBC_PUSH_UNDEFINED | Pushes an undefined value. |
|
||||
| CBC_PUSH_TRUE | Pushes a logical true. |
|
||||
| byte-code | description |
|
||||
| CBC_PUSH_LITERAL | Pushes the value of the given literal argument. |
|
||||
| CBC_PUSH_TWO_LITERALS | Pushes the values of the given two literal arguments. |
|
||||
| CBC_PUSH_UNDEFINED | Pushes an undefined value. |
|
||||
| CBC_PUSH_TRUE | Pushes a logical true. |
|
||||
| CBC_PUSH_PROP_LITERAL | Pushes a property whose base object is popped from the stack, and the property name is passed as a literal argument. |
|
||||
|
||||
</div>
|
||||
@@ -202,7 +202,7 @@ Branch byte-codes are used to perform conditional and unconditional jumps in the
|
||||
| CBC_JUMP_BACKWARD | Jumps backward by the 1 byte long relative offset argument. |
|
||||
| CBC_JUMP_BACKWARD_2 | Jumps backward by the 2 byte long relative offset argument. |
|
||||
| CBC_JUMP_BACKWARD_3 | Jumps backward by the 3 byte long relative offset argument. |
|
||||
| CBC_BRANCH_IF_TRUE_FORWARD | Jumps if the value on the top of the stack is true by the 1 byte long relative offset argument. |
|
||||
| CBC_BRANCH_IF_TRUE_FORWARD | Jumps forward if the value on the top of the stack is true by the 1 byte long relative offset argument. |
|
||||
|
||||
</div>
|
||||
|
||||
@@ -225,12 +225,14 @@ ECMA component of the engine is responsible for the following notions:
|
||||
|
||||
## Data Representation
|
||||
|
||||
The major structure for data representation is `ECMA_value`. The lower two bits of this structure encode value tag, which determines the type of the value:
|
||||
The major structure for data representation is `ECMA_value`. The lower three bits of this structure encode value tag, which determines the type of the value:
|
||||
|
||||
* simple
|
||||
* number
|
||||
* string
|
||||
* object
|
||||
* symbol
|
||||
* error
|
||||
|
||||
{: class="thumbnail center-block img-responsive" }
|
||||
|
||||
@@ -259,7 +261,7 @@ system. These "uncompressed pointers" increases the memory consumption by around
|
||||
|
||||
There are two possible representation of numbers according to standard IEEE 754:
|
||||
The default is 8-byte (double),
|
||||
but the engine supports the 4-byte (single precision) representation by setting CONFIG_ECMA_NUMBER_TYPE as well.
|
||||
but the engine supports the 4-byte (single precision) representation by setting JERRY_NUMBER_TYPE_FLOAT64 to 0 as well.
|
||||
|
||||
{: class="thumbnail center-block img-responsive" }
|
||||
|
||||
@@ -281,7 +283,6 @@ The objects are represented as following structure:
|
||||
|
||||
* Reference counter - number of hard (non-property) references
|
||||
* Next object pointer for the garbage collector
|
||||
* GC's visited flag
|
||||
* type (function object, lexical environment, etc.)
|
||||
|
||||
### Properties of Objects
|
||||
@@ -329,7 +330,7 @@ Collections are array-like data structures, which are optimized to save memory.
|
||||
|
||||
### Exception Handling
|
||||
|
||||
In order to implement a sense of exception handling, the return values of JerryScript functions are able to indicate their faulty or "exceptional" operation. The return values are actually ECMA values (see section [Data Representation](#data-representation)) in which the error bit is set if an erroneous operation is occurred.
|
||||
In order to implement a sense of exception handling, the return values of JerryScript functions are able to indicate their faulty or "exceptional" operation. The return values are ECMA values (see section [Data Representation](#data-representation)) and if an erroneous operation occurred the ECMA_VALUE_ERROR simple value is returned.
|
||||
|
||||
### Value Management and Ownership
|
||||
|
||||
|
||||
+28
-10
@@ -75,8 +75,8 @@ typedef enum
|
||||
* vfprintf(logfile), or both, depending on log level.
|
||||
*
|
||||
* Note:
|
||||
* This port function is called by jerry-core when JERRY_ENABLE_LOGGING is
|
||||
* defined. It is also common practice though to use this function in
|
||||
* 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, ...);
|
||||
@@ -95,7 +95,8 @@ void jerry_port_print_char (char c);
|
||||
|
||||
### ES2015 Module system helper functions
|
||||
|
||||
The import statement requires two specific functions for opening and closing files (the modules) port specific.
|
||||
The module system requires two specific functions for opening and closing files.
|
||||
It also requires a platform specific way of normalizing file paths.
|
||||
|
||||
```c
|
||||
/**
|
||||
@@ -118,6 +119,23 @@ jerry_port_release_source (uint8_t *buffer_p) /**< buffer to free */
|
||||
{
|
||||
free (buffer_p);
|
||||
} /* jerry_port_release_source */
|
||||
|
||||
/**
|
||||
* Normalize a file path
|
||||
*
|
||||
* @return length of the path written to the output buffer
|
||||
*/
|
||||
size_t
|
||||
jerry_port_normalize_path (const char *in_path_p, /**< input file path */
|
||||
char *out_buf_p, /**< output buffer */
|
||||
size_t out_buf_size, /**< size of output buffer */
|
||||
char *base_file_p) /**< base file path */
|
||||
{
|
||||
// normalize in_path_p by expanding relative paths etc.
|
||||
// if base_file_p is not NULL, in_path_p is relative to that file
|
||||
// write to out_buf_p the normalized path
|
||||
// return length of written path
|
||||
} /* jerry_port_normalize_path */
|
||||
```
|
||||
|
||||
## Date
|
||||
@@ -139,7 +157,7 @@ jerry_port_release_source (uint8_t *buffer_p) /**< buffer to free */
|
||||
*
|
||||
* Note:
|
||||
* This port function is called by jerry-core when
|
||||
* CONFIG_DISABLE_DATE_BUILTIN is _not_ defined. Otherwise this function is
|
||||
* 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
|
||||
@@ -161,7 +179,7 @@ double jerry_port_get_local_time_zone_adjustment (double unix_ms, bool is_utc);
|
||||
*
|
||||
* Note:
|
||||
* This port function is called by jerry-core when
|
||||
* CONFIG_DISABLE_DATE_BUILTIN is _not_ defined. It is also common practice
|
||||
* 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.
|
||||
*
|
||||
@@ -183,7 +201,7 @@ simultaneously.
|
||||
*
|
||||
* Note:
|
||||
* This port function is called by jerry-core when
|
||||
* JERRY_ENABLE_EXTERNAL_CONTEXT is defined. Otherwise this function is not
|
||||
* JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not
|
||||
* used.
|
||||
*
|
||||
* @return the pointer to the engine context.
|
||||
@@ -198,8 +216,8 @@ struct jerry_context_t *jerry_port_get_current_context (void);
|
||||
* Makes the process sleep for a given time.
|
||||
*
|
||||
* Note:
|
||||
* This port function is called by jerry-core when JERRY_DEBUGGER is
|
||||
* defined. Otherwise this function is not used.
|
||||
* This port function is called by jerry-core when JERRY_DEBUGGER is set to 1.
|
||||
* Otherwise this function is not used.
|
||||
*
|
||||
* @param sleep_time milliseconds to sleep.
|
||||
*/
|
||||
@@ -345,7 +363,7 @@ jerry_port_get_current_context (void)
|
||||
#include <unistd.h>
|
||||
#endif /* HAVE_TIME_H */
|
||||
|
||||
#ifdef JERRY_DEBUGGER
|
||||
#if defined (JERRY_DEBUGGER) && (JERRY_DEBUGGER == 1)
|
||||
void jerry_port_sleep (uint32_t sleep_time)
|
||||
{
|
||||
#ifdef HAVE_TIME_H
|
||||
@@ -359,5 +377,5 @@ void jerry_port_sleep (uint32_t sleep_time)
|
||||
#endif /* HAVE_TIME_H */
|
||||
(void) sleep_time;
|
||||
} /* jerry_port_sleep */
|
||||
#endif /* JERRY_DEBUGGER */
|
||||
#endif /* defined (JERRY_DEBUGGER) && (JERRY_DEBUGGER == 1) */
|
||||
```
|
||||
|
||||
+416
-1
@@ -8,6 +8,421 @@ permalink: /ext-reference-handler/
|
||||
* toc
|
||||
{:toc}
|
||||
|
||||
# Common methods to handle properties
|
||||
|
||||
The `jerryscript-ext/handler.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 exsits 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
|
||||
for this the following utility structures and methods are provided.
|
||||
|
||||
## jerryx_property_entry
|
||||
|
||||
**Summary**
|
||||
|
||||
Structure to define an array of properties with `name` and `value` fields which
|
||||
can be registered to a target object.
|
||||
|
||||
The engine must be initialied before specifying the `jerry_value_t` in the struct.
|
||||
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
const char *name;
|
||||
jerry_value_t value;
|
||||
} jerryx_function_list_entry;
|
||||
```
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerryx_set_properties](#jerryx_set_properties)
|
||||
|
||||
|
||||
## jerryx_register_result
|
||||
|
||||
**Summary**
|
||||
|
||||
Structure returned as the result of the [jerryx_set_properties](#jerryx_set_properties) operation.
|
||||
The `result` field will either be a JavaScript undefined value or an error object.
|
||||
In every case the `registered` field is used to indicated the number of
|
||||
successfully registered methods.
|
||||
|
||||
This must be passed for the [jerryx_release_property_entry](#jerryx_release_property_entry) method
|
||||
after the property registration.
|
||||
|
||||
If any error occured during the property registration the `result` field of the structure
|
||||
must be manually released after processing the error value.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
jerry_value_t result;
|
||||
uint32_t registered;
|
||||
} jerryx_register_result;
|
||||
```
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerryx_set_properties](#jerryx_set_properties)
|
||||
- [jerryx_release_property_entry](#jerryx_release_property_entry)
|
||||
|
||||
|
||||
## jerryx_set_properties
|
||||
|
||||
**Summary**
|
||||
|
||||
Set multiple properties on a target object.
|
||||
|
||||
The properties are an array of (name, jerry_value_t) pairs and
|
||||
this list must end with a (NULL, 0) entry.
|
||||
|
||||
Important notes:
|
||||
* Each property value in the input array is released after a successful property registration.
|
||||
* The method [jerryx_release_property_entry](#jerryx_release_property_entry) must be called if there is any failed registration
|
||||
to release the values in the entries array.
|
||||
It is safe to call this cleanup method in every case not just in case of failure.
|
||||
* If the error value is reported via the result it must be freed manually.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```c
|
||||
jerryx_register_result
|
||||
jerryx_set_properties (const jerry_value_t target_object,
|
||||
const jerryx_property_entry entries[]);
|
||||
```
|
||||
|
||||
- `target_object` - object on which the entries will be set.
|
||||
- `entries` - array of (name, jerry_value_t) pairs.
|
||||
- return a [jerryx_register_result](#jerryx_register_result).
|
||||
- if everything is ok, the struct's `result` field is set to a JS undefined value.
|
||||
- otherwise the `result` field is an error object indicating the problem.
|
||||
- in every case the `registered` field contains the number of successfully registered properties.
|
||||
|
||||
**Example**
|
||||
|
||||
[doctest]: # ()
|
||||
|
||||
```c
|
||||
#include "jerryscript.h"
|
||||
#include "jerryscript-ext/handler.h"
|
||||
|
||||
static jerry_value_t
|
||||
handler (const jerry_value_t function_obj,
|
||||
const jerry_value_t this_val,
|
||||
const jerry_value_t args_p[],
|
||||
const jerry_length_t args_cnt)
|
||||
{
|
||||
printf ("native handler called!\n");
|
||||
|
||||
return jerry_create_boolean (true);
|
||||
}
|
||||
|
||||
int
|
||||
main (int argc, char **argv)
|
||||
{
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
jerryx_property_entry methods[] =
|
||||
{
|
||||
{ "demo", jerry_create_external_function (handler) },
|
||||
{ NULL, 0 },
|
||||
};
|
||||
|
||||
jerry_value_t global = jerry_get_global_object ();
|
||||
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))
|
||||
{
|
||||
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_release_value (global);
|
||||
|
||||
jerry_cleanup();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
**Convenience macros**
|
||||
|
||||
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_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.
|
||||
* `JERRYX_PROPERTY_LIST_END()` - indicates the end of the property list.
|
||||
|
||||
**Example usage of Convenience macros**
|
||||
|
||||
[doctest]: # ()
|
||||
|
||||
```c
|
||||
#include "jerryscript.h"
|
||||
#include "jerryscript-ext/handler.h"
|
||||
|
||||
static jerry_value_t
|
||||
handler (const jerry_value_t function_obj,
|
||||
const jerry_value_t this_val,
|
||||
const jerry_value_t args_p[],
|
||||
const jerry_length_t args_cnt)
|
||||
{
|
||||
printf ("native handler called!\n");
|
||||
|
||||
return jerry_create_boolean (true);
|
||||
}
|
||||
|
||||
int
|
||||
main (int argc, char **argv)
|
||||
{
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
/**
|
||||
* Create a array of properties to be registered.
|
||||
* This must be done after initializing the engine as creating `jerry_value_t`
|
||||
* elements are invalid before `jerry_init`.
|
||||
*/
|
||||
jerryx_property_entry methods[] =
|
||||
{
|
||||
JERRYX_PROPERTY_FUNCTION ("demo", handler),
|
||||
JERRYX_PROPERTY_NUMBER ("test_num", 2.3),
|
||||
JERRYX_PROPERTY_UNDEFINED ("this_is_undefined"),
|
||||
JERRYX_PROPERTY_LIST_END(),
|
||||
};
|
||||
|
||||
jerry_value_t global = jerry_get_global_object ();
|
||||
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))
|
||||
{
|
||||
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_release_value (global);
|
||||
|
||||
jerry_cleanup();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
**See also**
|
||||
|
||||
- [jerryx_property_entry](#jerryx_property_entry)
|
||||
- [jerryx_release_property_entry](#jerryx_release_property_entry)
|
||||
- [jerryx_register_result](#jerryx_register_result)
|
||||
|
||||
## jerryx_release_property_entry
|
||||
|
||||
**Summary**
|
||||
|
||||
Release all `jerry_value_t` in a `jerryx_property_entry` array based on a previous [jerryx_set_properties](#jerryx_set_properties) call
|
||||
and also the error value (if any) in the `jerryx_register_result` structure.
|
||||
In case of a successful registration it is safe to call this method.
|
||||
|
||||
After the method call the `ęntries` array should not be used as all values are released.
|
||||
|
||||
**Prototype**
|
||||
|
||||
```
|
||||
void
|
||||
jerryx_release_property_entry (const jerryx_property_entry entries[],
|
||||
const jerryx_register_result register_result);
|
||||
```
|
||||
|
||||
- `entires` - array of [jerryx_property_entry](#jerryx_property_entry).
|
||||
- `register_result` - result of a previous [jerryx_set_properties](#jerryx_set_properties) call.
|
||||
|
||||
**Example**
|
||||
|
||||
For example usage see [jerryx_set_properties](#jerryx_set_properties).
|
||||
|
||||
|
||||
# Common external function handlers
|
||||
|
||||
## jerryx_handler_assert_fatal
|
||||
@@ -79,7 +494,7 @@ An alias to `jerryx_handler_assert_fatal`.
|
||||
**Summary**
|
||||
|
||||
Expose garbage collector to scripts. If the first argument of the function
|
||||
is logical true, it performs a high severity gc. Otherwise a low severity
|
||||
is logical true, it performs a high pressure gc. Otherwise a low pressure
|
||||
gc is performed, which is also the default if no parameters passed.
|
||||
|
||||
**Prototype**
|
||||
|
||||
@@ -51,7 +51,7 @@ main (void)
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
test_handle_scope_val ();
|
||||
jerry_gc (JERRY_GC_SEVERITY_LOW);
|
||||
jerry_gc (JERRY_GC_PRESSURE_LOW);
|
||||
|
||||
jerry_cleanup ();
|
||||
} /* main */
|
||||
@@ -103,7 +103,7 @@ main (void)
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
test_handle_scope_val ();
|
||||
jerry_gc (JERRY_GC_SEVERITY_LOW);
|
||||
jerry_gc (JERRY_GC_PRESSURE_LOW);
|
||||
|
||||
jerry_cleanup ();
|
||||
} /* main */
|
||||
|
||||
+65
-39
@@ -10,35 +10,49 @@ permalink: /module-system/
|
||||
|
||||
# ES6 module support for JerryScript
|
||||
|
||||
The module system allows users to write import and export statements in scripts. Therefore the logic of the application could be separated in custom modules.
|
||||
The module system allows users to write import and export statements in scripts, which can be used to separate the logic of the application into custom modules.
|
||||
The standard's relevant part can be found [here](https://www.ecma-international.org/ecma-262/6.0/#sec-modules).
|
||||
|
||||
## General
|
||||
|
||||
If the main script contains import statements, then Jerry opens and runs the appropriate scripts before the main script (as the standard says). The script's and the module's extension is `.js`, custom extensions are unnecessary.
|
||||
If a script contains import statements, then JerryScript will open and evaluate the the referenced modules before the main script runs, resolving and creating bindings for the referenced identifiers in the process.
|
||||
It is not necessary to use any specific filename extensions for modules, JerryScript will try to open the given file paths as they are, but will try to normalize them before doing so. The exact normalization process is dependant on the port implementation provided. It is the user's responsibility to verify that the given files are valid EcmaScript modules.
|
||||
|
||||
main.js
|
||||
|
||||
```js
|
||||
import { secret_number } from "./module.js"
|
||||
import { exported_value } from "./module.js"
|
||||
|
||||
print (secret_number);
|
||||
print (exported_value);
|
||||
```
|
||||
|
||||
module.js
|
||||
|
||||
```js
|
||||
var secret_number = 42;
|
||||
var exported_value = 42;
|
||||
|
||||
export secret_number;
|
||||
export exported_value;
|
||||
```
|
||||
|
||||
## Supported features
|
||||
|
||||
* import variable or function
|
||||
* add alias name to the imported variable (function)
|
||||
* export variable or function
|
||||
* add alias name to the exported variable (function)
|
||||
* exporting identifiers from the module's lexical environment
|
||||
* specifying export names for the exported values
|
||||
* importing exported identifiers from a module
|
||||
* specifying local binding names for the imported values
|
||||
* module namespace imports
|
||||
* `import * as module from 'module.js`
|
||||
* indirect export statements
|
||||
* `export {variable} from 'module.js'`
|
||||
* star export statements
|
||||
* `export * from 'module.js'`
|
||||
* importing a module for side-effects
|
||||
* `import 'module.js'`
|
||||
* default import and export statements
|
||||
* `export default local_identifier`
|
||||
* `import def from 'module.js'`
|
||||
* anonymous default exports
|
||||
* `export default function () {}`
|
||||
|
||||
### Example
|
||||
|
||||
@@ -79,22 +93,20 @@ export function getFeatureDetails() {
|
||||
}
|
||||
```
|
||||
|
||||
## Unsupported features
|
||||
### Module namespace import statements
|
||||
|
||||
* **snapshot**
|
||||
* errors from the imported scripts
|
||||
* redirection ( `export { a, b } from 'module.js'` )
|
||||
* default import and export
|
||||
* `import b from 'module.js'`
|
||||
* `export default b`,
|
||||
* whole module import statements
|
||||
* `import * from 'module.js`
|
||||
* `import { * as module } from 'module.js`
|
||||
* object freezing ( `Object.freeze (this)` )
|
||||
A module namespace object can be imported. In this case the local binding will contain an object holding the exported values of the module, including local exports and all indirect exports. Ambiguous exported names are exluded from the namespace object.
|
||||
|
||||
### Redirection
|
||||
```js
|
||||
import * as module from './module.js';
|
||||
|
||||
An export statement can import variables from a custom module and export it directly from the current script. This statement is called redirection. In this case the `export { b } from 'module2.js'` works as the `b` was imported before then exported as a local variable.
|
||||
print(">> Engine: " + module.engine);
|
||||
print(">> Version: " + module.version);
|
||||
```
|
||||
|
||||
### Indirect export statements
|
||||
|
||||
An export statement can transitively export variables from another module, either via named indirect exports or a star export statement. In this case the resolving process will follow the chain until it reaches a module containing a local binding for that export name. If there are multiple modules which satisfy the export, that means the export is ambiguous, and will result in a SyntaxError.
|
||||
|
||||
```js
|
||||
import { a, b } from 'module.js'
|
||||
@@ -115,28 +127,42 @@ export var b = 40;
|
||||
|
||||
### Default imports and exports
|
||||
|
||||
TODO: This part is going to be written in the next part of the patch.
|
||||
|
||||
### Import the whole module
|
||||
|
||||
The whole module can be imported. In this case the `m` object would contain the exported parts of the module. If the import is not aliased, the `global object` would contain the exports.
|
||||
Each module can optionally provide a single default export by using the `export default` statement. Default exports can either reference identifiers in the module's lexical environment, or be an anonymous default export, in which case they will only be accessible by an importing script.
|
||||
|
||||
```js
|
||||
import { * as m } from "./module.js"
|
||||
import defaultExport, { b as c } from 'module.js'
|
||||
|
||||
print (m.secret_number);
|
||||
print (m.getPrettifiedNumber());
|
||||
print (m.api.version);
|
||||
print (defaultExport); // 2
|
||||
print (c ()); // 42
|
||||
```
|
||||
|
||||
```js
|
||||
// module.js
|
||||
var secret_number = 42;
|
||||
export secret_number;
|
||||
|
||||
export function getPrettifiedNumber() {
|
||||
return "*** " + secret_number + " ***";
|
||||
export default 2;
|
||||
export function b () {
|
||||
return 42;
|
||||
}
|
||||
|
||||
export { ble as api } from "./ble.js";
|
||||
```
|
||||
|
||||
### Importing modules for side-effects
|
||||
|
||||
Evaluate a module without importing anything. Any errors encountered in the module will be propagated.
|
||||
|
||||
```js
|
||||
import 'module.js' // > module.js
|
||||
// "> module.js" is printed
|
||||
b (); // (ReferenceError) b is not defined
|
||||
```
|
||||
|
||||
```js
|
||||
// module.js
|
||||
export function b () {
|
||||
print ("> module.js");
|
||||
return 42;
|
||||
}
|
||||
b ();
|
||||
```
|
||||
|
||||
## Unsupported features
|
||||
|
||||
* **snapshot**
|
||||
|
||||
@@ -0,0 +1,782 @@
|
||||
---
|
||||
layout: page
|
||||
title: Migration Guide
|
||||
category: documents
|
||||
permalink: /migration-guide/
|
||||
---
|
||||
|
||||
* toc
|
||||
{:toc}
|
||||
|
||||
# Migration guide
|
||||
|
||||
This guide intends to describe the major changes between the JerryScript 1.0 and 2.0 versions.
|
||||
In addtion it is designed to provide a guide on how to modify the 1.0 version code to a
|
||||
2.0 compliant code.
|
||||
|
||||
During the development it was important to minimize the changes in the API functions and types.
|
||||
Each API method removal or chang is described below providing a ***before*** and ***after***
|
||||
code example.
|
||||
For more information on the current API methods please check the [API reference](02.API-REFERENCE.md) document.
|
||||
|
||||
# Short list of removed/renamed headers, types, functions, and macros
|
||||
|
||||
***Removed legacy headers***
|
||||
|
||||
- `jerry-internal.h`
|
||||
|
||||
***Renamed headers***
|
||||
|
||||
- `jerry-api.h` to `jerryscript.h`
|
||||
- `jerry-port.h` to `jerryscript-port.h`
|
||||
|
||||
***Removed API types***
|
||||
|
||||
- `jerry_char_ptr_t` usage replaced with `jerry_char_t *`
|
||||
- `jerry_object_free_callback_t` replaced by `jerry_object_native_free_callback_t`
|
||||
|
||||
***Removed API methods***
|
||||
|
||||
- `jerry_get_memory_limits`
|
||||
- `jerry_get_object_native_handle` replaced by `jerry_get_object_native_pointer`
|
||||
- `jerry_set_object_native_handle` replaced by `jerry_set_object_native_pointer`
|
||||
- `jerry_value_set_abort_flag` replaced by `jerry_create_abort_from_value`
|
||||
- `jerry_value_has_abort_flag` replaced by `jerry_value_is_abort`
|
||||
- `jerry_value_set_error_flag` replaced by `jerry_create_error_from_value`
|
||||
- `jerry_value_has_error_flag` replaced by `jerry_value_is_error`
|
||||
- `jerry_value_clear_error_flag` replaced by `jerry_get_value_from_error`
|
||||
- `jerry_get_value_without_error_flag` replaced by `jerry_get_value_from_error`
|
||||
- `jerry_parse_and_save_snapshot` replaced by `jerry_generate_snapshot`
|
||||
- `jerry_parse_and_save_function_snapshot` replaced by `jerry_generate_function_snapshot`
|
||||
|
||||
|
||||
***Removed unused configuration macros***
|
||||
|
||||
- `CONFIG_MEM_DATA_LIMIT_MINUS_HEAP_SIZE`
|
||||
- `CONFIG_MEM_STACK_LIMIT`
|
||||
- `CONFIG_VM_STACK_FRAME_INLINED_VALUES_NUMBER`
|
||||
- `CONFIG_ECMA_GLOBAL_ENVIRONMENT_DECLARATIVE`
|
||||
- All `CONFIG_..` macros have been renamed to use the `JERRY_` prefix format.
|
||||
|
||||
|
||||
# Modified API functions
|
||||
|
||||
## Error manipulating functions
|
||||
|
||||
The most important changes in the API are releated to error handling and manipulation.
|
||||
|
||||
### jerry_value_set_abort_flag
|
||||
|
||||
This function was replaced with [`jerry_create_abort_from_value`](02.API-REFERENCE.md#jerry_create_abort_from_value).
|
||||
Take note of the second argument of the new `jerry_create_abort_from_value` function which controls if the
|
||||
first argument should be usable after the call or not.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_set_abort_flag (&value);
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_t abort = jerry_create_abort_from_value (value, true);
|
||||
// using the 'value' variable after release is invalid
|
||||
|
||||
jerry_release_value (abort);
|
||||
}
|
||||
```
|
||||
|
||||
- OR
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
... // create or acquire value
|
||||
|
||||
jerry_value_t abort = jerry_create_abort_from_value (value, false);
|
||||
// both 'abort' and 'value' can be used and must be released when they are no longer needed
|
||||
|
||||
jerry_release_value (abort);
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
### jerry_value_has_abort_flag
|
||||
|
||||
This function was renamed to [`jerry_value_is_abort`](02.API-REFERENCE.md#jerry_value_is_abort).
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
if (jerry_value_has_abort_flag (value))
|
||||
{
|
||||
// ...
|
||||
}
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
if (jerry_value_is_abort (value))
|
||||
{
|
||||
// ...
|
||||
}
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
### jerry_value_set_error_flag
|
||||
|
||||
This function was replaced with [`jerry_create_error_from_value`](02.API-REFERENCE.md#jerry_create_error_from_value).
|
||||
Take note of the second argument of the new `jerry_create_error_from_value` function which controls if the
|
||||
first argument should be usable after the call or not.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_set_error_flag (&value);
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_t error = jerry_create_error_from_value (value, true);
|
||||
// using the 'value' variable after release is invalid
|
||||
|
||||
jerry_release_value (error);
|
||||
}
|
||||
```
|
||||
|
||||
- OR
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_t error = jerry_create_error_from_value (value, false);
|
||||
// both 'error' and 'value' can be used and must be released when they are no longer needed
|
||||
|
||||
jerry_release_value (error);
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
### jerry_value_has_error_flag
|
||||
|
||||
This function was renamed to [`jerry_value_is_error`](02.API-REFERENCE.md#jerry_value_is_error).
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
if (jerry_value_has_error_flag (value))
|
||||
{
|
||||
// ...
|
||||
}
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
if (jerry_value_is_error (value))
|
||||
{
|
||||
// ...
|
||||
}
|
||||
|
||||
jerry_release_value (value);
|
||||
}
|
||||
```
|
||||
|
||||
### jerry_value_clear_error_flag AND jerry_get_value_without_error_flag
|
||||
|
||||
These functions were merged into [`jerry_get_value_from_error`](02.API-REFERENCE.md#jerry_get_value_from_error).
|
||||
Please note the second argument of the new function which controls if the first argument passed should be released
|
||||
or not.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_set_error_flag (&value);
|
||||
jerry_value_clear_error_flag (&value);
|
||||
// or
|
||||
jerry_value_t real_value = jerry_get_value_without_error_flag (value);
|
||||
|
||||
jerry_release_value (value);
|
||||
jerry_release_value (real_value);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_value_t value;
|
||||
// create or acquire value
|
||||
// ...
|
||||
|
||||
jerry_value_t error = jerry_create_error_from_value (value, true);
|
||||
|
||||
jerry_value_t real_value = jerry_get_value_from_error (error, true);
|
||||
|
||||
jerry_release_value (real_value);
|
||||
}
|
||||
```
|
||||
|
||||
## Other functions changed
|
||||
|
||||
### jerry_register_magic_strings
|
||||
|
||||
In case of the `jerry_register_magic_strings` function the change is that
|
||||
the first argument's base type `jerry_char_ptr_t` was changed to `jerry_char_t*`.
|
||||
For more details see: [`jerry_register_magic_strings`](02.API-REFERENCE.md#jerry_register_magic_strings).
|
||||
|
||||
In the following code parts please take note of the type used for the `magic_string_items` array.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
// must be static, because 'jerry_register_magic_strings' does not copy
|
||||
// the items must be sorted by size at first, then lexicographically
|
||||
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[] = { 12, 12, 12 };
|
||||
jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
// must be static, because 'jerry_register_magic_strings' does not copy
|
||||
// the items must be sorted by size at first, then lexicographically
|
||||
static const jerry_char_t *magic_string_items[] = {
|
||||
(const jerry_char_t *) "magicstring1",
|
||||
(const jerry_char_t *) "magicstring2",
|
||||
(const jerry_char_t *) "magicstring3"
|
||||
};
|
||||
uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_t *));
|
||||
|
||||
// must be static, because 'jerry_register_magic_strings' does not copy
|
||||
static const jerry_length_t magic_string_lengths[] = { 12, 12, 12 };
|
||||
jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
|
||||
}
|
||||
```
|
||||
|
||||
## Snapshot generating API
|
||||
|
||||
### jerry_parse_and_save_snapshot
|
||||
|
||||
This function was replaced with [`jerry_generate_snapshot`](02.API-REFERENCE.md#jerry_generate_snapshot).
|
||||
The function returns an error object if there was any problem during snapshot generation and
|
||||
if there was no problem the return value is a number value containing the snapshot size in bytes.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
static uint32_t global_mode_snapshot_buffer[256];
|
||||
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
|
||||
|
||||
size_t global_mode_snapshot_size =
|
||||
jerry_parse_and_save_snapshot (code_to_snapshot_p,
|
||||
strlen ((const char *) code_to_snapshot_p),
|
||||
true,
|
||||
false,
|
||||
global_mode_snapshot_buffer,
|
||||
sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
|
||||
// use "global_mode_snapshot_buffer"
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
static uint32_t global_mode_snapshot_buffer[256];
|
||||
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
|
||||
|
||||
jerry_value_t generate_result;
|
||||
generate_result = jerry_generate_snapshot (NULL,
|
||||
0,
|
||||
code_to_snapshot_p,
|
||||
strlen ((const char *) code_to_snapshot_p),
|
||||
global_mode_snapshot_buffer,
|
||||
sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
|
||||
if (jerry_value_is_error (generate_result))
|
||||
{
|
||||
// There was a problem during snapshot generation, for example there is a SyntaxError.
|
||||
// Use the "generate_result" to check the error.
|
||||
}
|
||||
else
|
||||
{
|
||||
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
|
||||
// use "global_mode_snapshot_buffer"
|
||||
}
|
||||
jerry_release_value (generate_result);
|
||||
}
|
||||
```
|
||||
|
||||
### jerry_parse_and_save_function_snapshot
|
||||
|
||||
This function was replaced with [`jerry_generate_function_snapshot`](02.API-REFERENCE.md#jerry_parse_and_save_function_snapshot).
|
||||
The function returns an error object if there was any problem during snapshot generation and
|
||||
if there was no problem the return value is a number value containing the snapshot size in bytes.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
static uint32_t func_snapshot_buffer[1024];
|
||||
|
||||
const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
|
||||
const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
|
||||
|
||||
size_t func_snapshot_size =
|
||||
jerry_parse_and_save_function_snapshot (src_p,
|
||||
strlen ((const char *) src_p),
|
||||
args_p,
|
||||
strlen ((const char *) args_p),
|
||||
false,
|
||||
func_snapshot_buffer,
|
||||
sizeof (func_snapshot_buffer) / sizeof (uint32_t));
|
||||
// check "function_snapshot_size" and use "func_snapshot_buffer"
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
static uint32_t func_snapshot_buffer[1024];
|
||||
|
||||
const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
|
||||
const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
|
||||
|
||||
jerry_value_t generate_result;
|
||||
generate_result = jerry_generate_function_snapshot (NULL,
|
||||
0,
|
||||
src_p,
|
||||
strlen ((const char *) src_p),
|
||||
args_p,
|
||||
strlen ((const char *) args_p),
|
||||
0,
|
||||
func_snapshot_buffer,
|
||||
sizeof (func_snapshot_buffer) / sizeof (uint32_t));
|
||||
if (jerry_value_is_error (generate_result))
|
||||
{
|
||||
// There was a problem during snapshot generation, for example there is a SyntaxError.
|
||||
// Use the "generate_result" to check the error.
|
||||
}
|
||||
else
|
||||
{
|
||||
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
|
||||
// use "func_snapshot_buffer"
|
||||
}
|
||||
|
||||
jerry_release_value (generate_result)
|
||||
}
|
||||
```
|
||||
|
||||
## Garbage collection
|
||||
|
||||
### jerry_gc
|
||||
|
||||
The [`jerry_gc`](02.API-REFERENCE.md#jerry_gc) function was modified to handle an argument which represents the pressure for the garbage collector.
|
||||
For more information checkout the [`jerry_gc_mode_t`](02.API-REFERENCE.md#jerry_gc_mode_t) reference.
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_gc ();
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
{
|
||||
jerry_gc (JERRY_GC_PRESSURE_LOW);
|
||||
}
|
||||
```
|
||||
|
||||
## jerry_eval
|
||||
|
||||
The third argument of [`jerry_eval`](02.API-REFERENCE.md#jerry_eval) has been changed
|
||||
from `bool` to [`jerry_parse_opts_t`](02.API-REFERENCE.md#jerry_parse_opts_t).
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
const jerry_char_t *str_to_eval = (const jerry_char_t *) "1 + 1";
|
||||
jerry_value_t ret_val = jerry_eval (str_to_eval,
|
||||
strlen ((const char *) str_to_eval),
|
||||
false);
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
const jerry_char_t *str_to_eval = (const jerry_char_t *) "1 + 1";
|
||||
jerry_value_t ret_val = jerry_eval (str_to_eval,
|
||||
strlen ((const char *) str_to_eval),
|
||||
JERRY_PARSE_NO_OPTS);
|
||||
```
|
||||
|
||||
## Port API
|
||||
|
||||
### jerry_port_get_time_zone
|
||||
|
||||
The port API of handling timezones has been changed. The previous interface did not
|
||||
allow timezones to be handled correctly, even if the host system was up to the task.
|
||||
Check [the related issue](https://github.com/jerryscript-project/jerryscript/issues/1661)
|
||||
for more details.
|
||||
|
||||
The new port API function name is [jerry_port_get_local_time_zone_adjustment](05.PORT-API.md#date-1].
|
||||
|
||||
Below is the default implementations for both versions:
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p)
|
||||
{
|
||||
struct timeval tv;
|
||||
struct timezone tz;
|
||||
|
||||
/* gettimeofday may not fill tz, so zero-initializing */
|
||||
tz.tz_minuteswest = 0;
|
||||
tz.tz_dsttime = 0;
|
||||
|
||||
if (gettimeofday (&tv, &tz) != 0)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
tz_p->offset = tz.tz_minuteswest;
|
||||
tz_p->daylight_saving_time = tz.tz_dsttime > 0 ? 1 : 0;
|
||||
|
||||
return true;
|
||||
} /* jerry_port_get_time_zone */
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
double jerry_port_get_local_time_zone_adjustment (double unix_ms,
|
||||
bool is_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 */
|
||||
```
|
||||
|
||||
## Native pointers
|
||||
|
||||
The assignment of native pointers (previously called handles) have been changed
|
||||
since v1.0. In the previous version only one native pointer could be assigned to
|
||||
a `jerry_value_t`. Now it is allowed to register multiple native infos, which
|
||||
can be accessed with the corresponding
|
||||
[`jerry_object_native_info_t`](02.API-REFERENCE.md#jerry_object_native_info_t).
|
||||
The old functions were removed and replaced by new ones.
|
||||
|
||||
- `jerry_object_free_callback_t` callback type is replaced by `jerry_object_native_info_t`
|
||||
- `jerry_get_object_native_handle` is replaced by [`jerry_get_object_native_pointer`](02.API-REFERENCE.md#jerry_get_object_native_pointer)
|
||||
- `jerry_set_object_native_handle` is replaced by [`jerry_set_object_native_pointer`](02.API-REFERENCE.md#jerry_set_object_native_pointer)
|
||||
|
||||
**Before**
|
||||
|
||||
```c
|
||||
struct
|
||||
{
|
||||
int data;
|
||||
} my_info;
|
||||
|
||||
static void
|
||||
handler_construct_freecb (uintptr_t native_p)
|
||||
{
|
||||
// Invoked when the JS object is released and the
|
||||
// native data should be freed.
|
||||
|
||||
struct my_info *info = (struct my_info *) native_p;
|
||||
free (info);
|
||||
}
|
||||
|
||||
void
|
||||
demo (void)
|
||||
{
|
||||
jerry_value_t this_val;
|
||||
// create or acquire this_val
|
||||
// ...
|
||||
|
||||
struct my_info *info = (struct my_info *) malloc (sizeof (struct my_info));
|
||||
info->data = 11;
|
||||
|
||||
// setting the native handle
|
||||
jerry_set_object_native_handle (this_val,
|
||||
(uintptr_t) info,
|
||||
handler_construct_freecb);
|
||||
// ...
|
||||
// reading back the native handle
|
||||
uintptr_t ptr = (uintptr_t) NULL;
|
||||
bool is_ok = jerry_get_object_native_handle (this_val, &ptr);
|
||||
if (is_ok)
|
||||
{
|
||||
struct my_info *obj_info = (struct my_info *) ptr;
|
||||
// use "obj_info"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
**After**
|
||||
|
||||
```c
|
||||
struct
|
||||
{
|
||||
int data;
|
||||
} my_info;
|
||||
|
||||
static void
|
||||
handler_construct_freecb (void *native_p)
|
||||
{
|
||||
// Invoked when the JS object is released and the
|
||||
// native data should be freed.
|
||||
|
||||
struct my_info *info = (struct my_info *) native_p;
|
||||
free (info);
|
||||
}
|
||||
|
||||
static const jerry_object_native_info_t my_info_type_info =
|
||||
{
|
||||
.free_cb = handler_construct_freecb
|
||||
};
|
||||
|
||||
void
|
||||
demo (void)
|
||||
{
|
||||
jerry_value_t this_val;
|
||||
// create or acquire this_val
|
||||
// ...
|
||||
|
||||
struct my_info *info = (struct my_info *) malloc (sizeof (struct my_info));
|
||||
info->data = 11;
|
||||
|
||||
// setting the native handle
|
||||
jerry_set_object_native_pointer (this_val,
|
||||
info,
|
||||
&my_info_type_info);
|
||||
// ...
|
||||
// reading back the native handle pointed by the "my_info_type_info" variable
|
||||
void *ptr = NULL;
|
||||
bool has_p = jerry_get_object_native_pointer (this_val, &ptr, &my_info_type_info);
|
||||
if (has_p)
|
||||
{
|
||||
struct my_info *obj_info = (struct my_info *) ptr;
|
||||
// use "obj_info"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
# New API functions
|
||||
|
||||
In this section the new API functions are listed.
|
||||
|
||||
## Built-in objects
|
||||
|
||||
***ArrayBuffer***
|
||||
|
||||
- [`jerry_create_arraybuffer`](02.API-REFERENCE.md#jerry_create_arraybuffer)
|
||||
- [`jerry_create_arraybuffer_external`](02.API-REFERENCE.md#jerry_create_arraybuffer_external)
|
||||
- [`jerry_get_arraybuffer_pointer`](02.API-REFERENCE.md#jerry_get_arraybuffer_pointer)
|
||||
|
||||
***DataView***
|
||||
|
||||
- [`jerry_create_dataview`](02.API-REFERENCE.md#jerry_create_dataview)
|
||||
- [`jerry_value_is_dataview`](02.API-REFERENCE.md#jerry_value_is_dataview)
|
||||
- [`jerry_get_dataview_buffer`](02.API-REFERENCE.md#jerry_get_dataview_buffer)
|
||||
|
||||
***JSON***
|
||||
|
||||
- [`jerry_json_parse`](02.API-REFERENCE.md#jerry_json_parse)
|
||||
- [`jerry_json_stringify`](02.API-REFERENCE.md#jerry_json_stringify)
|
||||
|
||||
***Number***
|
||||
|
||||
- [`jerry_create_number_infinity`](02.API-REFERENCE.md#jerry_create_number_infinity)
|
||||
- [`jerry_create_number_nan`](02.API-REFERENCE.md#jerry_create_number_nan)
|
||||
|
||||
***Promise***
|
||||
|
||||
- [`jerry_run_all_enqueued_jobs`](02.API-REFERENCE.md#jerry_run_all_enqueued_jobs)
|
||||
- [`jerry_create_promise`](02.API-REFERENCE.md#jerry_create_promise)
|
||||
- [`jerry_resolve_or_reject_promise`](02.API-REFERENCE.md#jerry_resolve_or_reject_promise)
|
||||
- [`jerry_value_is_promise`](02.API-REFERENCE.md#jerry_value_is_promise)
|
||||
|
||||
***RegExp***
|
||||
|
||||
- [`jerry_create_regexp`](02.API-REFERENCE.md#jerry_create_regexp)
|
||||
- [`jerry_create_regexp_sz`](02.API-REFERENCE.md#jerry_create_regexp_sz)
|
||||
|
||||
***String***
|
||||
|
||||
- [`jerry_substring_to_utf8_char_buffer`](02.API-REFERENCE.md#jerry_substring_to_utf8_char_buffer)
|
||||
- [`jerry_get_utf8_string_size`](02.API-REFERENCE.md#jerry_get_utf8_string_size)
|
||||
- [`jerry_get_utf8_string_length`](02.API-REFERENCE.md#jerry_get_utf8_string_length)
|
||||
- [`jerry_create_string_from_utf8`](02.API-REFERENCE.md#jerry_create_string_from_utf8)
|
||||
- [`jerry_create_string_sz_from_utf8`](02.API-REFERENCE.md#jerry_create_string_sz_from_utf8)
|
||||
|
||||
***Symbol***
|
||||
|
||||
- [`jerry_create_symbol`](02.API-REFERENCE.md#jerry_create_symbol)
|
||||
- [`jerry_get_symbol_descriptive_string`](02.API-REFERENCE.md#jerry_get_symbol_descriptive_string)
|
||||
- [`jerry_value_is_symbol`](02.API-REFERENCE.md#jerry_value_is_symbol)
|
||||
|
||||
***TypedArray***
|
||||
|
||||
- [`jerry_create_typedarray`](02.API-REFERENCE.md#jerry_create_typedarray)
|
||||
- [`jerry_create_typedarray_for_arraybuffer`](02.API-REFERENCE.md#jerry_create_typedarray_for_arraybuffer)
|
||||
- [`jerry_create_typedarray_for_arraybuffer_sz`](02.API-REFERENCE.md#jerry_create_typedarray_for_arraybuffer_sz)
|
||||
- [`jerry_get_typedarray_type`](02.API-REFERENCE.md#jerry_get_typedarray_type)
|
||||
- [`jerry_get_typedarray_length`](02.API-REFERENCE.md#jerry_get_typedarray_length)
|
||||
- [`jerry_get_typedarray_buffer`](02.API-REFERENCE.md#jerry_get_typedarray_buffer)
|
||||
- [`jerry_value_is_typedarray`](02.API-REFERENCE.md#jerry_value_is_typedarray)
|
||||
|
||||
|
||||
## Instances and memory management
|
||||
|
||||
***JerryScript instances***
|
||||
|
||||
- [`jerry_create_context`](02.API-REFERENCE.md#jerry_create_context)
|
||||
- [`jerry_get_context_data`](02.API-REFERENCE.md#jerry_get_context_data)
|
||||
|
||||
***Memory management***
|
||||
|
||||
- [`jerry_heap_alloc`](02.API-REFERENCE.md#jerry_heap_alloc)
|
||||
- [`jerry_heap_free`](02.API-REFERENCE.md#jerry_heap_free)
|
||||
|
||||
|
||||
## Operations with JavaScript values
|
||||
|
||||
***Binary operations***
|
||||
|
||||
- [`jerry_binary_operation`](02.API-REFERENCE.md#jerry_binary_operation)
|
||||
|
||||
***Error manipulating***
|
||||
|
||||
- [`jerry_get_error_type`](02.API-REFERENCE.md#jerry_get_error_type)
|
||||
- [`jerry_get_backtrace`](02.API-REFERENCE.md#jerry_get_backtrace)
|
||||
|
||||
***Native pointers***
|
||||
|
||||
- [`jerry_delete_object_native_pointer`](02.API-REFERENCE.md#jerry_delete_object_native_pointer)
|
||||
- [`jerry_objects_foreach_by_native_info`](02.API-REFERENCE.md#jerry_objects_foreach_by_native_info)
|
||||
|
||||
***Property***
|
||||
|
||||
- [`jerry_delete_property_by_index`](02.API-REFERENCE.md#jerry_delete_property_by_index)
|
||||
- [`jerry_objects_foreach`](02.API-REFERENCE.md#jerry_objects_foreach)
|
||||
|
||||
|
||||
## Debugger
|
||||
|
||||
- [`jerry_debugger_is_connected`](07.DEBUGGER.md#jerry_debugger_is_connected)
|
||||
- [`jerry_debugger_stop`](07.DEBUGGER.md#jerry_debugger_stop)
|
||||
- [`jerry_debugger_continue`](07.DEBUGGER.md#jerry_debugger_continue)
|
||||
- [`jerry_debugger_stop_at_breakpoint`](07.DEBUGGER.md#jerry_debugger_stop_at_breakpoint)
|
||||
- [`jerry_debugger_wait_for_client_source`](07.DEBUGGER.md#jerry_debugger_wait_for_client_source)
|
||||
- [`jerry_debugger_send_output`](07.DEBUGGER.md#jerry_debugger_send_output)
|
||||
- [`jerry_debugger_send_log`](07.DEBUGGER.md#jerry_debugger_send_log)
|
||||
|
||||
|
||||
## Other
|
||||
|
||||
- [`jerry_is_feature_enabled`](02.API-REFERENCE.md#jerry_is_feature_enabled)
|
||||
- [`jerry_parse_and_save_literals`](02.API-REFERENCE.md#jerry_parse_and_save_literals)
|
||||
- [`jerry_set_vm_exec_stop_callback`](02.API-REFERENCE.md#jerry_set_vm_exec_stop_callback)
|
||||
|
||||
|
||||
## Port API functions
|
||||
|
||||
- [`jerry_port_normalize_path`](05.PORT-API.md#jerry_port_normalize_path)
|
||||
- [`jerry_port_read_source`](05.PORT-API.md#jerry_port_read_source)
|
||||
- [`jerry_port_release_source`](05.PORT-API.md#jerry_port_release_source)
|
||||
- [`jerry_port_print_char`](05.PORT-API.md#jerry_port_print_char)
|
||||
- [`jerry_port_get_current_context`](05.PORT-API.md#jerry_port_get_current_context)
|
||||
- [`jerry_port_fatal`](05.PORT-API.md#jerry_port_fatal)
|
||||
- [`jerry_port_sleep`](05.PORT-API.md#jerry_port_sleep)
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 27 KiB After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 7.0 KiB After Width: | Height: | Size: 6.2 KiB |
Reference in New Issue
Block a user