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

Update the webpage (#5127)

Browse Source 
The GitHub ribbon is also revived.

Related issue: #5125

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
This commit is contained in:
Zsolt Borbély
2024-02-07 06:07:21 +01:00
committed by GitHub
parent d0671c4ff1
commit 9192b862c9
14 changed files with 2732 additions and 3647 deletions
Download Patch File Download Diff File Expand all files Collapse all files
10.EXT-REFERENCE-HANDLER.md
+37 -197
View File
@@ -10,174 +10,9 @@ permalink: /ext-reference-handler/
# Common methods to handle properties
The `jerryscript-ext/handler.h` header defines a set of convenience methods
The `jerryscript-ext/properties.h` header defines a set of convenience methods
which makes the property access a bit straightforward.
## jerryx_set_property_str
**Summary**
Set a property on a target object with a given name.
*Note*:
- The property name must be a zero terminated UTF-8 string.
- There should be no '\0' (NULL) character in the name excluding the string terminator.
- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
jerry_value_t
jerryx_set_property_str (const jerry_value_t target_object,
const char *name,
const jerry_value_t value);
```
- `target_object` - the object where the property should be set
- `name` - name of the property
- `value` - property value to be set
- return value
- JS true value, if success
- thrown error, if there was a problem setting the property
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
int
main (int argc, char **argv)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t global = jerry_get_global_object ();
jerry_value_t value = jerry_create_number (3.3);
jerry_value_t result = jerryx_set_property_str (global, "value", value);
if (jerry_value_is_error (result))
{
/* The error type/reason can be extracted via the `jerry_get_value_from_error` method */
printf ("Error during property configuration\r\n");
}
jerry_release_value (result);
jerry_release_value (value);
jerry_release_value (global);
jerry_cleanup();
return 0;
}
```
## jerryx_get_property_str
**Summary**
Get the value of a property from the specified object with the given name.
*Notes*:
- The property name must be a zero terminated UTF-8 string.
- There should be no '\0' (NULL) character in the name excluding the string terminator.
- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```
jerry_value_t
jerryx_get_property_str (const jerry_value_t target_object,
const char *name);
```
- `target_object` - object on which the property name is accessed
- `name` - property name as an UTF-8 `char*`
- return value
- value of property, if success
- thrown error, if there was a problem accessing the property
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
int
main (int argc, char **argv)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t global = jerry_get_global_object ();
jerry_value_t math_object = jerryx_get_property_str (global, "Math");
/* use math_object */
jerry_release_value (math_object);
jerry_release_value (global);
jerry_cleanup();
return 0;
}
```
## jerryx_has_property_str
**Summary**
Check if a property exists on an object.
*Notes*:
- The operation performed is the same as what the `jerry_has_property` method.
- The property name must be a zero terminated UTF-8 string.
- There should be no '\0' (NULL) character in the name excluding the string terminator.
**Prototype**
```
bool
jerryx_has_property_str (const jerry_value_t target_object,
const char *name);
```
- `target_object` - object on which the property name is accessed
- `name` - property name as an UTF-8 `char*`
- return value
- true, if the given property name exists on the object
- false, if there is no such property name or there was an error accessing the property
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
int
main (int argc, char **argv)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t global = jerry_get_global_object ();
bool have_math = jerryx_has_property_str (global, "Math");
jerry_release_value (global);
jerry_cleanup();
return have_math ? 0 : 1;
}
```
# Utility to register multiple properties in bulk
In some cases it is useful to register multiple properties for a given object
@@ -273,8 +108,10 @@ jerryx_set_properties (const jerry_value_t target_object,
[doctest]: # ()
```c
#include <stdio.h>
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
#include "jerryscript-ext/properties.h"
static jerry_value_t
handler (const jerry_call_info_t *call_info_p,
@@ -283,7 +120,7 @@ handler (const jerry_call_info_t *call_info_p,
{
printf ("native handler called!\n");
return jerry_create_boolean (true);
return jerry_boolean (true);
}
int
@@ -293,24 +130,24 @@ main (int argc, char **argv)
jerryx_property_entry methods[] =
{
{ "demo", jerry_create_external_function (handler) },
{ "demo", jerry_function_external (handler) },
{ NULL, 0 },
};
jerry_value_t global = jerry_get_global_object ();
jerry_value_t global = jerry_current_realm ();
jerryx_register_result reg = jerryx_set_properties (global, methods);
/* if `reg.result` is undefined all methods are registered */
if (jerry_value_is_error (reg.result))
if (jerry_value_is_exception (reg.result))
{
printf ("Only registered %d properties\r\n", reg.registered);
/* clean up not registered property values */
jerryx_release_property_entry (methods, reg);
/* clean up the error */
jerry_release_value (reg.result);
jerry_value_free (reg.result);
}
jerry_release_value (global);
jerry_value_free (global);
jerry_cleanup();
@@ -324,8 +161,8 @@ To make property registration convenient, there are a set of macros to use
when setting a property entry:
* `JERRYX_PROPERTY_NUMBER(NAME, NUMBER)` - creates a number entry.
* `JERRYX_PROPERTY_STRING(NAME, STR)` - creates an UTF-8 string entry. This string must be zero terminated.
* `JERRYX_PROPERTY_STRING_SZ(NAME, STR, SIZE)` - creates an UTF-8 string entry using only `SIZE` bytes from the string.
* `JERRYX_PROPERTY_STRING(NAME, STR, SIZE)` - creates an UTF-8 string entry using `SIZE` bytes from the string.
* `JERRYX_PROPERTY_STRING_SZ(NAME, STR)` - creates an ASCII string entry. This string must be zero terminated.
* `JERRYX_PROPERTY_BOOLEAN(NAME, VALUE)` - creates a boolean entry.
* `JERRYX_PROPERTY_FUNCTION(NAME, NATIVE)` - creates a native C function entry.
* `JERRYX_PROPERTY_UNDEFINED(NAME)` - creates an undefined property entry.
@@ -336,8 +173,10 @@ when setting a property entry:
[doctest]: # ()
```c
#include <stdio.h>
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
#include "jerryscript-ext/properties.h"
static jerry_value_t
handler (const jerry_call_info_t *call_info_p,
@@ -346,7 +185,7 @@ handler (const jerry_call_info_t *call_info_p,
{
printf ("native handler called!\n");
return jerry_create_boolean (true);
return jerry_boolean (true);
}
int
@@ -367,20 +206,20 @@ main (int argc, char **argv)
JERRYX_PROPERTY_LIST_END(),
};
jerry_value_t global = jerry_get_global_object ();
jerry_value_t global = jerry_current_realm ();
jerryx_register_result reg = jerryx_set_properties (global, methods);
/* if `reg.result` is undefined all methods are registered */
if (jerry_value_is_error (reg.result))
if (jerry_value_is_exception (reg.result))
{
printf ("Only registered %d properties\r\n", reg.registered);
/* clean up not registered property values */
jerryx_release_property_entry (methods, reg);
/* clean up the error */
jerry_release_value (reg.result);
jerry_value_free (reg.result);
}
jerry_release_value (global);
jerry_value_free (global);
jerry_cleanup();
@@ -450,7 +289,7 @@ jerryx_handler_assert_fatal (const jerry_value_t func_obj_val, const jerry_value
**See also**
- [jerryx_handler_register_global](#jerryx_handler_register_global)
- [jerryx_register_global](#jerryx_register_global)
## jerryx_handler_assert_throw
@@ -476,7 +315,7 @@ jerryx_handler_assert_throw (const jerry_value_t func_obj_val, const jerry_value
**See also**
- [jerryx_handler_register_global](#jerryx_handler_register_global)
- [jerryx_register_global](#jerryx_register_global)
## jerryx_handler_assert
@@ -514,7 +353,7 @@ jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,
**See also**
- [jerryx_handler_register_global](#jerryx_handler_register_global)
- [jerryx_register_global](#jerryx_register_global)
## jerryx_handler_print
@@ -523,14 +362,14 @@ jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,
Provide a `print` implementation for scripts. The routine converts all of its
arguments to strings and outputs them char-by-char using
`jerry_port_print_char`. The NULL character is output as "\u0000",
`jerry_port_print_byte`. The NULL character is output as "\u0000",
other characters are output bytewise.
*Note*: This implementation does not use standard C `printf` to print its
output. This allows more flexibility but also extends the core JerryScript
engine port API. Applications that want to use `jerryx_handler_print` must
ensure that their port implementation also provides
`jerry_port_print_char`.
`jerry_port_print_byte`.
**Prototype**
@@ -549,26 +388,26 @@ jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this
**See also**
- [jerryx_handler_register_global](#jerryx_handler_register_global)
- [jerry_port_print_char](05.PORT-API.md#jerry_port_print_char)
- [jerryx_register_global](#jerryx_register_global)
- [jerry_port_print_byte](05.PORT-API.md#jerry_port_print_char)
# Handler registration helper
## jerryx_handler_register_global
## jerryx_register_global
**Summary**
Register a JavaScript function in the global object.
*Note*: Returned value must be freed with `jerry_release_value`, when it is no
*Note*: Returned value must be freed with `jerry_value_free`, when it is no
longer needed.
**Prototype**
```c
jerry_value_t
jerryx_handler_register_global (const jerry_char_t *name_p,
jerryx_register_global (const char *name_p,
jerry_external_handler_t handler_p);
```
@@ -583,7 +422,8 @@ jerryx_handler_register_global (const jerry_char_t *name_p,
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
#include "jerryscript-ext/handlers.h"
#include "jerryscript-ext/properties.h"
static const struct {
const char *name_p;
@@ -599,14 +439,14 @@ static const struct {
static void
register_common_functions (void)
{
jerry_value_t ret = jerry_create_undefined ();
jerry_value_t ret = jerry_undefined ();
for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_is_error (ret); i++)
for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_is_exception (ret); i++)
{
ret = jerryx_handler_register_global ((const jerry_char_t *) common_functions[i].name_p,
common_functions[i].handler_p);
ret = jerryx_register_global (common_functions[i].name_p,
common_functions[i].handler_p);
}
jerry_release_value (ret);
jerry_value_free (ret);
}
```