archive-gh-me/jerryscript
1
0
Fork 0
mirror of https://github.com/jerryscript-project/jerryscript.git synced 2025-12-15 16:29:21 +00:00
Code Issues Projects Releases Wiki Activity
jerryscript/docs/02.API-REFERENCE.md
István Kádár 5f7997d2d0 Documentation converter script. 
JerryScript-DCO-1.0-Signed-off-by: István Kádár ikadar@inf.u-szeged.hu
2016-07-05 13:58:04 +02:00

55 KiB
Raw Blame History

jerry_run_simple

Summary

The simplest way to run JavaScript.

Prototype

jerry_completion_code_t
jerry_run_simple (const jerry_char_t *script_source,
                  size_t script_source_size,
                  jerry_flag_t flags);
  • script_source - source code, it must be a valid utf8 string.
  • script_source_size - size of source code buffer, in bytes.
  • return value - completion code, indicating whether execution was successful (JERRY_COMPLETION_CODE_OK), or an unhandled JavaScript exception occurred (JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION).

Example

{
  const jerry_char_t *script = "print ('Hello, World!');";

  jerry_run_simple (script, strlen ((const char *) script), JERRY_FLAG_EMPTY);
}

See also

jerry_init

Summary

Initializes the JerryScript engine, making possible to run JavaScript code and perform operations on JavaScript values.

Prototype

void
jerry_init (jerry_flag_t flags);

flags - combination of various engine configuration flags:

  • JERRY_FLAG_EMPTY - no flags, just initialize in default configuration.
  • JERRY_FLAG_SHOW_OPCODES - print compiled byte-code.
  • JERRY_FLAG_MEM_STATS - dump memory statistics.
  • JERRY_FLAG_MEM_STATS_SEPARATE - dump memory statistics and reset peak values after parse.
  • JERRY_FLAG_ENABLE_LOG - enable logging.

Example

{
  jerry_init (JERRY_FLAG_SHOW_OPCODES | JERRY_FLAG_ENABLE_LOG);

  // ...

  jerry_cleanup ();
}

See also

jerry_cleanup

Summary

Finish JavaScript engine execution, freeing memory and JavaScript values.

Note: JavaScript values, received from engine, will be inaccessible after the cleanup.

Prototype

void
jerry_cleanup (void);

See also

jerry_parse

Summary

Parse specified script to execute in Global scope.

Note: Current API doesn't permit replacement or modification of Global scope's code without engine restart, which means 'jerry_parse' can be invoked only once between jerry_init and jerry_cleanup.

Prototype

bool
jerry_parse (const jerry_char_t *source_p,
             size_t source_size,
             jerry_object_t **error_obj_p);
  • source_p - string, containing source code to parse. It must be a valid utf8 string.
  • source_size - size of the string, in bytes.
  • error_obj_p - error object (output parameter).

Example

{
  jerry_init (JERRY_FLAG_EMPTY);

  char script [] = "print ('Hello, World!');";
  size_t script_size = strlen ((const char *) script);

  jerry_object_t *error_object_p = NULL;
  if (!jerry_parse (script, script_size, &error_object_p))
  {
    /* Error object must be freed, if parsing failed */
    jerry_release_object (error_object_p);
  }

  jerry_cleanup ();
}

See also

jerry_parse_and_save_snapshot

Summary

Generate snapshot from the specified source code.

Prototype

size_t
jerry_parse_and_save_snapshot (const jerry_char_t *source_p,
                               size_t source_size,
                               bool is_for_global,
                               uint8_t *buffer_p,
                               size_t buffer_size);
  • source_p - script source, it must be a valid utf8 string.
  • source_size - script source size, in bytes.
  • is_for_global - snapshot would be executed as global (true) or eval (false).
  • buffer_p - buffer to save snapshot to.
  • buffer_size - the buffer's size.
  • return value
    • the size of snapshot, if it was generated succesfully (i.e. there are no syntax errors in source code, buffer size is sufficient, and snapshot support is enabled in current configuration through JERRY_ENABLE_SNAPSHOT)
    • 0 otherwise.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);

  static uint8_t global_mode_snapshot_buffer[1024];
  const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";

  size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p,
                                                                    strlen (code_to_snapshot_p),
                                                                    true,
                                                                    global_mode_snapshot_buffer,
                                                                    sizeof (global_mode_snapshot_buffer));
}

See also

jerry_run

Summary

Run code of Global scope.

Note: The code should be previously registered through jerry_parse.

Prototype

jerry_completion_code_t
jerry_run (jerry_value_t *error_value_p);
  • error_value_p - error value (output parameter).
  • return value - completion code that indicates whether run performed successfully.
    • JERRY_COMPLETION_CODE_OK - successful completion
    • JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION - an unhandled JavaScript exception occurred
    • JERRY_COMPLETION_CODE_INVALID_SNAPSHOT_VERSION - snapshot version mismatch
    • JERRY_COMPLETION_CODE_INVALID_SNAPSHOT_FORMAT - snapshot format is not valid

Example

