diff --git a/03.api.md b/03.api.md index f13ea06f2..f4667f52e 100644 --- a/03.api.md +++ b/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 %}