@renault-digital/bash-base 2.4.1 → 2.5.0

package/src/argument.sh

@@ -2,7 +2,16 @@
 
 source src/constant.sh
 
-THIS_SCRIPT_NAME="$(basename "$0")" # the main script name
+if [[ -n "${ZSH_VERSION:-}" ]]; then
+	# zsh may temporarily replace $0 with the sourced filename when
+	# FUNCTION_ARGZERO is enabled. ZSH_ARGZERO always keeps the invocation name.
+	_bash_base_argzero="${ZSH_ARGZERO:-$0}"
+else
+	_bash_base_argzero="$0"
+fi
+THIS_SCRIPT_PATH="$_bash_base_argzero"               # script source path for args_valid_* lookup
+THIS_SCRIPT_NAME="$(basename "$_bash_base_argzero")" # the main script name
+unset _bash_base_argzero
 
 SHORT_DESC="${THIS_SCRIPT_NAME%%.*}"
 SHORT_DESC="${SHORT_DESC/[\-_]/ }" # redefine it to show your script short description in the 'NAME' field of generated -h response
@@ -17,9 +26,14 @@ USAGE=''                           # redefine it in your script only if the gene
 # @EXAMPLES
 #     args_parse $# "$@" newVar1 newVar2 newVar3
 # @SEE_ALSO