{
  const jerry_char_t script[] = "print ('Hello, World!');";
  size_t script_size = strlen ((const char *) script);

  /* Initialize engine */
  jerry_init (JERRY_FLAG_EMPTY);

  /* Setup Global scope code */
  jerry_object_t *error_object_p = NULL;
  if (!jerry_parse (script, script_size, &error_object_p))
  {
    /* Error object must be freed, if parsing failed */
    jerry_release_object (error_object_p);
  }
  else
  {
    /* Execute Global scope code
     *
     * Note:
     *      Initialization of 'error_value' is not mandatory here.
     */
    jerry_value_t error_value = jerry_create_undefined_value ();
    jerry_completion_code_t return_code = jerry_run (&error_value);

    if (return_code == JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION)
    {
      /* Error value must be freed, if 'jerry_run' returns with an unhandled exception */
      jerry_release_value (error_value);
    }
  }

  jerry_cleanup ();
}

See also

jerry_exec_snapshot

Summary

Execute snapshot from the specified buffer.

Prototype

jerry_completion_code_t
jerry_exec_snapshot (const void *snapshot_p,
                     size_t snapshot_size,
                     bool copy_bytecode,
                     jerry_value_t *retval_p);
  • snapshot_p - pointer to snapshot
  • snapshot_size - size of snapshot
  • copy_bytecode - flag, indicating whether the passed snapshot buffer should be copied to the engine's memory. If set the engine should not reference the buffer after the function returns (in this case, the passed buffer could be freed after the call). Otherwise (if the flag is not set) - the buffer could only be freed after the engine stops (i.e. after call to jerry_cleanup).
  • retval_p - return value, ECMA-262 'undefined' if code is executed as global scope code.
  • return value - completion code that indicates whether run performed successfully. Same as before.

Example

{
  bool is_ok;
  jerry_value_t res;
  static uint8_t global_mode_snapshot_buffer[1024];
  const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";

  jerry_init (JERRY_FLAG_EMPTY);
  size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p,
                                                                    strlen (code_to_snapshot_p),
                                                                    true,
                                                                    global_mode_snapshot_buffer,
                                                                    sizeof (global_mode_snapshot_buffer));
  jerry_cleanup ();

  jerry_init (JERRY_FLAG_EMPTY);

  is_ok = (jerry_exec_snapshot (global_mode_snapshot_buffer,
                                global_mode_snapshot_size,
                                false,
                                &res) == JERRY_COMPLETION_CODE_OK);
}

See also

jerry_get_memory_limits

Summary

Gets configured memory limits of JerryScript.

Prototype

void
jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p,
                         size_t *out_stack_limit_p);
  • out_data_bss_brk_limit_p - out parameter, that gives the maximum size of data + bss + brk sections.
  • out_stack_limit_p - out parameter, that gives the maximum size of the stack.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);

  size_t stack_limit;
  size_t data_dss_brk_limit;
  jerry_get_memory_limits (&stack_limit, &data_dss_brk_limit);
}

See also

jerry_gc

Summary

Performs garbage collection.

Prototype

void
jerry_gc (void);

Example

jerry_gc ();

jerry_eval

Summary

Perform JavaScript eval.

Prototype

jerry_completion_code_t
jerry_eval (const jerry_char_t *source_p,
            size_t source_size,
            bool is_direct,
            bool is_strict,
            jerry_value_t *retval_p);
  • source_p - source code to evaluate, it must be a valid utf8 string.
  • source_size - length of the source code
  • is_direct - whether to perform eval in "direct" mode (which means it is called as "eval" and not through some alias).
  • is_strict - perform eval as it is called from "strict mode" code.
  • retval_p - value, returned by eval (output parameter).
  • return value - completion code that indicates whether run performed successfully. Same as before.

Example

{
  jerry_value_t ret_val;

  jerry_completion_code_t status = jerry_eval (str_to_eval,
                                               strlen (str_to_eval),
                                               false,
                                               false,
                                               &ret_val);
}

See also

jerry_create_undefined_value

Summary

Creates a jerry_value_t representing an undefined value. The value has to be released by jerry_release_value.

Prototype

jerry_value_t
jerry_create_undefined_value (void);
  • return value - a jerry_value_t representing undefined.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t undefined_value = jerry_create_undefined_value ();

  ... // usage of the value

  jerry_release_value (undefined_value);
}

See also

jerry_create_null_value

Summary

Creates a jerry_value_t representing a null value. The value has to be released by jerry_release_value.

Prototype

jerry_value_t
jerry_create_null_value (void);
  • return value - a jerry_value_t representing null.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t null_value = jerry_create_null_value ();

  ... // usage of the value

  jerry_release_value (null_value);
}

See also

jerry_create_boolean_value

Summary

Creates a jerry_value_t representing a boolean value from the given boolean parameter. The value has to be released by jerry_release_value.

Prototype

jerry_value_t
jerry_create_boolean_value (bool value);
  • value - boolean value.
  • return value - a jerry_value_t created from the given boolean argument.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t boolean_value = jerry_create_boolean_value (true);

  ... // usage of the value

  jerry_release_value (boolean_value);
}

See also

jerry_create_number_value

Summary

Creates a jerry_value_t from the given double parameter. The value has to be released by jerry_release_value.

Prototype

