Merge pull request #10 from natelandau/linear/nat-14-use-columns-within_usage

Automate columns within help text

README.md

@@ -115,13 +115,13 @@ The files within `utilities/` contain BASH functions which can be used in your s
 
 Within the `utilities` folder are many BASH functions meant to ease development of more complicated scripts. These can be included in the template in two ways.
 
-#### 1. Copy and paste into standaloneTemplate.sh
+#### 1. Copy and paste into template_standalone.sh
 
 You can copy any complete function from the Utilities and place it into your script. Copy it beneath the `### Custom utility functions` line. Scripts created this way are fully portable among systems
 
 #### 2. Source all the utility files by using template.sh
 
-`template.sh` contains a function to source all the utility files into the script. Beware, that you'll need to update the paths within the `_sourceUtilities_` function to ensure your script can find this repository.
+`template.sh` contains a function to source all the utility files into the script. **IMPORTANT:** You will need to update the paths within the `_sourceUtilities_` function to ensure your script can find this repository.
 
 ## alerts.bash
 
@@ -130,6 +130,7 @@ You can copy any complete function from the Utilities and place it into your scr
 - **`_alert_`** Performs alerting functions including writing to a log file and printing to screen
 - **`_centerOutput_`** Prints text in the center of the terminal window
 - **`_setColors_`** Sets color constants for alerting (**Note:** Colors default to a dark theme.)
