Document subr.rtl/*.subr functions, pt. I.

1 files changed, 69 insertions, 36 deletions

diff --git a/subr.rtl/rtl_fetch_git.subr b/subr.rtl/rtl_fetch_git.subr
index 13eb672d..c3682255 100644
--- a/subr.rtl/rtl_fetch_git.subr
+++ b/subr.rtl/rtl_fetch_git.subr
@@ -3,19 +3,32 @@
 # set +o errexit -o noglob -o nounset is assumed.
 #
 
+#
+# rtlp_fetch_url_git() - fetch Git URL for item
+# @_dlcachedir:		absolute pathname to download cache directory
+# @_git_args:		optional argument string to pass to git(1)
+# @_git_branch:		name of Git branch
+# @_mirrors:		optional list of mirror base URLs
+# @_name:		single item name
+# @_target_subdir:	target subdirectory name
+# @_target_dname:	target directory name
+# @_url:		single Git URL
+#
+# Returns:		zero (0) on success, non-zero (>0) on failure
+#
 rtlp_fetch_url_git() {
-	local	_rpfug_cache_dname="${1}" _rpfug_git_args="${2}" _rpfug_git_branch="${3}"	\
-		_rpfug_mirrors="${4}" _rpfug_pkg_name="${5}" _rpfug_subdir="${6}"		\
-		_rpfug_tgtdir="${7}" _rpfug_url="${8}"						\
-		_rpfug_cache_dname_full="" _rpfug_clonefl=0 _rpfug_dname=""			\
+	local	_rpfug_dlcachedir="${1}" _rpfug_git_args="${2}" _rpfug_git_branch="${3}"	\
+		_rpfug_mirrors="${4}" _rpfug_name="${5}" _rpfug_target_subdir="${6}"		\
+		_rpfug_target_dname="${7}" _rpfug_url="${8}"					\
+		_rpfug_dlcachedir_full="" _rpfug_clonefl=0 _rpfug_dname=""			\
 		_rpfug_git_pull_log_fname="" _rpfug_oldpwd="" _rpfug_url_base="";
 
-	_rpfug_cache_dname_full="${_rpfug_cache_dname}/${_rpfug_subdir##*/}";
+	_rpfug_dlcachedir_full="${_rpfug_dlcachedir}/${_rpfug_target_subdir##*/}";
 	(set -o errexit -o noglob -o nounset;
 	rtl_flock_acquire 4 || exit "${?}";
-	trap "rm -f \"${_rpfug_cache_dname_full%%[/]}.fetching\"" EXIT;
-	if [ -e "${_rpfug_cache_dname_full}" ]; then
-		(rtl_fileop cd "${_rpfug_cache_dname_full}" || exit 1;
+	trap "rm -f \"${_rpfug_dlcachedir_full%%[/]}.fetching\"" EXIT;
+	if [ -e "${_rpfug_dlcachedir_full}" ]; then
+		(rtl_fileop cd "${_rpfug_dlcachedir_full}" || exit 1;
 		 _rpfug_git_pull_log_fname="$(mktemp)" || exit 1;
 		 trap 'rm -f "${_rpfug_git_pull_log_fname}" 2>/dev/null' EXIT HUP INT TERM USR1 USR2;
 		 if ! git pull ${_rpfug_git_args} origin "${_rpfug_git_branch:-main}" >"${_rpfug_git_pull_log_fname}" 2>&1; then
@@ -37,14 +50,14 @@ rtlp_fetch_url_git() {
 		 else
 			cat "${_rpfug_git_pull_log_fname}"; exit 0;
 		 fi;) || return 1;
-		(rtl_fileop cd "${_rpfug_cache_dname_full}" &&\
+		(rtl_fileop cd "${_rpfug_dlcachedir_full}" &&\
 			git submodule update) || return 1;
-	else	if git clone ${_rpfug_git_args} -b "${_rpfug_git_branch:-main}" "${_rpfug_url}" "${_rpfug_cache_dname_full}"; then
+	else	if git clone ${_rpfug_git_args} -b "${_rpfug_git_branch:-main}" "${_rpfug_url}" "${_rpfug_dlcachedir_full}"; then
 			_rpfug_clonefl=1;
 		elif [ "${_rpfug_mirrors}" = "skip" ]; then
 			return 1;
 		else	for _rpfug_url_base in ${_rpfug_mirrors}; do
-				if git clone ${_rpfug_git_args} -b "${_rpfug_git_branch:-main}" "${_rpfug_url_base}/${_rpfug_pkg_name}/${_rpfug_subdir}" "${_rpfug_cache_dname_full}"; then
+				if git clone ${_rpfug_git_args} -b "${_rpfug_git_branch:-main}" "${_rpfug_url_base}/${_rpfug_name}/${_rpfug_target_subdir}" "${_rpfug_dlcachedir_full}"; then
 					_rpfug_clonefl=1; break;
 				fi;
 			done;
@@ -52,23 +65,23 @@ rtlp_fetch_url_git() {
 		if [ "${_rpfug_clonefl}" -eq 0 ]; then
 			return 1;
 		else	if [ "${_rpfug_git_branch:+1}" = 1 ]; then
-				(rtl_fileop cd "${_rpfug_cache_dname_full}" &&\
+				(rtl_fileop cd "${_rpfug_dlcachedir_full}" &&\
 					git checkout "${_rpfug_git_branch}") || return 1;
 			fi;
-			(rtl_fileop cd "${_rpfug_cache_dname_full}" &&\
+			(rtl_fileop cd "${_rpfug_dlcachedir_full}" &&\
 				git submodule update --init) || return 1;
 		fi;
 	fi;
-	if [ "${_rpfug_cache_dname}" != "${_rpfug_tgtdir}" ]; then
-		_rpfug_oldpwd="${PWD}"; rtl_fileop cd "${_rpfug_tgtdir}" || return 1;
-		rtl_fileop rm "${_rpfug_tgtdir}/${_rpfug_subdir}" || return 1;
-		_rpfug_dname="${_rpfug_tgtdir}/${_rpfug_subdir}"; rtl_dirname \$_rpfug_dname;
+	if [ "${_rpfug_dlcachedir}" != "${_rpfug_target_dname}" ]; then
+		_rpfug_oldpwd="${PWD}"; rtl_fileop cd "${_rpfug_target_dname}" || return 1;
+		rtl_fileop rm "${_rpfug_target_dname}/${_rpfug_target_subdir}" || return 1;
+		_rpfug_dname="${_rpfug_target_dname}/${_rpfug_target_subdir}"; rtl_dirname \$_rpfug_dname;
 		if ! [ -e "${_rpfug_dname}" ]; then
 			rtl_fileop mkdir "${_rpfug_dname}";
 		fi;
-		rtl_fileop cp "${_rpfug_cache_dname_full}" "${_rpfug_tgtdir}/${_rpfug_subdir}" || return 1;
+		rtl_fileop cp "${_rpfug_dlcachedir_full}" "${_rpfug_target_dname}/${_rpfug_target_subdir}" || return 1;
 		rtl_fileop cd "${_rpfug_oldpwd}" || return 1;
-	fi) 4<>"${_rpfug_cache_dname_full%%[/]}.fetching";
+	fi) 4<>"${_rpfug_dlcachedir_full%%[/]}.fetching";
 
 	if [ "${?}" -eq 0 ]; then
 		cd "$(pwd)";
@@ -77,26 +90,34 @@ rtlp_fetch_url_git() {
 	fi;
 };
 
+#
+# rtlp_fetch_mirror_urls_git() - setup mirror for Git URL(s)
+# @_git_args:		optional argument string to pass to git(1)
+# @_target_dname:	target directory name
+# @...:			list of Git URLs
+#
+# Returns:		zero (0) on success, non-zero (>0) on failure
+#
 rtl_fetch_mirror_urls_git() {
-	local	_rfmug_git_args="${1}" _rfmug_tgtdir="${2}"				\
-		_rfmug_dname="" _rfmug_rc=0 _rfmug_repo_dname="" _rfmug_subdir=""	\
+	local	_rfmug_git_args="${1}" _rfmug_target_dname="${2}"				\
+		_rfmug_dname="" _rfmug_rc=0 _rfmug_repo_dname="" _rfmug_target_subdir=""	\
 		_rfmug_url="" _rfmug_url_spec=""; shift 2;
 
 	for _rfmug_url_spec in "${@}"; do
-		_rfmug_subdir="${_rfmug_url_spec%=*}"; _rfmug_subdir="${_rfmug_subdir##*/}"; _rfmug_url="${_rfmug_url_spec#*=}"; _rfmug_url="${_rfmug_url%@*}";
-		_rfmug_repo_dname="${_rfmug_subdir}"; [ "${_rfmug_repo_dname%.git}" = "${_rfmug_repo_dname}" ] && _rfmug_repo_dname="${_rfmug_repo_dname}.git";
+		_rfmug_target_subdir="${_rfmug_url_spec%=*}"; _rfmug_target_subdir="${_rfmug_target_subdir##*/}"; _rfmug_url="${_rfmug_url_spec#*=}"; _rfmug_url="${_rfmug_url%@*}";
+		_rfmug_repo_dname="${_rfmug_target_subdir}"; [ "${_rfmug_repo_dname%.git}" = "${_rfmug_repo_dname}" ] && _rfmug_repo_dname="${_rfmug_repo_dname}.git";
 
-		_rfmug_dname="${_rfmug_tgtdir}"; rtl_dirname \$_rfmug_dname;
+		_rfmug_dname="${_rfmug_target_dname}"; rtl_dirname \$_rfmug_dname;
 		if ! [ -e "${_rfmug_dname}" ]; then
 			rtl_fileop mkdir "${_rfmug_dname}";
 		fi;
 		(set -o errexit -o noglob -o nounset;
 		rtl_flock_acquire 4 || exit "${?}";
-		trap "rm -f \"${_rfmug_tgtdir}/.fetching\"" EXIT;
-		if [ -e "${_rfmug_tgtdir}/${_rfmug_repo_dname}" ]; then
-			(rtl_fileop cd "${_rfmug_tgtdir}/${_rfmug_repo_dname}" && git fetch ${_rfmug_git_args} --all) || return 1;
-		else	(rtl_fileop cd "${_rfmug_tgtdir}" && git clone ${_rfmug_git_args} --mirror "${_rfmug_url}" "${_rfmug_repo_dname}") || return 1;
-		fi) 4<>"${_rfmug_tgtdir}/.fetching";
+		trap "rm -f \"${_rfmug_target_dname}/.fetching\"" EXIT;
+		if [ -e "${_rfmug_target_dname}/${_rfmug_repo_dname}" ]; then
+			(rtl_fileop cd "${_rfmug_target_dname}/${_rfmug_repo_dname}" && git fetch ${_rfmug_git_args} --all) || return 1;
+		else	(rtl_fileop cd "${_rfmug_target_dname}" && git clone ${_rfmug_git_args} --mirror "${_rfmug_url}" "${_rfmug_repo_dname}") || return 1;
+		fi) 4<>"${_rfmug_target_dname}/.fetching";
 		if [ "${?}" -ne 0 ]; then
 			_rfmug_rc=1;
 		fi;
@@ -105,23 +126,35 @@ rtl_fetch_mirror_urls_git() {
 	return "${_rfmug_rc}";
 };
 
+#
+# rtl_fetch_url_git() - fetch Git URL(s) for item
+# @_dlcachedir:		absolute pathname to download cache directory
+# @_git_args:		optional argument string to pass to git(1)
+# @_target_dname:	target directory name
+# @_name:		single item name
+# @_mirrors:		optional list of mirror base URLs
+# @...:			list of Git URLs
+#
+# Returns:		zero (0) on success, non-zero (>0) on failure
+#
 rtl_fetch_urls_git() {
-	local	_rfug_cache_dname="${1}" _rfug_git_args="${2}" _rfug_tgtdir="${3}"	\
-		_rfug_pkg_name="${4}" _rfug_mirrors="${5}"				\
-	       	_rfug_git_branch="" _rfug_subdir="" _rfug_url="" _rfug_url_spec=""; shift 5;
+	local	_rfug_dlcachedir="${1}" _rfug_git_args="${2}" _rfug_target_dname="${3}"	\
+		_rfug_name="${4}" _rfug_mirrors="${5}"					\
+	       	_rfug_git_branch="" _rfug_target_subdir="" _rfug_url="" _rfug_url_spec="";
+	shift 5;
 
 	for _rfug_url_spec in "${@}"; do
-		_rfug_subdir="${_rfug_url_spec%=*}";
+		_rfug_target_subdir="${_rfug_url_spec%=*}";
 		_rfug_url="${_rfug_url_spec#*=}";
 		_rfug_url="${_rfug_url%@*}";
 		if [ "${_rfug_url_spec#*@}" != "${_rfug_url_spec}" ]; then
 			_rfug_git_branch=${_rfug_url_spec#*@};
 		fi;
 		if ! rtlp_fetch_url_git	\
-				"${_rfug_cache_dname}" "${_rfug_git_args}"	\
+				"${_rfug_dlcachedir}" "${_rfug_git_args}"	\
 				"${_rfug_git_branch}" "${_rfug_mirrors}"	\
-				"${_rfug_pkg_name}" "${_rfug_subdir}"		\
-				"${_rfug_tgtdir}" "${_rfug_url}";
+				"${_rfug_name}" "${_rfug_target_subdir}"	\
+				"${_rfug_target_dname}" "${_rfug_url}";
 		then
 			return 1;
 		fi;