jerry_value_t
jerry_create_number_value (double value);
  • value - double value from which a jerry_value_t will be created.
  • return value - a jerry_value_t created from the given double argument.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t number_value = jerry_create_number_value (3.14);

  ... // usage of the value

  jerry_release_value (number_value);
}

See also

jerry_create_object_value

Summary

Converts the given jerry_object_t parameter to a jerry_value_t. The value has to be released by jerry_release_value when it is no longer needed.

Prototype

jerry_value_t
jerry_create_object_value (jerry_object_t *value);
  • value - jerry_object_t from which a jerry_value_t will be created.
  • return value - a jerry_value_t created from the given jerry_object_t argument.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_object_t *object_p = jerry_create_object ();
  jerry_value_t object_value = jerry_create_object_value (object_p);

  ... // usage of object_value

  jerry_release_value (object_value);
}

See also

jerry_create_string_sz

Summary

Creates a string. The caller should release the string with jerry_release_string when it is no longer needed.

Prototype

jerry_string_t *
jerry_create_string_sz (const jerry_char_t *str_p,
                        jerry_size_t str_size)
  • str_p - string from which the result jerry_string_t will be created.
  • str_size - size of the string.
  • return value - a jerry_string_t* created from the given jerry_char_t* argument.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  const jerry_char_t char_array[] = "a string";
  jerry_string_t *string  = jerry_create_string_sz (char_array,
                                                    strlen ((char *) char_array));

  ... // usage of string

  jerry_release_string (string);
}

See also

jerry_create_string_value

Summary

Creates a jerry_value_t from the given jerry_string_t parameter. The value has to be released by jerry_release_value when it is no longer needed.

Prototype

jerry_value_t
jerry_create_string_value (jerry_string_t *value);
  • value - jerry_string_t from which a value will be created.
  • return value - a jerry_value_t created from the given jerry_string_t argument.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  const jerry_char_t char_array[] = "a string";
  jerry_string_t *string  = jerry_create_string_sz (char_array,
                                                    strlen ((char *) char_array));
  jerry_value_t string_value = jerry_create_string_value (string);

  ... // usage of string_value

  jerry_release_value (string_value);
}

See also

jerry_create_error_sz

Summary

Creates an error object. Caller should release the object with jerry_release_object, when the value is no longer needed.

Prototype

jerry_object_t *
jerry_create_error_sz (jerry_error_t error_type,
                       const jerry_char_t *message_p,
                       jerry_size_t message_size);
  • error_type - type of the error.
  • message_p - value of 'message' property of the constructed error object.
  • message_size - size of the message in bytes.
  • return value - pointer to the created error object.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_char_t message[] = "error";
  jerry_object_t *error_obj = jerry_create_error_sz (JERRY_ERROR_COMMON,
                                                     message,
                                                     strlen ((char *) message));

  ... // usage of error_obj

  jerry_release_object (error_obj);
}

See also

jerry_get_boolean_value

Summary

Gets the raw bool value form a jerry_value_t value.

Prototype

bool
jerry_get_boolean_value (const jerry_value_t value);
  • value - api value
  • return value - boolean value represented by the argument.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_is_boolean (value))
  {
    bool raw_value = jerry_get_boolean_value (value);

    ... // usage of raw value

  }

  jerry_release_value (value);
}

See also

jerry_get_number_value

Summary

Gets the number value of the given jerry_value_t parameter as a raw double.

Prototype

double
jerry_get_number_value (const jerry_value_t value);
  • value - api value
  • return value - the number value of the given jerry_value_t parameter as a raw double.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_is_number (value))
  {
    double raw_value = jerry_get_number_value (value);

    ... // usage of raw value

  }

  jerry_release_value (value);
}

See also

jerry_get_object_value

Summary

Gets the object value of the given jerry_value_t parameter.

Prototype

jerry_object_t *
jerry_get_object_value (const jerry_value_t value);
  • value - api value
  • return value - the object contained in the given jerry_value_t parameter.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_is_object (value))
  {
    jerry_object_t *raw_value = jerry_get_object_value (value);

    ... // usage of raw value

  }

  jerry_release_value (value);
}

See also

jerry_get_string_value

Summary

Gets the string value of the given jerry_value_t parameter.

Prototype

jerry_string_t *
jerry_get_string_value (const jerry_value_t value);
  • value - api value
  • return value - the string contained in the given jerry_value_t parameter.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_is_string (value))
  {
    jerry_string_t *raw_value = jerry_get_string_value (value);

    ... // usage of raw value

  }

  jerry_release_value (value);
}

See also

jerry_get_string_size

Summary

Gets the length of a jerry_string_t.

Prototype

jerry_size_t
jerry_get_string_size (const jerry_string_t *str_p);
  • str_p - input string.
  • return value - number of bytes in the buffer needed to represent the string.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_char_t char_array[] = "a string";
  jerry_string_t *string = jerry_create_string (char_array);

  jerry_size_t string_size = jerry_get_string_size ();

  ... // usage of string_size

  jerry_release_string (string);
}

See also

jerry_get_string_length

Summary

Gets the length of a jerry_string_t.

Prototype