+- **`_usageCommands_** Used to add commands to the `_usage_` function. Prints commands and their descriptions in two aligned columns. Uses an option 4 character tab count to indent the commands.
 
 Basic alerting, logging, and setting color functions (included in `scriptTemplate.sh` by default). Print messages to stdout and to a user specified logfile using the following functions.
 

template.sh

@@ -295,17 +295,31 @@ _usage_() {
 
   This is a script template.  Edit this description to print help to users.
 
-  ${bold}Options:${reset}
+  ${bold}${underline}Options:${reset}
-    -h, --help              Display this help and exit
+$(_usageCommands_ \
-    --loglevel [LEVEL]      One of: FATAL, ERROR, WARN, INFO, NOTICE, DEBUG, ALL, OFF
+        "-h, --help" \
-                            (Default is 'ERROR')
+        "Display this help and exit")
-    --logfile [FILE]        Full PATH to logfile.  (Default is '${HOME}/logs/$(basename "$0").log')
+$(_usageCommands_ \
-    -n, --dryrun            Non-destructive. Makes no permanent changes.
+            "--loglevel [LEVEL]" \
-    -q, --quiet             Quiet (no output)
+            "One of: FATAL, ERROR (default), WARN, INFO, NOTICE, DEBUG, ALL, OFF")
-    -v, --verbose           Output more information. (Items echoed to 'verbose')
+$(_usageCommands_ \
-    --force                 Skip all user interaction.  Implied 'Yes' to all actions.
+            "--logfile [FILE]" \
+            "Full PATH to logfile.  (Default is '${HOME}/logs/$(basename "$0").log')")
+$(_usageCommands_ \
+            "-n, --dryrun" \
+            "Non-destructive. Makes no permanent changes." \
+            2)
+$(_usageCommands_ \
+            "-q, --quiet" \
+            "Quiet (no output)")
+$(_usageCommands_ \
+            "-v, --verbose" \
+            "Output more information. (Items echoed to 'verbose')")
+$(_usageCommands_ \
+            "--force" \
+            "Skip all user interaction.  Implied 'Yes' to all actions.")
 
-  ${bold}Example Usage:${reset}
+  ${bold}${underline}Example Usage:${reset}
 
       ${gray}# Run the script and specify log level and log file.${reset}
       $(basename "$0") -vn --logfile "/path/to/file.log" --loglevel 'WARN'

template_standalone.sh

@@ -600,6 +600,65 @@ _parseOptions_() {
     fi
 }
 
+_usageCommands_() {
+    # DESC:
+    #					Used to add commands to the _usage_ function.  Prints commands and their descriptions
+    #         in two aligned columns.  Uses an option 4 character tab count to indent the commands.
+    # ARGS:
+    #         $1 (required): Key name (left column text)
+    #         $2 (required): Long value (right column text. Wraps around if too long)
+    #         $3 (optional): Number of 4 character tabs to indent the command (default 1)
+    # OUTS:
+    #         stdout: Prints the output in columns
+    # NOTE:
+    #         Long text or ANSI colors in the first column may create display issues
+    # USAGE:
+    #         _usageCommands_ "Key" "Long value text" [tab level]
+
+    [[ $# -lt 2 ]] && fatal "Missing required argument to ${FUNCNAME[0]}"
+
+    local _key="$1"
+    local _value="$2"
+    local _tabSize=4
+    local _tabLevel="${3-}"
+    local _line
+    local _rightIndent
+    local _leftIndent
+    if [[ -z ${3-} ]]; then
+        _tabLevel=1
+    fi
+
+    _leftIndent="$((_tabLevel * _tabSize))"
+
+    local _leftColumnWidth="$((32 - _leftIndent))"
+
+    if [ "$(tput cols)" -gt 180 ]; then
+        _rightIndent=80
+    elif [ "$(tput cols)" -gt 160 ]; then
+        _rightIndent=60
+    elif [ "$(tput cols)" -gt 130 ]; then
+        _rightIndent=30
+    elif [ "$(tput cols)" -gt 120 ]; then
+        _rightIndent=20
+    elif [ "$(tput cols)" -gt 110 ]; then
+        _rightIndent=10
+    else
+        _rightIndent=0
+    fi
+
+    local _rightWrapLength=$(($(tput cols) - _leftColumnWidth - _leftIndent - _rightIndent))
+
+    local _first_line=0
+    while read -r _line; do
+        if [[ ${_first_line} -eq 0 ]]; then
+            _first_line=1
+        else
+            _key=" "
+        fi
+        printf "%-${_leftIndent}s${bold}${white}%-${_leftColumnWidth}b${reset} %b\n" "" "${_key}${reset}" "${_line}"
+    done <<<"$(fold -w${_rightWrapLength} -s <<<"${_value}")"
+}
+
 _usage_() {
     cat <<USAGE_TEXT
 
@@ -607,17 +666,31 @@ _usage_() {
 
   This is a script template.  Edit this description to print help to users.
 
-  ${bold}Options:${reset}
+  ${bold}${underline}Options:${reset}
-    -h, --help              Display this help and exit
+$(_usageCommands_ \
-    --loglevel [LEVEL]      One of: FATAL, ERROR, WARN, INFO, NOTICE, DEBUG, ALL, OFF
+        "-h, --help" \
-                            (Default is 'ERROR')
+        "Display this help and exit")
-    --logfile [FILE]        Full PATH to logfile.  (Default is '${HOME}/logs/$(basename "$0").log')
+$(_usageCommands_ \
-    -n, --dryrun            Non-destructive. Makes no permanent changes.
+            "--loglevel [LEVEL]" \
-    -q, --quiet             Quiet (no output)
+            "One of: FATAL, ERROR (default), WARN, INFO, NOTICE, DEBUG, ALL, OFF")
-    -v, --verbose           Output more information. (Items echoed to 'verbose')
+$(_usageCommands_ \
-    --force                 Skip all user interaction.  Implied 'Yes' to all actions.
+            "--logfile [FILE]" \
+            "Full PATH to logfile.  (Default is '${HOME}/logs/$(basename "$0").log')")
+$(_usageCommands_ \
+            "-n, --dryrun" \
+            "Non-destructive. Makes no permanent changes." \
+            2)
+$(_usageCommands_ \
+            "-q, --quiet" \
+            "Quiet (no output)")
+$(_usageCommands_ \
+            "-v, --verbose" \
+            "Output more information. (Items echoed to 'verbose')")
+$(_usageCommands_ \
+            "--force" \
+            "Skip all user interaction.  Implied 'Yes' to all actions.")
 
-  ${bold}Example Usage:${reset}
+  ${bold}${underline}Example Usage:${reset}
 
       ${gray}# Run the script and specify log level and log file.${reset}
       $(basename "$0") -vn --logfile "/path/to/file.log" --loglevel 'WARN'

utilities/alerts.bash

@@ -334,3 +334,62 @@ _clearLine_() (
         done
     fi
 )
+
+_usageCommands_() {
+    # DESC:
+    #					Used to add commands to the _usage_ function.  Prints commands and their descriptions
+    #         in two aligned columns.  Uses an option 4 character tab count to indent the commands.
+    # ARGS:
+    #         $1 (required): Key name (left column text)
+    #         $2 (required): Long value (right column text. Wraps around if too long)
+    #         $3 (optional): Number of 4 character tabs to indent the command (default 1)
+    # OUTS:
+    #         stdout: Prints the output in columns
+    # NOTE:
+    #         Long text or ANSI colors in the first column may create display issues
+    # USAGE:
+    #         _usageCommands_ "Key" "Long value text" [tab level]
+
+    [[ $# -lt 2 ]] && fatal "Missing required argument to ${FUNCNAME[0]}"
+
+    local _key="$1"
+    local _value="$2"
+    local _tabSize=4
+    local _tabLevel="${3-}"
+    local _line
+    local _rightIndent
+    local _leftIndent
+    if [[ -z ${3-} ]]; then
+        _tabLevel=1
+    fi
+
+    _leftIndent="$((_tabLevel * _tabSize))"
+
+    local _leftColumnWidth="$((32 - _leftIndent))"
+
+    if [ "$(tput cols)" -gt 180 ]; then
+        _rightIndent=80
+    elif [ "$(tput cols)" -gt 160 ]; then
+        _rightIndent=60
+    elif [ "$(tput cols)" -gt 130 ]; then
+        _rightIndent=30
+    elif [ "$(tput cols)" -gt 120 ]; then
+        _rightIndent=20
+    elif [ "$(tput cols)" -gt 110 ]; then
+        _rightIndent=10
+    else
+        _rightIndent=0
+    fi
+
+    local _rightWrapLength=$(($(tput cols) - _leftColumnWidth - _leftIndent - _rightIndent))
+
+    local _first_line=0
+    while read -r _line; do
+        if [[ ${_first_line} -eq 0 ]]; then
+            _first_line=1
+        else
+            _key=" "
+        fi
+        printf "%-${_leftIndent}s${bold}${white}%-${_leftColumnWidth}b${reset} %b\n" "" "${_key}${reset}" "${_line}"
+    done <<<"$(fold -w${_rightWrapLength} -s <<<"${_value}")"
+}