diff --git a/README.md b/README.md index 869f39b..8e41dab 100644 --- a/README.md +++ b/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. diff --git a/template.sh b/template.sh index 1b1b3f2..7e1e8dd 100755 --- a/template.sh +++ b/template.sh @@ -295,17 +295,31 @@ _usage_() { This is a script template. Edit this description to print help to users. - ${bold}Options:${reset} - -h, --help Display this help and exit - --loglevel [LEVEL] One of: FATAL, ERROR, WARN, INFO, NOTICE, DEBUG, ALL, OFF - (Default is 'ERROR') - --logfile [FILE] Full PATH to logfile. (Default is '${HOME}/logs/$(basename "$0").log') - -n, --dryrun Non-destructive. Makes no permanent changes. - -q, --quiet Quiet (no output) - -v, --verbose Output more information. (Items echoed to 'verbose') - --force Skip all user interaction. Implied 'Yes' to all actions. + ${bold}${underline}Options:${reset} +$(_usageCommands_ \ + "-h, --help" \ + "Display this help and exit") +$(_usageCommands_ \ + "--loglevel [LEVEL]" \ + "One of: FATAL, ERROR (default), WARN, INFO, NOTICE, DEBUG, ALL, OFF") +$(_usageCommands_ \ + "--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' diff --git a/template_standalone.sh b/template_standalone.sh index de0c919..afbdb22 100755 --- a/template_standalone.sh +++ b/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 <