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

6 files changed, 179 insertions, 21 deletions

diff --git a/pkgtool.sh b/pkgtool.sh
index 068f0c67..0b4a518f 100755
--- a/pkgtool.sh
+++ b/pkgtool.sh
@@ -243,12 +243,12 @@ pkgtoolp_info() {
 
 				if [ "${_ppi_pkg_names:+1}" = 1 ]; then
 					rtl_log_msg "info_pkg_deps_full" "${MSG_info_pkg_deps_full}"\
-							"${_ppi_pkg_name}" "$(rtl_lsort "${_ppi_pkg_names}")";
+							"${_ppi_pkg_name}" "$(rtl_lsortV "${_ppi_pkg_names}")";
 				fi;
 
 				if [ "${_ppi_pkg_disabled:+1}" = 1 ]; then
 					rtl_log_msg "info_pkg_deps_full_disabled" "${MSG_info_pkg_deps_full_disabled}"\
-							"${_ppi_pkg_name}" "$(rtl_lsort "${_ppi_pkg_disabled}")";
+							"${_ppi_pkg_name}" "$(rtl_lsortV "${_ppi_pkg_disabled}")";
 				fi;
 			fi;
 		fi;
@@ -445,7 +445,7 @@ pkgtoolp_rdepends() {
 	then
 		rtl_log_msg "info" "${MSG_rdepends_pkg_deps_rev_none}" "${_ppr_pkg_name}";
 	else
-		for _ppr_pkg_name_rdepend in $(rtl_lsort	\
+		for _ppr_pkg_name_rdepend in $(rtl_lsortV	\
 				${_ppr_pkg_finished}		\
 				${_ppr_pkg_rdepends_direct});
 		do
@@ -453,7 +453,7 @@ pkgtoolp_rdepends() {
 
 			if [ "${_ppr_full_rdependsfl}" -eq 1 ]; then
 				rtl_get_var_unsafe \$_ppr_depends -u "PKG_"${_ppr_pkg_name}"_DEPENDS";
-				if rtl_lunfold_depends 'PKG_${_rld_name}_DEPENDS' \$_ppr_pkg_depends ${_ppr_depends}\
+				if rtl_lunfold_dependsV 'PKG_${_rld_name}_DEPENDS' \$_ppr_pkg_depends ${_ppr_depends}\
 				&& [ "${_ppr_pkg_depends:+1}" = 1 ]; then
 					rtl_lconcat \$_ppr_pkg_rdepends "${_ppr_pkg_depends}";
 				fi;
@@ -469,7 +469,7 @@ pkgtoolp_rdepends() {
 		fi;
 
 		if [ "${_ppr_pkg_disabled:+1}" = 1 ]; then
-			rtl_log_msg "info" "${MSG_rdepends_pkgs_deps_rev_disabled}" "${_ppr_pkg_name}" "$(rtl_lsort "${_ppr_pkg_disabled}")";
+			rtl_log_msg "info" "${MSG_rdepends_pkgs_deps_rev_disabled}" "${_ppr_pkg_name}" "$(rtl_lsortV "${_ppr_pkg_disabled}")";
 		fi;
 	fi;
 
diff --git a/subr.ex/ex_pkg.subr b/subr.ex/ex_pkg.subr
index 1fa0bc6f..978808a6 100644
--- a/subr.ex/ex_pkg.subr
+++ b/subr.ex/ex_pkg.subr
@@ -288,7 +288,7 @@ ex_pkg_unfold_depends() {
 	fi;
 	if [ "${_epud_restart:+1}" = 1 ]\
 	&& [ "${_epud_checkfl:-0}" -eq 1 ]; then
-		rtl_lunfold_depends 'PKG_${_rld_name}_DEPENDS' \$_epud_pkg_names ${_epud_pkg_names};
+		rtl_lunfold_dependsV 'PKG_${_rld_name}_DEPENDS' \$_epud_pkg_names ${_epud_pkg_names};
 		_epud_pkg_names="$(rtl_uniq ${_epud_pkg_names})";
 	fi;
 
@@ -353,7 +353,7 @@ ex_pkg_unfold_rdepends() {
 				continue;
 
 			elif rtl_get_var_unsafe \$_epur_depends -u "PKG_"${_epur_pkg_name}"_DEPENDS"\
-			  && rtl_lunfold_depends 'PKG_${_rld_name}_DEPENDS' \$_epur_pkg_depends ${_epur_depends}\
+			  && rtl_lunfold_dependsV 'PKG_${_rld_name}_DEPENDS' \$_epur_pkg_depends ${_epur_depends}\
 			  && [ "${_epur_pkg_depends:+1}" = 1 ]\
 			  && rtl_lmatch \$_epur_pkg_depends "${_epur_pkg_name_depend}";
 			then
diff --git a/subr.ex/ex_pkg_dispatch.subr b/subr.ex/ex_pkg_dispatch.subr
index a80ae21d..d95339ee 100644
--- a/subr.ex/ex_pkg_dispatch.subr
+++ b/subr.ex/ex_pkg_dispatch.subr
@@ -307,7 +307,7 @@ ex_pkg_dispatch() {
 		_epd_rc=0 _epd_reversefl=0;
 
 	case "${_epd_groups_inhibit_deps:-0}" in
-	0)	rtl_lunfold_depends '${_rld_name}_GROUP_DEPENDS' \$_epd_group_names ${_epd_group_names};
+	0)	rtl_lunfold_dependsV '${_rld_name}_GROUP_DEPENDS' \$_epd_group_names ${_epd_group_names};
 		_epd_group_names="$(rtl_uniq2 \$_epd_group_names)";
 	esac;
 
diff --git a/subr.ex/ex_pkg_env.subr b/subr.ex/ex_pkg_env.subr
index a177f6d2..e2cfb1db 100644
--- a/subr.ex/ex_pkg_env.subr
+++ b/subr.ex/ex_pkg_env.subr
@@ -150,7 +150,7 @@ ex_pkg_env() {
 # ex_pkg_state_set() - update build step status for single named package
 # @_pkg_name:		single package name
 # @_build_step:		build step set status of
-# [@${@}]:		optional list of build steps to invalidate status of
+# @...:			optional list of build steps to invalidate status of
 #
 # Returns:		zero (0) on success, non-zero (>0) on failure
 #
diff --git a/subr.pkg/pkg_install.subr b/subr.pkg/pkg_install.subr
index d606b6a1..8e795fa4 100644
--- a/subr.pkg/pkg_install.subr
+++ b/subr.pkg/pkg_install.subr
@@ -10,7 +10,7 @@ pkg_install() {
 	if ! rtl_fileop mkdir "${PKG_PREFIX}"; then
 		return 1;
 	else	for _destdir in "${PKG_DESTDIR}:${PKG_PREFIX}" "${PKG_DESTDIR_HOST}:${PREFIX}"; do
-			rtl_lassign "_destdir _destdir_prefix" ":" "${_destdir}";
+			rtl_lassignV "_destdir _destdir_prefix" ":" "${_destdir}";
 			if [ -e "${_destdir}" ]; then
 				(set +o errexit -o noglob; rtl_flock_acquire 4 || exit "${?}";
 				trap "rm -f \"${BUILD_WORKDIR}/install.lock\"" EXIT;
diff --git a/subr.rtl/rtl_list.subr b/subr.rtl/rtl_list.subr
index 793eccac..5934126f 100644
--- a/subr.rtl/rtl_list.subr
+++ b/subr.rtl/rtl_list.subr
@@ -5,7 +5,15 @@
 #	must specify "<SP><VT>" as IFS.
 #
 
-rtl_lassign() {
+#
+# rtl_lassignV() - assigns list of variables to list of values w/ separator
+# @_vnames:	list of variable names
+# @_sep:	single non-zero, possibly multi-character, separator
+# @...:		list as positional parameters
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
+rtl_lassignV() {
 	local	_rla_vnames="${1}" _rla_sep="${2}"	\
 		_rla_head="" _rla_tail="" _rla_vname="" _rla_vval="" IFS;
 	IFS="${_rla_sep}"; shift 2;
@@ -21,10 +29,27 @@ rtl_lassign() {
 	return 0;
 };
 
+#
+# rtl_lconcat() - concatenate list with item(s)
+# @_rlist:	inout reference to list
+# @_litem_new:	list item(s) to concatenate with
+# @[_sep]:	optional single non-zero, possibly multi-character, separator
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lconcat() {
 	rtl_lconcat2 "${1}" "${1}" "${2}" "${3:-}";
 };
 
+#
+# rtl_lconcat2() - concatenate list with item(s)
+# @_rlist_new:	out reference to new list
+# @_rlist:	in reference to list
+# @_litem_new:	list item(s) to concatenate with
+# @[_sep]:	optional single non-zero, possibly multi-character, separator
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lconcat2() {
 	local	_rlc2_rlist_new="${1#\$}" _rlc2_rlist="${2#\$}" _rlc2_litem_new="${3}"	\
 		_rlc2_sep="${4:- }" IFS="${4:-${IFS:- }}";
@@ -37,10 +62,27 @@ rtl_lconcat2() {
 	return 0;
 };
 
+#
+# rtl_lfilter() - remove item(s) from list
+# @_rlist:	inout reference to list
+# @_filter:	item(s) to remove
+# @[_sep]:	optional single non-zero, possibly multi-character, separator
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lfilter() {
 	rtl_lfilter2 "${1}" "${1}" "${2}" "${3:-}";
 };
 
+#
+# rtl_lfilter2() - remove item(s) from list
+# @_rlist:	in reference to list
+# @_rlist_new:	out reference to new list
+# @_filter:	item(s) to remove
+# @[_sep]:	optional single non-zero, possibly multi-character, separator
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lfilter2() {
 	local	_rlf2_rlist="${1#\$}" _rlf2_rlist_new="${2#\$}" _rlf2_filter="${3}" _rlf2_sep="${4:-}"\
 		_rlf2_filterfl="" _rlf2_list="" _rlf2_litem="" _rlf2_litem_filter="" _rlf2_lnew="";
@@ -71,6 +113,15 @@ rtl_lfilter2() {
 	return 0;
 };
 
+#
+# rtl_lfirst() - obtain first (head) and remaining (tail) item(s) in list
+# @_rhead:	out reference to first item (head) in list, if any
+# @_rtail:	out reference to remaining items (tail) in list, if any
+# @_list:	list
+# @_sep:	single non-zero, possibly multi-character, separator
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lfirst() {
 	local _rlf_rhead="${1#\$}" _rlf_rtail="${2#\$}" _rlf_list="${3}" _rlf_sep="${4}" IFS="${4}";
 
@@ -83,6 +134,14 @@ rtl_lfirst() {
 	return 0;
 };
 
+#
+# rtl_lindexV() - retrieve item from list
+# @_rlout:	out reference to list item
+# @_idx:	zero-based (from start of list) or negative (from end of list) index of list item
+# @...:		list as positional parameters
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lindexV() {
 	local	_rliV_rlout="${1#\$}" _rliV_idx="${2}"	\
 		_rliV_limit=0; shift 2;
@@ -107,6 +166,14 @@ rtl_lindexV() {
 	return 0;
 };
 
+#
+# rtl_llength() - obtain count of items in list
+# @_rlen:	out reference to count of items in list
+# @_rlist:	in reference to list
+# @[_sep]:	optional single non-zero, possibly multi-character, separator
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_llength() {
 	local _rll_rlen="${1#\$}" _rll_rlist="${2#\$}" _rll_sep="${3:- }" IFS="${3:-${IFS:- }}";
 
@@ -114,10 +181,27 @@ rtl_llength() {
 	return 0;
 };
 
+#
+# rtl_llift() - convert list w/ separator to new list w/ new separator
+# @_rlist:	inout reference to list
+# @_sep:	single non-zero, possibly multi-character, separator
+# @_sep_new:	single non-zero, possibly multi-character, separator of new list
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_llift() {
 	rtl_llift2 "${1}" "${1}" "${2}" "${3}";
 };
 
+#
+# rtl_llift2() - convert list w/ separator to new list w/ new separator
+# @_rlist:	in reference to list
+# @_rlist_new:	out reference to new list
+# @_sep:	single non-zero, possibly multi-character, separator
+# @_sep_new:	single non-zero, possibly multi-character, separator of new list
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_llift2() {
 	local	_rl2_rlist="${1#\$}" _rl2_rlist_new="${2#\$}" _rl2_sep="${3:-}"	\
 		_rl2_sep_new="${4}";
@@ -133,13 +217,29 @@ rtl_llift2() {
 	return 0;
 };
 
+#
+# rtl_lmatch() - check if item(s) in list
+# @_rlist:	in reference to list
+# @_item:	item(s) to search for
+# @[_sep]:	optional single non-zero, possibly multi-character, separator
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lmatch() {
-	local _rlm_rlist="${1#\$}" _rlm_item="${2}" _rlm_sep="${3:-}" _rlm_list_="";
+	local	_rlm_rlist="${1#\$}" _rlm_item="${2}" _rlm_sep="${3:-}"	\
+		_rlm_list_="";
 
 	rtl_lsearch2 "${_rlm_rlist}" \$_rlm_list_ "${_rlm_item}" "${_rlm_sep}";
 	[ "${_rlm_list_:+1}" = 1 ];
 };
 
+#
+# rtl_lmax() - obtain maximum length of items in list
+# @_rlist:	in reference to list
+# @_rmax:	out reference to maximum length of items variable
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lmax() {
 	local	_rlm2_rlist="${1#\$}" _rlm2_rmax="${2#\$}"	\
 		_rlm2_len=0 _rlm2_len_max=0;
@@ -155,6 +255,16 @@ rtl_lmax() {
 	return 0;
 };
 
+#
+# rtl_lrangeV() - retrieve item(s) from list w/ range
+# @_rlout:	out reference to list item
+# @_idx0:	zero-based (from start of list) or negative (from end of list) start index of list item
+# @_idx1:	zero-based (from start of list) or negative (from end of list) end index of list item
+# @_sep:	single non-zero, possibly multi-character, separator
+# @...:		list as positional parameters
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lrangeV() {
 	local	_rlrV_rlout="${1#\$}" _rlrV_idx0="${2}" _rlrV_idx1="${3}" _rlrV_sep="${4}"	\
 		_rlrV_limit=0; shift 4;
@@ -197,10 +307,27 @@ rtl_lrangeV() {
 	fi;
 };
 
+#
+# rtl_lsearch() - obtains item(s) from list
+# @_rlist:	inout reference to list
+# @_filter:	item(s) to search for and include in new list
+# @[_sep]:	optional single non-zero, possibly multi-character, separator
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lsearch() {
 	rtl_lsearch2 "${1}" "${1}" "${2}" "${3:-}";
 }
 
+#
+# rtl_lsearch2() - obtains item(s) from list
+# @_rlist:	in reference to list
+# @_rlist_new:	out reference to new list
+# @_filter:	item(s) to search for and include in new list
+# @[_sep]:	optional single non-zero, possibly multi-character, separator
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lsearch2() {
 	local	_rls2_rlist="${1#\$}" _rls2_rlist_new="${2#\$}"		\
 		_rls2_filter="${3}" _rls2_sep="${4:-}"			\
@@ -230,10 +357,27 @@ rtl_lsearch2() {
 	return 0;
 };
 
+#
+# rtl_lsearch_patternl() - obtain item(s) from list matching pattern
+# @_rlist:	inout reference to list
+# @_pattern:	pattern of item(s) to search for and include in list
+# @[_sep]:	optional single non-zero, possibly multi-character, separator
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lsearch_patternl() {
 	rtl_lsearch_patternl2 "${1}" "${1}" "${2}" "${3:-}";
 };
 
+#
+# rtl_lsearch_patternl2() - obtain item(s) from list matching pattern
+# @_rlist:	in reference to list
+# @_rlist_new:	out reference to new list
+# @_pattern:	pattern of item(s) to search for and include in new list
+# @[_sep]:	optional single non-zero, possibly multi-character, separator
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
 rtl_lsearch_patternl2() {
 	local	_rlsp2_rlist="${1#\$}" _rlsp2_rlist_new="${2#\$}"	\
 		_rlsp2_pattern="${3}" _rlsp2_sep="${4:- }"		\
@@ -252,13 +396,27 @@ rtl_lsearch_patternl2() {
 	return 0;
 };
 
-rtl_lsort() {
+#
+# rtl_lsortV() - sort list w/ sort(1)
+# @...:		list as positional parameters
+#
+# Returns:	zero (0) on success, non-zero (>0) on failure
+#
+rtl_lsortV() {
 	printf "%s" "${*}" | tr " " "\n" | sort | paste -s -d " ";
 	return 0;
 };
 
-RTL_LUNFOLD_DEPENDS_LEVEL=0;
-rtl_lunfold_depends() {
+#
+# rtl_lunfold_dependsV() - expand list into list w/ unfolded dependencies for each list item
+# @_vname_template:	template of variable names containing dependencies for each list item
+# @_rlist:		out reference to list w/ unfolded dependencies
+# @...:			list as positional parameters
+#
+# Returns:		zero (0) on success, non-zero (>0) on failure
+#
+RTL_LUNFOLD_DEPENDSV_LEVEL=0;
+rtl_lunfold_dependsV() {
 	local	_rld_vname_template="${1}" _rld_rlist="${2#\$}"		\
 		_rld_depends="" _rld_list="" _rld_name="" _rld_names=""	\
 		_rld_vname_template_="";
@@ -268,12 +426,12 @@ rtl_lunfold_depends() {
 		eval _rld_vname_template_=\"${_rld_vname_template}\";
 		if rtl_get_var_unsafe \$_rld_depends -u "${_rld_vname_template_}"\
 		&& [ "${_rld_depends:+1}" = 1 ]; then
-			: $((RTL_LUNFOLD_DEPENDS_LEVEL+=1));
-			eval _rld_depends${RTL_LUNFOLD_DEPENDS_LEVEL}='${_rld_depends}';
-			rtl_lunfold_depends "${_rld_vname_template}" \$_rld_depends${RTL_LUNFOLD_DEPENDS_LEVEL} ${_rld_depends};
-			eval _rld_depends='${_rld_depends'"${RTL_LUNFOLD_DEPENDS_LEVEL}"'}';
-			unset '_rld_depends'"${RTL_LUNFOLD_DEPENDS_LEVEL}";
-			: $((RTL_LUNFOLD_DEPENDS_LEVEL-=1));
+			: $((RTL_LUNFOLD_DEPENDSV_LEVEL+=1));
+			eval _rld_depends${RTL_LUNFOLD_DEPENDSV_LEVEL}='${_rld_depends}';
+			rtl_lunfold_dependsV "${_rld_vname_template}" \$_rld_depends${RTL_LUNFOLD_DEPENDSV_LEVEL} ${_rld_depends};
+			eval _rld_depends='${_rld_depends'"${RTL_LUNFOLD_DEPENDSV_LEVEL}"'}';
+			unset '_rld_depends'"${RTL_LUNFOLD_DEPENDSV_LEVEL}";
+			: $((RTL_LUNFOLD_DEPENDSV_LEVEL-=1));
 			rtl_lconcat \$_rld_names "${_rld_depends}";
 		fi;
 		rtl_lconcat \$_rld_names "${_rld_name}";