JerryScript Engine can be embedded into any application, providing the way to run JavaScript in a large range of environments - from desktops to low-memory microcontrollers.

This guide is intended to introduce you to JerryScript embedding API and to create a minimal JavaScript shell. The examples are not using all API methods please also check out the API reference document which contains additional examples.

Before trying out the examples: Get and build JerryScript library

Before getting started using the JerryScript library it should be cloned and built for a target os/device.

There are quite a few configuration options but for these examples the JerryScript is built with default configuration and installed to a user directory on a Linux system. This is done by the following commands:

  1. $ mkdir jerry
  2. $ cd jerry
  3. $ git clone https://github.com/jerryscript-project/jerryscript.git
  4. $ jerryscript/tools/build.py --builddir=$(pwd)/example_build --cmake-param="-DCMAKE_INSTALL_PREFIX=$(pwd)/example_install/"
  5. $ make -C $(pwd)/example_build install

With this the JerryScript library is installed into the $(pwd)/example_install/{include,lib} directories.

In this guide we will use pkg-config to ease the usage of headers and libraries. In order to do so, the following export is required (executed from the jerry directory):

  1. $ export PKG_CONFIG_PATH=$(pwd)/example_install/lib/pkgconfig/

Test if the pkg-config works for JerryScript:

  1. $ pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-ext libjerry-math

Example 1. Execute JavaScript from your application

The most basic example to test the engine is to create an api-example-1.c file containing the following code:

  1. #include "jerryscript.h"
  3. int
  4. main (void)
  5. {
  6.   const jerry_char_t script[] = "var str = 'Hello, World!';";
  8.   bool ret_value = jerry_run_simple (script, sizeof (script) - 1, JERRY_INIT_EMPTY);
  10.   return (ret_value ? 0 : 1);
  11. }

To compile it one can use the following command:

  1. $ gcc api-example-1.c -o api-example-1 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math)

If everything is correct the application returns with a zero exit code:

  1. $ ./api-example-1
  2. $ echo $?

Example 2. Split engine initialization and script execution.

In this example the engine is initialized directly with the jerry_init method and cleaned up with the jerry_cleanup method. The example JavaScript code is directly parsed and executed via the jerry_eval method. Each jerry_value_t returned by the API methods is freed with the jerry_release_value method.

To make sure that the code parsing and execution was ok, the jerry_value_is_error method is used to check for any errors.

Use the following code for the api-example-2.c file:

  1. #include "jerryscript.h"
  3. int
  4. main (void)
  5. {
  6.   const jerry_char_t script[] = "var str = 'Hello, World!';";
  7.   const jerry_length_t script_size = sizeof (script) - 1;
  8.   /* Note: sizeof can be used here only because the compiler knows the static character arrays's size.
  9.    * If this is not the case, strlen should be used instead.
  10.    */
  12.   /* Initialize engine */
  13.   jerry_init (JERRY_INIT_EMPTY);
  15.   /* Run the demo script with 'eval' */
  16.   jerry_value_t eval_ret = jerry_eval (script,
  17.                                        script_size,
  18.                                        JERRY_PARSE_NO_OPTS);
  20.   /* Check if there was any error (syntax or runtime) */
  21.   bool run_ok = !jerry_value_is_error (eval_ret);
  23.   /* Parsed source code must be freed */
  24.   jerry_release_value (eval_ret);
  26.   /* Cleanup engine */
  27.   jerry_cleanup ();
  29.   return (run_ok ? 0 : 1);
  30. }

To compile it one can use the following command:

  1. $ gcc api-example-2.c -o api-example-2 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math)

If everything is correct the application returns with a zero exit code:

  1. $ ./api-example-2
  2. $ echo $?

Example 3. Split JavaScript parsing and script execution

In this example the jerry_eval is replaced with a more common API calls:

  • script code setup - jerry_parse.
  • script execution - jerry_run.