jerry_length_t
jerry_get_string_length (const jerry_string_t *str_p);
  • str_p - input string
  • return value - number of characters in the string

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_char_t char_array[] = "a string";
  jerry_string_t *string = jerry_create_string (char_array);

  jerry_length_t string_length = jerry_get_string_length (string);

  ... // usage of string_length

  jerry_release_string (string);
}

See also

jerry_value_is_undefined

Summary

Returns whether the given jerry_value_t is an undefined value.

Prototype

bool
jerry_value_is_undefined (const jerry_value_t value);
  • value - api value
  • return value
    • true, if the given jerry_value_t is an undefined value
    • false, otherwise

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_is_undefined (value))
  {
    ...
  }

  jerry_release_value (value);
}

See also

jerry_value_is_boolean

Summary

Returns whether the given jerry_value_t is a boolean value.

Prototype

bool
jerry_value_is_boolean (const jerry_value_t value)
  • value - api value
  • return value
    • true, if the given jerry_value_t is a boolean value
    • false, otherwise

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_is_boolean (value))
  {
    ...
  }

  jerry_release_value (value);
}

See also

jerry_value_is_number

Summary

Returns whether the given jerry_value_t is a number value.

Prototype

bool
jerry_value_is_number (const jerry_value_t value);
  • value - api value
  • return value
    • true, if the given jerry_value_t is a number value
    • false, otherwise

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_is_number (value))
  {
    ...
  }

  jerry_release_value (value);
}

See also

jerry_value_is_function

Summary

Returns whether the given jerry_value_t is a function object.

Prototype

bool
jerry_value_is_function (const jerry_value_t value);
  • value - api value
  • return value
    • true, if the given jerry_value_t is a function object
    • false, otherwise

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_is_function (value))
  {
    ...
  }

  jerry_release_value (value);
}

See also

jerry_value_is_null

Summary

Returns whether the given jerry_value_t is a null value.

Prototype

bool
jerry_value_is_null (const jerry_value_t value);
  • value - api value
  • return value
    • true, if the given jerry_value_t is a null value
    • false, otherwise

Example

  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_is_null (value))
  {
    ...
  }

  jerry_release_value (value);

See also

jerry_value_is_object

Summary

Returns whether the given jerry_value_t is an object.

Prototype

bool
jerry_value_is_object (const jerry_value_t value);
  • value - api value
  • return value
    • true, if the given jerry_value_t is an object value
    • false, otherwise

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_is_object (value))
  {
    ...
  }

  jerry_release_value (value);
}

See also

jerry_value_is_string

Summary

Returns whether the given jerry_value_t is a string.

Prototype

bool
jerry_value_is_string (const jerry_value_t value);
  • value - api value
  • return value
    • true, if the given jerry_value_t is a string
    • false, otherwise

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_value_t value;
  ... // create or acquire value

  if (jerry_value_is_string (value))
  {
    ...
  }

  jerry_release_value (value);
}

See also

jerry_acquire_value

Summary

Acquires the specified Jerry API value.

For values of string, number and object types this acquires the underlying data, for all other types it is a no-op. The acquired pointer has to be released by jerry_release_value.

Prototype

jerry_value_t
jerry_acquire_value (jerry_value_t value);
  • value - api value
  • return value - pointer that may be used outside of the engine

Example

{
  jerry_init (JERRY_FLAG_EMPTY);
  jerry_object_t *object_p = jerry_create_object ();
  jerry_value_t object_value = jerry_create_object_value (object_p);

  jerry_value_t acquired_object = jerry_acquire_value (object_value);

  jerry_release_value (acquired_object);
  jerry_release_object (object_p);
}

See also

jerry_release_value

Summary

Release specified pointer to the value.

Prototype

void
jerry_release_value (jerry_value_t value);
  • value - api value

Example

{
    jerry_value_t val1 = jerry_create_object_value (jerry_create_object ());

    jerry_string_t *str_p = jerry_create_string ("abc");
    jerry_value_t val2 = jerry_create_string_value (str_p);

    ... // usage of val1

    jerry_release_value (val1);

    ... // usage of val2

    jerry_release_value (val2);
}

jerry_create_string

Summary

Create new JavaScript string.

Note: Returned value must be freed with jerry_release_object when it is no longer needed.

Prototype

jerry_string_t *
jerry_create_string (const jerry_char_t *v);
  • v - value of string to create;
  • return value - pointer to the created string.

Example

{
  jerry_string_t *string_p = jerry_create_string ((jerry_char_t *) "abc");

  ...

  jerry_release_string (string_p);
}

See also

jerry_string_to_char_buffer

Summary

Copy string characters to specified buffer. It is the caller's responsibility to make sure that the string fits in the buffer.

Note: '\0' could occur in characters.

Prototype

jerry_size_t
jerry_string_to_char_buffer (const jerry_string_t *string_p,
                             jerry_char_t *buffer_p,
                             jerry_size_t buffer_size);
  • string_p - pointer to a C string.
  • buffer_p - pointer to output buffer
  • buffer_size - size of the buffer
  • return value:
    • number of bytes, actually copied to the buffer.

Example

