octivi-bash-boilerplate

# SPDX-FileCopyrightText: 2016-2025  IMAGIN Sp. z o.o.
# SPDX-FileContributor: Marcin Engelmann <mengelmann@octivi.com>
# SPDX-License-Identifier: MIT
#
# Part of Octivi Bash Boilerplate https://github.com/octivi/bash-boilerplate
#
# Specify the shell for shellcheck as we don't use shebang here
# shellcheck shell=bash

################################################################################
# Define colors and formatting
#
# Define colors ANSI 4-bit colors
#   - https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
#   - https://misc.flogisoft.com/bash/tip_colors_and_formatting
#   - https://stackoverflow.com/questions/5947742/how-to-change-the-output-color-of-echo-in-linux
#   - https://superuser.com/questions/301353/escape-non-printing-characters-in-a-function-for-a-bash-prompt
################################################################################

# \x1b (ESC Escape) is hex equivalent of Bash '\e' that can be used more widely.
# Foreground                         # Background
readonly __c_black=$'\x1b[0;30m';    readonly __c_b_black=$'\x1b[0;40m'    #  0. Black
readonly __c_red=$'\x1b[0;31m';      readonly __c_b_red=$'\x1b[0;41m'      #  1. Red
readonly __c_green=$'\x1b[0;32m';    readonly __c_b_green=$'\x1b[0;42m'    #  2. Green
readonly __c_yellow=$'\x1b[0;33m';   readonly __c_b_yellow=$'\x1b[0;43m'   #  3. Yellow
readonly __c_blue=$'\x1b[0;34m';     readonly __c_b_blue=$'\x1b[0;44m'     #  4. Blue
readonly __c_magenta=$'\x1b[0;35m';  readonly __c_b_magenta=$'\x1b[0;45m'  #  5. Magenta
readonly __c_cyan=$'\x1b[0;36m';     readonly __c_b_cyan=$'\x1b[0;46m'     #  6. Cyan
readonly __c_white=$'\x1b[0;37m';    readonly __c_b_white=$'\x1b[0;47m'    #  7. White
readonly __c_grey=$'\x1b[1;30m';     readonly __c_b_grey=$'\x1b[1;40m'     #  8. Bright Black (Grey)
readonly __c_bred=$'\x1b[1;31m';     readonly __c_b_bred=$'\x1b[1;41m'     #  9. Bright Red
readonly __c_bgreen=$'\x1b[1;32m';   readonly __c_b_bgreen=$'\x1b[1;42m'   # 10. Bright Green
readonly __c_byellow=$'\x1b[1;33m';  readonly __c_b_byellow=$'\x1b[1;43m'  # 11. Bright Yellow
readonly __c_bblue=$'\x1b[1;34m';    readonly __c_b_bblue=$'\x1b[1;44m'    # 12. Bright Blue
readonly __c_bmagenta=$'\x1b[1;35m'; readonly __c_b_bmagenta=$'\x1b[1;45m' # 13. Bright Magenta
readonly __c_bcyan=$'\x1b[1;36m';    readonly __c_b_bcyan=$'\x1b[1;46m'    # 14. Bright Cyan
readonly __c_bwhite=$'\x1b[1;37m';   readonly __c_b_bwhite=$'\x1b[1;47m'   # 15. Bright White
readonly __c_default=$'\x1b[0;39m';  readonly __c_b_default=$'\x1b[0;49m'  # Default color

readonly __c_bld=$'\x1b[1m'     # Bold text
readonly __c_und=$'\x1b[4m'     # Underline text
readonly __c_inv=$'\x1b[7m'     # Inverse: swap background and foreground colors
readonly __c_reg=$'\x1b[22;24m' # Regular text only, keep colors
readonly __c_rst=$'\x1b[0m'     # Reset all attributes

readonly __c_error="${__c_red}"
readonly __c_warning="${__c_yellow}"
readonly __c_ok="${__c_green}"


################################################################################
# Print help message
#
# Usage: usage
#
# Outputs:
#   - Help message defined in the script code, prefixed with '#/'
################################################################################
function usage() {
  # __my_path is assigned in script that includes this library
  # shellcheck disable=SC2154
  printf "%b\n" "$(grep '^#/' "${__my_path}" | cut -c4-)" 1>&2
}


################################################################################
# Output current timestamp in ISO 8601 format (2020-02-11T08:56:00+00:00)
# to stdout
#
# Usage: now
#        echo "$(now)"
#
# Outputs:
#   - timestamp
################################################################################
function now() {
  printf '%(%Y-%m-%dT%H:%M:%S%z)T' -1
}


