path: root/functions.sh.in

# Copyright 1999-2023 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
# shellcheck shell=sh disable=3043

# This file contains a series of function declarations followed by some
# initialization code. Functions intended for internal use shall be prefixed
# with an <underscore> and shall not be considered as being a part of the public
# API. With the exception of those declared by the local builtin, all variables
# intended for internal use shall be prefixed with "genfun_" to indicate so,
# and to reduce the probability of name space conflicts.

#
#    Called by ebegin, eerrorn, einfon, and ewarnn.
#
_eprint() {
	local color msg
	color=$1
	shift

	# Check whether STDOUT is a terminal, and how capable it is.
	_update_tty_level <&1

	if [ "${genfun_tty}" -eq 2 ]; then
		# If the cursor is not situated on column 1, print a LF
		# character. The assumption here is that the last call may have
		# been via ebegin, or any of the other printing functions that
		# pass a message without a trailing LF.
		if [ "${genfun_x}" -ne 1 ]; then
			printf '\n'
		fi
	elif [ "${genfun_is_pending_lf}" -eq 1 ]; then
		# We are about to print to a dumb terminal or something other
		# than a terminal. Print a LF character because the last printed
		# message did not end with one. This technique is not ideal.
		# For one thing, it can be thwarted by having called a printing
		# function from a subshell or a shell launched by a subprocess,
		# because the change to the flag variable would be lost. For
		# another, it's possible for the user of the library to be
		# directing STDOUT/STDERR to different places between calls.
		# Such weaknesses cannot be addressed without some form of IPC.
		printf '\n'
	fi

	msg=$*
	if [ "${genfun_tty}" -lt 2 ]; then
		if [ "${genfun_tty}" -eq 1 ]; then
			# Print but do not attempt to save the cursor position.
			printf ' %s*%s %s%s' "${color}" "${NORMAL}" "${genfun_indent}" "${msg}"
		else
			printf ' * %s%s' "${genfun_indent}" "${msg}"
		fi
		if _ends_with_newline "${msg}"; then
			genfun_is_pending_lf=0
		else
			# Record the fact that a LF character is pending.
			genfun_is_pending_lf=1
		fi
	elif ! _ends_with_newline "${msg}"; then
		# Print the message before saving the cursor position with the
		# DECSC sequence. This is a private mode sequence that is not
		# defined by ECMA-48. However, it was introduced by DEC for the
		# VT100 and can be considered as a de-facto standard.
		printf ' %s*%s %s%s\0337' "${color}" "${NORMAL}" "${genfun_indent}" "${msg}"
	else
		# Strip all trailing LF characters before printing the message.
		while true; do
			msg=${msg%"${genfun_newline}"}
			if ! _ends_with_newline "${msg}"; then
				break
			fi
		done
		printf ' %s*%s %s%s' "${color}" "${NORMAL}" "${genfun_indent}" "${msg}"

		# Determine the current position of the cursor
		_update_cursor_coords <&1

		if [ "${genfun_y}" -ne "${genfun_rows}" ]; then
			# Have the terminal save the position of the cursor
			# with DECSC before printing a LF character to advance
			# to the next line.
			printf '\0337\n'
		else
			# The cursor is situated on the last row of the
			# terminal, meaning that vertical scrolling will occur.
			# Move the cursor up by one row with CUU (ECMA-48 CSI)
			# before having the terminal save the position of the
			# cursor with DECSC. Finally, print two LF characters to
			# advance to the next line.
			printf '\033[1A\0337\n\n'
		fi
	fi
}

#
#    hard set the indent used for e-commands.
#    num defaults to 0
#
_esetdent()
{
	if ! is_int "$1" || [ "$1" -lt 0 ]; then
		set -- 0
	fi
	genfun_indent=$(printf "%${1}s" '')
}

#
#    increase the indent used for e-commands.
#
eindent()
{
	if ! is_int "$1" || [ "$1" -le 0 ]; then
		set -- 2
	fi
	_esetdent "$(( ${#genfun_indent} + $1 ))"
}

