Update jerry-port and jerry-ext (#4907)

Notable changes:
  - Updated and the port API interface, new functions have been added
    and some have been changed. The port library is now cleaned up to
    not have any dependency on jerry-core, as it should be. The port library
    is now strictly a collection of functions that implement
    embedding/platform specific behavior.
  - The default port implementation has been split for windows and unix.
    Implemented port functions have been categorized and reorganized,
    and marked with attribute((weak)) for better reusability.
  - External context allocation has been moved to the port API instead
    of a core API callback. The iterface has also been extended with a
    function to free the allocated context. When external context is
    enabled, jerry_init now automatically calls the port implementation
    to allocate the context and jerry_cleanup automatically calls the port
    to free the context.
  - jerry_port_log has been changed to no longer require formatting to
    be implemented by the port. The reason beind this is that it was vague what
    format specifiers were used by the engine, and in what manner. The port
    function now takes a zero-terminated string, and should only implement
    how the string should be logged.
  - Logging and log message formatting is now handled by the core jerry library
    where it can be implemented as necessary. Logging can be done through a new
    core API function, which uses the port to output the final log message.
  - Log level has been moved into jerry-core, and an API function has
    been added to set the log level. It should be the library that
    filters log messages based on the requested log level, instead of
    logging everything and requiring the user to do so.
  - Module resolving logic has been moved into jerry-core. There's no
    reason to have it in the port library and requiring embedders to
    duplicate the code. It also added an unnecessary dependency on
    jerry-core to the port. Platform specific behavior is still used through
    the port API, like resolving module specifiers, and reading source file
    contents. If necessary, the resolving logic can still be overridden as
    previously.
  - The jerry-ext library has also been cleaned up, and many utility
    functions have been added that previously were implemented in
    jerry-main. This allows easier reusability for some common operations,
    like printing unhandled exceptions or providing a repl console.
  - Debugger interaction with logged/printed messages has been fixed, so
    that it's no longer the port implementations responsibility to send
    the output to the debugger, as the port should have no notion of what a
    debugger is.  The printing and logging functions will now pass the
    result message to the debugger, if connected.
  - Cleaned up TZA handling in the date port implementation, and simplified
    the API function prototype.
  - Moved property access helper functions that use ASCII strings as
    keys from jerry-ext to the core API.

JerryScript-DCO-1.0-Signed-off-by: Dániel Bátyai dbatyai@inf.u-szeged.hu

jerry-core/include/jerryscript-compiler.h

@@ -45,6 +45,9 @@ JERRY_C_API_BEGIN
 #define JERRY_ATTR_NORETURN           __attribute__ ((noreturn))
 #define JERRY_ATTR_PURE               __attribute__ ((pure))
 #define JERRY_ATTR_WARN_UNUSED_RESULT __attribute__ ((warn_unused_result))
+#define JERRY_ATTR_WEAK               __attribute__ ((weak))
+
+#define JERRY_WEAK_SYMBOL_SUPPORT
 
 #ifndef JERRY_LIKELY
 #define JERRY_LIKELY(x) __builtin_expect (!!(x), 1)
@@ -154,6 +157,13 @@ void *__cdecl _alloca (size_t _Size);
 #define JERRY_ATTR_WARN_UNUSED_RESULT
 #endif /* !JERRY_ATTR_WARN_UNUSED_RESULT */
 
+/**
+ * Function attribute to declare a function a weak symbol
+ */
+#ifndef JERRY_ATTR_WEAK
+#define JERRY_ATTR_WEAK
+#endif /* !JERRY_ATTR_WEAK */
+
 /**
  * Helper to predict that a condition is likely.
  */

jerry-core/include/jerryscript-core.h

@@ -37,7 +37,6 @@ JERRY_C_API_BEGIN
 void jerry_init (jerry_init_flag_t flags);
 void jerry_cleanup (void);
 
-jerry_context_t *jerry_context_alloc (jerry_size_t heap_size, jerry_context_alloc_cb_t alloc, void *cb_data_p);
 void *jerry_context_data (const jerry_context_data_manager_t *manager_p);
 
 jerry_value_t jerry_current_realm (void);
@@ -69,8 +68,10 @@ bool jerry_foreach_live_object_with_info (const jerry_object_native_info_t *nati
  * @{
  */
 
+void JERRY_ATTR_FORMAT (printf, 2, 3) jerry_log (jerry_log_level_t level, const char *format_p, ...);
+void jerry_log_set_level (jerry_log_level_t level);
 bool jerry_validate_string (const jerry_char_t *buffer_p, jerry_size_t buffer_size, jerry_encoding_t encoding);
-bool jerry_feature_enabled (const jerry_feature_t feature);
+bool JERRY_ATTR_CONST jerry_feature_enabled (const jerry_feature_t feature);
 void jerry_register_magic_strings (const jerry_char_t *const *ext_strings_p,
                                    uint32_t count,
                                    const jerry_length_t *str_lengths_p);
@@ -171,7 +172,7 @@ bool jerry_frame_is_strict (jerry_frame_t *frame_p);
  */
 
 /* Reference management */
-jerry_value_t jerry_value_copy (const jerry_value_t value);
+jerry_value_t JERRY_ATTR_WARN_UNUSED_RESULT jerry_value_copy (const jerry_value_t value);
 void jerry_value_free (jerry_value_t value);
 
 /**
@@ -256,8 +257,8 @@ jerry_value_t jerry_binary_op (jerry_binary_op_t operation, const jerry_value_t
  */
 jerry_value_t jerry_throw (jerry_error_t type, const jerry_value_t message);
 jerry_value_t jerry_throw_sz (jerry_error_t type, const char *message_p);
-jerry_value_t jerry_throw_value (const jerry_value_t value, bool take_ownership);
-jerry_value_t jerry_throw_abort (const jerry_value_t value, bool take_ownership);
+jerry_value_t jerry_throw_value (jerry_value_t value, bool take_ownership);
+jerry_value_t jerry_throw_abort (jerry_value_t value, bool take_ownership);
 /**
  * jerry-api-exception-ctor @}
  */
@@ -309,7 +310,7 @@ void jerry_on_throw (jerry_throw_cb_t callback, void *user_p);
  * @{
  */
 
-jerry_value_t jerry_undefined (void);
+jerry_value_t JERRY_ATTR_CONST jerry_undefined (void);
 
 /**
  * jerry-api-undefined-ctor @}
@@ -329,7 +330,7 @@ jerry_value_t jerry_undefined (void);
  * @{
  */
 
-jerry_value_t jerry_null (void);
+jerry_value_t JERRY_ATTR_CONST jerry_null (void);
 
 /**
  * jerry-api-null-ctor @}
@@ -349,7 +350,7 @@ jerry_value_t jerry_null (void);
  * @{
  */
 
-jerry_value_t jerry_boolean (bool value);
+jerry_value_t JERRY_ATTR_CONST jerry_boolean (bool value);
 
 /**
  * jerry-api-boolean-ctor @}
@@ -458,7 +459,6 @@ void jerry_string_iterate (const jerry_value_t value,
                            jerry_encoding_t encoding,
                            jerry_string_iterate_cb_t callback,
                            void *user_p);
-void jerry_string_print (const jerry_value_t value);
 /**
  * jerry-api-string-op @}
  */
@@ -550,6 +550,7 @@ bool jerry_object_foreach (const jerry_value_t object, jerry_object_property_for
  * @{
  */
 jerry_value_t jerry_object_set (jerry_value_t object, const jerry_value_t key, const jerry_value_t value);
+jerry_value_t jerry_object_set_sz (jerry_value_t object, const char *key_p, const jerry_value_t value);
 jerry_value_t jerry_object_set_index (jerry_value_t object, uint32_t index, const jerry_value_t value);
 jerry_value_t jerry_object_define_own_prop (jerry_value_t object,
                                             const jerry_value_t key,
@@ -567,6 +568,7 @@ void jerry_object_set_native_ptr (jerry_value_t object,
  * @{
  */
 jerry_value_t jerry_object_has (const jerry_value_t object, const jerry_value_t key);
+jerry_value_t jerry_object_has_sz (const jerry_value_t object, const char *key_p);
 jerry_value_t jerry_object_has_own (const jerry_value_t object, const jerry_value_t key);
 bool jerry_object_has_internal (const jerry_value_t object, const jerry_value_t key);
 bool jerry_object_has_native_ptr (const jerry_value_t object, const jerry_object_native_info_t *native_info_p);
@@ -579,6 +581,7 @@ bool jerry_object_has_native_ptr (const jerry_value_t object, const jerry_object
  * @{
  */
 jerry_value_t jerry_object_get (const jerry_value_t object, const jerry_value_t key);
+jerry_value_t jerry_object_get_sz (const jerry_value_t object, const char *key_p);
 jerry_value_t jerry_object_get_index (const jerry_value_t object, uint32_t index);
 jerry_value_t jerry_object_get_own_prop (const jerry_value_t object,
                                          const jerry_value_t key,
@@ -599,6 +602,7 @@ jerry_value_t jerry_object_find_own (const jerry_value_t object,
  * @{
  */
 jerry_value_t jerry_object_delete (jerry_value_t object, const jerry_value_t key);
+jerry_value_t jerry_object_delete_sz (const jerry_value_t object, const char *key_p);
 jerry_value_t jerry_object_delete_index (jerry_value_t object, uint32_t index);
 bool jerry_object_delete_internal (jerry_value_t object, const jerry_value_t key);
 bool jerry_object_delete_native_ptr (jerry_value_t object, const jerry_object_native_info_t *native_info_p);
@@ -1101,8 +1105,30 @@ jerry_value_t jerry_module_namespace (const jerry_value_t module);
  * @defgroup jerry-api-module-op Operations
  * @{
  */
+
+/**
+ * Resolve and parse a module file
+ *
+ * @param specifier: module request specifier string.
+ * @param referrer: parent module.
+ * @param user_p: user specified pointer.
+ *
+ * @return module object if resolving is successful, error otherwise.
+ */
+jerry_value_t jerry_module_resolve (const jerry_value_t specifier, const jerry_value_t referrer, void *user_p);
+
 jerry_value_t jerry_module_link (const jerry_value_t module, jerry_module_resolve_cb_t callback, void *user_p);
 jerry_value_t jerry_module_evaluate (const jerry_value_t module);
+
+/**
+ * Release known modules in the current context. If realm parameter is supplied, cleans up modules native to that realm
+ * only. This function should be called by the user application when the module database in the current context is no
+ * longer needed.
+ *
+ * @param realm: release only those modules which realm value is equal to this argument.
+ */
+void jerry_module_cleanup (const jerry_value_t realm);
+
 /**
  * jerry-api-module-op @}
  */
@@ -1116,7 +1142,7 @@ jerry_value_t jerry_native_module (jerry_native_module_evaluate_cb_t callback,
                                    size_t export_count);
 jerry_value_t jerry_native_module_get (const jerry_value_t native_module, const jerry_value_t export_name);
 jerry_value_t
-jerry_native_module_set (const jerry_value_t native_module, const jerry_value_t export_name, const jerry_value_t value);
+jerry_native_module_set (jerry_value_t native_module, const jerry_value_t export_name, const jerry_value_t value);
 /**
  * jerry-api-module-native @}
  */

jerry-core/include/jerryscript-debugger.h

@@ -16,7 +16,7 @@
 #ifndef JERRYSCRIPT_DEBUGGER_H
 #define JERRYSCRIPT_DEBUGGER_H
 
-#include "jerryscript-port.h"
+#include "jerryscript-types.h"
 
 JERRY_C_API_BEGIN
 
@@ -65,7 +65,6 @@ jerry_debugger_wait_for_client_source (jerry_debugger_wait_for_source_callback_t
                                        void *user_p,
                                        jerry_value_t *return_value);
 void jerry_debugger_send_output (const jerry_char_t *buffer, jerry_size_t str_size);
-void jerry_debugger_send_log (jerry_log_level_t level, const jerry_char_t *buffer, jerry_size_t str_size);
 
 /**
  * @}

jerry-core/include/jerryscript-port.h

@@ -16,233 +16,301 @@
 #ifndef JERRYSCRIPT_PORT_H
 #define JERRYSCRIPT_PORT_H
 
-#include <stdbool.h>
-#include <stdint.h>
-#include <stdio.h>
-
 #include "jerryscript-types.h"
 
 JERRY_C_API_BEGIN
 
-/** \addtogroup jerry_port Jerry engine port
+/**
+ * @defgroup jerry-port JerryScript Port API
  * @{
  */
 
-/*
- * Termination Port API
+/**
+ * @defgroup jerry-port-process Process management API
  *
- * Note:
- *      It is questionable whether a library should be able to terminate an
- *      application. However, as of now, we only have the concept of completion
- *      code around jerry_parse and jerry_run. Most of the other API functions
- *      have no way of signaling an error. So, we keep the termination approach
- *      with this port function.
+ * It is questionable whether a library should be able to terminate an
+ * application. However, as of now, we only have the concept of completion
+ * code around jerry_parse and jerry_run. Most of the other API functions
+ * have no way of signaling an error. So, we keep the termination approach
+ * with this port function.
+ *
+ * @{
  */
 
 /**
- * Error codes
+ * Error codes that can be passed by the engine when calling jerry_port_fatal
  */
 typedef enum
 {
-  ERR_OUT_OF_MEMORY = 10,
-  ERR_REF_COUNT_LIMIT = 12,
-  ERR_DISABLED_BYTE_CODE = 13,
-  ERR_UNTERMINATED_GC_LOOPS = 14,
-  ERR_FAILED_INTERNAL_ASSERTION = 120
+  JERRY_FATAL_OUT_OF_MEMORY = 10, /**< Out of memory */
+  JERRY_FATAL_REF_COUNT_LIMIT = 12, /**< Reference count limit reached */
+  JERRY_FATAL_DISABLED_BYTE_CODE = 13, /**< Executed disabled instruction */
+  JERRY_FATAL_UNTERMINATED_GC_LOOPS = 14, /**< Garbage collection loop limit reached */
+  JERRY_FATAL_FAILED_ASSERTION = 120 /**< Assertion failed */
 } jerry_fatal_code_t;
 
 /**
- * Signal the port that jerry experienced a fatal failure from which it cannot
+ * Signal the port that the process experienced a fatal failure from which it cannot
  * recover.
  *
- * @param code gives the cause of the error.
+ * A libc-based port may implement this with exit() or abort(), or both.
  *
- * Note:
- *      Jerry expects the function not to return.
+ * Note: This function is expected to not return.
  *
- * Example: a libc-based port may implement this with exit() or abort(), or both.
+ * @param code: the cause of the error.
  */
 void JERRY_ATTR_NORETURN jerry_port_fatal (jerry_fatal_code_t code);
 
-/*
- *  I/O Port API
- */
-
 /**
- * Jerry log levels. The levels are in severity order
- * where the most serious levels come first.
- */
-typedef enum
-{
-  JERRY_LOG_LEVEL_ERROR, /**< the engine will terminate after the message is printed */
-  JERRY_LOG_LEVEL_WARNING, /**< a request is aborted, but the engine continues its operation */
-  JERRY_LOG_LEVEL_DEBUG, /**< debug messages from the engine, low volume */
-  JERRY_LOG_LEVEL_TRACE /**< detailed info about engine internals, potentially high volume */
-} jerry_log_level_t;
-
-/**
- * Display or log a debug/error message. The function should implement a printf-like
- * interface, where the first argument specifies the log level
- * and the second argument specifies a format string on how to stringify the rest
- * of the parameter list.
+ * Make the process sleep for a given time.
  *
- * This function is only called with messages coming from the jerry engine as
- * the result of some abnormal operation or describing its internal operations
- * (e.g., data structure dumps or tracing info).
+ * This port function can be called by jerry-core when JERRY_DEBUGGER is enabled.
+ * Otherwise this function is not used.
  *
- * It should be the port that decides whether error and debug messages are logged to
- * the console, or saved to a database or to a file.
- *
- * Example: a libc-based port may implement this with vfprintf(stderr) or
- * vfprintf(logfile), or both, depending on log level.
- *
- * Note:
- *      This port function is called by jerry-core when JERRY_LOGGING is
- *      enabled. It is also common practice though to use this function in
- *      application code.
- */
-void JERRY_ATTR_FORMAT (printf, 2, 3) jerry_port_log (jerry_log_level_t level, const char *format, ...);
-
-/*
- * Date Port API
- */
-
-/**
- * Get local time zone adjustment, in milliseconds, for the given timestamp.
- * The timestamp can be specified in either UTC or local time, depending on
- * the value of is_utc. Adding the value returned from this function to
- * a timestamp in UTC time should result in local time for the current time
- * zone, and subtracting it from a timestamp in local time should result in
- * UTC time.
- *
- * Ideally, this function should satisfy the stipulations applied to LocalTZA
- * in section 20.3.1.7 of the ECMAScript version 9.0 spec.
- *
- * See Also:
- *          ECMA-262 v9, 20.3.1.7
- *
- * Note:
- *      This port function is called by jerry-core when
- *      JERRY_BUILTIN_DATE is defined to 1. Otherwise this function is
- *      not used.
- *
- * @param unix_ms The unix timestamp we want an offset for, given in
- *                millisecond precision (could be now, in the future,
- *                or in the past). As with all unix timestamps, 0 refers to
- *                1970-01-01, a day is exactly 86 400 000 milliseconds, and
- *                leap seconds cause the same second to occur twice.
- * @param is_utc Is the given timestamp in UTC time? If false, it is in local
- *               time.
- *
- * @return milliseconds between local time and UTC for the given timestamp,
- *         if available
- *.        0 if not available / we are in UTC.
- */
-double jerry_port_get_local_time_zone_adjustment (double unix_ms, bool is_utc);
-
-/**
- * Get system time
- *
- * Note:
- *      This port function is called by jerry-core when
- *      JERRY_BUILTIN_DATE is defined to 1. It is also common practice
- *      in application code to use this function for the initialization of the
- *      random number generator.
- *
- * @return milliseconds since Unix epoch
- */
-double jerry_port_get_current_time (void);
-
-/**
- * Get the current context of the engine. Each port should provide its own
- * implementation of this interface.
- *
- * Note:
- *      This port function is called by jerry-core when
- *      JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not
- *      used.
- *
- * @return the pointer to the engine context.
- */
-struct jerry_context_t *jerry_port_get_current_context (void);
-
-/**
- * Makes the process sleep for a given time.
- *
- * Note:
- *      This port function is called by jerry-core when JERRY_DEBUGGER is
- *      enabled (set to 1). Otherwise this function is not used.
- *
- * @param sleep_time milliseconds to sleep.
+ * @param sleep_time: milliseconds to sleep.
  */
 void jerry_port_sleep (uint32_t sleep_time);
 
 /**
- * Print a single character.
- *
- * Note:
- *      This port function is here so the jerry-ext components would have
- *      a common way to print out information.
- *      If possible do not use from the jerry-core.
- *
- * @param c the character to print.
+ * jerry-port-process @}
  */
-void jerry_port_print_char (char c);
 
 /**
- * Open a source file and read its contents into a buffer.
- *
- * Note:
- *      This port function is called by jerry-core when JERRY_MODULE_SYSTEM
- *      is enabled. The path is specified in the import statement's 'from "..."'
- *      section.
- *
- * @param file_name_p Path that points to the EcmaScript file in the
- *                    filesystem.
- * @param out_size_p The opened file's size in bytes.
- *
- * @return the pointer to the buffer which contains the content of the file.
+ * @defgroup jerry-port-context External Context API
+ * @{
  */
-uint8_t *jerry_port_read_source (const char *file_name_p, size_t *out_size_p);
 
 /**
- * Frees the allocated buffer after the contents of the file are not needed
- * anymore.
+ * Allocate a new context for the engine.
  *
- * @param buffer_p The pointer the allocated buffer.
+ * This port function is called by jerry_init when JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not
+ * used.
+ *
+ * The engine will pass the size required for the context structure. An implementation must make sure to
+ * allocate at least this amount.
+ *
+ * Excess allocated space will be used as the engine heap when JerryScript is configured to use it's internal allocator,
+ * this can be used to control the internal heap size.
+ *
+ * NOTE: The allocated memory must be pointer-aligned, otherwise the behavior is undefined.
+ *
+ * @param context_size: the size of the internal context structure
+ *
+ * @return total size of the allocated buffer
  */
-void jerry_port_release_source (uint8_t *buffer_p);
+size_t jerry_port_context_alloc (size_t context_size);
 
 /**
- * Default module resolver.
+ * Get the currently active context of the engine.
  *
- * Note:
- *      This port function is only used when JERRY_MODULE_SYSTEM is enabled.
+ * This port function is called by jerry-core when JERRY_EXTERNAL_CONTEXT is enabled.
+ * Otherwise this function is not used.
  *
- * @param specifier Module specifier string.
- * @param referrer Parent module.
- * @param user_p An unused pointer.
- *
- * @return A module object if resolving is successful, an error otherwise.
+ * @return the pointer to the currently used engine context.
  */
-jerry_value_t jerry_port_module_resolve (const jerry_value_t specifier, const jerry_value_t referrer, void *user_p);
+struct jerry_context_t *jerry_port_context_get (void);
 
 /**
- * Release known modules.
+ * Free the currently used context.
  *
- * Note:
- *      This port function should be called by the user application when
- *      the module database is no longer needed.
+ * This port function is called by jerry_cleanup when JERRY_EXTERNAL_CONTEXT is enabled.
+ * Otherwise this function is not used.
  *
- * @param realm If this argument is object, release only those modules,
- *              which realm value is equal to this argument.
+ * @return the pointer to the engine context.
  */
-void jerry_port_module_release (const jerry_value_t realm);
+void jerry_port_context_free (void);
 
 /**
- * @}
+ * jerry-port-context @}
+ */
+
+/**
+ * @defgroup jerry-port-io I/O API
+ * @{
+ */
+
+/**
+ * Display or log a debug/error message.
+ *
+ * The message is passed as a zero-terminated string. Messages may be logged in parts, which
+ * will result in multiple calls to this functions. The implementation should consider
+ * this before appending or prepending strings to the argument.
+ *
+ * This function is called with messages coming from the jerry engine as
+ * the result of some abnormal operation or describing its internal operations
+ * (e.g., data structure dumps or tracing info).
+ *
+ * The implementation can decide whether error and debug messages are logged to
+ * the console, or saved to a database or to a file.
+ */
+void jerry_port_log (const char *message_p);
+
+/**
+ * Print a single character to standard output.
+ *
+ * This port function is never called from jerry-core directly, it is only used by jerry-ext components to print
+ * information.
+ *
+ * @param byte: the byte to print.
+ */
+void jerry_port_print_byte (jerry_char_t byte);
+
+/**
+ * Print a buffer to standard output
+ *
+ * This port function is never called from jerry-core directly, it is only used by jerry-ext components to print
+ * information.
+ *
+ * @param buffer_p: input buffer
+ * @param buffer_size: data size
+ */
+void jerry_port_print_buffer (const jerry_char_t *buffer_p, jerry_size_t buffer_size);
+
+/**
+ * Read a line from standard input.
+ *
+ * The implementation should allocate storage necessary for the string. The result string should include the ending line
+ * terminator character(s) and should be zero terminated.
+ *
+ * An implementation may return NULL to signal that the end of input is reached, or an error occured.
+ *
+ * When a non-NULL value is returned, the caller will pass the returned value to `jerry_port_line_free` when the line is
+ * no longer needed. This can be used to finalize dynamically allocated buffers if necessary.
+ *
+ * This port function is never called from jerry-core directly, it is only used by some jerry-ext components that
+ * require user input.
+ *
+ * @param out_size_p: size of the input string in bytes, excluding terminating zero byte
+ *
+ * @return pointer to the buffer storing the string,
+ *         or NULL if end of input
+ */
+jerry_char_t *jerry_port_line_read (jerry_size_t *out_size_p);
+
+/**
+ * Free a line buffer allocated by jerry_port_line_read
+ *
+ * @param buffer_p: buffer returned by jerry_port_line_read
+ */
+void jerry_port_line_free (jerry_char_t *buffer_p);
+
+/**
+ * jerry-port-io @}
+ */
+
+/**
+ * @defgroup jerry-port-fd Filesystem API
+ * @{
+ */
+
+/**
+ * Canonicalize a file path.
+ *
+ * If possible, the implementation should resolve symbolic links and other directory references found in the input path,
+ * and create a fully canonicalized file path as the result.
+ *
+ * The function may return with NULL in case an error is encountered, in which case the calling operation will not
+ * proceed.
+ *
+ * The implementation should allocate storage for the result path as necessary. Non-NULL return values will be passed
+ * to `jerry_port_path_free` when the result is no longer needed by the caller, which can be used to finalize
+ * dynamically allocated buffers.
+ *
+ * NOTE: The implementation must not return directly with the input, as the input buffer is released after the call.
+ *
+ * @param path_p: zero-terminated string containing the input path
+ * @param path_size: size of the input path string in bytes, excluding terminating zero
+ *
+ * @return buffer with the normalized path if the operation is successful,
+ *         NULL otherwise
+ */
+jerry_char_t *jerry_port_path_normalize (const jerry_char_t *path_p, jerry_size_t path_size);
+
+/**
+ * Free a path buffer returned by jerry_port_path_normalize.
+ *
+ * @param path_p: the path buffer to free
+ */
+void jerry_port_path_free (jerry_char_t *path_p);
+
+/**
+ * Get the offset of the basename component in the input path.
+ *
+ * The implementation should return the offset of the first character after the last path separator found in the path.
+ * This is used by the caller to split the path into a directory name and a file name.
+ *
+ * @param path_p: input zero-terminated path string
+ *
+ * @return offset of the basename component in the input path
+ */
+jerry_size_t jerry_port_path_base (const jerry_char_t *path_p);
+
+/**
+ * Open a source file and read the content into a buffer.
+ *
+ * When the source file is no longer needed by the caller, the returned pointer will be passed to
+ * `jerry_port_source_free`, which can be used to finalize the buffer.
+ *
+ * @param file_name_p: Path that points to the source file in the filesystem.
+ * @param out_size_p: The opened file's size in bytes.
+ *
+ * @return pointer to the buffer which contains the content of the file.
+ */
+jerry_char_t *jerry_port_source_read (const char *file_name_p, jerry_size_t *out_size_p);
+
+/**
+ * Free a source file buffer.
+ *
+ * @param buffer_p: buffer returned by jerry_port_source_read
+ */
+void jerry_port_source_free (jerry_char_t *buffer_p);
+
+/**
+ * jerry-port-fs @}
+ */
+
+/**
+ * @defgroup jerry-port-date Date API
+ * @{
+ */
+
+/**
+ * Get local time zone adjustment in milliseconds for the given input time.
+ *
+ * The argument is a time value representing milliseconds since unix epoch.
+ *
+ * Ideally, this function should satisfy the stipulations applied to LocalTZA
+ * in section 21.4.1.7 of the ECMAScript version 12.0, as if called with isUTC true.
+ *
+ * This port function can be called by jerry-core when JERRY_BUILTIN_DATE is enabled.
+ * Otherwise this function is not used.
+ *
+ * @param unix_ms: time value in milliseconds since unix epoch
+ *
+ * @return local time offset in milliseconds applied to UTC for the given time value
+ */
+int32_t jerry_port_local_tza (double unix_ms);
+
+/**
+ * Get the current system time in UTC.
+ *
+ * This port function is called by jerry-core when JERRY_BUILTIN_DATE is enabled.
+ * It can also be used in the implementing application to initialize the random number generator.
+ *
+ * @return milliseconds since Unix epoch
+ */
+double jerry_port_current_time (void);
+
+/**
+ * jerry-port-date @}
+ */
+
+/**
+ * jerry-port @}
  */
 
 JERRY_C_API_END
 
 #endif /* !JERRYSCRIPT_PORT_H */
+
+/* vim: set fdm=marker fmr=@{,@}: */

jerry-core/include/jerryscript-types.h

@@ -40,6 +40,18 @@ typedef enum
   JERRY_INIT_MEM_STATS = (1u << 2), /**< dump memory statistics */
 } jerry_init_flag_t;
 
+/**
+ * Jerry log levels. The levels are in severity order
+ * where the most serious levels come first.
+ */
+typedef enum
+{
+  JERRY_LOG_LEVEL_ERROR = 0u, /**< the engine will terminate after the message is printed */
+  JERRY_LOG_LEVEL_WARNING = 1u, /**< a request is aborted, but the engine continues its operation */
+  JERRY_LOG_LEVEL_DEBUG = 2u, /**< debug messages from the engine, low volume */
+  JERRY_LOG_LEVEL_TRACE = 3u /**< detailed info about engine internals, potentially high volume */
+} jerry_log_level_t;
+
 /**
  * JerryScript API Error object types.
  */
@@ -316,9 +328,9 @@ typedef jerry_value_t (*jerry_halt_cb_t) (void *user_p);
 typedef void (*jerry_throw_cb_t) (const jerry_value_t exception_value, void *user_p);
 
 /**
- * Function type applied each byte of a string
+ * Function type applied to each unit of encoding when iterating over a string.
  */
-typedef void (*jerry_string_iterate_cb_t) (uint8_t byte, void *user_p);
+typedef void (*jerry_string_iterate_cb_t) (uint32_t value, void *user_p);
 
 /**
  * Function type applied for each data property of an object.