Implement source info retrieval API function (#4780)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2021-09-29 12:34:38 +02:00
parent 8b3eb93167
commit 2a82da62ad
7 changed files with 524 additions and 6 deletions
@@ -1413,6 +1413,49 @@ typedef struct

 - [jerry_exec_snapshot](#jerry_exec_snapshot)

+## jerry_source_info_enabled_fields_t
+
+Enum which describes the enabled fields of [jerry_source_info_t](#jerry_source_info_t).
+Possible values:
+
+ - JERRY_SOURCE_INFO_HAS_SOURCE_CODE - source_code field is valid
+ - JERRY_SOURCE_INFO_HAS_FUNCTION_ARGUMENTS - function_arguments field is valid
+ - JERRY_SOURCE_INFO_HAS_SOURCE_RANGE - both source_range_start and source_range_length fields are valid
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_source_info_t](#jerry_source_info_t)
+- [jerry_get_source_info](#jerry_get_source_info)
+
+## jerry_source_info_t
+
+**Summary**
+
+Source related information of a script/module/function.
+
+**Prototype**
+
+```c
+typedef struct
+{
+  uint32_t enabled_fields; /**< combination of jerry_source_info_enabled_fields_t values */
+  jerry_value_t source_code; /**< script source code or function body */
+  jerry_value_t function_arguments; /**< function arguments */
+  uint32_t source_range_start; /**< start position of the function in the source code */
+  uint32_t source_range_length; /**< source length of the function in the source code */
+} jerry_source_info_t;
+```
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_source_info_enabled_fields_t](#jerry_source_info_enabled_fields_t)
+- [jerry_get_source_info](#jerry_get_source_info)
+
+
 # General engine functions

 ## jerry_init
@@ -11835,6 +11878,8 @@ jerry_get_user_value (const jerry_value_t value);

 **Example**

+[doctest]: # ()
+
 ```c
 #include "jerryscript.h"

@@ -11845,10 +11890,10 @@ main (void)

  const jerry_char_t script[] = "function abc() {} abc";

-  jerry_value user_value = jerry_create_object ();
+  jerry_value_t user_value = jerry_create_object ();

  jerry_parse_options_t parse_options;
-  parse_options.options = ECMA_PARSE_HAS_USER_VALUE;
+  parse_options.options = JERRY_PARSE_HAS_USER_VALUE;
  parse_options.user_value = user_value;

  jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, &parse_options);
@@ -11857,7 +11902,7 @@ main (void)
  /* The jerry_get_user_value returns the object which
   * was created by jerry_create_object before. */

-  jerry_value user_value = jerry_get_user_value (parsed_code);
+  user_value = jerry_get_user_value (parsed_code);
  jerry_release_value (parsed_code);

  jerry_release_value (user_value);
@@ -11872,6 +11917,98 @@ main (void)
 - [jerry_generate_snapshot](#jerry_generate_snapshot)
 - [jerry_exec_snapshot](#jerry_exec_snapshot)

+## jerry_get_source_info
+
+**Summary**
+
+Returns a newly created source info structure corresponding to the passed script/module/function.
+The function is lower level than `toString()` operation, but provides more contextual information.
+
+*Notes*:
+- Returned value must be freed with [jerry_free_source_info](#jerry_free_source_info) when it
+is no longer needed.
+- This API depends on a build option (`JERRY_FUNCTION_TO_STRING`) and can be checked
+  in runtime with the `JERRY_FEATURE_FUNCTION_TO_STRING` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+jerry_source_info_t *jerry_get_source_info (const jerry_value_t value);
+```
+- `value` - script / module / function value which executes JavaScript
+            code (native modules / functions do not have source info).
+- return
+  - source info - a newly created source info, if at least one field is available,
+  - NULL - otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  const jerry_char_t script[] = "function abc() {} abc";
+
+  jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL);
+
+  jerry_source_info_t *source_info_p = jerry_get_source_info (parsed_code);
+  jerry_release_value (parsed_code);
+
+  if (source_info_p != NULL)
+  {
+    /* Check the information provided by jerry_get_source_info. */
+  }
+
+  jerry_free_source_info (source_info_p);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_free_source_info](#jerry_free_source_info)
+- [jerry_source_info_t](#jerry_source_info_t)
+
+## jerry_free_source_info
+
+**Summary**
+
+Frees the the source info structure returned by [jerry_get_source_info](#jerry_get_source_info).
+
+*Notes*:
+- This API depends on a build option (`JERRY_FUNCTION_TO_STRING`) and can be checked
+  in runtime with the `JERRY_FEATURE_FUNCTION_TO_STRING` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+void jerry_free_source_info (jerry_source_info_t *source_info_p)
+```
+- `source_info_p` - source info structure returned by [jerry_get_source_info](#jerry_get_source_info)
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+See [jerry_get_source_info](#jerry_get_source_info)
+
+**See also**
+
+- [jerry_get_source_info](#jerry_get_source_info)
+- [jerry_source_info_t](#jerry_source_info_t)
+

 # Functions for realm objects