mirror of
https://github.com/jerryscript-project/jerryscript.git
synced 2025-12-15 16:29:21 +00:00
Update API
This commit is contained in:
Evgeny Gavrin
parent
7b5a6dc624
commit
07c593199f
525
03.api.md
525
03.api.md
@ -4,4 +4,527 @@ title: API
|
||||
permalink: /API/
|
||||
---
|
||||
|
||||
TBD
|
||||
# jerry_init
|
||||
|
||||
## Summary
|
||||
|
||||
Initializes JerryScript engine, making possible to run JavaScript code and perform operations on JavaScript values.
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight cpp %}
|
||||
void jerry_init (jerry_flag_t flags);
|
||||
{% endhighlight %}
|
||||
|
||||
`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](/API#jerry_cleanup)
|
||||
|
||||
## Example
|
||||
|
||||
{% highlight cpp %}
|
||||
{
|
||||
jerry_init (JERRY_FLAG_ENABLE_LOG);
|
||||
|
||||
// ...
|
||||
|
||||
jerry_cleanup ();
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# jerry_cleanup
|
||||
|
||||
## Summary
|
||||
|
||||
Finish JavaScript engine execution, freeing memory and JavaScript values.
|
||||
|
||||
JavaScript values, received from engine, are inaccessible after the cleanup.
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight cpp %}
|
||||
void jerry_cleanup (void)
|
||||
{% endhighlight %}
|
||||
|
||||
## See also
|
||||
- [jerry_init](/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
|
||||
|
||||
{% highlight cpp %}
|
||||
bool jerry_parse (const char* source_p, size_t source_size)
|
||||
{% endhighlight %}
|
||||
- `source_p` - string, containing source code to parse;
|
||||
- `source_size` - size of the string, in bytes.
|
||||
|
||||
## See also
|
||||
- [jerry_run](/API#jerry_run)
|
||||
|
||||
## Example
|
||||
{% highlight cpp %}
|
||||
{
|
||||
jerry_init (JERRY_FLAG_ENABLE_LOG);
|
||||
|
||||
char script [] = "print ('Hello, World!');";
|
||||
jerry_parse (script, strlen (script));
|
||||
|
||||
jerry_run ();
|
||||
|
||||
jerry_cleanup ();
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# jerry_run
|
||||
|
||||
## Summary
|
||||
Run Global scope's code.
|
||||
|
||||
The code should be previously registered through `jerry_parse`.
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight cpp %}
|
||||
jerry_completion_code_t jerry_run (void)
|
||||
{% endhighlight %}
|
||||
|
||||
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](/API#jerry_parse)
|
||||
|
||||
## Example
|
||||
|
||||
{% highlight cpp %}
|
||||
{
|
||||
jerry_init (JERRY_FLAG_ENABLE_LOG);
|
||||
|
||||
char script [] = "print ('Hello, World!');";
|
||||
jerry_parse (script, strlen (script));
|
||||
|
||||
jerry_run ();
|
||||
|
||||
jerry_cleanup ();
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# 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
|
||||
|
||||
{% highlight 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;
|
||||
{% endhighlight %}
|
||||
|
||||
## See also
|
||||
- [jerry_api_string_t](/API#jerry_api_string_t)
|
||||
- [jerry_api_object_t](/API#jerry_api_object_t)
|
||||
- [jerry_api_eval](/API#jerry_api_eval)
|
||||
- [jerry_api_call_function](/API#jerry_api_call_function)
|
||||
- [jerry_api_construct_object](/API#jerry_api_construct_object)
|
||||
|
||||
|
||||
# jerry_api_eval
|
||||
|
||||
## Summary
|
||||
Perform JavaScript `eval`.
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight 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);
|
||||
{% endhighlight %}
|
||||
|
||||
- `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](/API#jerry_api_create_external_function)
|
||||
- [jerry_api_value_t](/API#jerry_api_value_t)
|
||||
|
||||
## Example
|
||||
{% highlight 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);
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# 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](/API#jerry_api_release_string).
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight cpp %}
|
||||
jerry_api_string_t* jerry_api_create_string (const char *v)
|
||||
{% endhighlight %}
|
||||
|
||||
- `v` - value of string to create;
|
||||
- returned value is pointer to created string.
|
||||
|
||||
|
||||
## See also
|
||||
- [jerry_api_acquire_string](/API#jerry_api_acquire_string)
|
||||
- [jerry_api_release_string](/API#jerry_api_release_string)
|
||||
|
||||
## Example
|
||||
{% highlight cpp %}
|
||||
{
|
||||
jerry_api_string_t *string_p = jerry_api_create_string ("abc");
|
||||
|
||||
...
|
||||
|
||||
jerry_api_release_string (string_p);
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# 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](/API#jerry_api_release_string).
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight cpp %}
|
||||
jerry_api_string_t* jerry_api_acquire_string (jerry_api_string_t *string_p)
|
||||
{% endhighlight %}
|
||||
|
||||
- `string_p` - pointer to the string;
|
||||
- returned value - new pointer to the string.
|
||||
|
||||
## See also
|
||||
- [jerry_api_release_string](/API#jerry_api_release_string)
|
||||
- [jerry_api_create_string](/API#jerry_api_create_string)
|
||||
|
||||
## Example
|
||||
{% highlight 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);
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# jerry_api_release_string
|
||||
|
||||
## Summary
|
||||
Release specified pointer to the string.
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight js %}
|
||||
void jerry_api_release_string (jerry_api_string_t *string_p)
|
||||
{% endhighlight %}
|
||||
|
||||
## See also
|
||||
- [jerry_api_acquire_string](/API#jerry_api_acquire_string)
|
||||
- [jerry_api_create_string](/API#jerry_api_create_string)
|
||||
|
||||
## Example
|
||||
{% highlight 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);
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# 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](/API#jerry_api_release_object).
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight cpp %}
|
||||
jerry_api_object_t* jerry_api_create_object (const char *v)
|
||||
{% endhighlight %}
|
||||
|
||||
- `v` - value of object to create;
|
||||
- returned value is pointer to created object.
|
||||
|
||||
|
||||
## See also
|
||||
- [jerry_api_acquire_object](/API#jerry_api_acquire_object)
|
||||
- [jerry_api_release_object](/API#jerry_api_release_object)
|
||||
|
||||
## Example
|
||||
{% highlight cpp %}
|
||||
{
|
||||
jerry_api_object_t *object_p = jerry_api_create_object ("abc");
|
||||
|
||||
...
|
||||
|
||||
jerry_api_release_object (object_p);
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# 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](/API#jerry_api_release_object).
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight cpp %}
|
||||
jerry_api_object_t* jerry_api_acquire_object (jerry_api_object_t *object_p)
|
||||
{% endhighlight %}
|
||||
|
||||
- `object_p` - pointer to the object;
|
||||
- returned value - new pointer to the object.
|
||||
|
||||
## See also
|
||||
- [jerry_api_release_object](/API#jerry_api_release_object)
|
||||
- [jerry_api_create_object](/API#jerry_api_create_object)
|
||||
|
||||
## Example
|
||||
{% highlight 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);
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# jerry_api_release_object
|
||||
|
||||
## Summary
|
||||
Release specified pointer to the object.
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight cpp %}
|
||||
void jerry_api_release_object (jerry_api_object_t *object_p)
|
||||
{% endhighlight %}
|
||||
|
||||
## See also
|
||||
- [jerry_api_acquire_object](/API#jerry_api_acquire_object)
|
||||
- [jerry_api_create_object](/API#jerry_api_create_object)
|
||||
|
||||
## Example
|
||||
{% highlight 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);
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# jerry_api_is_function
|
||||
|
||||
## Summary
|
||||
Check whether the specified object is a function object.
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight cpp %}
|
||||
bool jerry_api_is_function (const jerry_api_object_t* object_p)
|
||||
{% endhighlight %}
|
||||
|
||||
- `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](/API#jerry_api_value_t)
|
||||
- [jerry_api_is_constructor](/API#jerry_api_is_constructor)
|
||||
- [jerry_api_call_function](/API#jerry_api_call_function)
|
||||
|
||||
## Example
|
||||
{% highlight 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
|
||||
}
|
||||
}
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# jerry_api_is_constructor
|
||||
|
||||
## Summary
|
||||
Check whether the specified object is a constructor function object.
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight cpp %}
|
||||
bool jerry_api_is_constructor (const jerry_api_object_t* object_p)
|
||||
{% endhighlight %}
|
||||
|
||||
- `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](/API#jerry_api_value_t)
|
||||
- [jerry_api_is_function](/API#jerry_api_is_function)
|
||||
- [jerry_api_construct_object](/API#jerry_api_construct_object)
|
||||
|
||||
## Example
|
||||
{% highlight 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
|
||||
}
|
||||
}
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
# jerry_api_call_function
|
||||
|
||||
## Summary
|
||||
Call function object.
|
||||
|
||||
## Prototype
|
||||
|
||||
{% highlight 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)
|
||||
{% endhighlight %}
|
||||
|
||||
- `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](/API#jerry_api_release_value) just when it becomes unnecessary.
|
||||
|
||||
## See also
|
||||
- [jerry_api_is_function](/API#jerry_api_is_function)
|
||||
- [jerry_api_value_t](/API#jerry_api_value_t)
|
||||
|
||||
## Example
|
||||
{% highlight 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);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user