YourWishes/jerryscript
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix formatting in API

Browse Source
This commit is contained in:
Evgeny Gavrin
2015-06-14 14:50:14 +03:00
parent f8c37a292f
commit fe7cc16c6e
1 changed files with 187 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03.api.md
+187 -192
View File
@@ -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 %}
```