Introduce new jerry-ext methods to ease property registration

New methods
* jerryx_set_properties: Allows multiple property registration for via a single call
* jerryx_set_property_str: Allows property registration without the need to
    create the property name JS value. The property name can be directly passed
    as a `const char*` value and must be zero terminated.
* jerryx_get_property_str: Allows getting a property value on a given object.
    The property name can be directly passed as a `const char*` value.

JerryScript-DCO-1.0-Signed-off-by: Peter Gal [email protected]

Author: galpeter

docs/10.EXT-REFERENCE-HANDLER.md

@@ -1,3 +1,349 @@
+# Common methods to handle properties
+
+## jerryx_property_entry
+
+**Summary**
+
+Structure to define an array of properties with `name` and `value` fields which
+can be registered to a target object.
+
+The engine must be initialied before specifying the `jerry_value_t` in the struct.
+
+
+**Prototype**
+
+```c
+typedef struct {
+  const char *name;
+  jerry_value_t value;
+} jerryx_function_list_entry;
+```
+
+**See also**
+
+- [jerryx_set_properties](#jerryx_set_properties)
+
+
+## jerryx_register_result
+
+**Summary**
+
+Structure returned as the result of the [jerryx_set_properties](#jerryx_set_properties) operation.
+The `result` field will either be a JavaScript undefined value or an error object.
+In every case the `registered` field is used to indicated the number of
+successfully registered methods.
+
+This must be passed for the [jerryx_free_property_entry](#jerryx_free_property_entry) method
+after the property registration.
+
+**Prototype**
+
+```c
+typedef struct {
+  jerry_value_t result;
+  uint32_t registered;
+} jerryx_register_result;
+```
+
+**See also**
+
+- [jerryx_set_properties](#jerryx_set_properties)
+- [jerryx_free_property_entry](#jerryx_free_property_entry)
+
+
+## jerryx_set_properties
+
+**Summary**
+
+Set multiple properties on a target object.
+
+The properties are an array of (name, jerry_value_t) pairs and
+this list must end with a (NULL, 0) entry.
+
+Important notes:
+* Each property value in the input array is released after a successful property registration.
+* The method [jerryx_free_property_entry](#jerryx_free_property_entry) must be called if there is any failed registration
+  to release the values in the entries array.
+  It is safe to call this cleanup method in every case not just in case of failure.
+* If the error value is reported via the result it must be freed manually.
+
+**Prototype**
+
+```c
+jerryx_register_result
+jerryx_set_properties (const jerry_value_t target_object,
+                       const jerryx_property_entry entries[]);
+```
+
+- `target_object` - object on which the entries will be set.
+- `entries` - array of (name, jerry_value_t) pairs.
+- return a [jerryx_register_result](#jerryx_register_result).
+   - if everything is ok, the struct's `result` field is set to a JS undefined value.
+   - otherwise the `result` field is an error object indicating the problem.
+   - in every case the `registered` field contains the number of successfully registered properties.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+#include "jerryscript-ext/handler.h"
+
+static jerry_value_t
+handler (const jerry_value_t function_obj,
+         const jerry_value_t this_val,
+         const jerry_value_t args_p[],
+         const jerry_length_t args_cnt)
+{
+  printf ("native handler called!\n");
+
+  return jerry_create_boolean (true);
+}
+
+int
+main (int argc, char **argv)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerryx_property_entry methods[] =
+  {
+    { "demo", jerry_create_external_function (handler) },
+    { NULL, 0 },
+  };
+
+  jerry_value_t global = jerry_get_global_object ();
+  jerryx_register_result reg = jerryx_set_properties (global, methods);
+  /* if `reg.result` is undefined all methods are registered */
+  if (jerry_value_is_error (reg.result))
+  {
+    printf ("Only registered %d properties\r\n", reg.registered);
+    /* clean up not registered property values */
+    jerryx_free_property_entry (methods, reg);
+
+    /* clean up the error */
+    jerry_release_value (reg.result);
+  }
+
+  jerry_release_value (global);
+
+  jerry_cleanup();
+
+  return 0;
+}
+```
+
+**Convenience macros**
+
+To make property registration convenient, there are a set of macros to use
+when setting a property entry:
+
+* `JERRYX_PROPERTY_NUMBER(NAME, NUMBER)` - creates a number entry.
+* `JERRYX_PROPERTY_STRING(NAME, STR)` - creates an utf8 string entry.
+* `JERRYX_PROPERTY_STRING_SZ(NAME, STR, SIZE)` - creates an utf8 string entry using only `SIZE` bytes from the string.
+* `JERRYX_PROPERTY_BOOLEAN(NAME, VALUE)` - creates a boolean entry.
+* `JERRYX_PROPERTY_FUNCTION(NAME, NATIVE)` - creates a native C function entry.
+* `JERRYX_PROPERTY_UNDEFINED(NAME)` - creates an undefined property entry.
+* `JERRYX_PROPERTY_LIST_END()` - indicates the end of the property list.
+
+**Example usage of Convenience macros**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+#include "jerryscript-ext/handler.h"
+
+static jerry_value_t
+handler (const jerry_value_t function_obj,
+         const jerry_value_t this_val,
+         const jerry_value_t args_p[],
+         const jerry_length_t args_cnt)
+{
+  printf ("native handler called!\n");
+
+  return jerry_create_boolean (true);
+}
+
+int
+main (int argc, char **argv)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerryx_property_entry methods[] =
+  {
+    JERRYX_PROPERTY_FUNCTION ("demo", handler),
+    JERRYX_PROPERTY_NUMBER ("test_num", 2.3),
+    JERRYX_PROPERTY_UNDEFINED ("this_is_undefined"),
+    JERRYX_PROPERTY_LIST_END(),
+  };
+
+  jerry_value_t global = jerry_get_global_object ();
+  jerryx_register_result reg = jerryx_set_properties (global, methods);
+  /* if `reg.result` is undefined all methods are registered */
+  if (jerry_value_is_error (reg.result))
+  {
+    printf ("Only registered %d properties\r\n", reg.registered);
+    /* clean up not registered property values */
+    jerryx_free_property_entry (methods, reg);
+
+    /* clean up the error */
+    jerry_release_value (reg.result);
+  }
+
+  jerry_release_value (global);
+
+  jerry_cleanup();
+
+  return 0;
+}
+```
+
+
+**See also**
+
+- [jerryx_property_entry](#jerryx_property_entry)
+- [jerryx_free_property_entry](#jerryx_free_property_entry)
+- [jerryx_register_result](#jerryx_register_result)
+
+## jerryx_free_property_entry
+
+**Summary**
+
+Release all `jerry_value_t` in a `jerryx_property_entry` array based on a previous [jerryx_set_properties](#jerryx_set_properties) call
+and also the error value (if any) in the `jerryx_register_result` structure.
+In case of a successful registration it is safe to call this method.
+
+After the method call the `ęntries` array should not be used as all values are released.
+
+**Prototype**
+
+```
+void
+jerryx_free_property_entry (const jerryx_property_entry entries[],
+                            const jerryx_register_result register_result);
+```
+
+- `entires` - array of [jerryx_property_entry](#jerryx_property_entry).
+- `register_result` - result of a previous [jerryx_set_properties](#jerryx_set_properties) call.
+
+**Example**
+
+For example usage see [jerryx_set_properties](#jerryx_set_properties).
+
+
+## jerryx_set_property_str
+
+**Summary**
+
+Set a property on a target object with a given name.
+
+The property name must be provided as a zero terminated string.
+
+*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+
+
+**Prototype**
+
+```c
+jerry_value_t
+jerryx_set_property_str (const jerry_value_t target_object,
+                         const char *name,
+                         const jerry_value_t value);
+```
+
+- `target_object` - the object where the property should be set
+- `name` - name of the property
+- `value` - property value to be set
+- return value
+  - JS true value, if success
+  - thrown error, otherwise
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+#include "jerryscript-ext/handler.h"
+
+int
+main (int argc, char **argv)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t global = jerry_get_global_object ();
+
+  jerry_value_t value = jerry_create_number (3.3);
+  jerry_value_t result = jerryx_set_property_str (global, "value", value);
+  if (jerry_value_is_error (result))
+  {
+    printf ("Error during property configuration\r\n");
+  }
+
+  jerry_release_value (result);
+  jerry_release_value (value);
+  jerry_release_value (global);
+  jerry_cleanup();
+
+  return 0;
+}
+```
+
+
+## jerryx_get_property_str
+
+**Summary**
+
+Get the value of a property from the specified object with the given name.
+
+*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+
+
+**Prototype**
+
+```
+jerry_value_t
+jerryx_get_property_str (const jerry_value_t target_object,
+                         const char *name);
+```
+
+- `target_object` - object on which the property name is accessed
+- `name` - property name as a `char*`
+- return value
+  - value of property, if success
+  - thrown error, otherwise
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+#include "jerryscript-ext/handler.h"
+
+int
+main (int argc, char **argv)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t global = jerry_get_global_object ();
+
+  jerry_value_t math_object = jerryx_get_property_str (global, "Math");
+
+  /* use math_object */
+
+  jerry_release_value (math_object);
+  jerry_release_value (global);
+  jerry_cleanup();
+
+  return 0;
+}
+```
+
+
 #  Common external function handlers
 
 ## jerryx_handler_assert_fatal