diff options
Diffstat (limited to '10.EXT-REFERENCE-HANDLER.md')
| -rw-r--r-- | 10.EXT-REFERENCE-HANDLER.md | 234 |
1 files changed, 37 insertions, 197 deletions
diff --git a/10.EXT-REFERENCE-HANDLER.md b/10.EXT-REFERENCE-HANDLER.md index e9128e2b..c5d10191 100644 --- a/10.EXT-REFERENCE-HANDLER.md +++ b/10.EXT-REFERENCE-HANDLER.md @@ -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); } ``` |