jerryscript/03.api.md

layout	title	permalink
page	API	/API/

• toc {:toc}

jerry_init

Summary

Initializes 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_MEM_STATS - dump memory statistics;
• JERRY_FLAG_ENABLE_LOG - enable logging;
• JERRY_FLAG_SHOW_OPCODES - print compiled byte-code;
• JERRY_FLAG_EMPTY - no flags, just initialize in default configuration.

See also

• [jerry_cleanup]({{ site.baseurl }}/API#jerry_cleanup)

Example

{
  jerry_init (JERRY_FLAG_ENABLE_LOG);
  // ...
  jerry_cleanup ();
}

jerry_cleanup

Summary

Finish JavaScript engine execution, freeing memory and JavaScript values. JavaScript values, received from engine, are inaccessible after the cleanup.

Prototype

void jerry_cleanup (void);

See also

• [jerry_init]({{ site.baseurl }}/API#jerry_init)

jerry_parse

Summary Parse specified script to execute in Global scope.

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

Prototype

bool jerry_parse (const char* source_p, size_t source_size);

• source_p - string, containing source code to parse;
• source_size - size of the string, in bytes.

See also

• [jerry_run]({{ site.baseurl }}/API#jerry_run)

Example

 {
   jerry_init (JERRY_FLAG_ENABLE_LOG);

   char script [] = "print ('Hello, World!');";
   jerry_parse (script, strlen (script));

   jerry_run ();

   jerry_cleanup ();
 }

jerry_run

Summary Run Global scope's code. The code should be previously registered through jerry_parse.

Prototype

jerry_completion_code_t jerry_run (void);

Returned completion code indicates whether run performed successfully (JERRY_COMPLETION_CODE_OK), or an unhandled JavaScript exception occurred (JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION).

See also

• [jerry_parse]({{ site.baseurl }}/API#jerry_parse)

Example

{
  jerry_init (JERRY_FLAG_ENABLE_LOG);

  char script [] = "print ('Hello, World!');";
  jerry_parse (script, strlen (script));

  jerry_run ();

  jerry_cleanup ();
}

jerry_api_value_t

Summary The data type represents any JavaScript value that can be sent to / received from the engine. Type of value is identified by jerry_api_value_t::type, and can be one of the following:

• JERRY_API_DATA_TYPE_UNDEFINED - JavaScript undefined;
• JERRY_API_DATA_TYPE_NULL - JavaScript null;
• JERRY_API_DATA_TYPE_BOOLEAN - boolean;
• JERRY_API_DATA_TYPE_FLOAT64 - number;
• JERRY_API_DATA_TYPE_STRING - string;
• JERRY_API_DATA_TYPE_OBJECT - reference to JavaScript object.

Structure

typedef struct jerry_api_value_t
{
  jerry_api_data_type_t type;

  union
  {
    bool v_bool;

    float v_float32;
    double v_float64;

    uint32_t v_uint32;

    union
    {
      jerry_api_string_t* v_string;
      jerry_api_object_t* v_object;
    };
  };
} jerry_api_value_t;

See also

• [jerry_api_string_t]({{ site.baseurl }}/API#jerry_api_string_t)
• [jerry_api_object_t]({{ site.baseurl }}/API#jerry_api_object_t)
• [jerry_api_eval]({{ site.baseurl }}/API#jerry_api_eval)
• [jerry_api_call_function]({{ site.baseurl }}/API#jerry_api_call_function)
• [jerry_api_construct_object]({{ site.baseurl }}/API#jerry_api_construct_object)

jerry_api_eval

Summary Perform JavaScript eval.

Prototype

jerry_completion_code_t
jerry_api_eval (const char* source_p,
                size_t source_size,
                bool is_direct,
                bool is_strict,
                jerry_api_value_t* retval_p);

• source_p - source code to evaluate;
• source_size - length of the source code;
• is_direct - whether to perform eval in "direct" mode (possible only if eval invocation is performed from native function, called from JavaScript);
• is_strict - perform eval as it is called from "strict mode" code;
• retval_p - value, returned by eval (output parameter).

See also

• [jerry_api_create_external_function]({{ site.baseurl }}/API#jerry_api_create_external_function)
• [jerry_api_value_t]({{ site.baseurl }}/API#jerry_api_value_t)

Example

{
  jerry_api_value_t ret_val;

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

jerry_api_create_string

Summary Create new JavaScript string.

Upon the JavaScript string becomes unused, all pointers to it should be released using [jerry_api_release_string]({{ site.baseurl }}/API#jerry_api_release_string).

Prototype

jerry_api_string_t* jerry_api_create_string (const char* v);

• v - value of string to create;
• returned value is pointer to created string.

See also

• [jerry_api_acquire_string]({{ site.baseurl }}/API#jerry_api_acquire_string)
• [jerry_api_release_string]({{ site.baseurl }}/API#jerry_api_release_string)

Example

{
  jerry_api_string_t* string_p = jerry_api_create_string ("abc");
  // ...
  jerry_api_release_string (string_p);
}

jerry_api_acquire_string

Summary Acquire new pointer to the string for usage outside of the engine. The acquired pointer should be released with [jerry_api_release_string]({{ site.baseurl }}/API#jerry_api_release_string).

Prototype

jerry_api_string_t* jerry_api_acquire_string (jerry_api_string_t* string_p);

• string_p - pointer to the string;
• returned value - new pointer to the string.

See also

• [jerry_api_release_string]({{ site.baseurl }}/API#jerry_api_release_string)
• [jerry_api_create_string]({{ site.baseurl }}/API#jerry_api_create_string)

Example

{
  jerry_api_string_t* str_ptr1_p = jerry_api_create_string ("abc");
  jerry_api_string_t* str_ptr2_p = jerry_api_acquire_string (str_ptr1_p);
  // ... // usage of both pointers
  jerry_api_release_string (str_ptr1_p);
  // ... // usage of str_ptr2_p pointer
  jerry_api_release_string (str_ptr2_p);
}

jerry_api_release_string

Summary

Release specified pointer to the string.

Prototype

void jerry_api_release_string (jerry_api_string_t* string_p);

See also

• [jerry_api_acquire_string]({{ site.baseurl }}/API#jerry_api_acquire_string)
• [jerry_api_create_string]({{ site.baseurl }}/API#jerry_api_create_string)

Example

{
  jerry_api_string_t* str_ptr1_p = jerry_api_create_string ("abc");
  jerry_api_string_t* str_ptr2_p = jerry_api_acquire_string (str_ptr1_p);
  // ... // usage of both pointers
  jerry_api_release_string (str_ptr1_p);
  // ... // usage of str_ptr2_p pointer
  jerry_api_release_string (str_ptr2_p);
}

jerry_api_create_object

Summary

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

Upon the JavaScript object becomes unused, all pointers to it should be released using [jerry_api_release_object]({{ site.baseurl }}/API#jerry_api_release_object).

Prototype

jerry_api_object_t* jerry_api_create_object (const char* v);

• v - value of object to create;
• returned value is pointer to created object.

See also

• [jerry_api_acquire_object]({{ site.baseurl }}/API#jerry_api_acquire_object)
• [jerry_api_release_object]({{ site.baseurl }}/API#jerry_api_release_object)

Example

{
  jerry_api_object_t* object_p = jerry_api_create_object ("abc");
  // ...
  jerry_api_release_object (object_p);
}

jerry_api_acquire_object

Summary Acquire new pointer to the object for usage outside of the engine. The acquired pointer should be released with [jerry_api_release_object]({{ site.baseurl }}/API#jerry_api_release_object).

Prototype

jerry_api_object_t* jerry_api_acquire_object (jerry_api_object_t* object_p);

• object_p - pointer to the object;
• returned value - new pointer to the object.

See also

• [jerry_api_release_object]({{ site.baseurl }}/API#jerry_api_release_object)
• [jerry_api_create_object]({{ site.baseurl }}/API#jerry_api_create_object)

Example

{
  jerry_api_object_t* obj_ptr1_p = jerry_api_create_object ("abc");
  jerry_api_object_t* obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p);
  // ... // usage of both pointers
  jerry_api_release_object (obj_ptr1_p);
  // ... // usage of obj_ptr2_p pointer
  jerry_api_release_object (obj_ptr2_p);
}

jerry_api_release_object

Summary Release specified pointer to the object.

Prototype

void jerry_api_release_object (jerry_api_object_t* object_p);

See also

• [jerry_api_acquire_object]({{ site.baseurl }}/API#jerry_api_acquire_object)
• [jerry_api_create_object]({{ site.baseurl }}/API#jerry_api_create_object)

Example

{
  jerry_api_object_t* obj_ptr1_p = jerry_api_create_object ("abc");
  jerry_api_object_t* obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p);
  // ... // usage of both pointers
  jerry_api_release_object (obj_ptr1_p);
  // ... // usage of obj_ptr2_p pointer
  jerry_api_release_object (obj_ptr2_p);
}

jerry_api_is_function

Summary Check whether the specified object is a function object.

Prototype

bool jerry_api_is_function (const jerry_api_object_t* object_p);

• object_p - object to check;
• returned value - just boolean, indicating whether the specified object can be called as function.

See also

• [jerry_api_value_t]({{ site.baseurl }}/API#jerry_api_value_t)
• [jerry_api_is_constructor]({{ site.baseurl }}/API#jerry_api_is_constructor)
• [jerry_api_call_function]({{ site.baseurl }}/API#jerry_api_call_function)

Example

{
  jerry_api_value_t val;
  // ... // receiving val

  if (val.type == JERRY_API_DATA_TYPE_OBJECT) {
    if (jerry_api_is_function (val.v_object)) {
      // the object is function object
    }
  }
}

jerry_api_is_constructor

Summary Check whether the specified object is a constructor function object.

Prototype

bool jerry_api_is_constructor (const jerry_api_object_t* object_p);

• object_p - object to check;
• returned value - just boolean, indicating whether the specified object can be called as constructor.

See also

• [jerry_api_value_t]({{ site.baseurl }}/API#jerry_api_value_t)
• [jerry_api_is_function]({{ site.baseurl }}/API#jerry_api_is_function)
• [jerry_api_construct_object]({{ site.baseurl }}/API#jerry_api_construct_object)

Example

{
  jerry_api_value_t val;
  // ... // receiving val
  if (val.type == JERRY_API_DATA_TYPE_OBJECT) {
    if (jerry_api_is_constructor (val.v_object)) {
      // the object is constructor function object
    }
  }
}

jerry_api_call_function

Summary Call function object.

Prototype

bool
jerry_api_call_function (jerry_api_object_t* function_object_p,
                         jerry_api_object_t* this_arg_p,
                         jerry_api_value_t* retval_p,
                         const jerry_api_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';
• retval_p - function's return value (output parameter);
• args_p, args_count - array of arguments and number of them;
• returned value - true, if call was performed successfully, i.e.:
  • specified object is a function object (see also jerry_api_is_function);
  • no unhandled exceptions were thrown in connection with the call.

If call was performed successfully, returned value should be freed with [jerry_api_release_value]({{ site.baseurl }}/API#jerry_api_release_value) just when it becomes unnecessary.

See also

• [jerry_api_is_function]({{ site.baseurl }}/API#jerry_api_is_function)
• [jerry_api_value_t]({{ site.baseurl }}/API#jerry_api_value_t)

Example

{
  jerry_api_value_t val;
  // ... // receiving val
  if (val.type == JERRY_API_DATA_TYPE_OBJECT) {
    if (jerry_api_is_function (val.v_object)) {
      jerry_api_value_t ret_val;

      bool is_ok = jerry_api_call_function (val.v_object,
                                            NULL,
                                            &ret_val,
                                            NULL, 0);

      if (is_ok)
      {
        ... // handle return value

        jerry_api_release_value (&ret_val);
      }
    }
  }
}