The api-example-3.c file should contain the following code:

  1. #include "jerryscript.h"
  3. int
  4. main (void)
  5. {
  6.   bool run_ok = false;
  8.   const jerry_char_t script[] = "var str = 'Hello, World!';";
  10.   /* Initialize engine */
  11.   jerry_init (JERRY_INIT_EMPTY);
  13.   /* Setup Global scope code */
  14.   jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
  16.   /* Check if there is any JS code parse error */
  17.   if (!jerry_value_is_error (parsed_code))
  18.   {
  19.     /* Execute the parsed source code in the Global scope */
  20.     jerry_value_t ret_value = jerry_run (parsed_code);
  22.     /* Check the execution return value if there is any error */
  23.     run_ok = !jerry_value_is_error (ret_value);
  25.     /* Returned value must be freed */
  26.     jerry_release_value (ret_value);
  27.   }
  29.   /* Parsed source code must be freed */
  30.   jerry_release_value (parsed_code);
  32.   /* Cleanup engine */
  33.   jerry_cleanup ();
  35.   return (run_ok ? 0 : 1);
  36. }

To compile it one can use the following command:

  1. $ gcc api-example-3.c -o api-example-3 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math)

If everything is correct the application returns with a zero exit code:

  1. $ ./api-example-3
  2. $ echo $?

Example 4. Adding a C method for JavaScript

The previous examples were not that eye catching as there were no visual output by the JavaScript code and C program.

In this example a very simple “print” method is added which prints out a static string. This method will be implemented in C and will be called from the JavaScript code. For this a few extra API methods are required:

  • jerry_get_global_object
  • jerry_create_string
  • jerry_set_property
  • jerry_create_external_function

The api-example-4.c file should contain the following code:

  1. #include <stdio.h>
  2. #include "jerryscript.h"
  4. static jerry_value_t
  5. print_handler (const jerry_value_t function_object,
  6.                const jerry_value_t function_this,
  7.                const jerry_value_t arguments[],
  8.                const jerry_length_t argument_count)
  9. {
  10.   /* No arguments are used in this example */
  11.   /* Print out a static string */
  12.   printf ("Print handler was called\n");
  14.   /* Return an "undefined" value to the JavaScript engine */
  15.   return jerry_create_undefined ();
  16. }
  18. int
  19. main (void)
  20. {
  21.   const jerry_char_t script[] = "print ();";
  22.   const jerry_length_t script_size = sizeof (script) - 1;
  24.   /* Initialize engine */
  25.   jerry_init (JERRY_INIT_EMPTY);
  27.   /* Add the "print" method for the JavaScript global object */
  28.   {
  29.     /* Get the "global" object */
  30.     jerry_value_t global_object = jerry_get_global_object ();
  31.     /* Create a "print" JS string */
  32.     jerry_value_t property_name_print = jerry_create_string ((const jerry_char_t *) "print");
  33.     /* Create a function from a native C method (this function will be called from JS) */
  34.     jerry_value_t property_value_func = jerry_create_external_function (print_handler);
  35.     /* Add the "print" property with the function value to the "global" object */
  36.     jerry_value_t set_result = jerry_set_property (global_object, property_name_print, property_value_func);
  38.     /* Check if there was no error when adding the property (in this case it should never happen) */
  39.     if (jerry_value_is_error (set_result)) {
  40.       printf ("Failed to add the 'print' property\n");
  41.     }
  43.     /* Release all jerry_value_t-s */
  44.     jerry_release_value (set_result);
  45.     jerry_release_value (property_value_func);
  46.     jerry_release_value (property_name_print);
  47.     jerry_release_value (global_object);
  48.   }
  50.   /* Setup Global scope code */
  51.   jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
  53.   if (!jerry_value_is_error (parsed_code))
  54.   {
  55.     /* Execute the parsed source code in the Global scope */
  56.     jerry_value_t ret_value = jerry_run (parsed_code);
  58.     /* Returned value must be freed */
  59.     jerry_release_value (ret_value);
  60.   }
  62.   /* Parsed source code must be freed */
  63.   jerry_release_value (parsed_code);
  65.   /* Cleanup engine */
  66.   jerry_cleanup ();
  68.   return 0;
  69. }

To compile it one can use the following command:

  1. $ gcc api-example-4.c -o api-example-4 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math)

