Added the write_file() API function.

This function is added to provide a standard way of writing/overwriting
previously generated files within a project target directory, or creating
new files with custom/dynamic content, both when in form-based as well as
in Quickstart mode. This allows init code to create new files with dynamically
generated content, instead of having to use source templates with substitution
variables. The function automatically performs some safety checks and lets the
underlying initialization process fail in some cases. Therefore, by using this
function a caller can use the same API irrespective of the underlying
application mode context.

Author: kilo52

VERSION

@@ -1 +1 @@
-1.7.6-dev
+1.8.0-dev

libinit.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# Copyright (C) 2024 Raven Computing
+# Copyright (C) 2025 Raven Computing
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -5572,3 +5572,92 @@ function proceed_next_level() {
 
   source "$next_lvl_script";
 }
+
+# [API function]
+# Writes text to a file within the project target directory.
+#
+# The file to write is specified by the first argument. The file path argument
+# is interpreted as relative to the project target directory. The content to write
+# is specified by the second argument.
+#
+# When in regular (form-based) application mode, the project target directory must have
+# already been created by means of the project_init_copy() function before a file
+# can be written. If the specified file already exists, its content is overwritten.
+# If it does not already exist, it is created.
+#
+# When in Quickstart mode, the project target directory is the underlying Quickstart
+# current working directory, i.e. where the Quickstart was initiated. If the specified
+# file already exists, it is only overwritten if it was previously created by
+# a Quickstart function, otherwise the entire Quickstart operation is cancelled
+# by this function. The file is created if it does not already exists.
+#
+# Args:
+# $1 - The relative path of the source file to write to in the project
+#      target directory. The path must not be absolute. This is a mandatory argument
+# $2 - The file content to write to the specified file. Can be an empty string
+#      or omitted. This is an optional argument.
+#
+# Returns:
+# 0 - If the write operation was successful.
+# 1 - If the write operation to the specified file has failed.
+#
+# Examples:
+# write_file "src/project_file.txt" "The file content";
+#
+function write_file() {
+  local arg_file_path="$1";
+  local arg_file_data="$2";
+  if [ -z "$arg_file_path" ]; then
+    _make_func_hl "write_file";
+    logE "Programming error: Illegal function call:";
+    logE "at: '${BASH_SOURCE[1]}' (line ${BASH_LINENO[0]})";
+    failure "Programming error: Invalid call to ${HYPERLINK_VALUE} function: " \
+            "No file argument specified";
+  fi
+  if _is_absolute_path "$arg_file_path"; then
+    _make_func_hl "write_file";
+    logE "Programming error: Illegal argument '${arg_target}'";
+    logE "at: '${BASH_SOURCE[1]}' (line ${BASH_LINENO[0]})";
+    failure "Programming error: Invalid call to ${HYPERLINK_VALUE} function: " \
+            "The file argument must not be absolute";
+  fi
+
+  local file_path="";
+  if [[ $PROJECT_INIT_QUICKSTART_REQUESTED == true ]]; then
+    file_path="${_PROJECT_INIT_QUICKSTART_OUTPUT_DIR}/${arg_file_path}";
+    if [ -e "$file_path" ]; then
+      if ! _array_contains "$file_path" "${CACHE_ALL_FILES[@]}"; then
+        _make_func_hl "write_file";
+        logW "Cannot write to file '${arg_file_path}'";
+        logW "A file may only be written to by the ${HYPERLINK_VALUE} function if it was";
+        logW "previously generated by a Quickstart function";
+        _cancel_quickstart $EXIT_FAILURE;
+      fi
+      if ! [ -f "$file_path" ]; then
+        logW "Cannot write to file '${arg_file_path}'";
+        logW "File already exists but is not a regular file";
+        _cancel_quickstart $EXIT_FAILURE;
+      fi
+    fi
+  else
+    if [[ ${_FLAG_PROJECT_FILES_COPIED} == false ]]; then
+      _make_func_hl "write_file";
+      local _hl_write_file="$HYPERLINK_VALUE";
+      _make_func_hl "project_init_copy";
+      local _hl_pic="$HYPERLINK_VALUE";
+      logE "Programming error in init script:";
+      logE "at: '${BASH_SOURCE[1]}' (line ${BASH_LINENO[0]})";
+      failure "Missing call to project_init_copy() function:"                             \
+              "When calling the ${_hl_write_file} function, the target project directory" \
+              "must already be created. "                                                 \
+              "Make sure you first call the ${_hl_pic} function in your init script";
+    fi
+    file_path="${var_project_dir}/${arg_file_path}";
+  fi
+  echo -ne "$arg_file_data" > "$file_path";
+  if (( $? != 0 )); then
+    logW "Could not write to file '${file_path}'";
+    return 1;
+  fi
+  return 0;
+}