diff --git a/docs/API-EXAMPLE.md b/docs/API-EXAMPLE.md index 2cb4ec024..fd55e82cb 100644 --- a/docs/API-EXAMPLE.md +++ b/docs/API-EXAMPLE.md @@ -9,12 +9,16 @@ This guide is intended to introduce you to JerryScript embedding API through cre #include "jerry.h" int -main (int argc, char * argv[]) { - char script [] = "print ('Hello, World!');"; +main (int argc, char * argv[]) +{ + 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, - strlen (script), - JERRY_FLAG_EMPTY); + jerry_completion_code_t return_code = jerry_run_simple (script, + script_size, + 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" int -main (int argc, char * argv[]) { - char script [] = "print ('Hello, World!');"; +main (int argc, char * argv[]) +{ + 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); - // Setup Global scope code - jerry_parse (script, strlen (script)); + /* Setup Global scope code */ + 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 - jerry_completion_code_t code = jerry_run (); + if (return_code == JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION) + { + /* 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 (); + + return 0; } ``` @@ -65,29 +87,40 @@ Our code is more complex now, but it introduces possibilities to interact with J #include "jerry.h" int -main (int argc, char * argv[]) { - char script1 [] = "var s = 'Hello, World!';"; - char script2 [] = "print (s);"; +main (int argc, char * argv[]) +{ + 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_api_value_t eval_ret; - // Evaluate script1 - jerry_api_eval (script1, strlen (script1), - false, false, &eval_ret); - // Free JavaScript value, returned by eval + /* Evaluate script1 */ + jerry_api_eval (script_1, + strlen ((const char *) script_1), + false, + false, + &eval_ret); + + /* Free JavaScript value, returned by eval */ jerry_api_release_value (&eval_ret); - // Evaluate script2 - jerry_api_eval (script2, strlen (script2), - false, false, &eval_ret); - // Free JavaScript value, returned by eval + /* Evaluate script2 */ + jerry_api_eval (script_2, + strlen ((const char *) script_2), + false, + false, + &eval_ret); + + /* Free JavaScript value, returned by eval */ jerry_api_release_value (&eval_ret); - // Cleanup engine + /* Cleanup engine */ jerry_cleanup (); + + return 0; } ``` @@ -101,42 +134,49 @@ This way, we execute two independent script parts in one execution environment. int main (int argc, char * argv[]) { - char str [] = "Hello, World!"; - char var_name [] = "s"; - char script [] = "print (s);"; + const jerry_api_char_t str[] = "Hello, World!"; + const jerry_api_char_t var_name[] = "s"; + const jerry_api_char_t script[] = "print (s);"; - // Initializing JavaScript environment + /* Initializing JavaScript environment */ jerry_init (JERRY_FLAG_EMPTY); - // Getting pointer to the Global object - jerry_api_object_t *obj_p = jerry_api_get_global_object (); + /* Getting pointer to the 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); - // Constructing string value descriptor - jerry_api_value_t val; - val.type = JERRY_API_DATA_TYPE_STRING; - val.string_p = str_val_p; + /* Constructing string value descriptor */ + jerry_api_value_t value; + value.type = JERRY_API_DATA_TYPE_STRING; + value.u.v_string = str_val_p; - // Setting the string value to field of the Global object - jerry_api_set_object_field_value (obj_p, var_name, &val); + /* Setting the string value to field of the Global object */ + 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); - // Same for pointer to the Global object - jerry_api_release_object (obj_p); + /* Same for pointer to the Global object */ + jerry_api_release_object (object_p); jerry_api_value_t eval_ret; - // Now starting script that would output value of just initialized field - jerry_api_eval (script, strlen (script), - false, false, &eval_ret); + /* Now starting script that would output value of just initialized field */ + jerry_api_eval (script, + strlen ((const char *) script), + false, + false, + &eval_ret); + + /* Free JavaScript value, returned by eval */ jerry_api_release_value (&eval_ret); - // Freeing engine + /* Freeing engine */ 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: - `type` of the value: + - JERRY_API_DATA_TYPE_VOID (void); - JERRY_API_DATA_TYPE_UNDEFINED (undefined); - JERRY_API_DATA_TYPE_NULL (null); - JERRY_API_DATA_TYPE_BOOLEAN (true / false); + - JERRY_API_DATA_TYPE_FLOAT32 (number); - JERRY_API_DATA_TYPE_FLOAT64 (number); + - JERRY_API_DATA_TYPE_UINT32 (number); - JERRY_API_DATA_TYPE_STRING (string); - JERRY_API_DATA_TYPE_OBJECT (object reference); - `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_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: ```c +#include + static void -print_value (const jerry_api_value_t * value_p) +print_value (const jerry_api_value_t *value_p) { 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: + { printf ("undefined"); break; + } case JERRY_API_DATA_TYPE_NULL: + { printf ("null"); break; + } case JERRY_API_DATA_TYPE_BOOLEAN: - if (value_p->v_bool) + { + if (value_p->u.v_bool) + { printf ("true"); + } else + { printf ("false"); + } 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: - printf ("%lf", value_p->v_float64); + { + printf ("%lf", value_p->u.v_float64); 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: { - jerry_api_size_t req_sz, sz; - // determining required buffer size - req_sz = jerry_api_get_string_size (value_p->v_string); - char * str_buf_p = (char*) malloc (req_sz); - sz = jerry_api_string_to_char_buffer (value_p->v_string, - str_buf_p, - req_sz); - assert (sz == req_sz); + /* Determining required buffer size */ + jerry_api_size_t req_sz = jerry_api_get_string_size (value_p->u.v_string); + jerry_api_char_t *str_buf_p = (jerry_api_char_t *) malloc (req_sz); + jerry_api_string_to_char_buffer (value_p->u.v_string, + str_buf_p, + req_sz); - printf ("%s", str_buf_p); + printf ("%s", (const char *) str_buf_p); free (str_buf_p); break; } - - // Object reference + /* Object reference */ case JERRY_API_DATA_TYPE_OBJECT: + { printf ("[JS object]"); break; + } } printf ("\n"); @@ -232,58 +305,65 @@ Shell operation can be described with the following loop: - loop. ```c -#include #include #include #include #include "jerry.h" -static void -print_value (const jerry_api_value_t * value_p); +static void print_value (const jerry_api_value_t *value_p); int -main (int argc, char * argv[]) { - // Initialize engine +main (int argc, char * argv[]) +{ + jerry_completion_code_t status = JERRY_COMPLETION_CODE_OK; + + /* Initialize engine */ jerry_init (JERRY_FLAG_EMPTY); char cmd [256]; - while (true) { + while (true) + { printf ("> "); - // Input next command + /* Input next command */ if (fgets (cmd, sizeof (cmd), stdin) == NULL - || strcmp (cmd, "quit\n") == 0) { - // If the command is 'quit', exit from loop + || strcmp (cmd, "quit\n") == 0) + { + /* If the command is 'quit', exit from loop */ break; } jerry_api_value_t ret_val; - // Evaluate entered command - jerry_completion_code_t status = jerry_api_eval (cmd, strlen (cmd), - false, false, - &ret_val); + /* Evaluate entered command */ + status = jerry_api_eval ((const jerry_api_char_t *) cmd, + strlen (cmd), + false, + false, + &ret_val); - // If command evaluated successfully, print value, returned by eval - if (status == JERRY_COMPLETION_CODE_OK) { - // 'eval' completed successfully + /* If command evaluated successfully, print value, returned by eval */ + if (status == JERRY_COMPLETION_CODE_OK) + { + /* 'eval' completed successfully */ print_value (&ret_val); jerry_api_release_value (&ret_val); - } else { - // evaluated JS code thrown an exception - // and didn't handle it with try-catch-finally + } + else + { + /* Evaluated JS code thrown an exception + and didn't handle it with try-catch-finally */ printf ("Unhandled JS exception occured\n"); } - printf ("\n"); fflush (stdout); } - // Cleanup engine + /* Cleanup engine */ jerry_cleanup (); - return 0; + return (int) status; } ```