If everything is correct the application should print out the message present in the print_handler method:

  1. $ ./api-example-4

Example 5. Passing and processing arguments for native C code

In the previous example the print_handler simply wrote a static string to the standard output. However in most cases this is not useful, ideally the method’s argument(s) should be printed.

In this example the print_handler is extended to convert the first argument (which probably comes from a JavaScript source) to a JS string and prints it out to the standard output.

New API methods used:

  • jerry_value_to_string
  • jerry_string_to_utf8_char_buffer

The api-example-5.c file should contain the following code:

  1. #include <stdio.h>
  2. #include "jerryscript.h"
  4. static jerry_value_t
  5. print_handler (const jerry_value_t function_object,
  6.                const jerry_value_t function_this,
  7.                const jerry_value_t arguments[],
  8.                const jerry_length_t arguments_count)
  9. {
  10.   /* There should be at least one argument */
  11.   if (arguments_count > 0)
  12.   {
  13.     /* Convert the first argument to a string (JS "toString" operation) */
  14.     jerry_value_t string_value = jerry_value_to_string (arguments[0]);
  16.     /* A naive allocation of buffer for the string */
  17.     jerry_char_t buffer[256];
  19.     /* Copy the whole string to the buffer, without a null termination character,
  20.      * Please note that if the string does not fit into the buffer nothing will be copied.
  21.      * More details on the API reference page
  22.      */
  23.     jerry_size_t copied_bytes = jerry_string_to_utf8_char_buffer (string_value, buffer, sizeof (buffer) - 1);
  24.     buffer[copied_bytes] = '\0';
  26.     /* Release the "toString" result */
  27.     jerry_release_value (string_value);
  29.     printf ("%s\n", (const char *)buffer);
  30.   }
  32.   /* Return an "undefined" value to the JavaScript engine */
  33.   return jerry_create_undefined ();
  34. }
  36. int
  37. main (void)
  38. {
  39.   const jerry_char_t script[] = "print ('Hello from JS!');";
  40.   const jerry_length_t script_size = sizeof (script) - 1;
  42.   /* Initialize engine */
  43.   jerry_init (JERRY_INIT_EMPTY);
  45.   /* Add the "print" method for the JavaScript global object */
  46.   {
  47.     /* Get the "global" object */
  48.     jerry_value_t global_object = jerry_get_global_object ();
  49.     /* Create a "print" JS string */
  50.     jerry_value_t property_name_print = jerry_create_string ((const jerry_char_t *) "print");
  51.     /* Create a function from a native C method (this function will be called from JS) */
  52.     jerry_value_t property_value_func = jerry_create_external_function (print_handler);
  53.     /* Add the "print" property with the function value to the "global" object */
  54.     jerry_value_t set_result = jerry_set_property (global_object, property_name_print, property_value_func);
  56.     /* Check if there was no error when adding the property (in this case it should never happen) */
  57.     if (jerry_value_is_error (set_result)) {
  58.       printf ("Failed to add the 'print' property\n");
  59.     }
  61.     /* Release all jerry_value_t-s */
  62.     jerry_release_value (set_result);
  63.     jerry_release_value (property_value_func);
  64.     jerry_release_value (property_name_print);
  65.     jerry_release_value (global_object);
  66.   }
  68.   /* Setup Global scope code */
  69.   jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
  71.   if (!jerry_value_is_error (parsed_code))
  72.   {
  73.     /* Execute the parsed source code in the Global scope */
  74.     jerry_value_t ret_value = jerry_run (parsed_code);
  76.     /* Returned value must be freed */
  77.     jerry_release_value (ret_value);
  78.   }
  80.   /* Parsed source code must be freed */
  81.   jerry_release_value (parsed_code);
  83.   /* Cleanup engine */
  84.   jerry_cleanup ();
  86.   return 0;
  87. }

To compile it one can use the following command:

  1. $ gcc api-example-5.c -o api-example-5 $(pkg-config --cflags --libs libjerry-core libjerry-port-default libjerry-math)

If everything is correct the application should print out the string passed for the print method in the JS code:

  1. $ ./api-example-5

