improve documentation

utilities/debug.bash

@@ -41,20 +41,24 @@ _printArray_() {
     #         Prints the content of array as key value pairs for easier debugging. Only prints in verbose mode.
     # ARGS:
     #         $1 (Required) - String variable name of the array
+    #         $2 (Optional) - Line number where _printArray_ is called
     # OUTS:
-    #         stdout: Formatted key value of array.one
+    #         stdout: Formatted key value of array
     # USAGE:
     #         testArray=("1" "2" "3" "4")
-    #         _printArray_ "testArray"
+    #         _printArray_ "testArray" ${LINENO}
     # CREDIT:
     #         https://github.com/labbots/bash-utility/blob/master/src/debug.sh
 
     [[ $# == 0 ]] && fatal "Missing required argument to ${FUNCNAME[0]}"
 
     local _arrayName="${1}"
+    local _lineNumber="${2:-}"
     declare -n _arr="${1}"
+
     [[ ${VERBOSE} != true ]] && return 0
-    debug "Printing contents of \${${_arrayName}[@]}"
+
+    debug "Printing contents of \${${_arrayName}[@]}" "${_lineNumber}"
 
     for _k in "${!_arr[@]}"; do
         debug "${_k} = ${_arr[$_k]}"

utilities/files.bash

@@ -133,15 +133,6 @@ _createUniqueFilename_() {
     local _ext
     local i
 
-    if ! command -v realpath >/dev/null 2>&1; then
-        error "We must have 'realpath' installed and available in \$PATH to run."
-        if [[ $OSTYPE == "darwin"* ]]; then
-            notice "Install coreutils using homebrew and rerun this script."
-            info "\t$ brew install coreutils"
-        fi
-        _safeExit_ 1
-    fi
-
     # Find directories with realpath if input is an actual file
     if [ -e "${_fullFile}" ]; then
         _fullFile="$(realpath "${_fullFile}")"
@@ -150,6 +141,10 @@ _createUniqueFilename_() {
     _filePath="$(dirname "${_fullFile}")"
     _originalFile="$(basename "${_fullFile}")"
 
+    #shellcheck disable=SC2064
+    trap "$(shopt -p nocasematch)" RETURN # reset nocasematch when function exits
+    shopt -s nocasematch                  # Use case-insensitive regex
+
     # Detect some common multi-extensions
     case $(tr '[:upper:]' '[:lower:]' <<<"${_originalFile}") in
         *.tar.gz | *.tar.bz2) _levels=2 ;;
@@ -167,15 +162,15 @@ _createUniqueFilename_() {
         fi
         _fn=${_fn%.$_ext}
     done
-    debug "_extension: ${_extension}"
+
     if [[ ${_extension} == "${_originalFile}" ]]; then
         _extension=""
     else
-        _originalFile="${_originalFile%.$_extension}" && debug "_originalFile: ${_originalFile}"
+        _originalFile="${_originalFile%.$_extension}"
         _extension=".${_extension}"
     fi
 
-    _newFilename="${_filePath}/${_originalFile}${_extension:-}" && debug "_newFilename: ${_newFilename}"
+    _newFilename="${_filePath}/${_originalFile}${_extension:-}"
 
     if [ -e "${_newFilename}" ]; then
         _num=1
@@ -340,7 +335,6 @@ _fileName_() {
     #					_fileName_ "some/path/to/file" --> "file"
     [[ $# == 0 ]] && fatal "Missing required argument to ${FUNCNAME[0]}"
     printf "%s\n" "${1##*/}"
-
 }
 
 _fileBasename_() {
@@ -412,7 +406,8 @@ _fileExtension_() {
 
 _filePath_() {
     # DESC:
-    #					Finds the directory name from a file path. If it exists on filesystem, print absolute path.  If a string, remove the filename and return the path
+    #					Finds the directory name from a file path. If it exists on filesystem, print
+    #         absolute path.  If a string, remove the filename and return the path
     # ARGS:
     #					$1 (Required) - Input string path
     # OUTS:

utilities/strings.bash

@@ -89,7 +89,7 @@ _cleanString_() {
         _string="$(echo "${_string}" | sed -E "s/${_pairs[0]}/${_pairs[1]}/g")"
     fi
 
-    # trim trailing/leading white space and duplicate dashes
+    # trim trailing/leading white space and duplicate dashes & spaces
     _string="$(echo "${_string}" | tr -s '-' | tr -s '_')"
     _string="$(echo "${_string}" | sed -E 's/([_\-]) /\1/g' | sed -E 's/ ([_\-])/\1/g')"
     _string="$(echo "${_string}" | awk '{$1=$1};1')"
@@ -232,7 +232,7 @@ _ltrim_() {
 
 _regexCapture_() {
     # DESC:
-    #         Use regex to validate and parse strings
+    #         Use regex to capture a group of text from a string
     # ARGS:
     #         $1 (Required) - Input String
     #         $2 (Required) - Regex pattern
@@ -243,7 +243,9 @@ _regexCapture_() {
     #         1 - Regex did not match
     #         stdout: Prints string matching regex
     # USAGE:
-    #         _regex_ "#FFFFFF" '^(#?([a-fA-F0-9]{6}|[a-fA-F0-9]{3}))$'
+    #         HEXCODE=$(_regex_ "background-color: #FFFFFF;" '^(#?([a-fA-F0-9]{6}|[a-fA-F0-9]{3}))$')
+    #         $ printf "%s\n" "${HEXCODE}"
+    #         $ #FFFFFF
     # NOTE:
     #         This example only prints the first matching group. When using multiple capture
     #         groups some modification is needed.
@@ -462,14 +464,18 @@ _stripANSI_() {
 
 _trim_() {
     # DESC:
-    #         Removes all leading/trailing whitespace. Used through a pipe or here string.
+    #         Removes all leading/trailing whitespace and reduces internal duplicate spaces
+    #         to a single space.
     # ARGS:
-    #         None
+    #         $1 (Required) - String to be trimmed
     # OUTS:
-    #         None
+    #         stdout: Prints string with leading/trailing whitespace removed
     # USAGE:
     #         text=$(_trim_ <<<"$1")
     #         echo "STRING" | _trim_
+    # NOTE:
+    #         Used through a pipe or here string.
+
     awk '{$1=$1;print}'
 }