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

Update API-EXAMPLE.md

Browse Source 
Fix Jerry style and update to the current API.

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-05-09 13:57:34 +02:00
parent 7e0cd850a7
commit 210ba6dc85
1 changed files with 168 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API-EXAMPLE.md
+168 -88
View File
@@ -9,12 +9,16 @@ This guide is intended to introduce you to JerryScript embedding API through cre
#include "jerry.h" #include "jerry.h"
int int
main (int argc, char * argv[]) { main (int argc, char * argv[])
char script [] = "print ('Hello, World!');"; {
const jerry_api_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
jerry_completion_code_t code = jerry_run_simple (script, jerry_completion_code_t return_code = jerry_run_simple (script,
strlen (script), script_size,
JERRY_FLAG_EMPTY); JERRY_FLAG_EMPTY);
return (int) return_code;
} }
``` ```
@@ -39,20 +43,38 @@ Here we perform the same actions, as `jerry_run_simple`, while splitting into se
#include "jerry.h" #include "jerry.h"
int int
main (int argc, char * argv[]) { main (int argc, char * argv[])
char script [] = "print ('Hello, World!');"; {
const jerry_api_char_t script[] = "print ('Hello, World!');";
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_parse (script, strlen (script)); jerry_api_object_t *error_object_p = NULL;
if (!jerry_parse (script, script_size, &error_object_p))
{
/* Error object must be freed, if parsing failed */
jerry_api_release_object (error_object_p);
}
else
{
/* Execute Global scope code */
jerry_api_value_t error_value = jerry_api_create_void_value ();
jerry_completion_code_t return_code = jerry_run (&error_value);
// Execute Global scope code if (return_code == JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION)
jerry_completion_code_t code = jerry_run (); {
/* Error value must be freed, if 'jerry_run' returns with an unhandled exception */
jerry_api_release_value (&error_value);
}
}
// Cleanup engine /* Cleanup engine */
jerry_cleanup (); jerry_cleanup ();
return 0;
} }
``` ```
@@ -65,29 +87,40 @@ Our code is more complex now, but it introduces possibilities to interact with J
#include "jerry.h" #include "jerry.h"
int int
main (int argc, char * argv[]) { main (int argc, char * argv[])
char script1 [] = "var s = 'Hello, World!';"; {
char script2 [] = "print (s);"; const jerry_api_char_t script_1[] = "var s = 'Hello, World!';";
const jerry_api_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_api_value_t eval_ret;
// Evaluate script1 /* Evaluate script1 */
jerry_api_eval (script1, strlen (script1), jerry_api_eval (script_1,
false, false, &eval_ret); strlen ((const char *) script_1),
// Free JavaScript value, returned by eval false,
false,
&eval_ret);
/* Free JavaScript value, returned by eval */
jerry_api_release_value (&eval_ret); jerry_api_release_value (&eval_ret);
// Evaluate script2 /* Evaluate script2 */
jerry_api_eval (script2, strlen (script2), jerry_api_eval (script_2,
false, false, &eval_ret); strlen ((const char *) script_2),
// Free JavaScript value, returned by eval false,
false,
&eval_ret);
/* Free JavaScript value, returned by eval */
jerry_api_release_value (&eval_ret); jerry_api_release_value (&eval_ret);
// Cleanup engine /* Cleanup engine */
jerry_cleanup (); jerry_cleanup ();
return 0;
} }
``` ```
@@ -101,42 +134,49 @@ This way, we execute two independent script parts in one execution environment.
int int
main (int argc, char * argv[]) { main (int argc, char * argv[]) {
char str [] = "Hello, World!"; const jerry_api_char_t str[] = "Hello, World!";
char var_name [] = "s"; const jerry_api_char_t var_name[] = "s";
char script [] = "print (s);"; const jerry_api_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 *obj_p = jerry_api_get_global_object (); jerry_api_object_t *object_p = jerry_api_get_global ();
// Constructing string /* Constructing string */
jerry_api_string_t *str_val_p = jerry_api_create_string (str); jerry_api_string_t *str_val_p = jerry_api_create_string (str);
// Constructing string value descriptor /* Constructing string value descriptor */
jerry_api_value_t val; jerry_api_value_t value;
val.type = JERRY_API_DATA_TYPE_STRING; value.type = JERRY_API_DATA_TYPE_STRING;
val.string_p = 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 (obj_p, var_name, &val); jerry_api_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_api_release_string (str_val_p);
// Same for pointer to the Global object /* Same for pointer to the Global object */
jerry_api_release_object (obj_p); jerry_api_release_object (object_p);
jerry_api_value_t eval_ret; jerry_api_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, strlen (script), jerry_api_eval (script,
false, false, &eval_ret); strlen ((const char *) script),
false,
false,
&eval_ret);
/* Free JavaScript value, returned by eval */
jerry_api_release_value (&eval_ret); jerry_api_release_value (&eval_ret);
// Freeing engine /* Freeing engine */
jerry_cleanup (); jerry_cleanup ();
return 0;
} }
``` ```
@@ -147,14 +187,19 @@ The sample will also output 'Hello, World!'. However, now it is not just a part
Structure, used to put values to or receive values from the engine is the following: Structure, used to put values to or receive values from the engine is the following:
- `type` of the value: - `type` of the value:
- JERRY_API_DATA_TYPE_VOID (void);
- JERRY_API_DATA_TYPE_UNDEFINED (undefined); - JERRY_API_DATA_TYPE_UNDEFINED (undefined);
- JERRY_API_DATA_TYPE_NULL (null); - JERRY_API_DATA_TYPE_NULL (null);
- JERRY_API_DATA_TYPE_BOOLEAN (true / false); - JERRY_API_DATA_TYPE_BOOLEAN (true / false);
- JERRY_API_DATA_TYPE_FLOAT32 (number);
- JERRY_API_DATA_TYPE_FLOAT64 (number); - JERRY_API_DATA_TYPE_FLOAT64 (number);
- JERRY_API_DATA_TYPE_UINT32 (number);
- JERRY_API_DATA_TYPE_STRING (string); - JERRY_API_DATA_TYPE_STRING (string);
- JERRY_API_DATA_TYPE_OBJECT (object reference); - JERRY_API_DATA_TYPE_OBJECT (object reference);
- `v_bool` (if JERRY_API_DATA_TYPE_BOOLEAN) - boolean value; - `v_bool` (if JERRY_API_DATA_TYPE_BOOLEAN) - boolean value;
- `v_float64` (if JERRY_API_DATA_TYPE_FLOAT64) - number value; - `v_float32` (if JERRY_API_DATA_TYPE_FLOAT32) - float value;
- `v_float64` (if JERRY_API_DATA_TYPE_FLOAT64) - double value;
- `v_uint32` (if JERRY_API_DATA_TYPE_UINT32) - 32 bit unsigned integer value;
- `v_string` (if JERRY_API_DATA_TYPE_STRING) - pointer to string; - `v_string` (if JERRY_API_DATA_TYPE_STRING) - pointer to string;
- `v_object` (if JERRY_API_DATA_TYPE_OBJECT) - pointer to object. - `v_object` (if JERRY_API_DATA_TYPE_OBJECT) - pointer to object.
@@ -165,52 +210,80 @@ Pointers to strings or objects and values should be released just when become un
The following example function will output a JavaScript value: The following example function will output a JavaScript value:
```c ```c
#include <stdlib.h>
static void static void
print_value (const jerry_api_value_t * value_p) print_value (const jerry_api_value_t *value_p)
{ {
switch (value_p->type) switch (value_p->type)
{ {
// Simple values: undefined, null, false, true /* Simple values: void, undefined, null, false, true */
case JERRY_API_DATA_TYPE_VOID:
{
printf ("void");
break;
}
case JERRY_API_DATA_TYPE_UNDEFINED: case JERRY_API_DATA_TYPE_UNDEFINED:
{
printf ("undefined"); printf ("undefined");
break; break;
}
case JERRY_API_DATA_TYPE_NULL: case JERRY_API_DATA_TYPE_NULL:
{
printf ("null"); printf ("null");
break; break;
}
case JERRY_API_DATA_TYPE_BOOLEAN: case JERRY_API_DATA_TYPE_BOOLEAN:
if (value_p->v_bool) {
if (value_p->u.v_bool)
{
printf ("true"); printf ("true");
}
else else
{
printf ("false"); printf ("false");
}
break; break;
}
// Number value /* Float value */
case JERRY_API_DATA_TYPE_FLOAT32:
{
printf ("%f", value_p->u.v_float32);
break;
}
/* Double value */
case JERRY_API_DATA_TYPE_FLOAT64: case JERRY_API_DATA_TYPE_FLOAT64:
printf ("%lf", value_p->v_float64); {
printf ("%lf", value_p->u.v_float64);
break; break;
}
// String value /* Unsigned integer value */
case JERRY_API_DATA_TYPE_UINT32:
{
printf ("%d", value_p->u.v_uint32);
break;
}
/* String value */
case JERRY_API_DATA_TYPE_STRING: case JERRY_API_DATA_TYPE_STRING:
{ {
jerry_api_size_t req_sz, sz; /* Determining required buffer size */
// determining required buffer size jerry_api_size_t req_sz = jerry_api_get_string_size (value_p->u.v_string);
req_sz = jerry_api_get_string_size (value_p->v_string); jerry_api_char_t *str_buf_p = (jerry_api_char_t *) malloc (req_sz);
char * str_buf_p = (char*) malloc (req_sz); jerry_api_string_to_char_buffer (value_p->u.v_string,
sz = jerry_api_string_to_char_buffer (value_p->v_string, str_buf_p,
str_buf_p, req_sz);
req_sz);
assert (sz == req_sz);
printf ("%s", str_buf_p); printf ("%s", (const char *) str_buf_p);
free (str_buf_p); free (str_buf_p);
break; break;
} }
/* Object reference */
// Object reference
case JERRY_API_DATA_TYPE_OBJECT: case JERRY_API_DATA_TYPE_OBJECT:
{
printf ("[JS object]"); printf ("[JS object]");
break; break;
}
} }
printf ("\n"); printf ("\n");
@@ -232,58 +305,65 @@ Shell operation can be described with the following loop:
- loop. - loop.
```c ```c
#include <assert.h>
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
#include <string.h> #include <string.h>
#include "jerry.h" #include "jerry.h"
static void static void print_value (const jerry_api_value_t *value_p);
print_value (const jerry_api_value_t * value_p);
int int
main (int argc, char * argv[]) { main (int argc, char * argv[])
// Initialize engine {
jerry_completion_code_t status = JERRY_COMPLETION_CODE_OK;
/* Initialize engine */
jerry_init (JERRY_FLAG_EMPTY); jerry_init (JERRY_FLAG_EMPTY);
char cmd [256]; char cmd [256];
while (true) { while (true)
{
printf ("> "); printf ("> ");
// Input next command /* Input next command */
if (fgets (cmd, sizeof (cmd), stdin) == NULL if (fgets (cmd, sizeof (cmd), stdin) == NULL
|| strcmp (cmd, "quit\n") == 0) { || strcmp (cmd, "quit\n") == 0)
// If the command is 'quit', exit from loop {
/* If the command is 'quit', exit from loop */
break; break;
} }
jerry_api_value_t ret_val; jerry_api_value_t ret_val;
// Evaluate entered command /* Evaluate entered command */
jerry_completion_code_t status = jerry_api_eval (cmd, strlen (cmd), status = jerry_api_eval ((const jerry_api_char_t *) cmd,
false, false, strlen (cmd),
&ret_val); false,
false,
&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_api_release_value (&ret_val);
} else { }
// evaluated JS code thrown an exception else
// and didn't handle it with try-catch-finally {
/* Evaluated JS code thrown an exception
and didn't handle it with try-catch-finally */
printf ("Unhandled JS exception occured\n"); printf ("Unhandled JS exception occured\n");
} }
printf ("\n");
fflush (stdout); fflush (stdout);
} }
// Cleanup engine /* Cleanup engine */
jerry_cleanup (); jerry_cleanup ();
return 0; return (int) status;
} }
``` ```