Example 6. Using JerryScript Extensions

Some of the previous examples used a “print” method to write data out to the standard output. For convenience JerryScript provides an extension to add a simple “print” handler which can be used by other applications.

In this example the following extension methods are used:

  • jerryx_handler_register_global
  • jerryx_handler_print

In further examples this “print” handler will be used.

  1. #include "jerryscript.h"
  2. #include "jerryscript-ext/handler.h"
  4. int
  5. main (void)
  6. {
  7.   const jerry_char_t script[] = "print ('Hello from JS with ext!');";
  8.   const jerry_length_t script_size = sizeof (script) - 1;
  10.   /* Initialize engine */
  11.   jerry_init (JERRY_INIT_EMPTY);
  13.   /* Register 'print' function from the extensions to the global object */
  14.   jerryx_handler_register_global ((const jerry_char_t *) "print",
  15.                                   jerryx_handler_print);
  17.   /* Setup Global scope code */
  18.   jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
  20.   if (!jerry_value_is_error (parsed_code))
  21.   {
  22.     /* Execute the parsed source code in the Global scope */
  23.     jerry_value_t ret_value = jerry_run (parsed_code);
  25.     /* Returned value must be freed */
  26.     jerry_release_value (ret_value);
  27.   }
  29.   /* Parsed source code must be freed */
  30.   jerry_release_value (parsed_code);
  32.   /* Cleanup engine */
  33.   jerry_cleanup ();
  35.   return 0;
  36. }

To compile it one can use the following command:

(Note that the libjerry-ext was added before the libjerry-port-default entry for the pkg-config call.

  1. $ gcc api-example-6.c -o api-example-6 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math)

If everything is correct the application should print out the string passed for the print method in the JS code:

  1. $ ./api-example-6

Example 7. Interaction with JavaScript environment - adding a string property

Previously a C method was registered for the global object, now this examples show how one can add a string property.

Use the following code as the api-example-7.c file:

  1. #include "jerryscript.h"
  2. #include "jerryscript-ext/handler.h"
  4. int
  5. main (void)
  6. {
  7.   const jerry_char_t script[] = "print (my_var);";
  9.   /* Initializing JavaScript environment */
  10.   jerry_init (JERRY_INIT_EMPTY);
  12.   /* Register 'print' function from the extensions */
  13.   jerryx_handler_register_global ((const jerry_char_t *) "print",
  14.                                   jerryx_handler_print);
  16.   /* Getting pointer to the Global object */
  17.   jerry_value_t global_object = jerry_get_global_object ();
  19.   /* Constructing strings */
  20.   jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_var");
  21.   jerry_value_t prop_value = jerry_create_string ((const jerry_char_t *) "Hello from C!");
  23.   /* Setting the string value as a property of the Global object */
  24.   jerry_value_t set_result = jerry_set_property (global_object, prop_name, prop_value);
  25.   /* The 'set_result' should be checked if there was any error */
  26.   if (jerry_value_is_error (set_result)) {
  27.     printf ("Failed to add the 'my_var' property\n");
  28.   }
  29.   jerry_release_value (set_result);
  31.   /* Releasing string values, as it is no longer necessary outside of engine */
  32.   jerry_release_value (prop_name);
  33.   jerry_release_value (prop_value);
  35.   /* Releasing the Global object */
  36.   jerry_release_value (global_object);
  38.   /* Now starting script that would output value of just initialized field */
  39.   jerry_value_t eval_ret = jerry_eval (script,
  40.                                        sizeof (script) - 1,
  41.                                        JERRY_PARSE_NO_OPTS);
  43.   /* Free JavaScript value, returned by eval */
  44.   jerry_release_value (eval_ret);
  46.   /* Freeing engine */
  47.   jerry_cleanup ();
  49.   return 0;
  50. }

To compile it one can use the following command:

(Note that the libjerry-ext was added before the libjerry-port-default entry for the pkg-config call.

  1. $ gcc api-example-7.c -o api-example-7 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math)

The sample will output ‘Hello from C!’. However, now it is not just a part of the source script, but the value, dynamically supplied to the engine:

  1. $ ./api-example-7

