From fe7cc16c6ec69fb00addf9d85d15399e939ba450 Mon Sep 17 00:00:00 2001 From: Evgeny Gavrin Date: Sun, 14 Jun 2015 14:50:14 +0300 Subject: [PATCH] Fix formatting in API --- 03.api.md | 379 +++++++++++++++++++++++++++--------------------------- 1 file changed, 187 insertions(+), 192 deletions(-) diff --git a/03.api.md b/03.api.md index 9c77b18a3..5e43ae5f5 100644 --- a/03.api.md +++ b/03.api.md @@ -4,17 +4,20 @@ title: API permalink: /API/ --- +* toc +{:toc} + # jerry_init -## Summary +**Summary** Initializes JerryScript engine, making possible to run JavaScript code and perform operations on JavaScript values. -## Prototype +**Prototype** -{% highlight cpp %} +```cpp void jerry_init (jerry_flag_t flags); -{% endhighlight %} +``` `flags` - combination of various engine configuration flags: @@ -23,59 +26,60 @@ void jerry_init (jerry_flag_t flags); - `JERRY_FLAG_SHOW_OPCODES` - print compiled byte-code; - `JERRY_FLAG_EMPTY` - no flags, just initialize in default configuration. -## See also +**See also** + - [jerry_cleanup]({{ site.baseurl }}/API#jerry_cleanup) -## Example +**Example** -{% highlight cpp %} +```cpp { jerry_init (JERRY_FLAG_ENABLE_LOG); - // ... - jerry_cleanup (); } -{% endhighlight %} +``` # jerry_cleanup -## Summary +**Summary** -Finish JavaScript engine execution, freeing memory and JavaScript values. +Finish JavaScript engine execution, freeing memory and JavaScript values. JavaScript values, received from engine, are inaccessible after the cleanup. -JavaScript values, received from engine, are inaccessible after the cleanup. +**Prototype** -## Prototype +```cpp +void jerry_cleanup (void); +``` -{% highlight cpp %} -void jerry_cleanup (void) -{% endhighlight %} +**See also** -## See also - [jerry_init]({{ site.baseurl }}/API#jerry_init) # jerry_parse -## Summary +**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 +**Prototype** + +```cpp +bool jerry_parse (const char* source_p, size_t source_size); +``` -{% 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 +**See also** + - [jerry_run]({{ site.baseurl }}/API#jerry_run) -## Example -{% highlight cpp %} +**Example** + +```cpp { jerry_init (JERRY_FLAG_ENABLE_LOG); @@ -86,29 +90,28 @@ bool jerry_parse (const char* source_p, size_t source_size) jerry_cleanup (); } -{% endhighlight %} +``` # jerry_run -## Summary -Run Global scope's code. +**Summary** +Run Global scope's code. The code should be previously registered through `jerry_parse`. -The code should be previously registered through `jerry_parse`. +**Prototype** -## Prototype - -{% highlight cpp %} -jerry_completion_code_t jerry_run (void) -{% endhighlight %} +```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 +**See also** + - [jerry_parse]({{ site.baseurl }}/API#jerry_parse) -## Example +**Example** -{% highlight cpp %} +```cpp { jerry_init (JERRY_FLAG_ENABLE_LOG); @@ -119,13 +122,12 @@ Returned completion code indicates whether run performed successfully (`JERRY_CO jerry_cleanup (); } -{% endhighlight %} +``` # jerry_api_value_t -## Summary +**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; @@ -135,9 +137,9 @@ Type of value is identified by `jerry_api_value_t::type`, and can be one of the - `JERRY_API_DATA_TYPE_STRING` - string; - `JERRY_API_DATA_TYPE_OBJECT` - reference to JavaScript object. -## Structure +**Structure** -{% highlight cpp %} +```cpp typedef struct jerry_api_value_t { jerry_api_data_type_t type; @@ -153,14 +155,15 @@ typedef struct jerry_api_value_t union { - jerry_api_string_t *v_string; - jerry_api_object_t *v_object; + jerry_api_string_t* v_string; + jerry_api_object_t* v_object; }; }; } jerry_api_value_t; -{% endhighlight %} +``` + +**See also** -## 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) @@ -170,19 +173,19 @@ typedef struct jerry_api_value_t # jerry_api_eval -## Summary +**Summary** Perform JavaScript `eval`. -## Prototype +**Prototype** -{% highlight cpp %} +```cpp jerry_completion_code_t -jerry_api_eval (const char *source_p, +jerry_api_eval (const char* source_p, size_t source_size, bool is_direct, bool is_strict, - jerry_api_value_t *retval_p); -{% endhighlight %} + jerry_api_value_t* retval_p); +``` - `source_p` - source code to evaluate; - `source_size` - length of the source code; @@ -190,12 +193,14 @@ jerry_api_eval (const char *source_p, - `is_strict` - perform `eval` as it is called from "strict mode" code; - `retval_p` - value, returned by `eval` (output parameter). -## See also +**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 -{% highlight cpp %} +**Example** + +```cpp { jerry_api_value_t ret_val; @@ -204,231 +209,222 @@ jerry_api_eval (const char *source_p, false, false, &ret_val); } -{% endhighlight %} +``` # jerry_api_create_string -## Summary +**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 +**Prototype** -{% highlight cpp %} -jerry_api_string_t* jerry_api_create_string (const char *v) -{% endhighlight %} +```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 +**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 -{% highlight cpp %} +**Example** +```cpp { - jerry_api_string_t *string_p = jerry_api_create_string ("abc"); - - ... - + jerry_api_string_t* string_p = jerry_api_create_string ("abc"); + // ... jerry_api_release_string (string_p); } -{% endhighlight %} +``` # jerry_api_acquire_string -## Summary +**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 +**Prototype** -{% highlight cpp %} -jerry_api_string_t* jerry_api_acquire_string (jerry_api_string_t *string_p) -{% endhighlight %} +```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 +**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 -{% highlight cpp %} +**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_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 - + // ... // usage of str_ptr2_p pointer jerry_api_release_string (str_ptr2_p); } -{% endhighlight %} +``` # jerry_api_release_string -## Summary +**Summary** + Release specified pointer to the string. -## Prototype +**Prototype** -{% highlight js %} -void jerry_api_release_string (jerry_api_string_t *string_p) -{% endhighlight %} +```cpp +void jerry_api_release_string (jerry_api_string_t* string_p); +``` + +**See also** -## 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 -{% highlight cpp %} +**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_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 - + // ... // usage of str_ptr2_p pointer jerry_api_release_string (str_ptr2_p); } -{% endhighlight %} +``` # jerry_api_create_object -## Summary +**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 +**Prototype** -{% highlight cpp %} -jerry_api_object_t* jerry_api_create_object (const char *v) -{% endhighlight %} +```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 +**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 -{% highlight cpp %} +**Example** + +```cpp { - jerry_api_object_t *object_p = jerry_api_create_object ("abc"); - - ... - + jerry_api_object_t* object_p = jerry_api_create_object ("abc"); + // ... jerry_api_release_object (object_p); } -{% endhighlight %} +``` # jerry_api_acquire_object -## Summary +**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 +**Prototype** -{% highlight cpp %} -jerry_api_object_t* jerry_api_acquire_object (jerry_api_object_t *object_p) -{% endhighlight %} +```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 +**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 -{% highlight cpp %} +**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_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 - + // ... // usage of obj_ptr2_p pointer jerry_api_release_object (obj_ptr2_p); } -{% endhighlight %} +``` # jerry_api_release_object -## Summary +**Summary** Release specified pointer to the object. -## Prototype +**Prototype** -{% highlight cpp %} -void jerry_api_release_object (jerry_api_object_t *object_p) -{% endhighlight %} +```cpp +void jerry_api_release_object (jerry_api_object_t* object_p); +``` + +**See also** -## 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 -{% highlight cpp %} +**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_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 - + // ... // usage of obj_ptr2_p pointer jerry_api_release_object (obj_ptr2_p); } -{% endhighlight %} +``` # jerry_api_is_function -## Summary +**Summary** Check whether the specified object is a function object. -## Prototype +**Prototype** -{% highlight cpp %} -bool jerry_api_is_function (const jerry_api_object_t* object_p) -{% endhighlight %} +```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 +**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 -{% highlight cpp %} +**Example** + +```cpp { jerry_api_value_t val; - - ... // receiving val + // ... // receiving val if (val.type == JERRY_API_DATA_TYPE_OBJECT) { if (jerry_api_is_function (val.v_object)) { @@ -436,57 +432,56 @@ bool jerry_api_is_function (const jerry_api_object_t* object_p) } } } -{% endhighlight %} +``` # jerry_api_is_constructor -## Summary +**Summary** Check whether the specified object is a constructor function object. -## Prototype +**Prototype** -{% highlight cpp %} -bool jerry_api_is_constructor (const jerry_api_object_t* object_p) -{% endhighlight %} +```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 +**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 -{% highlight cpp %} +**Example** + +```cpp { jerry_api_value_t val; - - ... // receiving 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 +**Summary** Call function object. -## Prototype +**Prototype** -{% highlight cpp %} +```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, +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 %} + 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'; @@ -496,19 +491,19 @@ jerry_api_call_function (jerry_api_object_t *function_object_p, - 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. +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** -## 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 -{% highlight cpp %} +**Example** + +```cpp { jerry_api_value_t val; - - ... // receiving 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; @@ -527,4 +522,4 @@ jerry_api_call_function (jerry_api_object_t *function_object_p, } } } -{% endhighlight %} +```