#
#    decrease the indent used for e-commands.
#
eoutdent()
{
	if ! is_int "$1" || [ "$1" -le 0 ]; then
		set -- 2
	fi
	_esetdent "$(( ${#genfun_indent} - $1 ))"
}

#
# this function was lifted from OpenRC. It returns 0 if the argument  or
# the value of the argument is "yes", "true", "on", or "1" or 1
# otherwise.
#
yesno()
{
	for _ in 1 2; do
		case $1 in
			[Nn][Oo]|[Ff][Aa][Ll][Ss][Ee]|[Oo][Ff][Ff]|0|'')
				return 1
				;;
			[Yy][Ee][Ss]|[Tt][Rr][Uu][Ee]|[Oo][Nn]|1)
				return 0
		esac
		if [ "$_" -ne 1 ] || ! is_identifier "$1"; then
			! break
		else
			# The value appears to be a legal variable name. Treat
			# it as a name reference and try again, once only.
			eval "set -- \"\$$1\""
		fi
	done || vewarn "Invalid argument given to yesno (expected a boolean-like or a legal name)"
	return 1
}

#
#    use the system logger to log a message
#
esyslog()
{
	local pri tag msg

	if [ "$#" -lt 2 ]; then
		ewarn "Too few arguments for esyslog (got $#, expected at least 2)"
		return 1
	elif [ -n "${EINFO_LOG}" ] && hash logger 2>/dev/null; then
		pri=$1
		tag=$2
		shift 2
		msg=$*
		if _is_visible "${msg}"; then
			# This is not strictly portable because POSIX defines
			# no options whatsoever for logger(1).
			logger -p "${pri}" -t "${tag}" -- "${msg}"
		fi
	fi
}

#
#    show an informative message (without a newline)
#
einfon()
{
	if ! yesno "${EINFO_QUIET}"; then
		_eprint "${GOOD}" "$@"
	fi
}

#
#    show an informative message (with a newline)
#
einfo()
{
	einfon "${*}${genfun_newline}"
}

#
#    show a warning message (without a newline) and log it
#
ewarnn()
{
	if ! yesno "${EINFO_QUIET}"; then
		_eprint "${WARN}" "$@" >&2
		esyslog "daemon.warning" "${0##*/}" "$@"
	fi
}

#
#    show a warning message (with a newline) and log it
#
ewarn()
{
	ewarnn "${*}${genfun_newline}"
}

#
#    show an error message (without a newline) and log it
#
eerrorn()
{
	if ! yesno "${EERROR_QUIET}"; then
		_eprint "${BAD}" "$@" >&2
		esyslog "daemon.err" "${0##*/}" "$@"
	fi
	return 1
}

#
#    show an error message (with a newline) and log it
#
eerror()
{
	eerrorn "${*}${genfun_newline}"
}

#
#    show a message indicating the start of a process
#
ebegin()
{
	local msg

	if ! yesno "${EINFO_QUIET}"; then
		msg=$*
		while _ends_with_newline "${msg}"; do
			msg=${msg%"${genfun_newline}"}
		done
		_eprint "${GOOD}" "${msg} ...${genfun_newline}"
	fi
}