Example 8. Description of JerryScript value descriptors

JerryScript value can be a boolean, number, null, object, string, undefined or some special type of objects (arraybuffer, symbols, etc).

There is a special “error” value which wraps another value. This “error” can be created by throwing a JavaScript value from JS code or via API method(s). It is advised to check for this error with the jerry_value_is_error method as not all API methods can process error values. To extract the value from the “error” the API method jerry_get_value_from_error should be used. If an error object is created via API method (for example with jerry_create_error) the “error” value is automatically created.

Notice the difference between error value and error object:

  • The error object is a object which was constructed via one of the Error objects (available from the global object or from API). For example in JS such object be created with the following code example:
  1. var error_object = new Error ("error message");
  • The error value is not an object on its own. This is the exception raised/thrown either via API methods or from JS. For example, creating such error value in JS would look like this:
  1. throw "message";

To check what type a given jerry_value_t is the jerry_value_is_* methods or the jerry_value_get_type could be used. For example the following code snippet could print out a few types (not all types are checked):

  1. #include <stdio.h>
  2. #include <stdlib.h>
  3. #include "jerryscript.h"
  5. static void
  6. print_value (const jerry_value_t jsvalue)
  7. {
  8.   jerry_value_t value;
  9.   /* If there is an error extract the object from it */
  10.   if (jerry_value_is_error (jsvalue))
  11.   {
  12.     printf ("Error value detected: ");
  13.     value = jerry_get_value_from_error (jsvalue, false);
  14.   }
  15.   else
  16.   {
  17.     value = jerry_acquire_value (jsvalue);
  18.   }
  20.   if (jerry_value_is_undefined (value))
  21.   {
  22.     printf ("undefined");
  23.   }
  24.   else if (jerry_value_is_null (value))
  25.   {
  26.     printf ("null");
  27.   }
  28.   else if (jerry_value_is_boolean (value))
  29.   {
  30.     if (jerry_get_boolean_value (value))
  31.     {
  32.       printf ("true");
  33.     }
  34.     else
  35.     {
  36.       printf ("false");
  37.     }
  38.   }
  39.   /* Float value */
  40.   else if (jerry_value_is_number (value))
  41.   {
  42.     printf ("number: %lf", jerry_get_number_value (value));
  43.   }
  44.   /* String value */
  45.   else if (jerry_value_is_string (value))
  46.   {
  47.     jerry_char_t str_buf_p[256];
  49.     /* Determining required buffer size */
  50.     jerry_size_t req_sz = jerry_get_string_size (value);
  52.     if (req_sz <= 255)
  53.     {
  54.       jerry_string_to_char_buffer (value, str_buf_p, req_sz);
  55.       str_buf_p[req_sz] = '\0';
  56.       printf ("%s", (const char *) str_buf_p);
  57.     }
  58.     else
  59.     {
  60.       printf ("error: buffer isn't big enough");
  61.     }
  62.   }
  63.   /* Object reference */
  64.   else if (jerry_value_is_object (value))
  65.   {
  66.     printf ("[JS object]");
  67.   }
  69.   printf ("\n");
  70.   jerry_release_value (value);
  71. }

Example 8: Simple JavaScript shell

Now all building blocks, necessary to construct JavaScript shell, are ready.

Shell operation can be described with the following loop:

  • read command;
  • if command is ‘quit’
    • exit loop;
  • else
    • eval (command);
    • print result of eval;
    • loop.