-function args_parse() {
-	local nbArgValues nbPositionalVarNames option showUsage OPTARG OPTIND nbPositionalArgValues positionalArgValues positionalVarNames
-	local element validCommand description defaultUsage strPositionalVarNames strPositionalValuesExamples
+args_parse() {
+	local nbArgValues nbPositionalVarNames option OPTARG OPTIND nbPositionalArgValues
+	local showUsage=false
+	local element validCommand description defaultUsage
+	local strPositionalVarNames="" strPositionalValuesExamples=""
+	local -a positionalArgValues positionalVarNames
+	# Bash legacy contract: prompt, possibleValues, i, descriptions and
+	# onlyPositionalVarNames were caller-visible, not function-local.
 
 	nbArgValues=$1
 	shift 1
@@ -42,79 +56,103 @@ function args_parse() {
 	shift $((OPTIND - 1))
 
 	nbPositionalArgValues=$((nbArgValues - OPTIND + 1))
-	positionalArgValues=("${@:1:nbPositionalArgValues}")
-	positionalVarNames=("${@:nbPositionalArgValues+1:nbPositionalVarNames}")
+	positionalArgValues=()
+	# Split positional values from destination names without a new local
+	# counter; the historical Bash `i` global is handled below.
+	while (($# > nbPositionalVarNames)); do
+		positionalArgValues+=("$1")
+		shift
+	done
+	positionalVarNames=("$@")
 
 	onlyPositionalVarNames=()
 	descriptions=''
-	if ((nbPositionalVarNames > 0)); then
-		for i in $(seq 0 $((nbPositionalVarNames - 1))); do
-			element=${positionalVarNames[i]}
 
+	# Pair values with variable names without relying on Bash's 0-based array
+	# indexes (zsh uses a different default array index base).
+	set -- "${positionalArgValues[@]}"
+	for element in "${positionalVarNames[@]}"; do
+		# Do not introduce a local value variable: callers may legally name
+		# their destination positionalValue (or prompt).  Save it only in $1.
+
+		# zsh FUNCTION_ARGZERO may change $0 to the current function name.
+		# Only scan a caller script when there is an actual script file.
+		validCommand=''
+		if [[ -f "${THIS_SCRIPT_PATH:-}" ]]; then
 			validCommand="$(
-				grep -E "^\s*args_valid.*\s+${element}\s+" "$0" | head -1 |
+				grep -E "^[[:space:]]*args_valid.*[[:space:]]+${element}[[:space:]]+" "$THIS_SCRIPT_PATH" | head -1 |
 					awk -F "'" -v OFS="'" '{
-                for (i=2; i<=NF; i+=2) {
-                    gsub(/ /, "_SPACE_", $i);
-                    gsub(/\$/, "_DOLLAR_", $i);
-                    gsub(/\(/, "_PARENTHESES_LEFT_", $i);
-                    gsub(/\)/, "_PARENTHESES_RIGHT_", $i);
-                }
-                print
-            }' |
+                    for (i=2; i<=NF; i+=2) {
+                        gsub(/ /, "_SPACE_", $i);
+                        gsub(/\$/, "_DOLLAR_", $i);
+                        gsub(/\(/, "_PARENTHESES_LEFT_", $i);
+                        gsub(/\)/, "_PARENTHESES_RIGHT_", $i);
+                    }
+                    print
+                }' |
 					sed -e "s/\'//g"
 			)"
+		fi
 
-			if [[ -z ${validCommand} ]]; then
-				eval "${positionalVarNames[i]}='${positionalArgValues[i]}'"
+		if [[ -z $validCommand ]]; then
+			eval "${element}=\"\${1-}\""
+			onlyPositionalVarNames+=("${element}")
+			description="a valid value for ${element}"
+		else
+			if [[ "$validCommand" == *args_valid_or_select_pipe* ]]; then
+				eval "${element}=\"\${1-}\""
+				onlyPositionalVarNames+=("${element}")
+				prompt="$(reflect_nth_arg 4 "$validCommand")"
+				possibleValues=", possible values: $(reflect_nth_arg 3 "$validCommand")"
+			elif [[ "$validCommand" == *args_valid_or_select_args* ]]; then
+				eval "${element}=\"\${1-}\""
+				onlyPositionalVarNames+=("${element}")
+				prompt="$(reflect_nth_arg 3 "$validCommand")"
+				possibleValues=", you can select one using wizard if you do not know which value is valid"
+			elif [[ "$validCommand" == *args_valid_or_select* ]]; then
+				eval "${element}=\"\${1-}\""
 				onlyPositionalVarNames+=("${element}")
-				description="a valid value for ${element}"
-			else
-				if [[ "${validCommand}" =~ 'args_valid_or_select_pipe' ]]; then
-					eval "${positionalVarNames[i]}='${positionalArgValues[i]}'"
-					onlyPositionalVarNames+=("${element}")
-					prompt="$(reflect_nth_arg 4 "${validCommand}")"
-					possibleValues=", possible values: $(reflect_nth_arg 3 "$validCommand")"
-				elif [[ "${validCommand}" =~ 'args_valid_or_select_args' ]]; then
-					eval "${positionalVarNames[i]}='${positionalArgValues[i]}'"
-					onlyPositionalVarNames+=("${element}")
-					prompt="$(reflect_nth_arg 3 "${validCommand}")"
-					possibleValues=", you can select one using wizard if you do not know which value is valid"
-				elif [[ "${validCommand}" =~ 'args_valid_or_select' ]]; then
-					eval "${positionalVarNames[i]}='${positionalArgValues[i]}'"
-					onlyPositionalVarNames+=("${element}")
-					prompt="$(reflect_nth_arg 4 "${validCommand}")"
-					possibleValues=", you can select one using wizard if you do not know which value is valid"
-				elif [[ "${validCommand}" =~ args_valid_or_read ]]; then
-					eval "${positionalVarNames[i]}='${positionalArgValues[i]}'"
-					onlyPositionalVarNames+=("${element}")
-					prompt="$(reflect_nth_arg 4 "${validCommand}")"
-					if [[ -n $(reflect_nth_arg 5 "${validCommand}") ]]; then
-						prompt="${prompt}, proposed value: $(reflect_nth_arg 5 "${validCommand}")"
-					fi
-					possibleValues=""
-				elif [[ "${validCommand}" =~ args_valid_or_default ]]; then
-					prompt="optional, $(reflect_nth_arg 4 "${validCommand}"). should be set like '${element}=value' before ${THIS_SCRIPT_NAME} or export to OS environment"
-					if [[ -n $(reflect_nth_arg 5 "${validCommand}") ]]; then
-						prompt="${prompt}. if absent, fallback to: $(reflect_nth_arg 5 "${validCommand}")"
-					else
-						prompt="${prompt}, empty if absent"
-					fi
-					possibleValues=""
+				prompt="$(reflect_nth_arg 4 "$validCommand")"
+				possibleValues=", you can select one using wizard if you do not know which value is valid"
+			elif [[ "$validCommand" == *args_valid_or_read* ]]; then
+				eval "${element}=\"\${1-}\""
+				onlyPositionalVarNames+=("${element}")
+				prompt="$(reflect_nth_arg 4 "$validCommand")"
+				if [[ -n $(reflect_nth_arg 5 "$validCommand") ]]; then
+					prompt="${prompt}, proposed value: $(reflect_nth_arg 5 "$validCommand")"
+				fi
+				possibleValues=""
+			elif [[ "$validCommand" == *args_valid_or_default* ]]; then
+				prompt="optional, $(reflect_nth_arg 4 "$validCommand"). should be set like ${element}=value before ${THIS_SCRIPT_NAME} or export to OS environment"
+				if [[ -n $(reflect_nth_arg 5 "$validCommand") ]]; then
+					prompt="${prompt}. if absent, fallback to: $(reflect_nth_arg 5 "$validCommand")"
+				else
+					prompt="${prompt}, empty if absent"
 				fi
+				possibleValues=""
+			fi
 
-				prompt="$(
-					echo "${prompt}" |
-						string_replace "_SPACE_" " " |
-						string_replace "_DOLLAR_" "$" |
-						string_replace "_PARENTHESES_LEFT_" "(" |
-						string_replace "_PARENTHESES_RIGHT_" ")"
-				)"
+			prompt="$(
+				printf '%s\n' "${prompt}" |
+					string_replace "_SPACE_" " " |
+					string_replace "_DOLLAR_" "$" |
+					string_replace "_PARENTHESES_LEFT_" "(" |
+					string_replace "_PARENTHESES_RIGHT_" ")"
+			)"
 
