Common but non-standard JS function implementations in jerry-ext

CMakeLists.txt

@@ -47,6 +47,12 @@ if(JERRY_CMDLINE OR JERRY_CMDLINE_MINIMAL)
   set(JERRY_PORT_DEFAULT_MESSAGE " (FORCED BY CMDLINE)")
 endif()
 
+if(JERRY_CMDLINE)
+  set(JERRY_EXT "ON")
+
+  set(JERRY_EXT_MESSAGE " (FORCED BY CMDLINE)")
+endif()
+
 if("${PLATFORM}" STREQUAL "DARWIN")
   set(JERRY_LIBC         "OFF")
   set(JERRY_LIBM         "OFF")

docs/10.EXT-REFERENCE-HANDLER.md

@@ -0,0 +1,179 @@
+#  Common external function handlers
+
+## jerryx_handler_assert
+
+**Summary**
+
+Assert for scripts. The routine calls `jerry_port_fatal` on assertion failure.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerryx_handler_assert (const jerry_value_t func_obj_val, const jerry_value_t this_p,
+                       const jerry_value_t args_p[], const jerry_length_t args_cnt);
+```
+
+- `func_obj_val` - the function object that was called (unused).
+- `this_p` - the `this` value of the call (unused).
+- `args_p` - the array of function arguments.
+- `args_cnt` - the number of function arguments.
+- return value - `jerry_value_t` representing boolean true, if only one argument
+  was passed and that argument was a boolean true. Note that the function does
+  not return otherwise.
+
+**See also**
+
+- [jerryx_handler_register_global](#jerryx_handler_register_global)
+
+
+## jerryx_handler_gc
+
+**Summary**
+
+Expose garbage collector to scripts.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,
+                   const jerry_value_t args_p[], const jerry_length_t args_cnt);
+```
+
+- `func_obj_val` - the function object that was called (unused).
+- `this_p` - the `this` value of the call (unused).
+- `args_p` - the array of function arguments (unused).
+- `args_cnt` - the number of function arguments (unused).
+- return value - `jerry_value_t` representing `undefined`.
+
+**See also**
+
+- [jerryx_handler_register_global](#jerryx_handler_register_global)
+
+
+## jerryx_handler_print
+
+**Summary**
+
+Provide a `print` implementation for scripts. The routine converts all of its
+arguments to strings and outputs them char-by-char using
+`jerryx_port_handler_print_char`. The NUL character is output as "\u0000",
+other characters are output bytewise.
+
+*Note*: This implementation does not use standard C `printf` to print its
+output. This allows more flexibility but also extends the core JerryScript
+engine port API. Applications that want to use `jerryx_handler_print` must
+ensure that their port implementation also provides
+`jerryx_port_handler_print_char`.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this_p,
+                      const jerry_value_t args_p[], const jerry_length_t args_cnt);
+```
+
+- `func_obj_val` - the function object that was called (unused).
+- `this_p` - the `this` value of the call (unused).
+- `args_p` - the array of function arguments.
+- `args_cnt` - the number of function arguments.
+- return value - `jerry_value_t` representing `undefined` if all arguments could
+  be converted to strings, an `Error` otherwise.
+
+**See also**
+
+- [jerryx_handler_register_global](#jerryx_handler_register_global)
+- [jerryx_port_handler_print_char](#jerryx_port_handler_print_char)
+
+
+# Handler registration helper
+
+## jerryx_handler_register_global
+
+**Summary**
+
+Register a JavaScript function in the global object.
+
+*Note*: Returned value must be freed with `jerry_release_value`, when it is no
+longer needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerryx_handler_register_global (const jerry_char_t *name_p,
+                                jerry_external_handler_t handler_p);
+```
+
+- `name_p` - the name of the function to be registered.
+- `handler_p` - the address of the external function handler.
+- return value - `jerry_value_t` representing boolean true, if the operation was
+  successful, an `Error` otherwise.
+
+**Example**
+
+```c
+#include "jerryscript.h"
+#include "jerryscript-ext/handler.h"
+
+static const struct {
+  const char *name_p;
+  jerry_external_handler_t handler_p;
+} common_functions[] =
+{
+  { "assert", jerryx_handler_assert },
+  { "gc", jerryx_handler_gc },
+  { "print", jerryx_handler_print },
+  { NULL, NULL }
+};
+
+static void register_common_functions ()
+{
+  jerry_value_t ret = jerry_create_undefined ();
+
+  for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_has_error_flag (ret); i++)
+  {
+    ret = jerryx_handler_register_global ((const jerry_char_t *) common_functions[i].name_p,
+                                          common_functions[i].handler_p);
+  }
+
+  return ret;
+}
+```
+
+
+# Port API extension
+
+## jerryx_port_handler_print_char
+
+**Summary**
+
+Print a single character.
+
+**Prototype**
+
+```c
+void
+jerryx_port_handler_print_char (char c);
+```
+
+- `c` - the character to print.
+
+**Example**
+
+```c
+/**
+ * Print a character to stdout with printf.
+ */
+void
+jerryx_port_handler_print_char (char c)
+{
+  printf ("%c", c);
+} /* jerryx_port_handler_print_char */
+```
+
+**See also**
+
+- [jerryx_handler_print](#jerryx_handler_print)

jerry-core/include/jerryscript-port.h

@@ -62,7 +62,7 @@ typedef enum
  *
  * Example: a libc-based port may implement this with exit() or abort(), or both.
  */
-void jerry_port_fatal (jerry_fatal_code_t code);
+void jerry_port_fatal (jerry_fatal_code_t code) __attribute__((noreturn));
 
 /*
  *  I/O Port API

jerry-ext/CMakeLists.txt

@@ -20,7 +20,12 @@ project (${JERRY_EXT_NAME} C)
 set(INCLUDE_EXT "${CMAKE_CURRENT_SOURCE_DIR}/include")
 
 # Source directories
-file(GLOB SOURCE_EXT arg/*.c)
+file(GLOB SOURCE_EXT_ARG      arg/*.c)
+file(GLOB SOURCE_EXT_HANDLER  handler/*.c)
+
+set(SOURCE_EXT
+    ${SOURCE_EXT_ARG}
+    ${SOURCE_EXT_HANDLER})
 
 add_library(${JERRY_EXT_NAME} STATIC ${SOURCE_EXT})
 

jerry-ext/handler/handler-assert.c

@@ -0,0 +1,45 @@
+/* Copyright JS Foundation and other contributors, http://js.foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "jerryscript-ext/handler.h"
+#include "jerryscript-port.h"
+
+/**
+ * Assert for scripts. The routine calls jerry_port_fatal on assertion failure.
+ *
+ * @return true - if only one argument was passed and that argument was a boolean true.
+ *         Note that the function does not return otherwise.
+ */
+jerry_value_t
+jerryx_handler_assert (const jerry_value_t func_obj_val, /**< function object */
+                       const jerry_value_t this_p, /**< this arg */
+                       const jerry_value_t args_p[], /**< function arguments */
+                       const jerry_length_t args_cnt) /**< number of function arguments */
+{
+  (void) func_obj_val; /* unused */
+  (void) this_p; /* unused */
+
+  if (args_cnt == 1
+      && jerry_value_is_boolean (args_p[0])
+      && jerry_get_boolean_value (args_p[0]))
+  {
+    return jerry_create_boolean (true);
+  }
+  else
+  {
+    jerry_port_log (JERRY_LOG_LEVEL_ERROR, "Script Error: assertion failed\n");
+    jerry_port_fatal (ERR_FAILED_INTERNAL_ASSERTION);
+  }
+} /* jerryx_handler_assert */

jerry-ext/handler/handler-gc.c

@@ -0,0 +1,36 @@
+/* Copyright JS Foundation and other contributors, http://js.foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "jerryscript-ext/handler.h"
+
+/**
+ * Expose garbage collector to scripts.
+ *
+ * @return undefined.
+ */
+jerry_value_t
+jerryx_handler_gc (const jerry_value_t func_obj_val, /**< function object */
+                   const jerry_value_t this_p, /**< this arg */
+                   const jerry_value_t args_p[], /**< function arguments */
+                   const jerry_length_t args_cnt) /**< number of function arguments */
+{
+  (void) func_obj_val; /* unused */
+  (void) this_p; /* unused */
+  (void) args_p; /* unused */
+  (void) args_cnt; /* unused */
+
+  jerry_gc ();
+  return jerry_create_undefined ();
+} /* jerryx_handler_gc */