See the following api-example-8-shell.c file:

  1. #include <stdio.h>
  2. #include <stdlib.h>
  3. #include <string.h>
  4. #include "jerryscript.h"
  5. #include "jerryscript-ext/handler.h"
  7. static void
  8. print_value (const jerry_value_t jsvalue)
  9. {
  10.   jerry_value_t value;
  11.   /* If there is an error extract the object from it */
  12.   if (jerry_value_is_error (jsvalue))
  13.   {
  14.     printf ("Error value detected: ");
  15.     value = jerry_get_value_from_error (jsvalue, false);
  16.   }
  17.   else
  18.   {
  19.     value = jerry_acquire_value (jsvalue);
  20.   }
  22.   if (jerry_value_is_undefined (value))
  23.   {
  24.     printf ("undefined");
  25.   }
  26.   else if (jerry_value_is_null (value))
  27.   {
  28.     printf ("null");
  29.   }
  30.   else if (jerry_value_is_boolean (value))
  31.   {
  32.     if (jerry_get_boolean_value (value))
  33.     {
  34.       printf ("true");
  35.     }
  36.     else
  37.     {
  38.       printf ("false");
  39.     }
  40.   }
  41.   /* Float value */
  42.   else if (jerry_value_is_number (value))
  43.   {
  44.     printf ("number: %lf", jerry_get_number_value (value));
  45.   }
  46.   /* String value */
  47.   else if (jerry_value_is_string (value))
  48.   {
  49.     jerry_char_t str_buf_p[256];
  51.     /* Determining required buffer size */
  52.     jerry_size_t req_sz = jerry_get_string_size (value);
  54.     if (req_sz <= 255)
  55.     {
  56.       jerry_string_to_char_buffer (value, str_buf_p, req_sz);
  57.       str_buf_p[req_sz] = '\0';
  58.       printf ("%s", (const char *) str_buf_p);
  59.     }
  60.     else
  61.     {
  62.       printf ("error: buffer isn't big enough");
  63.     }
  64.   }
  65.   /* Object reference */
  66.   else if (jerry_value_is_object (value))
  67.   {
  68.     printf ("[JS object]");
  69.   }
  71.   printf ("\n");
  72.   jerry_release_value (value);
  73. }
  75. int
  76. main (void)
  77. {
  78.   bool is_done = false;
  80.   /* Initialize engine */
  81.   jerry_init (JERRY_INIT_EMPTY);
  83.   /* Register 'print' function from the extensions */
  84.   jerryx_handler_register_global ((const jerry_char_t *) "print",
  85.                                   jerryx_handler_print);
  87.   while (!is_done)
  88.   {
  89.     char cmd[256];
  90.     char *cmd_tail = cmd;
  91.     size_t len = 0;
  93.     printf ("> ");
  95.     /* Read next command */
  96.     while (true)
  97.     {
  98.       if (fread (cmd_tail, 1, 1, stdin) != 1 && len == 0)
  99.       {
  100.         is_done = true;
  101.         break;
  102.       }
  103.       if (*cmd_tail == '\n')
  104.       {
  105.         break;
  106.       }
  108.       cmd_tail++;
  109.       len++;
  110.     }
  112.     /* If the command is "quit", break the loop */
  113.     if (!strncmp (cmd, "quit\n", sizeof ("quit\n") - 1))
  114.     {
  115.       break;
  116.     }
  118.     jerry_value_t ret_val;
  120.     /* Evaluate entered command */
  121.     ret_val = jerry_eval ((const jerry_char_t *) cmd,
  122.                           len,
  123.                           JERRY_PARSE_NO_OPTS);
  125.     /* Print out the value */
  126.     print_value (ret_val);
  128.     jerry_release_value (ret_val);
  129.   }
  131.   /* Cleanup engine */
  132.   jerry_cleanup ();
  134.   return 0;
  135. }

To compile it one can use the following command:

(Note that the libjerry-ext was added before the libjerry-port-default entry for the pkg-config call.

  1. $ gcc api-example-8-shell.c -o api-example-8-shell $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math)

The application reads lines from standard input and evaluates them, one after another. To try out run:

  1. $ ./api-example-8-shell

Example 9. Creating JS object in global context