#
#    indicate the completion of process, called from eend/ewend
#    if error, show errstr via efunc
#
_eend()
{
	local efunc indent msg offset retval

	efunc=$1
	shift
	if [ "$#" -eq 0 ]; then
		retval=0
	elif ! is_int "$1" || [ "$1" -lt 0 ]; then
		ewarn "Invalid argument given to ${GENFUN_CALLER} (the exit status code must be an integer >= 0)"
		retval=0
		msg=
	else
		retval=$1
		shift
		msg=$*
	fi

	# Stash the last known terminal dimensions, if any.
	set -- "${genfun_rows}" "${genfun_cols}"

	# Check whether STDOUT is a terminal, and how capable it is.
	_update_tty_level <&1

	if [ "${retval}" -ne 0 ]; then
		# If a message was given, print it with the specified function.
		if _is_visible "${msg}"; then
			"${efunc}" "${msg}"
		fi
		# Generate an indicator for ebegin's unsuccessful conclusion.
		if [ "${genfun_tty}" -eq 0 ]; then
			msg="[ !! ]"
		else
			msg="${BRACKET}[ ${BAD}!!${BRACKET} ]${NORMAL}"
		fi
	elif yesno "${EINFO_QUIET}"; then
		return "${retval}"
	else
		# Generate an indicator for ebegin's successful conclusion.
		if [ "${genfun_tty}" -eq 0 ]; then
			msg="[ ok ]"
		else
			msg="${BRACKET}[ ${GOOD}ok${BRACKET} ]${NORMAL}"
		fi
	fi

	if [ "${genfun_tty}" -lt 2 ]; then
		printf ' %s\n' "${msg}"
		genfun_is_pending_lf=0
	else
		# Provided that the terminal has not since been resized, it may
		# be possible to write the indicator on the same row as the
		# last printed message, even if it were LF-terminated.
		if [ "${genfun_rows}" -eq "$1" ] && [ "${genfun_cols}" -eq "$2" ]; then
			# Stash the current position of the cursor.
			set -- "${genfun_y}" "${genfun_x}"

			# Using the DECRC sequence, restore the cursor position
			# to wherever it was just after the last message was
			# printed, but before the trailing LF character, if any.
			# This is a private mode sequence, and thus not defined
			# by ECMA-48. However, it was introduced by DEC for the
			# VT100 and can be considered as a de-facto standard.
			printf '\0338'

			# Determine the position of the cursor again.
			_update_cursor_coords <&1

			# Check whether the act of restoring the cursor position
			# moved it to a different row, excepting the immediately
			# preceding row. If it did, assume that scrolling has
			# occurred since printing the last message and move the
			# cursor back to where it was with CUP (ECMA-48 CSI).
			offset=$(( $1 - genfun_y ))
			if [ "${offset}" -lt 0 ] || [ "${offset}" -gt 1 ]; then
				printf '\033[%d;%dH' "$1" "$2"
				genfun_y=$1
				genfun_x=$2
			fi
		fi

		# Calculate the column at which the indicator may be printed.
		indent=$(( genfun_cols - genfun_x - 6 ))

		# Determine whether the cursor needs to be repositioned.
		if [ "${indent}" -gt 0 ]; then
			# Use CHA (ECMA-48 CSI) to move the cursor to the right.
			printf '\033[%dG' "$(( genfun_x + indent ))"
		elif [ "${indent}" -lt 0 ]; then
			# The indent is negative, meaning that there is not
			# enough room. Arrange for the indicator to be printed
			# on the next line instead.
			printf '\n\033[%dG' "$(( genfun_cols - 6 ))"
		fi

		# Finally, print the indicator.
		printf ' %s\n' "${msg}"
	fi

	return "${retval}"
}

#
#    indicate the completion of process
#    if error, show errstr via eerror
#
eend()
{
	GENFUN_CALLER=${GENFUN_CALLER:-eend} _eend eerror "$@"
}

#
#    indicate the completion of process
#    if error, show errstr via ewarn
#
ewend()
{
	GENFUN_CALLER=${GENFUN_CALLER:-ewend} _eend ewarn "$@"
}

# v-e-commands honor EINFO_VERBOSE which defaults to no.
veinfo()
{
	if yesno "${EINFO_VERBOSE}"; then
		einfo "$@"
	fi
}

veinfon()
{
	if yesno "${EINFO_VERBOSE}"; then
		einfon "$@"
	fi
}

vewarn()
{
	if yesno "${EINFO_VERBOSE}"; then
		ewarn "$@"
	fi
}

veerror()
{
	if yesno "${EINFO_VERBOSE}"; then
		eerror "$@"
	fi
}

vebegin()
{
	if yesno "${EINFO_VERBOSE}"; then
		ebegin "$@"
	fi
}

veend()
{
	if yesno "${EINFO_VERBOSE}"; then
		GENFUN_CALLER=veend eend "$@"
	elif [ "$#" -gt 0 ] && { ! is_int "$1" || [ "$1" -lt 0 ]; }; then
		ewarn "Invalid argument given to veend (the exit status code must be an integer >= 0)"
	else
		return "$1"
	fi
}