{
  jerry_object_t *obj_p = jerry_get_global ();
  
  jerry_value_t val = jerry_get_object_field_value (obj_p,
                                                    "field_with_string_value");

  if (!jerry_value_is_error (val))
  {
    if (jerry_value_is_string (val))
    {
      char str_buf_p[128];
      jerry_string_t *str_p = jerry_get_string_value (val);
      jerry_size_t str_size = jerry_get_string_size (str_p);
      jerry_size_t sz = jerry_string_to_char_buffer (str_p, (jerry_char_t *) str_buf_p, str_size);
      str_buf_p[sz] = '\0';

      printf ("%s", str_buf_p);
    }

    jerry_release_value (val);
  }

  jerry_release_object (obj_p);
}

See also

jerry_acquire_string

Summary

Acquire new pointer to the string for usage outside of the engine. The acquired pointer has to be released with jerry_release_string.

Prototype

jerry_string_t *
jerry_acquire_string (jerry_string_t *string_p);
  • string_p - pointer to the string.
  • return value - pointer to the string.

Example

{
  jerry_string_t *str_ptr1_p = jerry_create_string ((jerry_char_t *) "abc");
  jerry_string_t *str_ptr2_p = jerry_acquire_string (str_ptr1_p);

  ... // usage of both pointers

  jerry_release_string (str_ptr1_p);

  ... // usage of str_ptr2_p pointer

  jerry_release_string (str_ptr2_p);
}

See also

jerry_release_string

Summary

Release specified pointer to the string.

Prototype

void
jerry_release_string (jerry_string_t *string_p);
  • string_p - pointer to the string.

Example

{
  jerry_string_t *str_ptr1_p = jerry_create_string ("abc");
  jerry_string_t *str_ptr2_p = jerry_acquire_string (str_ptr1_p);

  ... // usage of both pointers

  jerry_release_string (str_ptr1_p);

  ... // usage of str_ptr2_p pointer

  jerry_release_string (str_ptr2_p);
}

See also

jerry_create_object

Summary

Create new JavaScript object, like with new Object().

Note: Returned value must be freed with jerry_release_object when it is no longer needed.

Prototype

jerry_object_t *
jerry_create_object ();
  • return value - pointer to the created object.

Example

{
  jerry_object_t *object_p = jerry_create_object ();

  ...

  jerry_release_object (object_p);
}

See also

jerry_acquire_object

Summary

Acquire new pointer to the object for usage outside of the engine. The acquired pointer has to be released with jerry_release_object.

Prototype

jerry_object_t *
jerry_acquire_object (jerry_object_t *object_p);
  • object_p - pointer to the object.
  • return value - new pointer to the object.

Example

{
  jerry_object_t *obj_ptr1_p = jerry_create_object ();
  jerry_object_t *obj_ptr2_p = jerry_acquire_object (obj_ptr1_p);

  ... // usage of both pointers

  jerry_release_object (obj_ptr1_p);

  ... // usage of obj_ptr2_p pointer

  jerry_release_object (obj_ptr2_p);
}

See also

jerry_release_object

Summary

Release specified pointer to the object.

Prototype

void
jerry_release_object (jerry_object_t *object_p);
  • object_p - pointer to the object.

Example

{
  jerry_object_t *obj_ptr1_p = jerry_create_object ();
  jerry_object_t *obj_ptr2_p = jerry_acquire_object (obj_ptr1_p);

  ... // usage of both pointers

  jerry_release_object (obj_ptr1_p);

  ... // usage of obj_ptr2_p pointer

  jerry_release_object (obj_ptr2_p);
}

See also

jerry_get_global

Summary

Get the Global object.

Prototype

jerry_object_t *
jerry_get_global (void);
  • return value - pointer to the Global object.

Received pointer should be released with jerry_release_object, just when the value is no longer needed.

Example

{
  jerry_object_t *glob_obj_p = jerry_get_global ();

  jerry_value_t val = jerry_get_object_field_value (glob_obj_p, "some_field_name");
  if (!jerry_value_is_error (val))
  {
    ... // usage of 'val'
  }

  jerry_release_value (val);
  jerry_release_object (glob_obj_p);
}

See also

jerry_add_object_field

Summary

Create field (named data property) in an object.

Prototype

bool
jerry_add_object_field (jerry_object_t *object_p,
                        const jerry_char_t *field_name_p,
                        const jerry_value_t field_value,
                        bool is_writable);
  • object_p - pointer to object to add field at.
  • field_name_p - name of the field.
  • field_value - value of the field.
  • is_writable - flag indicating whether the created field should be writable.
  • return value
    • true, if field was created successfully, i.e. upon the call:
      • there is no field with same name in the object;
      • the object is extensible.

Example

{
  jerry_object_t *obj_p = jerry_create_object ();

  jerry_value_t val;

  ... // initialize val

  // Make new constant field
  jerry_add_object_field (obj_p, "some_field_name", val, false);
}

See also

jerry_delete_object_field

Summary

Delete field (property) in the specified object

Prototype

bool
jerry_delete_object_field (jerry_object_t *object_p,
                           const jerry_char_t *field_name_p);
  • object_p - pointer to object to delete field at.
  • field_name_p - name of the field.
  • return value - true, if field was deleted successfully, i.e. upon the call:
    • there is field with specified name in the object.

Example

{
  jerry_object_t *obj_p;
  ... // receive or construct obj_p

  jerry_delete_object_field (obj_p, "some_field_name");
}