In this example (api-example-9.c) an object with a native function is added to the global object.

  1. #include "jerryscript.h"
  2. #include "jerryscript-ext/handler.h"
  4. struct my_struct
  5. {
  6.   const char *msg;
  7. } my_struct;
  9. /**
  10.  * Get a string from a native object
  11.  */
  12. static jerry_value_t
  13. get_msg_handler (const jerry_value_t func_value, /**< function object */
  14.                  const jerry_value_t this_value, /**< this arg */
  15.                  const jerry_value_t *args_p, /**< function arguments */
  16.                  const jerry_length_t args_cnt) /**< number of function arguments */
  17. {
  18.   return jerry_create_string ((const jerry_char_t *) my_struct.msg);
  19. } /* get_msg_handler */
  21. int
  22. main (void)
  23. {
  24.   /* Initialize engine */
  25.   jerry_init (JERRY_INIT_EMPTY);
  27.   /* Register 'print' function from the extensions */
  28.   jerryx_handler_register_global ((const jerry_char_t *) "print",
  29.                                   jerryx_handler_print);
  31.   /* Do something with the native object */
  32.   my_struct.msg = "Hello, World!";
  34.   /* Create an empty JS object */
  35.   jerry_value_t object = jerry_create_object ();
  37.   /* Create a JS function object and wrap into a jerry value */
  38.   jerry_value_t func_obj = jerry_create_external_function (get_msg_handler);
  40.   /* Set the native function as a property of the empty JS object */
  41.   jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "myFunc");
  42.   jerry_release_value (jerry_set_property (object, prop_name, func_obj));
  43.   jerry_release_value (prop_name);
  44.   jerry_release_value (func_obj);
  46.   /* Wrap the JS object (not empty anymore) into a jerry api value */
  47.   jerry_value_t global_object = jerry_get_global_object ();
  49.   /* Add the JS object to the global context */
  50.   prop_name = jerry_create_string ((const jerry_char_t *) "MyObject");
  51.   jerry_release_value (jerry_set_property (global_object, prop_name, object));
  52.   jerry_release_value (prop_name);
  53.   jerry_release_value (object);
  54.   jerry_release_value (global_object);
  56.   /* Now we have a "builtin" object called MyObject with a function called myFunc()
  57.    *
  58.    * Equivalent JS code:
  59.    *                    var MyObject = { myFunc : function () { return "some string value"; } }
  60.    */
  61.   const jerry_char_t script[] = " \
  62.     var str = MyObject.myFunc (); \
  63.     print (str); \
  64.   ";
  66.   /* Evaluate script */
  67.   jerry_value_t eval_ret = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
  69.   /* Free JavaScript value, returned by eval */
  70.   jerry_release_value (eval_ret);
  72.   /* Cleanup engine */
  73.   jerry_cleanup ();
  75.   return 0;
  76. }

To compile it one can use the following command:

(Note that the libjerry-ext was added before the libjerry-port-default entry for the pkg-config call.

  1. $ gcc api-example-9.c -o api-example-9 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math)

Execute the example with:

  1. $ ./api-example-9

The application will generate the following output:

  1. Hello, World

Example 10. Extending JS Objects with native functions

The example creates a JS Object with jerry_eval, then it is extended from C with a native function. In addition this native function shows how to get a property value from the object and how to manipulate it.