vewend()
{
	if yesno "${EINFO_VERBOSE}"; then
		GENFUN_CALLER=vewend ewend "$@"
	elif [ "$#" -gt 0 ] && { ! is_int "$1" || [ "$1" -lt 0 ]; }; then
		ewarn "Invalid argument given to vewend (the exit status code must be an integer >= 0)"
	else
		return "$1"
	fi
}

veindent()
{
	if yesno "${EINFO_VERBOSE}"; then
		eindent "$@"
	fi
}

veoutdent()
{
	if yesno "${EINFO_VERBOSE}"; then
		eoutdent "$@"
	fi
}

#
#   return 0 if gentoo=param was passed to the kernel
#
#   EXAMPLE:  if get_bootparam "nodevfs" ; then ....
#
get_bootparam()
(
	# Gentoo cmdline parameters are comma-delimited, so a search
	# string containing a comma must not be allowed to match.
	# Similarly, the empty string must not be allowed to match.
	case $1 in ''|*,*) return 1 ;; esac

	# Reset the value of IFS because there is no telling what it may be.
	IFS=$(printf ' \n\t')

	if [ "${TEST_GENFUNCS}" = 1 ]; then
		read -r cmdline
	else
		read -r cmdline < /proc/cmdline
	fi || return

	# Disable pathname expansion. The definition of this function
	# is a compound command that incurs a subshell. Therefore, the
	# prior state of the option does not need to be recalled.
	set -f
	for opt in ${cmdline}; do
		gentoo_opt=${opt#gentoo=}
		if [ "${opt}" != "${gentoo_opt}" ]; then
			case ,${gentoo_opt}, in
				*,"$1",*) return 0
			esac
		fi
	done
	return 1
)

#
#   return 0 if any of the files/dirs are newer than
#   the reference file
#
#   EXAMPLE: if is_older_than a.out *.o ; then ...
is_older_than()
{
	local ref has_gfind

	if [ "$#" -lt 2 ]; then
		ewarn "Too few arguments for is_older_than (got $#, expected at least 2)"
		return 1
	elif [ -e "$1" ]; then
		ref=$1
	else
		ref=
	fi
	shift

	# Consult the hash table in the present shell, prior to forking.
	hash gfind 2>/dev/null; has_gfind=$(( $? == 0 ))

	for path; do
		if [ -e "${path}" ]; then
			printf '%s\0' "${path}"
		fi
	done |
	{
		set -- -L -files0-from - ${ref:+-newermm} ${ref:+"${ref}"} -printf '\n' -quit
		if [ "${has_gfind}" -eq 1 ]; then
			gfind "$@"
		else
			find "$@"
		fi
	} |
	read -r _
}

#
#   Determine whether the first operand is in the form of an integer. A leading
#   <hypen-minus> shall be permitted. Thereafter, leading zeroes shall not be
#   permitted because the string might later be considered to be octal in an
#   arithmetic context, causing the shell to exit if the number be invalid.
#
is_int() {
	set -- "${1#-}"
	case $1 in
		''|*[!0123456789]*)
			false
			;;
		0)
			true
			;;
		*)
			test "$1" = "${1#0}"
	esac
}

#
#   A safe wrapper for the cd builtin. To run cd "$dir" is problematic because:
#
#   1) it may consider its operand as an option
#   2) it will search CDPATH for an operand not beginning with ./, ../ or /
#   3) it will switch to OLDPWD if the operand is -
#   4) cdable_vars causes bash to treat the operand as a potential variable name
#
chdir() {
	if [ "$BASH" ]; then
		# shellcheck disable=3044
		shopt -u cdable_vars
	fi
	if [ "$1" = - ]; then
		set -- ./-
	fi
	# shellcheck disable=1007,2164
	CDPATH= cd -- "$@"
}

#
#   Determine whether the first operand contains any visible characters.
#
_is_visible() {
	! case $1 in *[[:graph:]]*) false ;; esac
}

#
#   Determine whether the first operand is a valid identifier (variable name).
#
is_identifier()
(
	LC_ALL=C
	case $1 in
		''|_|[[:digit:]]*|*[!_[:alnum:]]*) false
	esac
)

