Add module C API functions (#4636)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2021-03-31 19:40:58 +02:00
parent 6677fa0a12
commit 4377ef684d
8 changed files with 715 additions and 62 deletions
@@ -747,6 +747,21 @@ typedef void (*jerry_error_object_created_callback_t) (const jerry_value_t error

 - [jerry_set_error_object_created_callback](#jerry_set_error_object_created_callback)

+## jerry_module_state_t
+
+An enum representing the current status of a module
+
+ - JERRY_MODULE_STATE_INVALID - Return value for jerry_module_get_state when its argument is not a module
+ - JERRY_MODULE_STATE_UNLINKED - Module is currently unlinked
+ - JERRY_MODULE_STATE_LINKING - Module is currently being linked
+ - JERRY_MODULE_STATE_LINKED - Module has been linked (its depencencies has been resolved)
+ - JERRY_MODULE_STATE_EVALUATING - Module is currently being evaluated
+ - JERRY_MODULE_STATE_EVALUATED - Module has been evaluated (its source code has been executed)
+ - JERRY_MODULE_STATE_ERROR - An error has been encountered before the evaluated state is reached
+ - JERRY_MODULE_STATE_NATIVE - Module is native module
+
+*New in version [[NEXT_RELEASE]]*.
+
 ## jerry_module_resolve_callback_t

 **Summary**
@@ -4365,6 +4380,341 @@ main (void)
 **See also**
 - [jerry_module_resolve_callback_t](#jerry_module_resolve_callback_t)

+## jerry_module_evaluate
+
+Evaluate a module and its dependencies. The module must be in linked state.
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value)
+  when it is no longer needed.
+- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked
+  in runtime with the `JERRY_FEATURE_MODULE` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+jerry_value_t jerry_module_evaluate (const jerry_value_t module_val);
+```
+
+- `module_val` - module object
+- return
+  - result of module bytecode execution - if evaluation was successful
+  - error, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+#include <stdio.h>
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  const jerry_char_t script[] = "export var a = 6";
+  const jerry_char_t file[] = "a.mjs";
+
+  jerry_parse_options_t parse_options;
+  parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE;
+  parse_options.resource_name_p = file;
+  parse_options.resource_name_length = sizeof (file) - 1;
+
+  jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+
+  jerry_release_value (jerry_module_link (module_value, NULL, NULL));
+  jerry_release_value (jerry_module_evaluate (module_value));
+
+  jerry_release_value (module_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_module_link](#jerry_module_link)
+
+## jerry_module_get_state
+
+**Summary**
+
+Returns the current status of a module. The available values
+are listed in [jerry_module_state_t](#jerry_module_state_t)
+
+*Notes*:
+- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked
+  in runtime with the `JERRY_FEATURE_MODULE` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+jerry_module_state_t jerry_module_get_state (const jerry_value_t module_val);
+```
+
+- `module_val` - module object
+- return
+  - current status - if module_val is a module
+  - JERRY_MODULE_STATE_INVALID - otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+#include <stdio.h>
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  const jerry_char_t script[] = "import a from 'b.mjs'";
+  const jerry_char_t file[] = "a.mjs";
+
+  jerry_parse_options_t parse_options;
+  parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE;
+  parse_options.resource_name_p = file;
+  parse_options.resource_name_length = sizeof (file) - 1;
+
+  jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+
+  if (jerry_module_get_state (module_value) == JERRY_MODULE_STATE_UNLINKED)
+  {
+    printf ("Module parsing has been successful\n");
+  }
+
+  jerry_release_value (module_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_module_state_t](#jerry_module_state_t)
+
+## jerry_module_get_number_of_requests
+
+**Summary**
+
+Returns the number of import/export requests of a module.
+The requests can be queried by [jerry_module_get_request](#jerry_module_get_request).
+
+
+*Notes*:
+- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked
+  in runtime with the `JERRY_FEATURE_MODULE` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+size_t jerry_module_get_number_of_requests (const jerry_value_t module_val);
+```
+
+- `module_val` - module object
+- return
+  - number of import/export requests of a module, if `module_val` is module,
+  - 0, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+#include <stdio.h>
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  const jerry_char_t script[] = "export * from 'b.mjs'"
+                                "import a from 'c.mjs'";
+  const jerry_char_t file[] = "a.mjs";
+
+  jerry_parse_options_t parse_options;
+  parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE;
+  parse_options.resource_name_p = file;
+  parse_options.resource_name_length = sizeof (file) - 1;
+
+  jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+
+  /* Prints 2. */
+  printf ("Number of requests: %d\n", (int) jerry_module_get_number_of_requests (module_value));
+
+  jerry_release_value (module_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_module_get_request](#jerry_module_get_request)
+- [jerry_parse](#jerry_parse)
+- [jerry_module_link](#jerry_module_link)
+
+## jerry_module_get_request
+
+**Summary**
+
+Returns the module request specified by the `request_index` argument. The requests
+are ordered in source code occurence. When parsing is completed, all returned values
+are strings. If [jerry_module_link](#jerry_module_link) is completed successfully
+all returned values are module objects instead. If linking is in progress or fails,
+the successfully resolved dependencies are module objects, the rest are strings.
+The number of requests can be queried by
+[jerry_module_get_number_of_requests](#jerry_module_get_number_of_requests).
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value)
+  when it is no longer needed.
+- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked
+  in runtime with the `JERRY_FEATURE_MODULE` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+jerry_value_t jerry_module_get_request (const jerry_value_t module_val, size_t request_index);
+```
+
+- `module_val` - module object
+- return
+  - string, if the request has not been resolved yet
+  - module object, if the request has been resolved successfully
+  - error, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  const jerry_char_t script[] = "export * from 'b.mjs'"
+                                "import a from 'c.mjs'";
+  const jerry_char_t file[] = "a.mjs";
+
+  jerry_parse_options_t parse_options;
+  parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE;
+  parse_options.resource_name_p = file;
+  parse_options.resource_name_length = sizeof (file) - 1;
+
+  jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+
+  jerry_value_t request_value = jerry_module_get_request (module_value, 0);
+  /* Returns with b.mjs */
+  jerry_release_value (request_value);
+
+  request_value = jerry_module_get_request (module_value, 1);
+  /* Returns with c.mjs */
+  jerry_release_value (request_value);
+
+  jerry_release_value (module_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_module_get_number_of_requests](#jerry_module_get_number_of_requests)
+- [jerry_parse](#jerry_parse)
+- [jerry_module_link](#jerry_module_link)
+
+## jerry_module_get_namespace
+
+Returns the namespace object of a module
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value)
+  when it is no longer needed.
+- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked
+  in runtime with the `JERRY_FEATURE_MODULE` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+jerry_value_t jerry_module_get_namespace (const jerry_value_t module_val);
+```
+
+- `module_val` - module object
+- return
+  - object, if namespace object is available
+  - error, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+#include <stdio.h>
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  const jerry_char_t script[] = "export var a = 6";
+  const jerry_char_t file[] = "a.mjs";
+
+  jerry_parse_options_t parse_options;
+  parse_options.options = JERRY_PARSE_MODULE | JERRY_PARSE_HAS_RESOURCE;
+  parse_options.resource_name_p = file;
+  parse_options.resource_name_length = sizeof (file) - 1;
+
+  jerry_value_t module_value = jerry_parse (script, sizeof (script) - 1, &parse_options);
+
+  jerry_release_value (jerry_module_link (module_value, NULL, NULL));
+  jerry_release_value (jerry_module_evaluate (module_value));
+
+  jerry_value_t namespace_value = jerry_module_get_namespace (module_value);
+
+  /* Exports can be checked. */
+
+  jerry_release_value (namespace_value);
+  jerry_release_value (module_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_module_link](#jerry_module_link)
+- [jerry_module_evaluate](#jerry_module_evaluate)
+
 # Functions for promise objects

 These APIs all depend on the es.next profile (or on some build options).