See also

jerry_get_object_field_value

Summary

Get value of field (property) in the specified object, i.e. perform Get operation.

Prototype

jerry_value_t
jerry_get_object_field_value (jerry_object_t *object_p,
                              const jerry_char_t *field_name_p);
  • object_p - pointer to object.
  • field_name_p - name of the field.
  • return value - jerry value of the given field.

Note: Returned value must be freed with jerry_release_object when it is no longer needed.

Example

{
  jerry_object_t *obj_p;
  ... // receive or construct obj_p

  jerry_value_t val = jerry_get_object_field_value (obj_p, "some_field_name");

  if (!jerry_value_is_error (val))
  {
    ... // usage of 'val'

  }

  jerry_release_value (val);
}

See also

jerry_get_object_field_value_sz

Summary

Gets the value of a field in the specified object.

Prototype

jerry_value_t
jerry_get_object_field_value_sz (jerry_object_t *object_p,
                                 const jerry_char_t *field_name_p,
                                 jerry_size_t field_name_size);
  • object_p - pointer to object.
  • field_name_p - name of the field.
  • field_name_size - size of field name in bytes.
  • return value - jerry value of the given field.

Note: Returned value must be freed with jerry_release_object when it is no longer needed.

Example

{
  jerry_init (JERRY_FLAG_EMPTY);

  jerry_char_t field_name[] = "field";
  jerry_value_t field_value = jerry_create_number_value (3.14);

  jerry_object_t* object_p = jerry_create_object ();
  jerry_add_object_field (object_p,
                          field_name,
                          strlen ((char *) field_name),
                          field_value, 
                          true);

  jerry_value_t retrieved_field_value;
  retrieved_field_value = jerry_get_object_field_value_sz (object_p,
                                                           field_name,
                                                           strlen ((char *) field_name));
  if (!jerry_value_is_error (retrieved_field_value))
  {
    ... // usage of the retrieved field
  }

  jerry_release_value (retrieved_field_value);
  jerry_release_object (object_p);
}

See also

jerry_set_object_field_value

Summary

Set value of a field (property) in the specified object, i.e. perform Put operation.

Prototype

bool
jerry_set_object_field_value (jerry_object_t *object_p,
                              const jerry_char_t *field_name_p,
                              jerry_value_t field_value);
  • object_p - pointer to object.
  • field_name_p - name of the field.
  • field_value - field value to set.
  • return value - true, if field value was set successfully, i.e. upon the call:
    • field value is writable.

Example

{
  jerry_object_t *obj_p;
  jerry_value_t val;

  ... // receive or construct obj_p and val

  bool is_ok = jerry_set_object_field_value (obj_p,
                                             (const jerry_char_t *) "some_field_name",
                                             val);
}

See also

jerry_set_object_field_value_sz

Summary

Set value of field in the specified object.

Prototype

bool
jerry_set_object_field_value_sz (jerry_object_t *object_p,
                                 const jerry_char_t *field_name_p,
                                 jerry_size_t field_name_size,
                                 const jerry_value_t field_value);
  • object_p - pointer to object
  • field_name_p - name of the field
  • field_name_size - size of field name in bytes
  • field_value - field value to set
  • return value
  • true, if field value was set successfully
  • false, otherwise

Example

{
  jerry_object_t *obj_p;
  jerry_char_t field_name[] = "some_field_name";
  jerry_value_t val;

  ... // receive or construct obj_p and val

  bool is_ok = jerry_set_object_field_value_sz (obj_p,
                                                field_name,
                                                strlen ((char *) field_name),
                                                val);
}

See also

jerry_get_object_native_handle

Summary

Get native handle, previously associated with specified object.

Prototype

bool
jerry_get_object_native_handle (jerry_object_t *object_p,
                                uintptr_t *out_handle_p);
  • object_p - pointer to object to get handle from.
  • out_handle_p - handle value (output parameter).
  • return value - true, if there is handle associated with the object.

Example

{
  jerry_object_t *obj_p;
  uintptr_t handle_set;

  ... // receive or construct obj_p and handle_set value

  jerry_set_object_native_handle (obj_p, handle_set, NULL);

  ...

  uintptr_t handle_get;
  bool is_there_associated_handle = jerry_get_object_native_handle (obj_p, &handle_get);
}

See also

jerry_set_object_native_handle

Summary

Set native handle and, optionally, "free" callback for the specified object.

If native handle or "free" callback were already set for the object, corresponding value is updated.

Prototype

void
jerry_set_object_native_handle (jerry_object_t *object_p,
                                uintptr_t handle,
                                jerry_object_free_callback_t freecb_p);
  • object_p - pointer to object to set handle in;
  • handle - handle value;
  • freecb_p - pointer to "free" callback or NULL (if not NULL the callback would be called upon GC of the object).

Example

{
  jerry_object_t *obj_p;
  uintptr_t handle_set;

  ... // receive or construct obj_p and handle_set value

  jerry_set_object_native_handle (obj_p, handle_set, NULL);

  ...

  uintptr_t handle_get;
  bool is_there_associated_handle = jerry_get_object_native_handle (obj_p, &handle_get);
}

See also

jerry_is_function

Summary

Check whether the specified object is a function object.

