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 when it is no longer needed.

Prototype

  1. jerry_value_t
  2. jerryx_set_property_str (const jerry_value_t target_object,
  3.                          const char *name,
  4.                          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

  1. #include "jerryscript.h"
  2. #include "jerryscript-ext/handler.h"
  4. int
  5. main (int argc, char **argv)
  6. {
  7.   jerry_init (JERRY_INIT_EMPTY);
  9.   jerry_value_t global = jerry_get_global_object ();
  11.   jerry_value_t value = jerry_create_number (3.3);
  12.   jerry_value_t result = jerryx_set_property_str (global, "value", value);
  13.   if (jerry_value_is_error (result))
  14.   {
  15.     /* The error type/reason can be extracted via the `jerry_get_value_from_error` method */
  16.     printf ("Error during property configuration\r\n");
  17.   }
  19.   jerry_release_value (result);
  20.   jerry_release_value (value);
  21.   jerry_release_value (global);
  22.   jerry_cleanup();
  24.   return 0;
  25. }

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 when it is no longer needed.

Prototype

  1. jerry_value_t
  2. jerryx_get_property_str (const jerry_value_t target_object,
  3.                          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

  1. #include "jerryscript.h"
  2. #include "jerryscript-ext/handler.h"
  4. int
  5. main (int argc, char **argv)
  6. {
  7.   jerry_init (JERRY_INIT_EMPTY);
  9.   jerry_value_t global = jerry_get_global_object ();
  11.   jerry_value_t math_object = jerryx_get_property_str (global, "Math");
  13.   /* use math_object */
  15.   jerry_release_value (math_object);
  16.   jerry_release_value (global);
  17.   jerry_cleanup();
  19.   return 0;
  20. }

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

  1. bool
  2. jerryx_has_property_str (const jerry_value_t target_object,
  3.                          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

  1. #include "jerryscript.h"
  2. #include "jerryscript-ext/handler.h"
  4. int
  5. main (int argc, char **argv)
  6. {
  7.   jerry_init (JERRY_INIT_EMPTY);
  9.   jerry_value_t global = jerry_get_global_object ();
  11.   bool have_math = jerryx_has_property_str (global, "Math");
  13.   jerry_release_value (global);
  14.   jerry_cleanup();
  16.   return have_math ? 0 : 1;
  17. }

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

  1. typedef struct {
  2.   const char *name;
  3.   jerry_value_t value;
  4. } jerryx_function_list_entry;

See also

jerryx_register_result

Summary

Structure returned as the result of the 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 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

  1. typedef struct {
  2.   jerry_value_t result;
  3.   uint32_t registered;
  4. } jerryx_register_result;

See also

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 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

  1. jerryx_register_result
  2. jerryx_set_properties (const jerry_value_t target_object,
  3.                        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.
    • 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

  1. #include "jerryscript.h"
  2. #include "jerryscript-ext/handler.h"
  4. static jerry_value_t
  5. handler (const jerry_value_t function_obj,
  6.          const jerry_value_t this_val,
  7.          const jerry_value_t args_p[],
  8.          const jerry_length_t args_cnt)
  9. {
  10.   printf ("native handler called!\n");
  12.   return jerry_create_boolean (true);
  13. }
  15. int
  16. main (int argc, char **argv)
  17. {
  18.   jerry_init (JERRY_INIT_EMPTY);
  20.   jerryx_property_entry methods[] =
  21.   {
  22.     { "demo", jerry_create_external_function (handler) },
  23.     { NULL, 0 },
  24.   };
  26.   jerry_value_t global = jerry_get_global_object ();
  27.   jerryx_register_result reg = jerryx_set_properties (global, methods);
  28.   /* if `reg.result` is undefined all methods are registered */
  29.   if (jerry_value_is_error (reg.result))
  30.   {
  31.     printf ("Only registered %d properties\r\n", reg.registered);
  32.     /* clean up not registered property values */
  33.     jerryx_release_property_entry (methods, reg);
  35.     /* clean up the error */
  36.     jerry_release_value (reg.result);
  37.   }
  39.   jerry_release_value (global);
  41.   jerry_cleanup();
  43.   return 0;
  44. }

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

  1. #include "jerryscript.h"
  2. #include "jerryscript-ext/handler.h"
  4. static jerry_value_t
  5. handler (const jerry_value_t function_obj,
  6.          const jerry_value_t this_val,
  7.          const jerry_value_t args_p[],
  8.          const jerry_length_t args_cnt)
  9. {
  10.   printf ("native handler called!\n");
  12.   return jerry_create_boolean (true);
  13. }
  15. int
  16. main (int argc, char **argv)
  17. {
  18.   jerry_init (JERRY_INIT_EMPTY);
  20.   /**
  21.    * Create a array of properties to be registered.
  22.    * This must be done after initializing the engine as creating `jerry_value_t`
  23.    * elements are invalid before `jerry_init`.
  24.    */
  25.   jerryx_property_entry methods[] =
  26.   {
  27.     JERRYX_PROPERTY_FUNCTION ("demo", handler),
  28.     JERRYX_PROPERTY_NUMBER ("test_num", 2.3),
  29.     JERRYX_PROPERTY_UNDEFINED ("this_is_undefined"),
  30.     JERRYX_PROPERTY_LIST_END(),
  31.   };
  33.   jerry_value_t global = jerry_get_global_object ();
  34.   jerryx_register_result reg = jerryx_set_properties (global, methods);
  35.   /* if `reg.result` is undefined all methods are registered */
  36.   if (jerry_value_is_error (reg.result))
  37.   {
  38.     printf ("Only registered %d properties\r\n", reg.registered);
  39.     /* clean up not registered property values */
  40.     jerryx_release_property_entry (methods, reg);
  42.     /* clean up the error */
  43.     jerry_release_value (reg.result);
  44.   }
  46.   jerry_release_value (global);
  48.   jerry_cleanup();
  50.   return 0;
  51. }

See also

jerryx_release_property_entry

Summary

Release all jerry_value_t in a jerryx_property_entry array based on a previous 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

  1. void
  2. jerryx_release_property_entry (const jerryx_property_entry entries[],
  3.                                const jerryx_register_result register_result);

Example

For example usage see jerryx_set_properties.

Common external function handlers

jerryx_handler_assert_fatal

Summary

Hard assert for scripts. The routine calls jerry_port_fatal on assertion failure.

If the JERRY_FEATURE_LINE_INFO runtime feature is enabled (build option: JERRY_LINE_INFO) a backtrace is also printed out.

Prototype

  1. jerry_value_t
  2. jerryx_handler_assert_fatal (const jerry_value_t func_obj_val, const jerry_value_t this_p,
  3.                              const jerry_value_t args_p[], const jerry_length_t args_cnt);
  • func_obj_val - the function object that was called (unused).
  • this_p - the this value of the call (unused).
  • args_p - the array of function arguments.
  • args_cnt - the number of function arguments.
  • return value - jerry_value_t representing boolean true, if only one argument was passed and that argument was a boolean true. Note that the function does not return otherwise.

See also

jerryx_handler_assert_throw

Summary

Soft assert for scripts. The routine throws an error on assertion failure.

Prototype

  1. jerry_value_t
  2. jerryx_handler_assert_throw (const jerry_value_t func_obj_val, const jerry_value_t this_p,
  3.                              const jerry_value_t args_p[], const jerry_length_t args_cnt);
  • func_obj_val - the function object that was called (unused).
  • this_p - the this value of the call (unused).
  • args_p - the array of function arguments.
  • args_cnt - the number of function arguments.
  • return value - jerry_value_t representing boolean true, if only one argument was passed and that argument was a boolean true, an error otherwise.

See also

jerryx_handler_assert

Summary

An alias to jerryx_handler_assert_fatal.

See also

jerryx_handler_gc

Summary

Expose garbage collector to scripts. If the first argument of the function 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

  1. jerry_value_t
  2. jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,
  3.                    const jerry_value_t args_p[], const jerry_length_t args_cnt);
  • func_obj_val - the function object that was called (unused).
  • this_p - the this value of the call (unused).
  • args_p - the array of function arguments (unused).
  • args_cnt - the number of function arguments (unused).
  • return value - jerry_value_t representing undefined.

See also

jerryx_handler_print

Summary

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 NUL 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.

Prototype

  1. jerry_value_t
  2. jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this_p,
  3.                       const jerry_value_t args_p[], const jerry_length_t args_cnt);
  • func_obj_val - the function object that was called (unused).
  • this_p - the this value of the call (unused).
  • args_p - the array of function arguments.
  • args_cnt - the number of function arguments.
  • return value - jerry_value_t representing undefined if all arguments could be converted to strings, an Error otherwise.

See also

Handler registration helper

jerryx_handler_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 longer needed.

Prototype

  1. jerry_value_t
  2. jerryx_handler_register_global (const jerry_char_t *name_p,
  3.                                 jerry_external_handler_t handler_p);
  • name_p - the name of the function to be registered.
  • handler_p - the address of the external function handler.
  • return value - jerry_value_t representing boolean true, if the operation was successful, an Error otherwise.

Example

  1. #include "jerryscript.h"
  2. #include "jerryscript-ext/handler.h"
  4. static const struct {
  5.   const char *name_p;
  6.   jerry_external_handler_t handler_p;
  7. } common_functions[] =
  8. {
  9.   { "assert", jerryx_handler_assert },
  10.   { "gc", jerryx_handler_gc },
  11.   { "print", jerryx_handler_print },
  12.   { NULL, NULL }
  13. };
  15. static void
  16. register_common_functions (void)
  17. {
  18.   jerry_value_t ret = jerry_create_undefined ();
  20.   for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_is_error (ret); i++)
  21.   {
  22.     ret = jerryx_handler_register_global ((const jerry_char_t *) common_functions[i].name_p,
  23.                                           common_functions[i].handler_p);
  24.   }
  26.   jerry_release_value (ret);
  27. }