_has_dumb_terminal() {
	! case ${TERM} in *dumb*) false ;; esac
}

_has_monochrome_terminal() {
	local colors

	# The tput(1) invocation is not portable, though ncurses suffices. In
	# this day and age, it is exceedingly unlikely that it will be needed.
	if _has_dumb_terminal; then
		true
	elif colors=$(tput colors 2>/dev/null) && is_int "${colors}"; then
		test "${colors}" -eq -1
	else
		false
	fi
}

_ends_with_newline() {
	test "${genfun_newline}" \
	&& ! case $1 in *"${genfun_newline}") false ;; esac
}

_update_tty_level() {
	# Grade the capability of the terminal attached to STDIN (if any) on a
	# scale of 0 to 2, assigning the resulting value to genfun_tty. If no
	# terminal is detected, the value shall be 0. If a dumb terminal is
	# detected, the value shall be 1. If a smart terminal is detected, the
	# value shall be 2.
	#
	# In the case that a smart terminal is detected, its dimensions shall
	# be assigned to genfun_cols and genfun_rows, and the position of the
	# cursor shall be assigned to genfun_x and genfun_y. Further, it may
	# reasonably be assumed that the ECMA-48 CSI and DECSC/DECRC escape
	# sequences are supported.
	if [ ! -t 0 ]; then
		genfun_tty=0
	elif _has_dumb_terminal || ! _update_winsize || ! _update_cursor_coords; then
		genfun_tty=1
	else
		genfun_tty=2
	fi
}

_update_winsize() {
	# The following use of stty(1) is portable as of POSIX Issue 8. It would
	# be beneficial to leverage the checkwinsize option in bash but the
	# implementation is buggy. Given that Chet has agreed to investigate,
	# it may eventually become possible to support it.
	# shellcheck disable=2046
	set -- $(stty size 2>/dev/null)
	if [ "$#" -eq 2 ] && is_int "$1" && is_int "$2"; then
		genfun_rows=$1
		genfun_cols=$2
	else
		genfun_rows=
		genfun_cols=
		false
	fi
}

_update_cursor_coords() {
	# shellcheck disable=2046
	set -- $(_ecma48_cpr)
	if [ "$#" -eq 2 ] && is_int "$1" && is_int "$2"; then
		genfun_y=$1
		genfun_x=$2
	else
		genfun_y=
		genfun_x=
		false
	fi
}

_ecma48_cpr() {
	@GENTOO_LIBEXEC_DIR@/ecma48-cpr
}

# This is the main script, please add all functions above this point!
# shellcheck disable=2034
RC_GOT_FUNCTIONS="yes"

# Dont output to stdout?
EINFO_QUIET="${EINFO_QUIET:-no}"
EINFO_VERBOSE="${EINFO_VERBOSE:-no}"

# Set the initial value for e-message indentation.
genfun_indent=

# Assign the LF ('\n') character for later expansion. POSIX Issue 8 permits
# $'\n' but it may take years for it to be commonly implemented.
genfun_newline='
'

# Whether the last printed message is pending a concluding LF character.
genfun_is_pending_lf=0

# Should we use color?
if [ -n "${NO_COLOR}" ]; then
	# See https://no-color.org/.
	RC_NOCOLOR="yes"
else
	RC_NOCOLOR="${RC_NOCOLOR:-no}"
	for _ in "$@"; do
		case $_ in
			--nocolor|--nocolour|-C)
				RC_NOCOLOR="yes"
				break
		esac
	done
fi

if _has_monochrome_terminal || yesno "${RC_NOCOLOR}"; then
	unset -v BAD BRACKET GOOD HILITE NORMAL WARN
else
	# Define some ECMA-48 SGR sequences for color support. These variables
	# are public, in so far as users of the library may be expanding them.
	# Conveniently, these sequences are documented by console_codes(4).
	BAD=$(printf '\033[31;01m')
	BRACKET=$(printf '\033[34;01m')
	GOOD=$(printf '\033[32;01m')
	# shellcheck disable=2034
	HILITE=$(printf '\033[36;01m')
	NORMAL=$(printf '\033[0m')
	WARN=$(printf '\033[33;01m')
fi