Prototype

bool
jerry_is_function (const jerry_object_t *object_p);
  • object_p - pointer to object to check;
  • return value - boolean, indicating whether the specified object can be called as function.

Example

{
  jerry_value_t val;

  ... // receiving val

  if (jerry_value_is_object (val))
  {
    if (jerry_is_function (jerry_get_object_value (val)))
    {
      // the object is function object
    }
  }
}

See also

jerry_is_constructor

Summary

Check whether the specified object is a constructor function object.

Prototype

bool
jerry_is_constructor (const jerry_object_t *object_p);
  • object_p - pointer to object to check.
  • return value - boolean, indicating whether the specified object can be called as constructor.

Example

{
  jerry_value_t val;

  ... // receiving val

  if (jerry_value_is_object (val))
  {
    if (jerry_is_constructor (jerry_get_object_value (val)))
    {
      // the object is constructor function object
    }
  }
}

See also

jerry_call_function

Summary

Call function object.

Prototype

jerry_value_t
jerry_call_function (jerry_object_t *function_object_p,
                     jerry_object_t *this_arg_p,
                     const jerry_value_t args_p[],
                     uint16_t args_count);
  • function_object_p - the function object to call;
  • this_arg_p - object to use as 'this' during the invocation, or NULL - to set the Global object as 'this';
  • args_p, args_count - array of arguments and number of them;
  • return value - function's return value

Returned value must be freed with jerry_release_object when it is no longer needed.

Example

{
  jerry_value_t val;

  ... // receiving val

  if (jerry_value_is_object (val))
  {
    if (jerry_is_function (jerry_get_object_value (val)))
    {
      jerry_value_t ret_val;

      ret_val = jerry_call_function (jerry_get_object_value (val), NULL, NULL, 0);

      if (!jerry_value_is_error (ret_val))
      {
        ... // handle return value
      }

      jerry_release_value (ret_val);
    }
  }
}

See also

jerry_construct_object

Summary

Construct object, invoking specified function object as constructor.

Prototype

jerry_value_t
jerry_construct_object (jerry_object_t *function_object_p,
                        const jerry_value_t args_p[],
                        uint16_t args_count);
  • function_object_p - the function object to invoke.
  • args_p, args_count - array of arguments and number of them.
  • return value - return value of function invoked as constructor, i.e. like with 'new' operator.

Note: Returned value must be freed with jerry_release_object when it is no longer needed.

Example

{
  jerry_value_t val;

  ... // receiving val

  if (jerry_value_is_object (val))
  {
    if (jerry_is_function (jerry_get_object_value (val)))
    {
      jerry_value_t ret_val;

      ret_val = jerry_construct_object (jerry_get_object_value (val), NULL, 0);

      if (!jerry_value_is_error (ret_val))
      {
        ... // handle return value
      }

      jerry_release_value (ret_val);
    }
  }
}

See also

jerry_external_handler_t

Summary

The data type represents pointer to call handler of a native function object.

Structure

typedef bool (* jerry_external_handler_t) (const jerry_object_t *function_obj_p,
                                           const jerry_value_t this_p,
                                           const jerry_value_t args_p[],
                                           const uint16_t args_count,
                                           jerry_value_t *ret_val_p);

See also

jerry_create_external_function

Summary

Create an external function object.

Prototype

jerry_object_t *
jerry_create_external_function (jerry_external_handler_t handler_p);
  • handler_p - pointer to native handler of the function object;
  • return value - pointer to constructed external function object.

Received pointer should be released with jerry_release_object, when the value is no longer needed.

Example

static bool
handler (const jerry_object_t *function_obj_p,
         const jerry_value_t this_p,
         const jerry_value_t args_p[],
         const uint16_t args_cnt,
         jerry_value_t *ret_val_p)
{
  printf ("native handler called!\n");

  *ret_val_p = jerry_create_boolean_value (true);
  return true;
}

{
  jerry_object_t *obj_p = jerry_create_external_function (handler);
  jerry_object_t *glob_obj_p = jerry_get_global ();

  jerry_value_t val = jerry_create_object_value (obj_p);

  // after this, script can invoke the native handler through "handler_field (1, 2, 3);"
  jerry_set_object_field_value (glob_obj_p, "handler_field", val);

  jerry_release_object (glob_obj_p);
  jerry_release_object (obj_p);
}

See also

jerry_create_array_object

Summary

Create new JavaScript array object.

Note: Returned value must be freed with jerry_release_object when it is no longer needed.

Prototype

jerry_object_t *
jerry_create_array_object (jerry_size_t array_size);
  • array_size - size of array;
  • return value is pointer to the created array object.

Example

{
    jerry_object_t *array_object_p = jerry_create_array_object (10);

    ...

    jerry_release_object (array_object_p);
}

See also

jerry_set_array_index_value

Summary

Set value of an indexed element in the specified array object.

Prototype

bool
jerry_set_array_index_value (jerry_object_t *array_object_p,
                             jerry_length_t index,
                             jerry_value_t value);
  • array_object_p - pointer to the array object;
  • index - index of the array element;
  • value - value to set;
  • return value - true, if value was set successfully.

Example

