Support shared user data for scripts (#4710)

The same data is returned for the script and all of its functions,
including those which are created by an eval call.

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com

1 files changed, 113 insertions, 3 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 75023173..854c72df 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -243,6 +243,7 @@ Option bits for [jerry_parse_options_t](#jerry_parse_options_t).
  - JERRY_PARSE_MODULE - Parse source as an ECMAScript module
  - JERRY_PARSE_HAS_RESOURCE - `resource_name_p` and `resource_name_length` fields are valid
  - JERRY_PARSE_HAS_START - `start_line` and `start_column` fields are valid
+ - JERRY_PARSE_HAS_USER_VALUE - `user_value` field is valid
 
 *New in version [[NEXT_RELEASE]]*.
 
@@ -310,6 +311,10 @@ Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) functions:
  - JERRY_SNAPSHOT_EXEC_COPY_DATA - copy snapshot data into memory (see below)
  - JERRY_SNAPSHOT_EXEC_ALLOW_STATIC - allow executing static snapshots
  - JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION - load snapshot as function instead of executing it
+ - JERRY_SNAPSHOT_EXEC_HAS_RESOURCE - resource_name_p and resource_name_length fields are valid
+                                      in [jerry_exec_snapshot_option_values_t](#jerry_exec_snapshot_option_values_t)
+ - JERRY_SNAPSHOT_EXEC_HAS_USER_VALUE - user_value field is valid
+                                        in [jerry_exec_snapshot_option_values_t](#jerry_exec_snapshot_option_values_t)
 
 *Changed in version [[NEXT_RELEASE]]*: The `JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION` value is added,
                                        which replaces the `jerry_load_function_snapshot` function.
@@ -536,6 +541,8 @@ typedef struct
                                 *   if JERRY_PARSE_HAS_RESOURCE is set in options */
   uint32_t start_line; /**< start line of the source code if JERRY_PARSE_HAS_START is set in options */
   uint32_t start_column; /**< start column of the source code if JERRY_PARSE_HAS_START is set in options */
+  jerry_value_t user_value; /**< user value assigned to all functions created by this script including eval
+                             *   calls executed by the script if JERRY_PARSE_HAS_USER_VALUE is set in options */
 } jerry_parse_options_t;
 ```
 
@@ -547,6 +554,7 @@ typedef struct
 - [jerry_parse_function](#jerry_parse_function)
 - [jerry_generate_snapshot](#jerry_generate_snapshot)
 - [jerry_generate_function_snapshot](#jerry_generate_function_snapshot)
+- [jerry_exec_snapshot](#jerry_exec_snapshot)
 - [jerry_parse_option_enable_feature_t](#jerry_parse_option_enable_feature_t)
 
 ## jerry_property_descriptor_t
@@ -1231,6 +1239,33 @@ TypedArray support is not in the engine.
 - [jerry_get_typedarray_type](#jerry_get_typedarray_type)
 
 
+## jerry_exec_snapshot_option_values_t
+
+**Summary**
+
+Various configuration options for [jerry_exec_snapshot](#jerry_exec_snapshot)
+
+**Prototype**
+
+```c
+typedef struct
+{
+  const jerry_char_t *resource_name_p; /**< resource name (usually a file name)
+                                        *   if JERRY_SNAPSHOT_EXEC_HAS_RESOURCE is set in exec_snapshot_opts */
+  size_t resource_name_length; /**< length of resource name
+                                *   if JERRY_SNAPSHOT_EXEC_HAS_RESOURCE is set in exec_snapshot_opts */
+  jerry_value_t user_value; /**< user value assigned to all functions created by this script including
+                             *   eval calls executed by the script if JERRY_SNAPSHOT_EXEC_HAS_USER_VALUE
+                             *   is set in exec_snapshot_opts */
+} jerry_exec_snapshot_option_values_t;
+```
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_exec_snapshot](#jerry_exec_snapshot)
+
 # General engine functions
 
 ## jerry_init
@@ -10221,19 +10256,24 @@ jerry_value_t
 jerry_exec_snapshot (const uint32_t *snapshot_p,
                      size_t snapshot_size,
                      size_t func_index,
-                     uint32_t exec_snapshot_opts);
+                     uint32_t exec_snapshot_opts,
+                     const jerry_exec_snapshot_option_values_t *options_values_p);
 ```
 
 - `snapshot_p` - pointer to snapshot.
 - `snapshot_size` - size of snapshot in bytes.
 - `func_index` - index of executed function.
 - `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags.
+- `options_values_p` - additional loadig options, can be NULL if not used. The fields are described in
+                       [jerry_exec_snapshot_option_values_t](#jerry_exec_snapshot_option_values_t).
 - return value
   - result of bytecode, if run was successful.
   - thrown error, otherwise (an error is reported if the snapshot execution feature is not enabled).
 
 *Changed in version 2.0*: Added `func_index` and `exec_snapshot_opts` arguments. Removed the `copy_bytecode` last argument.
 
+*Changed in version [[NEXT_RELEASE]]*: Added `options_p` argument.
+
 **Example 1**
 
 [doctest]: # ()
@@ -10269,7 +10309,8 @@ main (void)
   jerry_value_t res = jerry_exec_snapshot (snapshot_buffer,
                                            snapshot_size,
                                            0,
-                                           0);
+                                           0,
+                                           NULL);
 
   /* 'res' now contains 'string from snapshot' */
   jerry_release_value (res);
@@ -10317,7 +10358,8 @@ main (void)
   jerry_value_t func = jerry_exec_snapshot (snapshot_buffer,
                                             snapshot_size,
                                             0,
-                                            JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION);
+                                            JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION,
+                                            NULL);
   /* 'func' can be used now as a function object. */
 
   jerry_value_t this_value = jerry_create_undefined ();
@@ -11141,6 +11183,74 @@ main (void)
 
 - [jerry_create_external_function](#jerry_create_external_function)
 
+## jerry_get_user_value
+
+**Summary**
+
+Returns the user value assigned to a script / module / function. This value is
+set by the parser when the JERRY_PARSE_HAS_USER_VALUE flag is set in the `options`
+member of the [jerry_parse_options_t](#jerry_parse_options_t) structure.
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_get_user_value (const jerry_value_t value);
+```
+- `value` - script / module / function value which executes JavaScript
+            code (native modules / functions do not have user value).
+- return
+  - user value - if available,
+  - undefined - otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  const jerry_char_t script[] = "function abc() {} abc";
+
+  jerry_value user_value = jerry_create_object ();
+
+  jerry_parse_options_t parse_options;
+  parse_options.options = ECMA_PARSE_HAS_USER_VALUE;
+  parse_options.user_value = user_value;
+
+  jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, &parse_options);
+  jerry_release_value (user_value);
+
+  /* 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);
+  jerry_release_value (parsed_code);
+
+  jerry_release_value (user_value);
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_parse](#jerry_parse)
+- [jerry_parse_function](#jerry_parse_function)
+- [jerry_generate_snapshot](#jerry_generate_snapshot)
+- [jerry_generate_function_snapshot](#jerry_generate_function_snapshot)
+- [jerry_exec_snapshot](#jerry_exec_snapshot)
+
+
 # Functions for realm objects
 
 These APIs all depend on build option (`JERRY_BUILTIN_REALMS`).