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

Updated API examples, after API changes

Browse Source 
JerryScript-DCO-1.0-Signed-off-by: László Langó llango.u-szeged@partner.samsung.com
This commit is contained in:
László Langó
2016-06-08 09:29:00 +02:00
parent 824d39c2a2
commit b5efa2ea03
1 changed files with 109 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API-EXAMPLE.md
+109 -119
View File
@@ -11,7 +11,7 @@ This guide is intended to introduce you to JerryScript embedding API through cre
int int
main (int argc, char * argv[]) main (int argc, char * argv[])
{ {
const jerry_api_char_t script[] = "print ('Hello, World!');"; const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script); size_t script_size = strlen ((const char *) script);
jerry_completion_code_t return_code = jerry_run_simple (script, jerry_completion_code_t return_code = jerry_run_simple (script,
@@ -45,29 +45,29 @@ Here we perform the same actions, as `jerry_run_simple`, while splitting into se
int int
main (int argc, char * argv[]) main (int argc, char * argv[])
{ {
const jerry_api_char_t script[] = "print ('Hello, World!');"; const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script); size_t script_size = strlen ((const char *) script);
/* Initialize engine */ /* Initialize engine */
jerry_init (JERRY_FLAG_EMPTY); jerry_init (JERRY_FLAG_EMPTY);
/* Setup Global scope code */ /* Setup Global scope code */
jerry_api_object_t *error_object_p = NULL; jerry_object_t *error_object_p = NULL;
if (!jerry_parse (script, script_size, &error_object_p)) if (!jerry_parse (script, script_size, &error_object_p))
{ {
/* Error object must be freed, if parsing failed */ /* Error object must be freed, if parsing failed */
jerry_api_release_object (error_object_p); jerry_release_object (error_object_p);
} }
else else
{ {
/* Execute Global scope code */ /* Execute Global scope code */
jerry_api_value_t error_value = jerry_api_create_void_value (); jerry_value_t error_value = jerry_create_void_value ();
jerry_completion_code_t return_code = jerry_run (&error_value); jerry_completion_code_t return_code = jerry_run (&error_value);
if (return_code == JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION) if (return_code == JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION)
{ {
/* Error value must be freed, if 'jerry_run' returns with an unhandled exception */ /* Error value must be freed, if 'jerry_run' returns with an unhandled exception */
jerry_api_release_value (&error_value); jerry_release_value (&error_value);
} }
} }
@@ -89,33 +89,33 @@ Our code is more complex now, but it introduces possibilities to interact with J
int int
main (int argc, char * argv[]) main (int argc, char * argv[])
{ {
const jerry_api_char_t script_1[] = "var s = 'Hello, World!';"; const jerry_char_t script_1[] = "var s = 'Hello, World!';";
const jerry_api_char_t script_2[] = "print (s);"; const jerry_char_t script_2[] = "print (s);";
/* Initialize engine */ /* Initialize engine */
jerry_init (JERRY_FLAG_EMPTY); jerry_init (JERRY_FLAG_EMPTY);
jerry_api_value_t eval_ret; jerry_value_t eval_ret;
/* Evaluate script1 */ /* Evaluate script1 */
jerry_api_eval (script_1, jerry_eval (script_1,
strlen ((const char *) script_1), strlen ((const char *) script_1),
false, false,
false, false,
&eval_ret); &eval_ret);
/* Free JavaScript value, returned by eval */ /* Free JavaScript value, returned by eval */
jerry_api_release_value (&eval_ret); jerry_release_value (&eval_ret);
/* Evaluate script2 */ /* Evaluate script2 */
jerry_api_eval (script_2, jerry_eval (script_2,
strlen ((const char *) script_2), strlen ((const char *) script_2),
false, false,
false, false,
&eval_ret); &eval_ret);
/* Free JavaScript value, returned by eval */ /* Free JavaScript value, returned by eval */
jerry_api_release_value (&eval_ret); jerry_release_value (&eval_ret);
/* Cleanup engine */ /* Cleanup engine */
jerry_cleanup (); jerry_cleanup ();
@@ -134,44 +134,44 @@ This way, we execute two independent script parts in one execution environment.
int int
main (int argc, char * argv[]) { main (int argc, char * argv[]) {
const jerry_api_char_t str[] = "Hello, World!"; const jerry_char_t str[] = "Hello, World!";
const jerry_api_char_t var_name[] = "s"; const jerry_char_t var_name[] = "s";
const jerry_api_char_t script[] = "print (s);"; const jerry_char_t script[] = "print (s);";
/* Initializing JavaScript environment */ /* Initializing JavaScript environment */
jerry_init (JERRY_FLAG_EMPTY); jerry_init (JERRY_FLAG_EMPTY);
/* Getting pointer to the Global object */ /* Getting pointer to the Global object */
jerry_api_object_t *object_p = jerry_api_get_global (); jerry_object_t *object_p = jerry_get_global ();
/* Constructing string */ /* Constructing string */
jerry_api_string_t *str_val_p = jerry_api_create_string (str); jerry_string_t *str_val_p = jerry_create_string (str);
/* Constructing string value descriptor */ /* Constructing string value descriptor */
jerry_api_value_t value; jerry_value_t value;
value.type = JERRY_API_DATA_TYPE_STRING; value.type = JERRY_API_DATA_TYPE_STRING;
value.u.v_string = str_val_p; value.u.v_string = str_val_p;
/* Setting the string value to field of the Global object */ /* Setting the string value to field of the Global object */
jerry_api_set_object_field_value (object_p, var_name, &value); jerry_set_object_field_value (object_p, var_name, &value);
/* Releasing string value, as it is no longer necessary outside of engine */ /* Releasing string value, as it is no longer necessary outside of engine */
jerry_api_release_string (str_val_p); jerry_release_string (str_val_p);
/* Same for pointer to the Global object */ /* Same for pointer to the Global object */
jerry_api_release_object (object_p); jerry_release_object (object_p);
jerry_api_value_t eval_ret; jerry_value_t eval_ret;
/* Now starting script that would output value of just initialized field */ /* Now starting script that would output value of just initialized field */
jerry_api_eval (script, jerry_eval (script,
strlen ((const char *) script), strlen ((const char *) script),
false, false,
false, false,
&eval_ret); &eval_ret);
/* Free JavaScript value, returned by eval */ /* Free JavaScript value, returned by eval */
jerry_api_release_value (&eval_ret); jerry_release_value (&eval_ret);
/* Freeing engine */ /* Freeing engine */
jerry_cleanup (); jerry_cleanup ();
@@ -205,7 +205,7 @@ Structure, used to put values to or receive values from the engine is the follow
Abstract values, to be sent to or received from the engine are described with the structure. Abstract values, to be sent to or received from the engine are described with the structure.
Pointers to strings or objects and values should be released just when become unnecessary, using `jerry_api_release_string` or `jerry_api_release_object` and `jerry_api_release_value`, correspondingly. Pointers to strings or objects and values should be released just when become unnecessary, using `jerry_release_string` or `jerry_release_object` and `jerry_release_value`, correspondingly.
The following example function will output a JavaScript value: The following example function will output a JavaScript value:
@@ -213,7 +213,7 @@ The following example function will output a JavaScript value:
#include <stdlib.h> #include <stdlib.h>
static void static void
print_value (const jerry_api_value_t *value_p) print_value (const jerry_value_t *value_p)
{ {
switch (value_p->type) switch (value_p->type)
{ {
@@ -267,11 +267,9 @@ print_value (const jerry_api_value_t *value_p)
case JERRY_API_DATA_TYPE_STRING: case JERRY_API_DATA_TYPE_STRING:
{ {
/* Determining required buffer size */ /* Determining required buffer size */
jerry_api_size_t req_sz = jerry_api_get_string_size (value_p->u.v_string); jerry_size_t req_sz = jerry_get_string_size (value_p->u.v_string);
jerry_api_char_t *str_buf_p = (jerry_api_char_t *) malloc (req_sz); jerry_char_t *str_buf_p = (jerry_char_t *) malloc (req_sz);
jerry_api_string_to_char_buffer (value_p->u.v_string, jerry_string_to_char_buffer (value_p->u.v_string, str_buf_p, req_sz);
str_buf_p,
req_sz);
printf ("%s", (const char *) str_buf_p); printf ("%s", (const char *) str_buf_p);
@@ -311,7 +309,7 @@ Shell operation can be described with the following loop:
#include "jerry.h" #include "jerry.h"
static void print_value (const jerry_api_value_t *value_p); static void print_value (const jerry_value_t *value_p);
int int
main (int argc, char * argv[]) main (int argc, char * argv[])
@@ -334,21 +332,21 @@ main (int argc, char * argv[])
break; break;
} }
jerry_api_value_t ret_val; jerry_value_t ret_val;
/* Evaluate entered command */ /* Evaluate entered command */
status = jerry_api_eval ((const jerry_api_char_t *) cmd, status = jerry_eval ((const jerry_char_t *) cmd,
strlen (cmd), strlen (cmd),
false, false,
false, false,
&ret_val); &ret_val);
/* If command evaluated successfully, print value, returned by eval */ /* If command evaluated successfully, print value, returned by eval */
if (status == JERRY_COMPLETION_CODE_OK) if (status == JERRY_COMPLETION_CODE_OK)
{ {
/* 'eval' completed successfully */ /* 'eval' completed successfully */
print_value (&ret_val); print_value (&ret_val);
jerry_api_release_value (&ret_val); jerry_release_value (&ret_val);
} }
else else
{ {
@@ -386,14 +384,14 @@ struct my_struct
* Get a string from a native object * Get a string from a native object
*/ */
static bool static bool
get_msg_handler (const jerry_api_object_t *function_obj_p, /**< function object */ get_msg_handler (const jerry_object_t *function_obj_p, /**< function object */
const jerry_api_value_t *this_p, /**< this arg */ const jerry_value_t *this_p, /**< this arg */
jerry_api_value_t *ret_val_p, /**< return argument */ jerry_value_t *ret_val_p, /**< return argument */
const jerry_api_value_t *args_p, /**< function arguments */ const jerry_value_t *args_p, /**< function arguments */
const jerry_api_length_t args_cnt) /**< number of function arguments */ const jerry_length_t args_cnt) /**< number of function arguments */
{ {
jerry_api_string_t *msg_str_p = jerry_api_create_string ((const jerry_api_char_t *) my_struct.msg); jerry_string_t *msg_str_p = jerry_create_string ((const jerry_char_t *) my_struct.msg);
*ret_val_p = jerry_api_create_string_value (msg_str_p); *ret_val_p = jerry_create_string_value (msg_str_p);
return true; return true;
} /* get_msg_handler */ } /* get_msg_handler */
@@ -410,53 +408,49 @@ main (int argc, char * argv[])
my_struct.msg = "Hello World"; my_struct.msg = "Hello World";
/* Create an empty JS object */ /* Create an empty JS object */
jerry_api_object_t *object_p = jerry_api_create_object (); jerry_object_t *object_p = jerry_create_object ();
/* Create a JS function object and wrap into a jerry value */ /* Create a JS function object and wrap into a jerry value */
jerry_api_value_t object_value; jerry_value_t object_value;
object_value.type = JERRY_API_DATA_TYPE_OBJECT; object_value.type = JERRY_API_DATA_TYPE_OBJECT;
object_value.u.v_object = jerry_api_create_external_function (get_msg_handler); object_value.u.v_object = jerry_create_external_function (get_msg_handler);
/* Set the native function as a property of the empty JS object */ /* Set the native function as a property of the empty JS object */
jerry_api_set_object_field_value (object_p, jerry_set_object_field_value (object_p,
(const jerry_api_char_t *) "myFunc", (const jerry_char_t *) "myFunc",
&object_value); &object_value);
jerry_api_release_value (&object_value); jerry_release_value (&object_value);
/* Wrap the JS object (not empty anymore) into a jerry api value */ /* Wrap the JS object (not empty anymore) into a jerry api value */
object_value.type = JERRY_API_DATA_TYPE_OBJECT; object_value.type = JERRY_API_DATA_TYPE_OBJECT;
object_value.u.v_object = object_p; object_value.u.v_object = object_p;
jerry_api_object_t *global_obj_p = jerry_api_get_global (); jerry_object_t *global_obj_p = jerry_get_global ();
/* Add the JS object to the global context */ /* Add the JS object to the global context */
jerry_api_set_object_field_value (global_obj_p, jerry_set_object_field_value (global_obj_p,
(const jerry_api_char_t *) "MyObject", (const jerry_char_t *) "MyObject",
&object_value); &object_value);
jerry_api_release_value (&object_value); jerry_release_value (&object_value);
jerry_api_release_object (global_obj_p); jerry_release_object (global_obj_p);
/* Now we have a "builtin" object called MyObject with a function called myFunc() /* Now we have a "builtin" object called MyObject with a function called myFunc()
* *
* Equivalent JS code: * Equivalent JS code:
* var MyObject = { myFunc : function () { return "some string value"; } } * var MyObject = { myFunc : function () { return "some string value"; } }
*/ */
const jerry_api_char_t script[] = " \ const jerry_char_t script[] = " \
var str = MyObject.myFunc (); \ var str = MyObject.myFunc (); \
print (str); \ print (str); \
"; ";
size_t script_size = strlen ((const char *) script); size_t script_size = strlen ((const char *) script);
jerry_api_value_t eval_ret; jerry_value_t eval_ret;
/* Evaluate script */ /* Evaluate script */
status = jerry_api_eval (script, status = jerry_eval (script, script_size, false, false, &eval_ret);
script_size,
false,
false,
&eval_ret);
/* Free JavaScript value, returned by eval */ /* Free JavaScript value, returned by eval */
jerry_api_release_value (&eval_ret); jerry_release_value (&eval_ret);
/* Cleanup engine */ /* Cleanup engine */
jerry_cleanup (); jerry_cleanup ();
@@ -473,7 +467,7 @@ Hello World
## Step 7. Extending JS Objects with native functions ## Step 7. Extending JS Objects with native functions
Here we create a JS Object with `jerry_api_eval`, then extend it with a native function. This function shows how to get a property value from the object and how to manipulate it. Here we create a JS Object with `jerry_eval`, then extend it with a native function. This function shows how to get a property value from the object and how to manipulate it.
```c ```c
#include <string.h> #include <string.h>
@@ -483,30 +477,30 @@ Here we create a JS Object with `jerry_api_eval`, then extend it with a native f
* Add param to 'this.x' * Add param to 'this.x'
*/ */
static bool static bool
add_handler (const jerry_api_object_t *function_obj_p, /**< function object */ add_handler (const jerry_object_t *function_obj_p, /**< function object */
const jerry_api_value_t *this_p, /**< this arg */ const jerry_value_t *this_p, /**< this arg */
jerry_api_value_t *ret_val_p, /**< return argument */ jerry_value_t *ret_val_p, /**< return argument */
const jerry_api_value_t *args_p, /**< function arguments */ const jerry_value_t *args_p, /**< function arguments */
const jerry_api_length_t args_cnt) /**< number of function arguments */ const jerry_length_t args_cnt) /**< number of function arguments */
{ {
jerry_api_value_t x_val; jerry_value_t x_val;
/* Get 'this.x' */ /* Get 'this.x' */
if (jerry_api_get_object_field_value (jerry_api_get_object_value (this_p), if (jerry_get_object_field_value (jerry_get_object_value (this_p),
(const jerry_api_char_t *) "x", (const jerry_char_t *) "x",
&x_val)) &x_val))
{ {
/* Convert Jerry API values to double */ /* Convert Jerry API values to double */
double x = jerry_api_get_number_value (&x_val); double x = jerry_get_number_value (&x_val);
double d = jerry_api_get_number_value (args_p); double d = jerry_get_number_value (args_p);
/* Add the parameter to 'x' */ /* Add the parameter to 'x' */
jerry_api_value_t res_val = jerry_api_create_number_value (x + d); jerry_value_t res_val = jerry_create_number_value (x + d);
/* Set the new value of 'this.x' */ /* Set the new value of 'this.x' */
jerry_api_set_object_field_value (jerry_api_get_object_value (this_p), jerry_set_object_field_value (jerry_get_object_value (this_p),
(const jerry_api_char_t *) "x", (const jerry_char_t *) "x",
&res_val); &res_val);
} }
@@ -522,7 +516,7 @@ main (int argc, char * argv[])
jerry_init (JERRY_FLAG_EMPTY); jerry_init (JERRY_FLAG_EMPTY);
/* Create a JS object */ /* Create a JS object */
const jerry_api_char_t my_js_object[] = " \ const jerry_char_t my_js_object[] = " \
MyObject = \ MyObject = \
{ x : 12, \ { x : 12, \
y : 'Value of x is ', \ y : 'Value of x is ', \
@@ -533,32 +527,32 @@ main (int argc, char * argv[])
} \ } \
"; ";
jerry_api_value_t my_js_obj_val; jerry_value_t my_js_obj_val;
/* Evaluate script */ /* Evaluate script */
status = jerry_api_eval (my_js_object, status = jerry_eval (my_js_object,
strlen ((const char *) my_js_object), strlen ((const char *) my_js_object),
false, false,
false, false,
&my_js_obj_val); &my_js_obj_val);
jerry_api_object_t *object_p = jerry_api_get_object_value (&my_js_obj_val); jerry_object_t *object_p = jerry_get_object_value (&my_js_obj_val);
/* Create a JS function object and wrap into a jerry value */ /* Create a JS function object and wrap into a jerry value */
jerry_api_value_t object_value; jerry_value_t object_value;
object_value.type = JERRY_API_DATA_TYPE_OBJECT; object_value.type = JERRY_API_DATA_TYPE_OBJECT;
object_value.u.v_object = jerry_api_create_external_function (add_handler); object_value.u.v_object = jerry_create_external_function (add_handler);
/* Set the native function as a property of previously created MyObject */ /* Set the native function as a property of previously created MyObject */
jerry_api_set_object_field_value (object_p, jerry_set_object_field_value (object_p,
(const jerry_api_char_t *) "add2x", (const jerry_char_t *) "add2x",
&object_value); &object_value);
jerry_api_release_value (&object_value); jerry_release_value (&object_value);
/* Free JavaScript value, returned by eval (my_js_object) */ /* Free JavaScript value, returned by eval (my_js_object) */
jerry_api_release_value (&my_js_obj_val); jerry_release_value (&my_js_obj_val);
const jerry_api_char_t script[] = " \ const jerry_char_t script[] = " \
var str = MyObject.foo (); \ var str = MyObject.foo (); \
print (str); \ print (str); \
MyObject.add2x (5); \ MyObject.add2x (5); \
@@ -566,17 +560,13 @@ main (int argc, char * argv[])
"; ";
size_t script_size = strlen ((const char *) script); size_t script_size = strlen ((const char *) script);
jerry_api_value_t eval_ret; jerry_value_t eval_ret;
/* Evaluate script */ /* Evaluate script */
status = jerry_api_eval (script, status = jerry_eval (script, script_size, false, false, &eval_ret);
script_size,
false,
false,
&eval_ret);
/* Free JavaScript value, returned by eval */ /* Free JavaScript value, returned by eval */
jerry_api_release_value (&eval_ret); jerry_release_value (&eval_ret);
/* Cleanup engine */ /* Cleanup engine */
jerry_cleanup (); jerry_cleanup ();