#!/bin/bash
# SPDX-Version: 3.0
# SPDX-CreationInfo: 2025-06-17; WEIDNER, Marc S.; <msw@coresecret.dev>
# SPDX-ExternalRef: GIT https://git.coresecret.dev/msw/CISS.debian.installer.git
# SPDX-FileContributor: WEIDNER, Marc S.; Centurion Intelligence Consulting Agency
# SPDX-FileCopyrightText: 2024-2025; WEIDNER, Marc S.; <msw@coresecret.dev>
# SPDX-FileType: SOURCE
# SPDX-License-Identifier: EUPL-1.2 OR LicenseRef-CCLA-1.0
# SPDX-LicenseComment: This file is part of the CISS.debian.installer.secure framework.
# SPDX-PackageName: CISS.debian.installer
# SPDX-Security-Contact: security@coresecret.eu

guard_sourcing

#######################################
# Converts the value of a passed variable to lowercase.
# Example:
#   ensure_lowercase "VAR"
# Globals:
#   None
# Arguments:
#   1: VARIABLE name only
# Returns:
#   0: on success
#   ERR_UNBOUND_VARIABLE
#######################################
ensure_lowercase() {
  declare -r name="$1"
  if ! declare -p "${name}" &>/dev/null; then
    do_log "emergency" "file_only" "0008() Unbound variable: [${name}]."
    return "${ERR_UNBOUND_VARIABLE}"
  fi
  declare -n ref="${name}"
  ref="${ref,,}"
  return 0
}
### Prevents accidental 'unset -f'.
# shellcheck disable=SC2034
readonly -f ensure_lowercase

#######################################
# Converts the value of a passed variable to uppercase.
# Example:
#   ensure_uppercase "VAR"
# Globals:
#   None
# Arguments:
#   1: VARIABLE name only
# Returns:
#   0: on success
#   ERR_UNBOUND_VARIABLE
#######################################
ensure_uppercase() {
  declare -r name="$1"
  if ! declare -p "${name}" &>/dev/null; then
    do_log "emergency" "file_only" "0008() Unbound variable: [${name}]."
    return "${ERR_UNBOUND_VARIABLE}"
  fi
  declare -n ref="${name}"
  ref="${ref^^}"
  return 0
}
### Prevents accidental 'unset -f'.
# shellcheck disable=SC2034
readonly -f ensure_uppercase

#######################################
# Removes leading and trailing spaces in the value.
# Example:
#   ensure_trimmed "VAR"
# Globals:
#   None
# Arguments:
#   1: VARIABLE name only
# Returns:
#   0: on success
#   ERR_UNBOUND_VARIABLE
#######################################
ensure_trimmed() {
  declare -r name="$1"
  if ! declare -p "${name}" &>/dev/null; then
    do_log "emergency" "file_only" "0008() Unbound variable: [${name}]."
    return "${ERR_UNBOUND_VARIABLE}"
  fi
  declare -n ref="${name}"
  ref="${ref#"${ref%%[![:space:]]*}"}"
  ref="${ref%"${ref##*[![:space:]]}"}"
  return 0
}
### Prevents accidental 'unset -f'.
# shellcheck disable=SC2034
readonly -f ensure_trimmed

#######################################
# Resets the value of the variable to a default value if it is empty or contains only whitespace.
# Example:
#   reset_to_default "VAR" "fallback"
# Globals:
#   None
# Arguments:
#   1: VARIABLE name only
#   2: Fallback value
# Returns:
#   0: on success
#   ERR_UNBOUND_VARIABLE
#######################################
reset_to_default() {
  declare -r name="$1"
  declare -r fallback="$2"
  if ! declare -p "${name}" &>/dev/null; then
    do_log "emergency" "file_only" "0008() Unbound variable: [${name}]."
    return "${ERR_UNBOUND_VARIABLE}"
  fi
  declare -n ref="${name}"
  declare    trimmed="${ref#"${ref%%[![:space:]]*}"}"
  trimmed="${trimmed%"${trimmed##*[![:space:]]}"}"
  if [[ -z "${trimmed}" ]]; then
    ref="${fallback}"
  fi
  return 0
}
### Prevents accidental 'unset -f'.
# shellcheck disable=SC2034
readonly -f reset_to_default

#######################################
# Checks whether the content of a variable matches a specific regex.
# Example:
#   assert_match "FOO" '^[a-z0-9_-]+$'
# Globals:
#   None
# Arguments:
#   1: VARIABLE name only
#   2: Regex in 'single quotes'
# Returns:
#   0: on success
#   ERR_UNBOUND_VARIABLE
#   ERR_VAR_REGEX_CHK
#######################################
assert_match() {
  declare -r name="$1"
  declare -r pattern="$2"
  if ! declare -p "${name}" &>/dev/null; then
    do_log "emergency" "file_only" "0008() Unbound variable: [${name}]."
    return "${ERR_UNBOUND_VARIABLE}"
  fi
  declare -n ref="${name}"
  if ! [[ "${ref}" =~ ${pattern} ]]; then
    do_log "emergency" "file_only" "0008() Variable: [${name}] not matching Regex: [${pattern}]: [${ref}]."
    return "${ERR_VAR_REGEX_CHK}"
  fi
  return 0
}
### Prevents accidental 'unset -f'.
# shellcheck disable=SC2034
readonly -f assert_match
# vim: number et ts=2 sw=2 sts=2 ai tw=128 ft=sh