From dbea968f56bada8cc90a55ab5291e3c7ed7863e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luc=C3=ADa=20Andrea=20Illanes=20Albornoz?= Date: Tue, 21 Mar 2023 09:33:01 +0100 Subject: Document subr.rtl/*.subr functions, pt. III. --- subr.rtl/rtl_list.subr | 180 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 169 insertions(+), 11 deletions(-) (limited to 'subr.rtl') 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 "" 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}"; -- cgit v1.2.3