Add public API functions for internal property management (#3128)

These 4 new API functions give possibility to perform [[Get]], [[Set]], [[Has]], [[Delete]] operations for properties which are not accessible from the JavaScript context only from the public API. JerryScript-DCO-1.0-Signed-off-by: Robert Fancsik frobert@inf.u-szeged.hu
2019-10-17 13:56:49 +02:00
parent a40eb9bab8
commit fd1f7eab9f
5 changed files with 684 additions and 0 deletions
@@ -4683,6 +4683,63 @@ main (void)
 - [jerry_delete_property](#jerry_delete_property)


+## jerry_has_internal_property
+
+**Summary**
+
+Checks whether the object has the given internal property.
+
+*Note*:
+ - Properties which were not created with [jerry_set_internal_property](#jerry_set_internal_property) are excluded
+   during the operation.
+ - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+
+**Prototype**
+
+```c
+bool
+jerry_has_internal_property (const jerry_value_t obj_val,
+                             const jerry_value_t prop_name_val);
+```
+
+- `obj_val` - object value
+- `prop_name_val` - property name
+- return value
+  - true, if the property exists
+  - false, otherwise
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t global_object = jerry_get_global_object ();
+  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property");
+
+  bool has_internal_js_prop = jerry_has_internal_property (global_object, prop_name);
+
+  jerry_release_value (prop_name);
+  jerry_release_value (global_object);
+
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_delete_internal_property](#jerry_delete_internal_property)
+- [jerry_get_internal_property](#jerry_get_internal_property)
+- [jerry_set_internal_property](#jerry_set_internal_property)
+
+
 ## jerry_delete_property

 **Summary**
@@ -4772,6 +4829,50 @@ jerry_delete_property_by_index (const jerry_value_t obj_val,
 - [jerry_get_property_by_index](#jerry_get_property_by_index)
 - [jerry_set_property_by_index](#jerry_set_property_by_index)

+## jerry_delete_internal_property
+
+**Summary**
+
+Delete an internal property from an object.
+
+*Note*: Properties which were not created with [jerry_set_internal_property](#jerry_set_internal_property) are excluded
+        during the operation.
+
+**Prototype**
+
+```c
+bool
+jerry_delete_internal_property (const jerry_value_t obj_val,
+                                const jerry_value_t prop_name_val);
+```
+
+- `obj_val` - object value
+- `prop_name_val` - property name
+- return value
+  - true, if property was deleted successfully
+  - false, otherwise
+
+**Example**
+
+```c
+{
+  jerry_value_t global_object = jerry_get_global_object ();
+  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property");
+
+  bool delete_result = jerry_delete_internal_property (global_object, prop_name);
+  /* use "delete_result" */
+
+  jerry_release_value (prop_name);
+  jerry_release_value (global_object);
+}
+```
+
+**See also**
+
+- [jerry_has_internal_property](#jerry_has_internal_property)
+- [jerry_get_internal_property](#jerry_get_internal_property)
+- [jerry_set_internal_property](#jerry_set_internal_property)
+

 ## jerry_get_property

@@ -4884,6 +4985,66 @@ jerry_get_property_by_index (const jerry_value_t obj_val,
 - [jerry_set_property](#jerry_set_property)
 - [jerry_set_property_by_index](#jerry_set_property_by_index)

+## jerry_get_internal_property
+
+**Summary**
+
+Get value of an internal property to the specified object with the given name.
+
+*Note*:
+ - Properties which were not created with [jerry_set_internal_property](#jerry_set_internal_property) are excluded
+   during the operation.
+ - 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_internal_property (const jerry_value_t obj_val,
+                             const jerry_value_t prop_name_val);
+```
+
+- `obj_val` - object value
+- `prop_name_val` - property name
+- return value
+  - value of property, if the internal property exists
+  - undefined value, if the, if the internal does not property exists
+  - thrown error, otherwise
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t global_object = jerry_get_global_object ();
+  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property");
+
+  jerry_value_t prop_value = jerry_get_internal_property (global_object, prop_name);
+
+  /* use "prop_value" then release it. */
+
+  jerry_release_value (prop_value);
+  jerry_release_value (prop_name);
+  jerry_release_value (global_object);
+
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_has_internal_property](#jerry_has_internal_property)
+- [jerry_delete_internal_property](#jerry_delete_internal_property)
+- [jerry_set_internal_property](#jerry_set_internal_property)
+

 ## jerry_set_property

@@ -5001,6 +5162,68 @@ jerry_set_property_by_index (const jerry_value_t obj_val,
 - [jerry_get_property_by_index](#jerry_get_property_by_index)


+## jerry_set_internal_property
+
+**Summary**
+
+Set an internal property to the specified object with the given name.
+
+*Note*:
+ - The property cannot be accessed from the JavaScript context, only from the public API.
+ - It is different from [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) in that any jerry API value
+   can be hidden from the JavaScript context, not only native pointers.
+
+**Prototype**
+
+```c
+bool
+jerry_set_internal_property (const jerry_value_t obj_val,
+                             const jerry_value_t prop_name_val,
+                             const jerry_value_t value_to_set)
+```
+
+- `obj_val` - object value
+- `prop_name_val` - property name
+- `value_to_set` - value to set
+- return value
+  - true, if success
+  - thrown error, otherwise
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t global_object = jerry_get_global_object ();
+  jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "hidden_property");
+  jerry_value_t value_to_set = jerry_create_number (5);
+
+  bool set_result = jerry_set_internal_property (global_object, prop_name, value_to_set);
+
+  /* check the result of internal property set call */
+
+  jerry_release_value (value_to_set);
+  jerry_release_value (prop_name);
+  jerry_release_value (global_object);
+
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_has_internal_property](#jerry_has_internal_property)
+- [jerry_delete_internal_property](#jerry_delete_internal_property)
+- [jerry_get_internal_property](#jerry_get_internal_property)
+
+
 ## jerry_init_property_descriptor_fields

 **Summary**
@@ -5763,6 +5986,9 @@ You can get them by calling [jerry_get_object_native_pointer](#jerry_get_object_
   the free callback will be invoked during the execution of `jerry_cleanup`.
 - The free callback **must not** invoke API functions.

+*Note*: If possible do not store API values in native pointers, rather check
+        [jerry_set_internal_property](#jerry_set_internal_property).
+
 **Prototype**

 ```c