@renault-digital/bash-base 2.4.0 → 2.5.0

package/src/reflection.sh

@@ -13,15 +13,50 @@
 #     string="args_valid_or_read myVar '^[0-9a-z]{3,3}$' \"SIA\""
 #     reflect_nth_arg 4 $string ==> "SIA"
 # @SEE_ALSO
-function reflect_nth_arg() {
-	local index string args
+reflect_nth_arg() {
+	local index string word position
 
-	string="$(echo "$@" | string_replace_regex '(\\|\||\{|>|<|&)' '\\\1')"
-	args=()
-	eval 'for word in '"${string}"'; do args+=("$word"); done'
+	if [[ -n "${ZSH_VERSION:-}" ]]; then
+		# zsh's lexer splits shell-quoted words without executing their contents.
+		# Keep this expansion in eval so Bash can still parse the source file.
+		string="$*"
+		local -a __bash_base_reflect_words
+		eval '__bash_base_reflect_words=( "${(@Q)${(z)string}}" )' || return 1
+		set -- "${__bash_base_reflect_words[@]}"
+	else
+		string="$(printf '%s\n' "$*" | string_replace_regex '(\\|\||\{|>|<|&)' '\\\1')"
 
-	index="${args[0]}"
-	echo "${args[$index]}"
+		# Parse the same shell-like argument string as the historical implementation,
+		# but use positional parameters instead of an indexed array so Bash/zsh array
+		# index bases cannot change the result.
+		eval "set -- ${string}"
+	fi
+	index="${1-}"
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# Bash legacy indexing addressed the entire parsed list, including
+		# the index argument at [0]; missing indexes printed a blank line.
+		# Keep that behavior, including Bash's native negative indexes.
+		local -a __bash_base_legacy_reflect_words
+		__bash_base_legacy_reflect_words=("$@")
+		echo "${__bash_base_legacy_reflect_words[$index]}"
+		return 0
+	fi
+	shift || true
+
+	if ! [[ "$index" =~ ^[0-9]+$ ]] || ((index < 1)); then
+		return 1
+	fi
+
+	position=1
+	for word in "$@"; do
+		if ((position == index)); then
+			printf '%s\n' "$word"
+			return 0
+		fi
+		position=$((position + 1))
+	done
+
+	return 1
 }
 
 # @NAME
@@ -34,9 +69,9 @@ function reflect_nth_arg() {
 #     reflect_get_function_definition confirm_to_continue
 # @SEE_ALSO
 #     reflect_function_names_of_file
-function reflect_get_function_definition() {
+reflect_get_function_definition() {
 	local functionName="$1"
-	declare -f "$functionName"
+	typeset -f "$functionName"
 }
 
 # @NAME
@@ -50,9 +85,14 @@ function reflect_get_function_definition() {
 #     reflect_function_names_of_file scripts/my_script.sh
 # @SEE_ALSO
 #     reflect_get_function_definition
-function reflect_function_names_of_file() {
+reflect_function_names_of_file() {
 	local shellScriptFile="$1"
-	grep -E '^[[:space:]]*(function)?[[:space:]]*[0-9A-Za-z_\-]+[[:space:]]*\(\)[[:space:]]*\{?' "${shellScriptFile}" | cut -d'(' -f1 | sed -e "s/function//"
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# Existing Bash callers may rely on the original output spelling.
+		grep -E '^[[:space:]]*(function)?[[:space:]]*[0-9A-Za-z_\-]+[[:space:]]*\(\)[[:space:]]*\{?' "$shellScriptFile" | cut -d'(' -f1 | sed -e 's/function//'
+		return
+	fi
+	grep -E '^[[:space:]]*(function[[:space:]]+)?[0-9A-Za-z_-]+[[:space:]]*\(\)[[:space:]]*\{?' "$shellScriptFile" | sed -E -e 's/^[[:space:]]*function[[:space:]]+//' -e 's/[[:space:]]*\(\).*//' -e 's/[[:space:]]+$//'
 }
 
 # @NAME
@@ -66,9 +106,13 @@ function reflect_function_names_of_file() {
 #     reflect_function_definitions_of_file scripts/my_script.sh
 # @SEE_ALSO
 #     reflect_get_function_definition
-function reflect_function_definitions_of_file() {
+reflect_function_definitions_of_file() {
 	local shellScriptFile="$1"
-	sed -E -n '/^[[:space:]]*(function)?[[:space:]]*[0-9A-Za-z_\-]+[[:space:]]*\(\)[[:space:]]*\{?/,/^[[:space:]]*}/p' "${shellScriptFile}"
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		sed -E -n '/^[[:space:]]*(function)?[[:space:]]*[0-9A-Za-z_\-]+[[:space:]]*\(\)[[:space:]]*\{?/,/^[[:space:]]*}/p' "$shellScriptFile"
+		return
+	fi
+	sed -E -n '/^[[:space:]]*(function[[:space:]]+)?[0-9A-Za-z_-]+[[:space:]]*\(\)[[:space:]]*\{?/,/^[[:space:]]*}/p' "$shellScriptFile"
 }
 
 # @NAME
@@ -82,9 +126,17 @@ function reflect_function_definitions_of_file() {
 #     reflect_search_function '^args_.*'
 # @SEE_ALSO
 #     reflect_search_variable
-function reflect_search_function() {
+reflect_search_function() {
 	local functionNamePattern="$1"
-	declare -f | grep -E '\s+\(\)\s+' | sed -E 's/[(){ ]//g' | grep -Ei "${functionNamePattern}"
+
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# Exact Bash legacy extraction/output (no new sorting or dedupe).
+		typeset -f | grep -E '\s+\(\)\s+' | sed -E 's/[(){ ]//g' | grep -Ei "$functionNamePattern"
+	elif [[ -n "${ZSH_VERSION:-}" ]]; then
+		# Hide zsh-only parameter-expansion flags inside eval so the file still
+		# parses in Bash.
+		eval 'printf "%s\\n" "${(k)functions[@]}"' | LC_ALL=C sort -u | grep -Ei "$functionNamePattern"
+	fi
 }
 
 # @NAME
@@ -98,7 +150,14 @@ function reflect_search_function() {
 #     reflect_search_variable '^COLOR'
 # @SEE_ALSO
 #     reflect_search_function
-function reflect_search_variable() {
+reflect_search_variable() {
 	local variableNamePattern="$1"
-	declare -p | grep -Eo '\s+\w+=' | sed -E 's/[= ]//g' | grep -Ei "${variableNamePattern}"
+
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# Enumerate Bash variables directly. Parsing typeset -p using \s/\w
+		# depends on grep extensions unavailable on some macOS versions.
+		compgen -A variable | grep -Ei "$variableNamePattern"
+	elif [[ -n "${ZSH_VERSION:-}" ]]; then
+		eval 'printf "%s\\n" "${(k)parameters[@]}"' | LC_ALL=C sort -u | grep -Ei "$variableNamePattern"
+	fi
 }

package/src/string.sh

@@ -13,7 +13,7 @@ source src/tool.sh
 #     string_trim < logfile
 #     echo " add " | string_trim
 # @SEE_ALSO
-function string_trim() {
+string_trim() {
 	local string="${1-$(cat)}"
 	echo "${string}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' #trim ' '
 }
@@ -29,7 +29,7 @@ function string_trim() {
 #     string_repeat 'abc' 5
 #     echo 5 | string_repeat 'abc'
 # @SEE_ALSO
-function string_repeat() {
+string_repeat() {
 	local string="$1"
 	local nbTimes=${2-$(cat)}
 	printf "${string}%.0s" $(seq 1 "$nbTimes")
@@ -46,7 +46,7 @@ function string_repeat() {
 #     string_length < logfile
 #     echo " add " | string_length
 # @SEE_ALSO
-function string_length() {
+string_length() {
 	local string index
 	string="${1-$(cat)}"
 
@@ -66,7 +66,7 @@ function string_length() {
 #     echo " add " | string_is_empty
 # @SEE_ALSO
 #     string_length
-function string_is_empty() {
+string_is_empty() {
 	local string="${1-$(cat)}"
 
 	[[ $(string_length "$string") -eq 0 ]]
@@ -82,7 +82,7 @@ function string_is_empty() {
 #     string_revert 'aBc'
 #     echo 'aBc' | string_revert
 # @SEE_ALSO
-function string_revert() {
+string_revert() {
 	local string="${1-$(cat)}"
 	echo "${string}" | rev
 }
@@ -98,9 +98,16 @@ function string_revert() {
 #     echo 'abc' | string_upper
 # @SEE_ALSO
 #     string_upper_first, string_lower
-function string_upper() {
+string_upper() {
 	local string=${1-$(cat)}
-	echo "${string^^}"
+	if [[ -n "${BASH_VERSION:-}" ]] && ((BASH_VERSINFO[0] >= 4)); then
+		# Bash's case expansion is locale-aware (unlike many tr versions).
+		# Keep the Bash 4+/5+ echo behavior verbatim. Construct the expression
+		# at runtime so Bash 3.2 can source this file without evaluating it.
+		eval 'echo "${string'"^^"'}"'
+		return
+	fi
+	printf '%s\n' "$string" | tr '[:lower:]' '[:upper:]'
 }
 
 # @NAME
@@ -114,9 +121,13 @@ function string_upper() {
 #     echo 'aBc' | string_lower
 # @SEE_ALSO
 #     string_upper, string_upper_first
-function string_lower() {
+string_lower() {
 	local string=${1-$(cat)}
-	echo "${string,,}"
+	if [[ -n "${BASH_VERSION:-}" ]] && ((BASH_VERSINFO[0] >= 4)); then
+		eval 'echo "${string'",,"'}"'
+		return
+	fi
+	printf '%s\n' "$string" | tr '[:upper:]' '[:lower:]'
 }
 
 # @NAME
@@ -130,10 +141,29 @@ function string_lower() {
 #     echo 'aBc' | string_upper_first
 # @SEE_ALSO
 #     string_lower, string_upper
-function string_upper_first() {
+string_upper_first() {
 	local string=${1-$(cat)}
-	local lower="${string,,}"
-	echo "${lower^}"
+	local lower first rest
+
+	if [[ -n "${BASH_VERSION:-}" ]] && ((BASH_VERSINFO[0] >= 4)); then
+		# Do not round-trip through command substitution: it strips the
+		# trailing newlines that the old Bash parameter expansion preserved.
+		eval 'lower="${string'",,"'}"'
+		eval 'echo "${lower'"^"'}"'
+		return
+	fi
+
+	lower="$(string_lower "$string")"
+	[[ -n "$lower" ]] || {
+		printf '\n'
+		return 0
+	}
+
+	# `${var^^}` / `${var,,}` / `${var^}` are Bash-specific.  Parameter
+	# prefix/suffix removal is shared by Bash and zsh.
+	rest="${lower#?}"
+	first="${lower%"$rest"}"
+	printf '%s%s\n' "$(string_upper "$first")" "$rest"
 }
 
 # @NAME
@@ -149,11 +179,37 @@ function string_upper_first() {
 #     string_sub 3 5 < temp_file.txt
 #     echo ' as fd ' | string_sub 2 4
 # @SEE_ALSO
-function string_sub() {
+string_sub() {
 	local startIndex=$1
 	local subStringLength=$2
 	local string="${3-$(cat)}"
-	echo "${string:$startIndex:$subStringLength}"
+	if [[ -n "${BASH_VERSION:-}" ]] && ((BASH_VERSINFO[0] >= 4)); then
+		# Keep Bash 4+/5+ substring and error behavior exactly as before.
+		# Bash 3.2 continues to use the portable negative-length fallback.
+		echo "${string:$startIndex:$subStringLength}"
+		return
+	fi
+	local totalLength=${#string}
+	local actualStart=$startIndex
+	local actualLength=$subStringLength
+
+	# Bash 3.2 cannot use a negative substring length.  Convert the
+	# documented negative start/end offsets to nonnegative bounds first.
+	if ((actualStart < 0)); then
+		actualStart=$((totalLength + actualStart))
+	fi
+	if ((actualLength < 0)); then
+		actualLength=$((totalLength + actualLength - actualStart))
+	fi
+	# Out-of-range starts produce an empty result (as in modern Bash).
+	if ((actualStart < 0 || actualStart > totalLength)); then
+		printf '\n'
+		return 0
+	fi
+	if ((actualLength < 0)); then
+		return 1
+	fi
+	printf '%s\n' "${string:$actualStart:$actualLength}"
 }
 
 # @NAME
@@ -167,7 +223,7 @@ function string_sub() {
 #     string_match 'name;+' "name;name;"
 # @SEE_ALSO
 #     string_index_first
-function string_match() {
+string_match() {
 	local value regExp
 	regExp=${1}
 	string="${2-$(cat)}"
@@ -185,10 +241,14 @@ function string_match() {
 #     escape_sed 'a$'
 # @SEE_ALSO
 #     string_replace
-function escape_sed() {
-	echo "${1}" | sed -e 's/\//\\\//g' -e 's/\&/\\\&/g' -e 's/\./\\\./g' -e 's/\^/\\\^/g' -e 's/\[/\\\[/g' -e 's/\$/\\\$/g'
+escape_sed() {
+	if [[ -n "${ZSH_VERSION:-}" ]]; then
+		printf '%s\n' "$1"
+	else
+		# Preserve historical Bash echo semantics.
+		echo "$1"
+	fi | sed -e 's/\//\\\//g' -e 's/\&/\\\&/g' -e 's/\./\\\./g' -e 's/\^/\\\^/g' -e 's/\[/\\\[/g' -e 's/\$/\\\$/g'
 }
-export -f escape_sed >/dev/null
 
 # @NAME
 #     string_replace -- replace literally the token string to new string, not support regular expression
@@ -204,11 +264,16 @@ export -f escape_sed >/dev/null
 #     string_replace '\*' 'b' 'a*a'  ==> 'aba'
 # @SEE_ALSO
 #     escape_sed, string_replace_regex
-function string_replace() {
+string_replace() {
 	local tokenString newString
 	tokenString=$(escape_sed "${1}")
 	newString=$(escape_sed "${2}")
-	echo "${3-$(cat)}" | sed -e "s/${tokenString}/${newString}/g"
+	if [[ -n "${ZSH_VERSION:-}" ]]; then
+		printf '%s\n' "${3-$(cat)}" | sed -e "s/${tokenString}/${newString}/g"
+	else
+		# Preserve historical Bash echo semantics.
+		echo "${3-$(cat)}" | sed -e "s/${tokenString}/${newString}/g"
+	fi
 }
 
 # @NAME
@@ -225,7 +290,7 @@ function string_replace() {
 #     string_replace_regex '*' 'b' 'a*a'  ==> 'aba'
 # @SEE_ALSO
 #     string_replace
-function string_replace_regex() {
+string_replace_regex() {
 	echo "${3-$(cat)}" | sed -E -e "s/$1/$2/g"
 }
 
@@ -242,11 +307,11 @@ function string_replace_regex() {
 #     echo " add " | string_index_first "token"
 # @SEE_ALSO
 #     string_before_first, string_after_first
-function string_index_first() {
+string_index_first() {
 	local tokenString=$1
 	local string="${2-$(cat)}"
 	local prefix="${string%%${tokenString}*}"
-	[ "${string}" == "${prefix}" ] && echo -1 || echo ${#prefix}
+	[[ "${string}" == "${prefix}" ]] && printf '%s\n' -1 || printf '%s\n' "${#prefix}"
 }
 
 # @NAME
@@ -262,7 +327,7 @@ function string_index_first() {
 #     echo " add " | string_before_first "dd"
 # @SEE_ALSO
 #     string_index_first, string_after_first
-function string_before_first() {
+string_before_first() {
 	local tokenString=$1
 	local string="${2-$(cat)}"
 	echo "${string%%${tokenString}*}" # Remove the first - and everything following it
@@ -281,7 +346,7 @@ function string_before_first() {
 #     echo " add " | string_after_first "dd"
 # @SEE_ALSO
 #     string_index_first, string_before_first
-function string_after_first() {
+string_after_first() {
 	local tokenString=$1
 	local string="${2-$(cat)}"
 	echo "${string#*${tokenString}}" # Remove everything up to and including first -
@@ -303,7 +368,7 @@ function string_after_first() {
 #     string_split_to_array $'\n' branchesToSelectArray "${branchesToSelectString}"
 # @SEE_ALSO
 #     array_join, array_describe, array_from_describe, string_pick_to_array
-function string_split_to_array() {
+string_split_to_array() {
 	local tokenString="$1"
 	local newArrayVarName="$2"
 	local string="${3-$(cat)}"
@@ -341,7 +406,7 @@ function string_split_to_array() {
 #     string_pick_to_array '{age:' '}' newArray "$str"
 # @SEE_ALSO
 #     array_join, array_describe, array_from_describe, string_split_to_array
-function string_pick_to_array() {
+string_pick_to_array() {
 	local startTokenString="$1"
 	local endTokenString="$2"
 	local newArrayVarName="$3"

package/src/tool.sh

@@ -15,7 +15,7 @@ source src/out.sh
 #     stop_if_failed "ERROR: can't delete the directory '${destProjectPath}' !"
 # @SEE_ALSO
 #     confirm_to_continue
-function stop_if_failed() {
+stop_if_failed() {
 	if [[ $? -ne 0 ]]; then
 		print_error "$*"
 		exit 1
@@ -34,19 +34,25 @@ function stop_if_failed() {
 #     confirm_to_continue a b
 # @SEE_ALSO
 #     print_args, stop_if_failed
-function confirm_to_continue() {
+confirm_to_continue() {
 	local response
 	print_args "$@"
-	if ! [ "${modeQuiet}" == true ]; then
-		read -r -p "Continue ? [y/N] " response
 
-		case "${response}" in
-		[yY][eE][sS] | [yY])
-			echo -e "Continue..."
-			sleep 1s
+	if [[ "${modeQuiet:-false}" != true ]]; then
+		# Bash `read -p` and zsh `read "name?prompt"` are shell-specific.
+		# Match Bash read -p behavior by showing the prompt only for a TTY.
+		if [[ -t 0 ]]; then
+			printf '%s' 'Continue ? [y/N] ' >&2
+		fi
+		read -r response || response=""
+
+		case "$response" in
+		[yY] | [yY][eE][sS])
+			printf '%s\n' 'Continue...'
+			sleep 1
 			;;
 		*)
-			echo -e "Exiting..."
+			printf '%s\n' 'Exiting...'
 			exit 1
 			;;
 		esac
@@ -64,8 +70,8 @@ function confirm_to_continue() {
 # @EXAMPLES
 #     wait_for 'test -f /tmp/output.txt' 'file existed' 3
 # @SEE_ALSO
-#     confirm_to_continue, stop_if_failed, is_http_ok
-function wait_for() {
+#     confirm_to_continue, stop_if_failed
+wait_for() {
 	local predicate="${1}"
 	local subject="${2-${predicate}}"
 	local interval=${3-3}
@@ -91,6 +97,16 @@ function wait_for() {
 #     record2
 #     EOF
 # @SEE_ALSO
-function declare_heredoc() {
-	eval "$1='$(cat)'"
+declare_heredoc() {
+	local _bash_base_heredoc_target="${1-}"
+	local _bash_base_heredoc_content
+
+	# Only identifier names may appear as the left-hand side of an eval.
+	case "$_bash_base_heredoc_target" in
+	'' | [!a-zA-Z_]* | *[!a-zA-Z0-9_]*) return 2 ;;
+	esac
+
+	_bash_base_heredoc_content="$(cat)"
+	# Expand the content as a variable value, never parse it as shell code.
+	eval "${_bash_base_heredoc_target}=\"\$_bash_base_heredoc_content\""
 }