-				description="${prompt}${possibleValues}"
-			fi
-			descriptions+="$(printf "\n    %-20s%s" "${element} " "${description}")"
-		done
+			description="${prompt}${possibleValues}"
+		fi
+		descriptions+="$(printf "\n    %-20s%s" "${element} " "${description}")"
+		if (($# > 0)); then
+			shift
+		fi
+	done
+	if [[ -n "${BASH_VERSION:-}" && $nbPositionalVarNames -gt 0 ]]; then
+		# The original Bash implementation used a caller-visible `i` as
+		# a loop counter over output names. Respect a destination named i.
+		if ! array_in i "${positionalVarNames[@]}"; then
+			i=$((nbPositionalVarNames - 1))
+		fi
 	fi
 
 	if [ ${#onlyPositionalVarNames[@]} -gt 0 ]; then
@@ -122,36 +160,36 @@ function args_parse() {
 		strPositionalValuesExamples=" \"$(array_join 'Value" "' onlyPositionalVarNames)Value\""
 	fi
 
-	declare_heredoc defaultUsage <<-EOF
-		${COLOR_BOLD_YELLOW}NAME${COLOR_END}
-		    ${THIS_SCRIPT_NAME} -- ${SHORT_DESC}
+	declare_heredoc defaultUsage <<EOF
+${COLOR_BOLD_YELLOW}NAME${COLOR_END}
+    ${THIS_SCRIPT_NAME} -- ${SHORT_DESC}
 
-		${COLOR_BOLD_YELLOW}SYNOPSIS${COLOR_END}
-		    [optionalVariable=value ...] ./${THIS_SCRIPT_NAME} [-qh]${strPositionalVarNames}
+${COLOR_BOLD_YELLOW}SYNOPSIS${COLOR_END}
+    [optionalVariable=value ...] ./${THIS_SCRIPT_NAME} [-qh]${strPositionalVarNames}
 
-		${COLOR_BOLD_YELLOW}DESCRIPTION${COLOR_END}
-		    [-h]                help, print the usage
-		    [-q]                optional, Run quietly, no confirmation
-		${descriptions}
+${COLOR_BOLD_YELLOW}DESCRIPTION${COLOR_END}
+    [-h]                help, print the usage
+    [-q]                optional, Run quietly, no confirmation
+${descriptions}
 
-		${COLOR_BOLD_YELLOW}EXAMPLES${COLOR_END}
-		    help, print the usage:
-		        ./${THIS_SCRIPT_NAME} -h
+${COLOR_BOLD_YELLOW}EXAMPLES${COLOR_END}
+    help, print the usage:
+        ./${THIS_SCRIPT_NAME} -h
 
-		    run with all params, if run in quiet mode with -q, be sure all the params are valid:
-		        ./${THIS_SCRIPT_NAME} [-q]${strPositionalValuesExamples}
+    run with all params, if run in quiet mode with -q, be sure all the params are valid:
+        ./${THIS_SCRIPT_NAME} [-q]${strPositionalValuesExamples}
 
-		    run using wizard, input value for params step by step:
-		        ./${THIS_SCRIPT_NAME}
+    run using wizard, input value for params step by step:
+        ./${THIS_SCRIPT_NAME}
 
-		    run with optional variables, example:
-		        myOpt1=myValue1 myOpt2=myValue2 ./${THIS_SCRIPT_NAME}
+    run with optional variables, example:
+        myOpt1=myValue1 myOpt2=myValue2 ./${THIS_SCRIPT_NAME}
 
-		    or you can run with some params, and input value for other params using wizard.
-	EOF
+    or you can run with some params, and input value for other params using wizard.
+EOF
 
-	if [ "$showUsage" == true ]; then
-		echo -e "${USAGE:-$defaultUsage}"
+	if [[ "$showUsage" == true ]]; then
+		printf '%b\n' "${USAGE:-$defaultUsage}"
 		exit 0
 	fi
 }
@@ -172,26 +210,38 @@ function args_parse() {
 #     args_valid_or_select varEmpty arr "Which app"
 # @SEE_ALSO
 #     args_valid_or_select_pipe, args_valid_or_read, args_valid_or_default
-function args_valid_or_select() {
-	local valueVarName validValuesVarName prompt value validValues PS3
+args_valid_or_select() {
+	local valueVarName validValuesVarName prompt value PS3
+	local -a validValues
+
 	valueVarName="${1}"
-	validValuesVarName=$2
-	validValues="$2[@]"
+	validValuesVarName="$2"
 	prompt="${3}"
-
-	value=$(eval eval "echo '$'${valueVarName}")
+	eval 'value="${'"$valueVarName"'-}"'
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# Preserve Bash's historical echo/word-splitting normalization, without
+		# reparsing the value with eval (which would execute input as code).
+		# shellcheck disable=SC2086,SC2116
+		value="$(echo $value)"
+	fi
+	eval "validValues=( \"\${${validValuesVarName}[@]}\" )"
 
 	while ! array_contains "${validValuesVarName}" "${value}"; do
-		echo -e "\n${prompt} ?"
+		printf '\n%s ?\n' "$prompt"
 		[[ -n "${value}" ]] && print_error "the input '${value}' is not valid."
 
 		PS3="choose one by ${COLOR_BOLD_YELLOW}number${COLOR_END} [1|2|...] ? "
-		select value in "${!validValues}"; do
+		select value in "${validValues[@]}"; do
 			break
 		done
 	done
-	eval "${valueVarName}='${value}'"
-	printf "Selected value: ${COLOR_BLUE}'%s'${COLOR_END}\n" "$(eval echo '$'"${valueVarName}")"
+
+	eval "${valueVarName}=\"\$value\""
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# shellcheck disable=SC2086,SC2116
+		value="$(echo $value)"
+	fi
+	printf "Selected value: ${COLOR_BLUE}'%s'${COLOR_END}\n" "$value"
 }
 
 # @NAME
@@ -207,8 +257,9 @@ function args_valid_or_select() {
 #     args_valid_or_select_pipe sel "a|ab|d" "which value"
 # @SEE_ALSO
 #     args_valid_or_select, args_valid_or_select_args, args_valid_or_read, args_valid_or_default
-function args_valid_or_select_pipe() {
-	local valueVarName validValues prompt newArray
+args_valid_or_select_pipe() {
+	local valueVarName validValues prompt
+	local -a newArray
 	valueVarName="${1}"
 	validValues="${2}"
 	prompt="${3}"
@@ -230,15 +281,21 @@ function args_valid_or_select_pipe() {
 #     args_valid_or_select_args sel "which value" "a" "ab" "d"
 # @SEE_ALSO
 #     args_valid_or_select, args_valid_or_select_pipe, args_valid_or_read, args_valid_or_default
-function args_valid_or_select_args() {
+args_valid_or_select_args() {
 	local valueVarName value prompt PS3
 	valueVarName="${1}"
-	value=$(eval eval "echo '$'${valueVarName}")
+	eval 'value="${'"$valueVarName"'-}"'
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# Preserve Bash's historical echo/word-splitting normalization, without
+		# reparsing the value with eval (which would execute input as code).
+		# shellcheck disable=SC2086,SC2116
+		value="$(echo $value)"
+	fi
 	prompt="${2}"
 	shift 2
 
 	while ! array_in "${value}" "$@"; do
-		echo -e "\n${prompt} ?"
+		printf '\n%s ?\n' "$prompt"
 		[[ -n "${value}" ]] && print_error "the input '${value}' is not valid."
 
 		PS3="choose one by ${COLOR_BOLD_YELLOW}number${COLOR_END} [1|2|...] ? "
@@ -246,8 +303,13 @@ function args_valid_or_select_args() {
 			break
 		done
 	done
-	eval "${valueVarName}='${value}'"
-	printf "Selected value: ${COLOR_BLUE}'%s'${COLOR_END}\n" "$(eval echo '$'"${valueVarName}")"
+
+	eval "${valueVarName}=\"\$value\""
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# shellcheck disable=SC2086,SC2116
+		value="$(echo $value)"
+	fi
+	printf "Selected value: ${COLOR_BLUE}'%s'${COLOR_END}\n" "$value"
 }
 
 # @NAME
@@ -265,28 +327,48 @@ function args_valid_or_select_args() {
 #     args_valid_or_read destRootPackage '^.+$' "Destination root package" "${defaultDestRootPackage}"
 # @SEE_ALSO
 #     args_valid_or_select, args_valid_or_select_args, args_valid_or_select_pipe, args_valid_or_default
-function args_valid_or_read() {
-	local value regExp prompt proposedValue
-	value=$(eval eval "echo '$'$1")
-	regExp=${2}
-	prompt="${3}"
-	proposedValue="${4}"
+args_valid_or_read() {
+	local valueVarName="$1"
+	local regExp="${2}"
+	local prompt="${3}"
+	local proposedValue="${4-}"
+	local value
+
+	eval 'value="${'"$valueVarName"'-}"'
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# Preserve Bash's historical echo/word-splitting normalization, without
+		# reparsing the value with eval (which would execute input as code).
+		# shellcheck disable=SC2086,SC2116
+		value="$(echo $value)"
+	fi
 
 	if [[ -n "${proposedValue}" ]]; then
 		prompt="${prompt} [${proposedValue}]"
-		if [[ -z "${value}" && "${modeQuiet}" == true ]]; then
+		if [[ -z "${value}" && "${modeQuiet:-false}" == true ]]; then
 			value="${proposedValue}"
 		fi
 	fi
-	while ! [[ ${value} =~ ${regExp} ]]; do
+
+	while ! [[ $value =~ $regExp ]]; do
 		[[ -n "${value}" ]] && print_error "the input '${value}' is not valid, please input again."
-		read -r -p "${prompt}: " value
+		if [[ -t 0 ]]; then
+			printf '%s: ' "$prompt" >&2
+		fi
+		read -r value || value=""
 		if [[ -z "${value}" ]]; then
 			value="${proposedValue}"
 		fi
 	done
-	eval "${1}='${value}'"
-	printf "Inputted value: ${COLOR_BLUE}'%s'${COLOR_END}\n" "$(eval echo '$'"${1}")"
+
+	eval "${valueVarName}=\"\$value\""
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# Legacy Bash printed via `eval echo $name`: collapse display-only
+		# whitespace, but leave the actual assigned value unchanged.
+		# shellcheck disable=SC2086,SC2116
+		printf "Inputted value: ${COLOR_BLUE}'%s'${COLOR_END}\n" "$(echo $value)"
+	else
+		printf "Inputted value: ${COLOR_BLUE}'%s'${COLOR_END}\n" "$value"
+	fi
 }
 
 # @NAME
@@ -307,20 +389,36 @@ function args_valid_or_read() {
 #     args_valid_or_default destRootPackage '^.+$' "Destination root package" "${defaultDestRootPackage}"
 # @SEE_ALSO
 #     args_valid_or_select, args_valid_or_select_args, args_valid_or_select_pipe, args_valid_or_read
-function args_valid_or_default() {
-	local value regExp prompt defaultValue
-	value=$(eval eval "echo '$'$1")
-	regExp=${2}
-	prompt="${3}"
-	defaultValue="${4}"
+args_valid_or_default() {
+	local valueVarName="$1"
+	local regExp="${2}"
+	local prompt="${3}"
+	local defaultValue="${4-}"
+	local value
+
+	eval 'value="${'"$valueVarName"'-}"'
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# Preserve Bash's historical echo/word-splitting normalization, without
+		# reparsing the value with eval (which would execute input as code).
+		# shellcheck disable=SC2086,SC2116
+		value="$(echo $value)"
+	fi
 
-	if [[ -z "${value}" || ! ${value} =~ ${regExp} ]]; then
-		prompt="for param ${1}:"
+	if [[ -z "${value}" || ! $value =~ $regExp ]]; then
+		prompt="for param ${valueVarName}:"
 		[[ -n "${value}" ]] && prompt+=" the input '${value}' is not valid" || prompt+=" no input"
 		[[ -n "${defaultValue}" ]] && prompt+=", fallback to default value '${defaultValue}'" || prompt+=", fallback to empty"
 		print_warn "${prompt}"
 		value="${defaultValue}"
 	fi
-	eval "${1}='${value}'"
-	printf "Inputted value: ${COLOR_BLUE}'%s'${COLOR_END}\n" "$(eval echo '$'"${1}")"
+
+	eval "${valueVarName}=\"\$value\""
+	if [[ -n "${BASH_VERSION:-}" ]]; then
+		# Legacy Bash printed via `eval echo $name`: collapse display-only
+		# whitespace, but leave the actual assigned value unchanged.
+		# shellcheck disable=SC2086,SC2116
+		printf "Inputted value: ${COLOR_BLUE}'%s'${COLOR_END}\n" "$(echo $value)"
+	else
+		printf "Inputted value: ${COLOR_BLUE}'%s'${COLOR_END}\n" "$value"
+	fi
 }