################################################################################
# Output timestamp and message to stdout
#
# Usage: echo "message" | print
#        print "message"
#
# Arguments:
#   - message to print on stdout (optional)
#
# Outputs:
#   - timestamp and message
################################################################################
function print() {
  if (($# == 0)) && [[ -p /dev/stdin ]]; then
    # No arguments and stdin is opened, so read message from stdin
    while read -r line; do
      print "${line}"
    done
  else
    # Message passed as an argument
    printf '%s %b\n' "$(now)" "$*"
  fi
}


################################################################################
# Print error message to stderr
#
# Usage: echo "message" | error
#        error "message"
#
# Arguments:
#   - message to print on stderr (optional)
#
# Outputs:
#   - message
################################################################################
function error() {
  if (($# == 0)) && [[ -p /dev/stdin ]]; then
    # No arguments and stdin is opened, so read message from stdin
    while read -r line; do
      error "${line}"
    done
  else
    # Message passed as an argument
    if [[ -z ${NO_COLOR-} || -n ${FORCE_COLOR-} ]]; then
      print "${__c_error}ERROR: $*${__c_rst}" 1>&2
    else
      print "ERROR: $*" 1>&2
    fi
  fi
}


################################################################################
# Print warning message to stderr
#
# Usage: echo "message" | warning
#        warning "message"
#
# Arguments:
#   - message to print on stderr (optional)
#
# Outputs:
#   - message
################################################################################
function warning() {
  if (($# == 0)) && [[ -p /dev/stdin ]]; then
    # No arguments and stdin is opened, so read message from stdin
    while read -r line; do
      warning "${line}"
    done
  else
    # Message passed as an argument
    if [[ -z ${NO_COLOR-} || -n ${FORCE_COLOR-} ]]; then
      print "${__c_warning}WARN: $*${__c_rst}" 1>&2
    else
      print "WARN: $*" 1>&2
    fi
  fi
}


################################################################################
# Print OK message to stdout
#
# Usage: echo "message" | ok
#        ok "message"
#
# Arguments:
#   - message to print on stdout (optional)
#
# Outputs:
#   - message
################################################################################
function ok() {
  if (($# == 0)) && [[ -p /dev/stdin ]]; then
    # No arguments and stdin is opened, so read message from stdin
    while read -r line; do
      ok "${line}"
    done
  else
    # Message passed as an argument
    if [[ -z ${NO_COLOR-} || -n ${FORCE_COLOR-} ]]; then
      print "${__c_ok}OK: $*${__c_rst}"
    else
      print "OK: $*"
    fi
  fi
}


################################################################################
# Print a bigger header to stdout
#
# Usage: echo "header" | header
#        header "header"
#
# Arguments:
#   - header to print on stdout (optional)
#
# Outputs:
#   - header
################################################################################
function header() {
  if (($# == 0)) && [[ -p /dev/stdin ]]; then
    # No arguments and stdin is opened, so read header from stdin
    while read -r line; do
      header "${line}"
    done
  else
    # Message passed as an argument
    print "##########"
    print "# $*"
    print "##########"
  fi
}


################################################################################
# Print an optional message and exit with either the given status or that of the
# most recent command
#
# Based on https://mywiki.wooledge.org/BashFAQ/101
#
# Usage: some_command || die [status code] [message]
#        die [status code] [message]
#
# Arguments:
#   - status code (optional)
#   - message to print on exit (optional)
#
# Outputs:
#   - message
################################################################################
function die() {
  # Get the exit code of the most recent command.
  local ret=$?

  if (( $# > 0 )) && [[ $1 != *[^0-9]* ]]; then
    # At least one argument and it is a number, use as an exit code
    ret="$1"
    shift
  fi

  if (( $# > 0 )); then
    # Still at least one argument, use all of them as a message
    local -r message="$*"
  fi

  if [[ -v message ]]; then
    if [[ $ret ]]; then
      error "${message}"
    else
      print "${message}"
    fi
  fi
  exit "${ret}"
}


################################################################################
# Check if this instance of bash version is at least X.Y
#
# Usage: require_bash_version 4 4 || die 2 "At least Bash 4.4 is required"
#
# Arguments:
#   - minor
#   - major
#
# Returns:
#   - 0 bash version is at least as required
#   - 1 bash version is older than required
################################################################################
function require_bash_version() {
  [[ ${BASH_VERSINFO[0]} -gt $1 || (${BASH_VERSINFO[0]} -eq $1 && ${BASH_VERSINFO[1]} -ge $2) ]]
  return
}


################################################################################
# Check if required command is available
#
# Usage: require_command || die 2 "Cannot find 'X'. Install 'xxx' package"
#        require_command || die 2
#
# Arguments:
#   - required command
#
# Returns:
#   - 0 required command is available
#   - 1 required command is not available
################################################################################
function require_command() {
  type -P "$1" > /dev/null
  return
}


################################################################################
# Check if script is being run by root user
#
# Usage: require_root || die 2 "This script must be run as root"
#        require_root && die 2 "This script must not be run as root"
#
# Returns:
#   - 0 being run as root
#   - 1 not being run as root
################################################################################
function require_root() {
  (( EUID == 0 ))
  return
}


################################################################################
# Check if script is piped
#
# Usage: is_piped
#
# Returns:
#   - 0 being piped
#   - 1 not being piped
################################################################################
function is_piped() {
  [[ ! -t 1 ]]
  return
}


# Disable colors if script is piped
if is_piped; then
  NO_COLOR=1
fi