jerryscript/03.api.md

---
layout: page
title: API
permalink: /API/
---

* toc
{:toc}

# jerry_init

**Summary**

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

**Prototype**

```cpp
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**

```cpp
{
  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**

```cpp
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**

```cpp
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**

```cpp
 {
   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**

```cpp
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**

```cpp
{
  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**

```cpp
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**

```cpp
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**

```cpp
{
  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**

```cpp
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**

```cpp
{
  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**

```cpp
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**

```cpp
{
  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**

```cpp
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**

```cpp
{
  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**

```cpp
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**

```cpp
{
  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**

```cpp
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**

```cpp
{
  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**

```cpp
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**

```cpp
{
  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**

```cpp
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**

```cpp
{
  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**

```cpp
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**

```cpp
{
  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**

```cpp
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**

```cpp
{
  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);
      }
    }
  }
}
```