Use the following code for api-example-10.c:

  1. #include "jerryscript.h"
  2. #include "jerryscript-ext/handler.h"
  4. /**
  5.  * Add param to 'this.x'
  6.  */
  7. static jerry_value_t
  8. add_handler (const jerry_value_t func_value, /**< function object */
  9.              const jerry_value_t this_val, /**< this arg */
  10.              const jerry_value_t args_p[], /**< function arguments */
  11.              const jerry_length_t args_cnt) /**< number of function arguments */
  12. {
  13.   /* The the 'this_val' is the 'MyObject' from the JS code below */
  14.   /* Note: that the argument count check is ignored for the example's case */
  16.   /* Get 'this.x' */
  17.   jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "x");
  18.   jerry_value_t x_val = jerry_get_property (this_val, prop_name);
  20.   if (!jerry_value_is_error (x_val))
  21.   {
  22.     /* Convert Jerry API values to double */
  23.     double x = jerry_get_number_value (x_val);
  24.     double d = jerry_get_number_value (args_p[0]);
  26.     /* Add the parameter to 'x' */
  27.     jerry_value_t res_val = jerry_create_number (x + d);
  29.     /* Set the new value of 'this.x' */
  30.     jerry_release_value (jerry_set_property (this_val, prop_name, res_val));
  31.     jerry_release_value (res_val);
  32.   }
  34.   jerry_release_value (x_val);
  35.   jerry_release_value (prop_name);
  37.   return jerry_create_undefined ();
  38. } /* add_handler */
  40. int
  41. main (void)
  42. {
  43.   /* Initialize engine */
  44.   jerry_init (JERRY_INIT_EMPTY);
  46.   /* Register 'print' function from the extensions */
  47.   jerryx_handler_register_global ((const jerry_char_t *) "print",
  48.                                   jerryx_handler_print);
  50.   /* Create a JS object */
  51.   const jerry_char_t my_js_object[] = " \
  52.     MyObject = \
  53.     { x : 12, \
  54.       y : 'Value of x is ', \
  55.       foo: function () \
  56.       { \
  57.         return this.y + this.x; \
  58.       } \
  59.     } \
  60.   ";
  62.   jerry_value_t my_js_obj_val;
  64.   /* Evaluate script */
  65.   my_js_obj_val = jerry_eval (my_js_object,
  66.                               sizeof (my_js_object) - 1,
  67.                               JERRY_PARSE_NO_OPTS);
  69.   /* Create a JS function object and wrap into a jerry value */
  70.   jerry_value_t add_func_obj = jerry_create_external_function (add_handler);
  72.   /* Set the native function as a property of previously created MyObject */
  73.   jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "add2x");
  74.   jerry_release_value (jerry_set_property (my_js_obj_val, prop_name, add_func_obj));
  75.   jerry_release_value (add_func_obj);
  76.   jerry_release_value (prop_name);
  78.   /* Free JavaScript value, returned by eval (my_js_object) */
  79.   jerry_release_value (my_js_obj_val);
  81.   const jerry_char_t script[] = " \
  82.     var str = MyObject.foo (); \
  83.     print (str); \
  84.     MyObject.add2x (5); \
  85.     print (MyObject.foo ()); \
  86.   ";
  88.   /* Evaluate script */
  89.   jerry_value_t eval_ret = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
  91.   /* Free JavaScript value, returned by eval */
  92.   jerry_release_value (eval_ret);
  94.   /* Cleanup engine */
  95.   jerry_cleanup ();
  97.   return 0;
  98. }

To compile it one can use the following command:

(Note that the libjerry-ext was added before the libjerry-port-default entry for the pkg-config call.

  1. $ gcc api-example-10.c -o api-example-10 $(pkg-config --cflags --libs libjerry-core libjerry-ext libjerry-port-default libjerry-math)

Execute the example with:

  1. $ ./api-example-10
  1. Value of x is 12
  2. Value of x is 17

Example 11. Changing the seed of pseudorandom generated numbers

If you want to change the seed of Math.random() generated numbers, you have to initialize the seed value with srand. A recommended method is using jerry_port_get_current_time() or something based on a constantly changing value, therefore every run produces truly random numbers.

  1. #include <stdlib.h>
  2. #include "jerryscript.h"
  3. #include "jerryscript-port.h"
  4. #include "jerryscript-ext/handler.h"
  6. int
  7. main (void)
  8. {
  9.   /* Initialize srand value */
  10.   union { double d; unsigned u; } now = { .d = jerry_port_get_current_time () };
  11.   srand (now.u);
  13.   /* Generate a random number, and print it */
  14.   const jerry_char_t script[] = "var a = Math.random (); print(a)";
  16.   /* Initialize the engine */
  17.   jerry_init (JERRY_INIT_EMPTY);
  19.   /* Register the print function */
  20.   jerryx_handler_register_global ((const jerry_char_t *) "print",
  21.                                   jerryx_handler_print);
  23.   /* Evaluate the script */
  24.   jerry_value_t eval_ret = jerry_eval (script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
  26.   /* Free the JavaScript value returned by eval */
  27.   jerry_release_value (eval_ret);
  29.   /* Cleanup the engine */
  30.   jerry_cleanup ();
  32.   return 0;
  33. }

Further steps

For further API description, please visit API Reference page on JerryScript home page.