{
    jerry_object_t *array_object_p = jerry_create_array_object (10);
    jerry_value_t val;

    ... // receive or construct val

    jerry_set_array_index_value (array_object_p, 5, val);

    jerry_release_object (array_object_p);
}

See also

jerry_get_array_index_value

Summary

Get value of an indexed element in the specified array object.

Prototype

bool
jerry_get_array_index_value (jerry_object_t *array_object_p,
                             jerry_length_t index,
                             jerry_value_t *value_p);
  • array_object_p - pointer to the array object;
  • index - index of the array element;
  • value_p - retrieved indexed value (output parameter);
  • return value - true, if value was retrieved successfully.

Example

{
    jerry_object_t *array_object_p;
    ... // receive or construct array_object_p

    jerry_value_t val;
    bool is_ok = jerry_get_array_index_value (array_object_p, 5, &val);
    if (is_ok)
    {
      ... // usage of 'val'
    }
}

See also

jerry_create_error

Summary

Create new JavaScript error object. It should be throwed from a handle attached to an external function object.

Prototype

jerry_object_t *
jerry_create_error (jerry_error_t error_type,
                    const jerry_char_t *message_p);
  • error_type - error type of object;
  • message_p - human-readable description of the error;
  • return value is pointer to the created error object.

Example

static bool
handler (const jerry_object_t *function_obj_p,
         const jerry_value_t this_p,
         const jerry_value_t args_p[],
         const uint16_t args_cnt,
         jerry_value_t *ret_val_p)
{
  jerry_object_t *error_p = jerry_create_error (JERRY_ERROR_TYPE,
                                                (jerry_char_t * ) "error");

  jerry_acquire_object (error_p);
  *ret_val_p = jerry_create_error_value (error_p);

  jerry_release_object (error_p);

  return false;
}

{
  jerry_object_t *throw_obj_p = jerry_create_external_function (handler);
  jerry_object_t *glob_obj_p = jerry_get_global ();

  jerry_value_t val = jerry_create_object_value (throw_obj_p);

  // after this, script can invoke the native handler through "error_func ();"
  // and "error_func" will throw an error when called.
  jerry_set_object_field_value (glob_obj_p, "error_func", val);

  jerry_release_object (glob_obj_p);
  jerry_release_object (throw_obj_p);
}

See also

jerry_register_external_magic_strings

Summary

Registers an external magic string array.

Prototype

void
jerry_register_external_magic_strings  (const jerry_char_ptr_t *ex_str_items,
                                        uint32_t  count,
                                        const jerry_length_t *str_lengths);
  • ex_str_items - character arrays, representing external magic strings' contents
  • count number - of the strings
  • str_lengths - lengths of the strings

Example

{
  jerry_init (JERRY_FLAG_EMPTY);

  // must be static, because 'jerry_register_external_magic_strings' does not copy
  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_external_magic_strings' does not copy
  static const jerry_length_t magic_string_lengths[] = {
                                                         (jerry_length_t)strlen (magic_string_items[0]),
                                                         (jerry_length_t)strlen (magic_string_items[1]),
                                                         (jerry_length_t)strlen (magic_string_items[2])
                                                       };
  jerry_register_external_magic_strings (magic_string_items,
                                         num_magic_string_items,
                                         magic_string_lengths);
}

See also

jerry_value_to_string

Summary

Creates the textual representation of an API value using the ToString ecma builtin operation.

Prototype

jerry_value_t
jerry_value_to_string (const jerry_value_t value);
  • value - api value.
  • return value - textual representation of the given value.

Example

{
  jerry_value_t value;

  ... // receive or construct value

  jerry_value_t to_string_value = jerry_value_to_string (&value);

  jerry_release_value (to_string_value);
}

jerry_object_field_foreach_t

Summary

Function type applied for each fields of an object by API function jerry_foreach_object_field.

Definition

typedef bool (*jerry_object_field_foreach_t) (const jerry_string_t *field_name_p,
                                              const jerry_value_t field_value,
                                              void *user_data_p);
  • field_name_p - name of the field
  • field_value - value of the field
  • user_data_p - user data
  • return value
    • true, if the operation executed successfully
    • false, otherwise

See also

jerry_foreach_object_field

Summary

Applies the given function to every fields in the given objects.

Prototype

bool
jerry_foreach_object_field (jerry_object_t *object_p,
                            jerry_object_field_foreach_t foreach_p,
                            void *user_data_p);
  • object_p - pointer to object
  • foreach_p - foreach function, that will be apllied for each fields
  • user_data_p - user data for foreach function
  • return value
    • true, if object fields traversal was performed successfully, i.e.:
      • no unhandled exceptions were thrown in object fields traversal
      • object fields traversal was stopped on callback that returned false
    • false, otherwise, if getter of field threw a exception or unhandled exceptions were thrown during traversal

Example

bool foreach_function (const jerry_string_t *field_name_p,
                       const jerry_value_t field_value,
                       void *user_data_p)
{

  ... // implementation of the foreach function

}

{
  jerry_init (JERRY_FLAG_EMPTY);

  jerry_object_t* object_p;
  ... // receive or construct object_p

  double data = 3.14; // example data

  jerry_foreach_object_field (object_p, foreach_function, &data);

}

See also