jerryscript/docs/10.EXT-REFERENCE-HANDLER.md

Common external function handlers

jerryx_handler_assert_fatal

Summary

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

Prototype

jerry_value_t
jerryx_handler_assert_fatal (const jerry_value_t func_obj_val, const jerry_value_t this_p,
                             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_register_global

jerryx_handler_assert_throw

Summary

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

Prototype

jerry_value_t
jerryx_handler_assert_throw (const jerry_value_t func_obj_val, const jerry_value_t this_p,
                             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_register_global

jerryx_handler_assert

Summary

An alias to jerryx_handler_assert_fatal.

See also

• jerryx_handler_assert_fatal

jerryx_handler_gc

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 gc is performed, which is also the default if no parameters passed.

Prototype

jerry_value_t
jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,
                   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_register_global

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

jerry_value_t
jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this_p,
                      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

• jerryx_handler_register_global
• jerry_port_print_char

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

jerry_value_t
jerryx_handler_register_global (const jerry_char_t *name_p,
                                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

#include "jerryscript.h"
#include "jerryscript-ext/handler.h"

static const struct {
  const char *name_p;
  jerry_external_handler_t handler_p;
} common_functions[] =
{
  { "assert", jerryx_handler_assert },
  { "gc", jerryx_handler_gc },
  { "print", jerryx_handler_print },
  { NULL, NULL }
};

static void
register_common_functions (void)
{
  jerry_value_t ret = jerry_create_undefined ();

  for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_is_error (ret); i++)
  {
    ret = jerryx_handler_register_global ((const jerry_char_t *) common_functions[i].name_p,
                                          common_functions[i].handler_p);
  }

  jerry_release_value (ret);
}