diff --git a/src/environmentSetup/environmentSetup.sh b/src/environmentSetup/environmentSetup.sh index cfce2e523..851815232 100755 --- a/src/environmentSetup/environmentSetup.sh +++ b/src/environmentSetup/environmentSetup.sh @@ -39,59 +39,48 @@ IFS='' read -r -d '' ENVIRONMENT_SETUP_DOC <<"EOF" #/ #/ RETURN CODE(S): #/ - 0: Returned when: -#/ - Help message is requested OR -#/ - Processing is successful. -#/ - 1: Returned when: -#/ - Script needs to source file containing shell scripts, but can't find that file. -#/ - 20: Returned when: -#/ - Given option is invalid. -#/ - 21: Returned when: -#/ - Run from any directory other than the one the script is in. -#/ - 22: Retruned when: -#/ - User says they don't want to setup the current user's shell environment. -#/ - 23: Returned when: -#/ - User that's running this is one of a list of known system users -#/ (i.e. not the user's normally account). -#/ - 24: Returned when: -#/ - Back up directory already exists. Shouldn't occur unless user runs script, -#/ quickly stops it, then re-runs it. -#/ - 25: Returned when: -#/ - Failed to determine name of shell running in. -#/ - 26: Returned when: -#/ - Failed to create directory for backing up user's current shell -#/ enviroment configuration file(s). -#/ - 27: Returned when: -#/ - Failed to configure user's shell environment, but was able to revert it. -#/ - 28: Returned when: +#/ - Help message is requested and produced. +#/ - User's environment is configured. +#/ - 3: Returned when: +#/ - Failed to configure user's shell environment, but was able to revert +#/ to original environment configuration. +#/ - Failed to create file of flatpak aliases. You'll need to create alias +#/ of flatpak apps yourself. +#/ - 4: Returned when: #/ - Failed to configure user's shell environment and failed to revert to -#/ original hidden shell files (*this is bad*). -#/ - 29: Returned when: +#/ original hidden shell file(s) (*this is bad*). #/ - Failed to configure user's shell environment and failed to revert to #/ original shell directory (*this is bad*). -#/ - 30: Returned when: -#/ - Failed to configure user's shell environment and failed to remove new -#/ hidden shell file(s) from user's home directory. User will need to -#/ manually remove shell files in there home and copy the hidden shell -#/ file(s) from the back up directory to there home directory. -#/ - 31: Returned when: -#/ - Failed to configure user's shell environment and failed to copy -#/ user's original hidden shell file(s) back to there home directory. -#/ User will need to manually copy back up directory to there home -#/ directory. -#/ - 32: Returned when: -#/ - Failed to configure user's shell environment and failed to remove new -#/ shell directory from user's home directory. User will need to -#/ manually remove shell directory from there home and copy all -#/ file(s) and directory(ies) from the back up directory to there -#/ home directory. -#/ - 33: Returned when: -#/ - Failed to configure user's shell environment and fialed to copy -#/ user's original shell directory back to there home directory. User -#/ will need to manually remove hidden shell file(s) from there home -#/ and copy all file(s) and directory(ies) from the back up directory -#/ to there home directory. -#/ - 34: Returned when: -#/ - Failed to create file of flatpak app aliases. +#/ - 131: Returned when user provides a response that should lead to program exit. +#/ - 140: Returned when given option name is invalid. +#/ - 162: Returned when failed to configure user's shell environment and +#/ failed to remove new hidden shell file(s) from user's home +#/ directory. User will need to manually remove shell file(s) in +#/ their home and copy the hidden shell file(s) from the back up +#/ directory to there home directory. +#/ - 166: Returned when failed to configure user's shell environment and +#/ failed to copyuser's original hidden shell file(s) back to user's +#/ home directory. User will need to manually copy file(s) from back +#/ up directory to there home directory. +#/ - 171: Returned when failed to create directory for backing up user's +#/ current shell environment configuration file(s). +#/ - 172: Returned when failed to configure user's shell environment and +#/ failed to remove new shell directory from user's home directory. +#/ User will need to manually remove shell directory from their home +#/ directory and copy all file(s) and directory(ies) from the back up +#/ directory to their home directory. +#/ - 173: Returned when back up directory already exists. +#/ - 175: Returned when failed to configure user's shell environment and +#/ failed to copy user's original shell directory back to their home +#/ directory. User will need to manually remove hidden shell file(s) +#/ from their home and copy all file(s) and directory(ies) from the +#/ back up directory to their home directory. +#/ - 180: Returned when: +#/ - Run from any directory other than the one this script is located in. +#/ - 194: Returned when user that's running this is one of a list of known +#/ system users (i.e. not the user's normal account). +#/ - 202: Returned when can't find file that's sourced to ensure access to other shell script(s). +#/ - 209: Returned when failed to determine name of shell running in. #/ #/ EXAMPLE(S): #/ ./environmentSetup.sh @@ -101,6 +90,7 @@ IFS='' read -r -d '' ENVIRONMENT_SETUP_DOC <<"EOF" #/ TODO(S): #/ - Rather than moving user's original files to the back up directory, copy them then remove them. #/ - Set a default answer and make user input checking more robust. +#/ - Return 193 when calling user is root, 194 otherwise. EOF # Ensure script is being run from the same location as it's located. if [[ "./$(basename $0)" == $0 ]]; then @@ -111,7 +101,7 @@ if [[ "./$(basename $0)" == $0 ]]; then . $shellRoot else echo "Failed to find file used to locate (source) shell scripts ($shellRoot)." - exit 1 + exit 202 fi fi @@ -158,7 +148,7 @@ if [[ "./$(basename $0)" == $0 ]]; then *) log $errorLvl --full-title -m="Invalid given argument: '$fullArg', see doc:" echo "$ENVIRONMENT_SETUP_DOC" - return 20 ;; + exit 140 ;; esac done @@ -253,7 +243,7 @@ if [[ "./$(basename $0)" == $0 ]]; then exit 0 else log $errorLvl -m="Failed to create file of flatpak app aliases. flatpakAliasCreaator() error output:" -m="$errOut" - exit 34 + exit 3 fi else log $errorLvl -m="Failed to copy directory with shell scripts to $USER's home." @@ -270,7 +260,7 @@ if [[ "./$(basename $0)" == $0 ]]; then # Check if deletion worked. if [[ $rtOut -ne 0 ]]; then log $errorLvl -m="Failed to revert environment, you'll need to manually copy contents of '$BACK_UP_DIR' back to '$userHome'." - exit 32 + exit 172 fi else log $infoLvl -m="Skipping removal of 'shell' directory from $USER's home because it doesn't exist." @@ -288,7 +278,7 @@ if [[ "./$(basename $0)" == $0 ]]; then # Check if deletion worked. if [[ $rtOut -ne 0 ]]; then log $errorLvl -m="Failed to revert environment, you'll need to manually copy contents of '$BACK_UP_DIR' back to '$userHome'." - exit 33 + exit 175 fi else log $infoLvl -m="Skipping copying 'shell' directory from back up because the back up doesn't contain it." @@ -306,7 +296,7 @@ if [[ "./$(basename $0)" == $0 ]]; then # Stop copying files if a copy fails. if [[ $rtOut -ne 0 ]]; then log $errorLvl -m="Failed to move '$shellFilePath' to '$newShellFilePath'." - exit 30 + exit 162 fi # Revert to original hidden shell file(s). @@ -321,7 +311,7 @@ if [[ "./$(basename $0)" == $0 ]]; then # Stop copying files if a copy fails. if [[ $rtOut -ne 0 ]]; then log $errorLvl -m="Failed to move hidden files from '$BACK_UP_DIR' back to $USER's home, you'll need to manually copy contents." - exit 31 + exit 166 fi else log $warnLvl -m="Skipping copying of hidden shell file(s) because the back up doesn't contain any." @@ -340,7 +330,7 @@ if [[ "./$(basename $0)" == $0 ]]; then # Check if deletion worked. if [[ $rtOut -ne 0 ]]; then log $errorLvl -m="Failed to revert to original shell directory, you'll need to manually copy contents of '$BACK_UP_DIR' back to '$userHome'." - exit 29 + exit 4 fi fi else @@ -357,34 +347,35 @@ if [[ "./$(basename $0)" == $0 ]]; then # Check if deletion worked. if [[ $rtOut -ne 0 ]]; then log $errorLvl -m="Failed to revert to original hidden shell file(s), you'll need to manually copy contents of '$BACK_UP_DIR/' back to '$userHome/'." - exit 28 + exit 4 fi fi log $infoLvl -m="Shell environment configuration reverted." - exit 27 + exit 3 else log $errorLvl -m="Failed to create directory for backing up $USER's data." - exit 26 + exit 171 fi else log $errorLvl -m="Failed, couldn't determine shell name." - exit 25 + exit 209 fi else log $errorLvl -m="Failed because back up directory '$BACK_UP_DIR' already exists." - exit 24 + exit 173 fi else log $errorLvl -m="Failed, script must be run using your user, not '$USER'." - exit 23 + # TODO: Return 193 when calling user is root, 194 otherwise. + exit 194 fi else log $errorLvl --line-title -m="Re-launch this as the user you'd like to configure the environment of." - exit 22 + exit 131 fi else log $errorLvl -m="Failed, script must be run from the same directory it's located in." - exit 21 + exit 180 fi diff --git a/src/environmentSetup/util/flatpakAliasCreator.sh b/src/environmentSetup/util/flatpakAliasCreator.sh index 89797bb3e..7bb1e7651 100755 --- a/src/environmentSetup/util/flatpakAliasCreator.sh +++ b/src/environmentSetup/util/flatpakAliasCreator.sh @@ -33,20 +33,15 @@ IFS='' read -r -d '' FLATPAK_ALIAS_CREATOR_DOC <<"EOF" #/ #/ RETURN CODE(S): #/ - 0: Returned when: -#/ - Help message is requested OR +#/ - Help message is requested and produced. #/ - Aliases are created and written to file. -#/ - 20: Returned when: -#/ - Given option is invalid. -#/ - 21: Returned when: -#/ - Failed to create file for flatpak aliases. -#/ - 22: Returned when: -#/ - Failed to write to flatpak aliases file. File removed. -#/ - 23: Returned when: -#/ - Failed to write to flatpak aliases file. File not removed because it -#/ couldn't be accessed. -#/ - 24: Returned when: -#/ - Failed to write to flatpak aliases file and failed to remove file. -#/ User must remove it manually. +#/ - 140: Returned when given option name is invalid. +#/ - 161: Returned when failed to create file for flatpak aliases. +#/ - 161: Returned when failed to write to flatpak aliases file and file is then removed. +#/ - 162: Returned when failed to write to flatpak aliases file and failed to +#/ remove file. User must remove it manually. +#/ - 164: Returned when failed to write to flatpak aliases file and failed to +#/ remove it because it couldn't be accessed. #/ #/ EXAMPLE(S): #/ flatpakAliasCreator @@ -54,7 +49,7 @@ IFS='' read -r -d '' FLATPAK_ALIAS_CREATOR_DOC <<"EOF" #/ flatpakAliasCreator --help #/ #/ TODO(S): -#/ - NoOp +#/ - None EOF funcName=flatpakAliasCreator @@ -99,7 +94,7 @@ for fullArg in "${@}"; do *) log $errorLvl --full-title -m="Invalid given argument: '$fullArg', see doc:" echo "$FLATPAK_ALIAS_CREATOR_DOC" - return 20 ;; + exit 140 ;; esac done @@ -163,17 +158,17 @@ if [[ $rtOut -eq 0 ]]; then > >(stdOut=$(cat); typeset -p stdOut); rtOut=$?; typeset -p rtOut )" if [[ $rtVal -ne 0 ]]; then log $errorLvl -m="Failed to remove flatpak aliases file '$flatpakAliasFilePath'." - exit 24 + exit 162 fi else log $warnLvl -m="Flatpak aliases file doesn't exist or can't be accessed, removal skipped." - exit 23 + exit 164 fi log $infoLvl -m="Removed flatpak aliases file." - exit 22 + exit 161 fi else log $errorLvl -m="Failed to create file for flatpak aliases ($flatpakAliasFilePath)." - exit 21 + exit 161 fi diff --git a/src/shell/functions/README.md b/src/shell/functions/README.md index 800ef009e..c8ab2bd57 100644 --- a/src/shell/functions/README.md +++ b/src/shell/functions/README.md @@ -1,3 +1,58 @@ +# Return Codes + +Meaning of each return code: + +| Code | Returned When | Example | Note(s) | +| -------:|:--------------------------------------------------------------------------------------------- |:--------------------------------------- |:---------------------------------------------------------- | +| `0` | | | | +| `1` | POSIX Standard: `Catchall for general errors` | `let "var1 = 1/0"` | https://tldp.org/LDP/abs/html/exitcodes.html | +| `2` | POSIX Standard: `Misuse of shell builtins (according to Bash documentation)` | `empty_function() {}` | https://tldp.org/LDP/abs/html/exitcodes.html | +| `3` | Failed to execute, but it's not that bad. | Failed to change file, but reverted it. | | +| `4` | Failed to execute, and it is that bad. | Failed to change file & to revert it. | | +| `126` | POSIX Standard: `Command invoked cannot execute` | `/dev/null` | https://tldp.org/LDP/abs/html/exitcodes.html | +| `127` | POSIX Standard: `command not found` | `illegal_command` | https://tldp.org/LDP/abs/html/exitcodes.html | +| `128` | POSIX Standard: `Invalid argument to exit` | `exit 3.14159` | https://tldp.org/LDP/abs/html/exitcodes.html | +| `128+n` | POSIX Standard: `Fatal error signal "n"` | `kill -9 $PPID of script` | https://tldp.org/LDP/abs/html/exitcodes.html | +| `130` | POSIX Standard: `Script terminated by Control-C` | `Ctl-C` | https://tldp.org/LDP/abs/html/exitcodes.html | +| `131` | Control-C is handled prior to exiting or user chooses to exit through the UI. | | | +| `140` | A provided option name is invalid. | | Codes in the 14Xs relate to options. | +| `141` | A provided option value is invalid. | | | +| `142` | A required option is not provided. | | | +| `151` | A provided argument value is invalid. | | Codes in the 15Xs relate to arguments. | +| `152` | A required argument is not provided. | | | +| `160` | Required file doesn't exist. | | Codes in the 16Xs relate to file access. | +| `161` | Failed to create a file. | | | +| `162` | Failed to remove file. | | | +| `163` | File already exists. | | | +| `164` | File doesn't already exist or can't be found/accessed. | | | +| `165` | Failed to move/rename file. | | | +| `166` | Failed to copy file. | | | +| `167` | Failed to open file. | | | +| `168` | Failed read from file. | | | +| `169` | Failed to write to file. | | | +| `170` | Required directory doesn't exist. | | Codes in the 17Xs relate to directory access. | +| `171` | Failed to create a directory. | | | +| `172` | Failed to remove directory. | | | +| `173` | Directory already exists. | | | +| `174` | Directory doesn't already exist or can't be found/accessed. | | | +| `175` | Failed to move/rename directory. | | | +| `176` | Failed to copy directory. | | | +| `177` | Failed to enter directory. | | | +| `180` | Code not run from same directory it's located in. | | Codes in the 18Xs relate to the location code is run from. | +| `181` | Code not run from user's home directory. | | | +| `182` | Code not run from the correct directory (generic version of other codes). | | | +| `190` | Code sourced when it shouldn't be. | | Codes in the 19Xs relate to how the code is envoked. | +| `191` | Code isn't sourced when it should be. | | | +| `192` | Code not run by/as root when it should be. | | | +| `193` | Code run as/by root when it shouldn't be. | | | +| `194` | Code run by incorrect user. | | | +| `200` | Environment variable(s) set to unsupported value. | | Codes in the 20Xs relate to environment setup. | +| `201` | Environment variable(s) not set. | | | +| `202` | Requried script/function not accessible (doesn't exist at expected path, isn't sourced, etc). | | | +| `203` | Required system commands not accessible. | | | +| `209` | Any other environment issue. | | | +| `255` | POSIX Standard: `Exit status out of range` | `exit -1` | https://tldp.org/LDP/abs/html/exitcodes.html | + # POSIX Functions, Globals, and Constants TODO diff --git a/src/shell/functions/backUp.sh b/src/shell/functions/backUp.sh index 6554b7e88..ce6b7452f 100755 --- a/src/shell/functions/backUp.sh +++ b/src/shell/functions/backUp.sh @@ -3,6 +3,8 @@ ######################### ## Global(s)/Constant(s) ## ######################### +## Global(s) ## +# NoOp ## Constant(s) ## . $SHELL_FUNCTIONS_CONSTANTS/backUp.sh @@ -31,8 +33,7 @@ IFS='' read -r -d '' BACKUP_DOC <<"EOF" #/   #/ OPTION(S): #/ -h, --help -#/ Print this help message. Function will return code of '0'. No processing will be -#/ done. +#/ Print this help message. Function will return code of '0'. No processing will be done. #/ (OPTIONAL) #/ -q, --quiet #/ Produces no output other than error level. @@ -41,13 +42,11 @@ IFS='' read -r -d '' BACKUP_DOC <<"EOF" #/ (OPTIONAL) #/ #/ RETURN CODE(S): -#/ - 0: -#/ Returned when: -#/ - Help message is requested OR -#/ - Back up is successful. -#/ - 20: -#/ Returned when: -#/ - Given option is invalid. +#/ - 0: Returned when: +#/ - Help message is requested and produced. +#/ - Back up is successful. +#/ - 140: Returned when given option is invalid. +#/ - 203: Returned when rsync isn't installed/accessible. #/ #/ EXAMPLE(S): #/ backUp @@ -62,6 +61,7 @@ IFS='' read -r -d '' BACKUP_DOC <<"EOF" #/ - Missing back up location should be handled. EOF log -c="backUp" -m="Resetting local variable(s)..." + ############################### ## Reset/Set Local Variable(s) ## ############################### @@ -104,7 +104,7 @@ for fullArg in "${@}"; do *) log $errLvl --full-title -m="Invalid given argument: '$fullArg', see doc:" echo "$BACKUP_DOC" - exit 20 ;; + exit 140 ;; esac done @@ -116,7 +116,7 @@ if [[ "$(command -v rsync)" != "" ]]; then log $traceLvl -m="rsync is installed." else log $errLvl -m="rsync isn't installed." - exit 21 + exit 203 fi ############### diff --git a/src/shell/functions/checkRequiredOpts.sh b/src/shell/functions/checkRequiredOpts.sh index 63a5f911a..8d31220a7 100755 --- a/src/shell/functions/checkRequiredOpts.sh +++ b/src/shell/functions/checkRequiredOpts.sh @@ -1,14 +1,27 @@ #!/usr/bin/env sh + ######################### +## Global(s)/Constant(s) ## + ######################### +## Global(s) ## +# NoOp +## Constant(s) ## +# NoOp + + ##################### +## Local Variable(s) ## + ##################### +# NoOp + ############### ## Function(s) ## ############### IFS='' read -r -d '' CHECK_REQUIRED_OPTS_DOC <<"EOF" #/ DESCRIPTION: -#/ When given a message and any number of variable(s) (see '-a'), each variables will -#/ be checked to ensure it has been set to something, If it has not been, a code of -#/ '1' will be returned. If all given value(s) were set, a code of '0' will be -#/ returned. +#/ When given a message and any number of variable(s) (see '-a'), each +#/ variables will be checked to ensure it has been set to something, If it has +#/ not been, a code of '1' will be returned. If all given value(s) were set, +#/ a code of '0' will be returned. #/ #/ USAGE: checkRequiredOpts "" [OPTIONS]... #/ @@ -39,19 +52,17 @@ IFS='' read -r -d '' CHECK_REQUIRED_OPTS_DOC <<"EOF" #/ offending value be surrounded with excapted '" before and after #/ the value (i.e. "-a=\"\"'). #/ (REQUIRED) +#/ -h, --help +#/ Print this help message. Function will return code of '0'. No processing will be done. +#/ (OPTIONAL) #/ #/ RETURN CODE(S): -#/ - 0: -#/ Returned when: -#/ - Help message is requested OR -#/ - Processing is successful. -#/ - 1: -#/ Returned when: -#/ - Required argument(s) haven't been set. -#/ - 20: -#/ Returned when: -#/ - Provided option is invalid OR -#/ - No option is provided. +#/ - 0: Returned when: +#/ - Help message is requested and produced. +#/ - Processing is successful. +#/ - 3: Returned when one or more of the options provided for error checking are invalid. +#/ - 140: Returned when given option name is invalid. +#/ - 152: Returned when required argument (doc) isn't provided. #/ #/ EXAMPLE(S): #/ checkRequiredOpts --help @@ -82,7 +93,7 @@ done if [[ -z $1 ]]; then printf "# No option was provided, nothing to do, see doc bellow for usage... #\n" echo "$CHECK_REQUIRED_OPTS_DOC" - exit 20 + exit 152 else docString="$1" set -- "${@:2}" @@ -102,7 +113,7 @@ for fullArg in "${@}"; do if [[ -z $arg ]]; then printf "# Missing required argument(s), see doc bellow... #\n" echo "$docString" - exit 1 + exit 3 fi ;; -h|--help) echo "$CHECK_REQUIRED_OPTS_DOC" @@ -110,7 +121,9 @@ for fullArg in "${@}"; do *) printf "## Invalid given argument: '$fullArg', see doc: ##\n" echo "$CHECK_REQUIRED_OPTS_DOC" - exit 20 ;; + exit 140 ;; esac done +exit 0 + diff --git a/src/shell/functions/example_function.sh b/src/shell/functions/example_function.sh index 5afd49ebc..5806e3396 100755 --- a/src/shell/functions/example_function.sh +++ b/src/shell/functions/example_function.sh @@ -27,16 +27,14 @@ IFS='' read -r -d '' FUNCTION_NAME_DOC <<"EOF" #/ #/ OPTION(S): #/ -h, --help -#/ Print this help message. Function will return code of '0'. No processing will be -#/ done. +#/ Print this help message. Function will return code of '0'. No processing will be done. #/ (OPTIONAL) #/ #/ RETURN CODE(S): #/ - 0: Returned when: -#/ - Help message is requested OR +#/ - Help message is requested and produced. #/ - Processing is successful. -#/ - 20: Returned when: -#/ - Given option is invalid. +#/ - 140: Returned when given option is invalid. #/ #/ EXAMPLE(S): #/ functionName --help @@ -85,7 +83,7 @@ function functionName { *) log $errorLvl --full-title -m="Invalid given argument: '$fullArg', see doc:" echo "$FUNCTION_NAME_DOC" - return 20 ;; + exit 140 ;; esac done diff --git a/src/shell/functions/log.sh b/src/shell/functions/log.sh index 669211c37..1f86add83 100755 --- a/src/shell/functions/log.sh +++ b/src/shell/functions/log.sh @@ -1,19 +1,26 @@ #!/usr/bin/env sh - ########################################### -## Global(s)/Constant(s)/Local Variable(s) ## - ########################################### + ######################### +## Global(s)/Constant(s) ## + ######################### +## Global(s) ## +# NoOp ## Constant(s) ## # Includes constant(s) relevant to logger method. . $SHELL_FUNCTIONS_CONSTANTS/log.sh + ##################### +## Local Variable(s) ## + ##################### +# NoOp + ############### ## Function(s) ## ############### IFS='' read -r -d '' LOG_DOC <<"EOF" #/ DESCRIPTION: -#/ Used to produce log messages. Current global log level, tracked by 'SHELL_LOG_LEVEL', -#/ is used to determine if given message should be printed. +#/ Used to produce log messages. Current global log level, tracked by +#/ 'SHELL_LOG_LEVEL', is used to determine if given message should be printed. #/ #/ USAGE: log [OPTIONS]... -m="message text"... #/ @@ -22,8 +29,7 @@ IFS='' read -r -d '' LOG_DOC <<"EOF" #/ #/ OPTION(S): #/ -h, --help -#/ Print this help message. Function will return code of '0'. No processing will be -#/ done. +#/ Print this help message. Function will return code of '0'. No processing will be done. #/ (OPTIONAL) #/ -c= #/ Name of calling code (function). @@ -31,89 +37,84 @@ IFS='' read -r -d '' LOG_DOC <<"EOF" #/ (OPTIONAL) #/ -m=, --msg= #/ Message user would like log produced of. -#/ - Note: At least one of these is required. If multiple are given, each -#/ will show up on a new line. +#/ - Note: At least one of these is required. If multiple are given, +#/ each will show up on a new line. #/ (REQUIRED) #/ --line-title #/ When given, resulting log text will include a prefix and postfix. #/ - Note: Shouldn't be combined with any other title option. -#/ - Note: If no title option is given, then no prefix, postfis, header, or -#/ footer will be included in the resulting log text. +#/ - Note: If no title option is given, then no prefix, postfis, +#/ header, or footer will be included in the resulting log text. #/ (OPTIONAL) #/ --full-title -#/ When given, resulting log text will include a prefix, postfix, header, and -#/ footer. +#/ When given, resulting log text will include a prefix, postfix, header, and footer. #/ - Note: Shouldn't be combined with any other title option. -#/ - Note: If no title option is given, then no prefix, postfis, header, or -#/ footer will be included in the resulting log text. +#/ - Note: If no title option is given, then no prefix, postfis, +#/ header, or footer will be included in the resulting log text. #/ (OPTIONAL) #/ -t, --trace -#/ When given, the default *trace* formatting character will be used by prefix, -#/ postfix, header, and footer (if used). Providing this option will also cause a -#/ log message with the given text to be printed to stdout *if* the shell log level -#/ ($SHELL_LOG_LEVEL) is equal to, or higher than, *trace*. This includes: trace, -#/ debug, info, warn, and error. +#/ When given, the default *trace* formatting character will be used by +#/ prefix, postfix, header, and footer (if used). Providing this option +#/ will also cause a log message with the given text to be printed to +#/ stdout *if* the shell log level ($SHELL_LOG_LEVEL) is equal to, or +#/ higher than, *trace*. This includes: trace,debug, info, warn, and error. #/ - Note: Shouldn't be combined with any other log level option. -#/ - Note: If multiple loge level options are given in a single call, the -#/ last one given will be used. +#/ - Note: If multiple loge level options are given in a single call, +#/ the last one given will be used. #/ - Note: When no log level option is provided, *trace* level is used. #/ (DEFAULT) #/ -d, --debug -#/ When given, the default *debug* formatting character will be used by prefix, -#/ postfix, header, and footer (if used). Providing this option will also cause a -#/ log message with the given text to be printed to stdout *if* the shell log level -#/ ($SHELL_LOG_LEVEL) is equal to, or higher than, *debug*. This includes: debug, -#/ info, warn, and error. +#/ When given, the default *debug* formatting character will be used by +#/ prefix, postfix, header, and footer (if used). Providing this option +#/ will also cause a log message with the given text to be printed to +#/ stdout *if* the shell log level ($SHELL_LOG_LEVEL) is equal to, or +#/ higher than, *debug*. This includes: debug, info, warn, and error. #/ - Note: Shouldn't be combined with any other log level option. -#/ - Note: If multiple loge level options are given in a single call, the -#/ last one given will be used. +#/ - Note: If multiple loge level options are given in a single call, +#/ the last one given will be used. #/ - Note: When no log level option is provided, *trace* level is used. #/ (OPTIONAL) #/ -i, --info -#/ When given, the default *info* formatting character will be used by prefix, -#/ postfix, header, and footer (if used). Providing this option will also cause a -#/ log message with the given text to be printed to stdout *if* the shell log level -#/ ($SHELL_LOG_LEVEL) is equal to, or higher than, *info*. This includes: info, warn, -#/ and error. +#/ When given, the default *info* formatting character will be used by +#/ prefix, postfix, header, and footer (if used). Providing this option +#/ will also cause a log message with the given text to be printed to +#/ stdout *if* the shell log level ($SHELL_LOG_LEVEL) is equal to, or +#/ higher than, *info*. This includes: info, warn, and error. #/ - Note: Shouldn't be combined with any other log level option. -#/ - Note: If multiple loge level options are given in a single call, the -#/ last one given will be used. +#/ - Note: If multiple loge level options are given in a single call, +#/ the last one given will be used. #/ - Note: When no log level option is provided, *trace* level is used. #/ (OPTIONAL) #/ -w, --warn -#/ When given, the default *warn* formatting character will be used by prefix, -#/ postfix, header, and footer (if used). Providing this option will also cause a -#/ log message with the given text to be printed to stdout *if* the shell log level -#/ ($SHELL_LOG_LEVEL) is equal to, or higher than, *debug*. This includes: warn -#/ and error. +#/ When given, the default *warn* formatting character will be used by +#/ prefix, postfix, header, and footer (if used). Providing this option +#/ will also cause a log message with the given text to be printed to +#/ stdout *if* the shell log level ($SHELL_LOG_LEVEL) is equal to, or +#/ higher than, *debug*. This includes: warn and error. #/ - Note: Shouldn't be combined with any other log level option. -#/ - Note: If multiple loge level options are given in a single call, the -#/ last one given will be used. +#/ - Note: If multiple loge level options are given in a single call, +#/ the last one given will be used. #/ - Note: When no log level option is provided, *trace* level is used. #/ (OPTIONAL) #/ -e, --error -#/ When given, the default *error* formatting character will be used by prefix, -#/ postfix, header, and footer (if used). Providing this option will also cause a -#/ log message with the given text to be printed to stdout *if* the shell log level -#/ ($SHELL_LOG_LEVEL) is equal to, or higher than, *error*. This includes: error. +#/ When given, the default *error* formatting character will be used by +#/ prefix, postfix, header, and footer (if used). Providing this option +#/ will also cause a log message with the given text to be printed to +#/ stdout *if* the shell log level($SHELL_LOG_LEVEL) is equal to, or +#/ higher than, *error*. This includes: error. #/ - Note: Shouldn't be combined with any other log level option. -#/ - Note: If multiple loge level options are given in a single call, the -#/ last one given will be used. +#/ - Note: If multiple loge level options are given in a single call, +#/ the last one given will be used. #/ - Note: When no log level option is provided, *trace* level is used. #/ (OPTIONAL) #/ #/ RETURN CODE(S): -#/ - 0: -#/ Returned when: -#/ - Help message is requested OR -#/ - Processing is successfull OR +#/ - 0: Returned when: +#/ - Help message is requested and produced. +#/ - Processing is successful #/ - No arguments are provided. -#/ - 1: -#/ Returned when: -#/ - Required argument(s) haven't been provided. -#/ - 20: -#/ Returned when: -#/ - Provided option is invalid. +#/ - 140: Returned when given option name is invalid. +#/ - 142: Returned when a required option is not provided. #/ #/ EXAMPLE(S): #/ log --help @@ -182,7 +183,7 @@ for fullArg in "${@}"; do printf "$pfix ERROR log:\t" $SHELL_FUNCTIONS/output/output.sh --pp -m="Calling function provided invalid option: '$fullArg', see doc:" echo "$LOG_DOC" - exit 20 ;; + exit 140 ;; esac done @@ -192,7 +193,7 @@ done $SHELL_FUNCTIONS/checkRequiredOpts.sh "$LOG_DOC" -a="${msg[@]}" rtVal=$? if [[ $rtVal -ne 0 ]]; then - exit $rtVal + exit 142 fi # Determine if log message should be output. @@ -234,3 +235,5 @@ if [[ $SHELL_LOG_LEVEL -ge $lvl ]]; then printf "$msg" fi +exit 0 + diff --git a/src/shell/functions/output/output.sh b/src/shell/functions/output/output.sh index ea11d6653..98f62d372 100755 --- a/src/shell/functions/output/output.sh +++ b/src/shell/functions/output/output.sh @@ -35,14 +35,14 @@ IFS='' read -r -d '' OUTPUT_DOC <<"EOF" #/ #/ OPTION(S): #/ -h, --help -#/ Print this help message. Function will return code of '0'. No processing will be -#/ done. +#/ Print this help message. Function will return code of '0'. No processing will be done. #/ (OPTIONAL) #/ -m=, --msg= #/ Message user would like formatted output produced of. #/ - Note: If multiple are given, each will show up on a new line. -#/ - Note: If one line exceeds the set max line length, it will be broken up. -#/ The est of the line will start with the same inditation. +#/ - Note: If one line exceeds the set max line length, it will be +#/ broken up. The est of the line will start with the same +#/ inditation. #/ - Note: '\t' and '\n\ will be handled as the 'printf' function would. #/ - Note: At least one instance of this option must be provided. #/ (REQUIRED) @@ -57,7 +57,7 @@ IFS='' read -r -d '' OUTPUT_DOC <<"EOF" #/ - Note: Redundant if -p. #/ (OPTIONAL) #/ -l=, --lineLength= -#/ Sets max number of characters that may be included on a sinlge line. +#/ Sets max number of characters that may be included on a single line. #/ - Note: Line length includes prefix and postfix if included. #/ - Note: Default value: 100. #/ (OPTIONAL) @@ -69,68 +69,59 @@ IFS='' read -r -d '' OUTPUT_DOC <<"EOF" #/ Sets character used by header, footer, prefix, and postfix. #/ - Note: Default value: $DEFAULT_CHAR. #/ - Note: Some special characters may require two to be given (ex. -c="%%"). -#/ - Note: Some *other* special characters may not work at all (ex. back -#/ slash). +#/ - Note: Some *other* special characters may not work at all (ex. back slash). #/ (OPTIONAL) #/ --indent= -#/ Sets number of spaces formatted message, including prefix/postfix/header/footer -#/ if used, should be indented. +#/ Sets number of spaces formatted message, including +#/ prefix/postfix/header/footer if used, should be indented. #/ - Note: Default value: $DEFAULT_INDENT. #/ (OPTIONAL) #/ -t, --trace -#/ When given, *trace* formatting character ($TRACE_CHAR) is used as formatting -#/ character. -#/ - Note: If the formatting character isn't set, and no level is provided -#/ (ex. debug, error), then the default formatting character -#/ ($DEFAULT_CHAR) is used. +#/ When given, *trace* formatting character ($TRACE_CHAR) is used as formatting character. +#/ - Note: If the formatting character isn't set, and no level is +#/ provided (ex. debug, error), then the default formatting +#/ character ($DEFAULT_CHAR) is used. #/ (OPTIONAL) #/ -d, --debug -#/ When given, *debug* formatting character ($DEBUG_CHAR) is used as formatting -#/ character. -#/ - Note: If the formatting character isn't set, and no level is provided -#/ (ex. debug, error), then the default formatting character -#/ ($DEFAULT_CHAR) is used. +#/ When given, *debug* formatting character ($DEBUG_CHAR) is used as +#/ formatting character. +#/ - Note: If the formatting character isn't set, and no level is +#/ provided (ex. debug, error), then the default formatting +#/ character ($DEFAULT_CHAR) is used. #/ (OPTIONAL) #/ -i, --info -#/ When given, *info* formatting character ($INFO_CHAR) is used as formatting -#/ character. -#/ - Note: If the formatting character isn't set, and no level is provided -#/ (ex. debug, error), then the default formatting character -#/ ($DEFAULT_CHAR) is used. +#/ When given, *info* formatting character ($INFO_CHAR) is used as +#/ formatting character. +#/ - Note: If the formatting character isn't set, and no level is +#/ provided (ex. debug, error), then the default formatting +#/ character ($DEFAULT_CHAR) is used. #/ (OPTIONAL) #/ -w, --warn -#/ When given, *warn* formatting character ($WARN_CHAR) is used as formatting -#/ character. -#/ - Note: If the formatting character isn't set, and no level is provided -#/ (ex. debug, error), then the default formatting character -#/ ($DEFAULT_CHAR) is used. +#/ When given, *warn* formatting character ($WARN_CHAR) is used as +#/ formatting character. +#/ - Note: If the formatting character isn't set, and no level is +#/ provided (ex. debug, error), then the default formatting +#/ character ($DEFAULT_CHAR) is used. #/ (OPTIONAL) #/ -e, --error -#/ When given, *error* formatting character ($ERROR_CHAR) is used as formatting -#/ character. -#/ - Note: If the formatting character isn't set, and no level is provided -#/ (ex. debug, error), then the default formatting character -#/ ($DEFAULT_CHAR) is used. +#/ When given, *error* formatting character ($ERROR_CHAR) is used as +#/ formatting character. +#/ - Note: If the formatting character isn't set, and no level is +#/ provided (ex. debug, error), then the default formatting +#/ character ($DEFAULT_CHAR) is used. #/ (OPTIONAL) #/ #/ RETURN CODE(S): -#/ - 0: -#/ Returned when: -#/ - Help message is requested OR -#/ - Processing is successfull. -#/ - 2: -#/ Returned when: -#/ - No message text is given. -#/ - 3: -#/ Returned when: -#/ - Provided indent value is negative. -#/ - 4: -#/ Returned when: -#/ - Provided max line length value is too small: -#/ - Line length - prefix - postfix > 0. -#/ - 20: -#/ Returned when: -#/ - Provided option is invalid. +#/ - 0: Returned when: +#/ - Help message is requested and produced. +#/ - Processing is successful. +#/ - 3: Returned when header/footer fails to be generated. +#/ - 140: Returned when given option name is invalid. +#/ - 141: Returned when: +#/ - Provided indent value is negative. +#/ - Provided max line length value is too small: +#/ - Line length - prefix - postfix > 0. +#/ - 142: Returned when a required option is not provided. #/ #/ EXAMPLE(S): #/ output --help @@ -144,10 +135,10 @@ IFS='' read -r -d '' OUTPUT_DOC <<"EOF" #/ output -m="line 1" -p --char="&&" #/ #/ TODO(S): -#/ - Implement: Dynamicly determine, based on last character of line being split up, if -#/ a '-' is needed. -#/ - Implement: Ability to append end of line that was too long to fit on one row to -#/ the start of the next line. +#/ - Implement: Dynamically determine, based on last character of line being +#/ split up, if a '-' is needed. +#/ - Implement: Ability to append end of line that was too long to fit on one +#/ row to the start of the next line. #/ - Implement: Support for '%' as a formatting character. EOF ############################### @@ -247,7 +238,7 @@ for fullArg in "${@}"; do *) printf "$errPrefix Calling function provided invalid option: '$fullArg', see doc:\n" echo "$OUTPUT_DOC" - exit 20 ;; + exit 140 ;; esac done @@ -258,7 +249,7 @@ done if [[ -z "${msg[@]}" ]]; then printf "$errPrefix Message text must be given, see doc:\n" echo "$OUTPUT_DOC" - exit 2 + exit 142 fi ## Ensure Valid Indent Value Was Given ## @@ -270,7 +261,7 @@ if [[ $indent -ge 0 ]]; then else printf "$errPrefix Indentation value: '$indent' invalid. Must be non-negative, see doc:\n" echo "$OUTPUT_DOC" - exit 3 + exit 141 fi # Remove prefix & postfix length from max message character(s) per line. if $prePostFix; then @@ -282,7 +273,7 @@ fi if [[ $maxAlwMsgLen -lt 1 ]]; then printf "$errPrefix Max line length of '$maxAlwLineLen' invalid because there's no room for message text. See Doc:\n" echo "$OUTPUT_DOC" - exit 4 + exit 141 fi ######################## @@ -331,15 +322,26 @@ fi if $headerFooter; then # Call function that creates header/footer. if $prePostFix; then - createHeaderFooter --prefix -l=$maxGvnLineLen -c=$fChar + cmd="createHeaderFooter --prefix -l=$maxGvnLineLen -c=$fChar" else - createHeaderFooter -l=$maxGvnLineLen -c=$fChar + cmd="createHeaderFooter -l=$maxGvnLineLen -c=$fChar" fi - # Save off header/footer. - if [[ ! -z $indentTxt ]]; then - headerFooterTxt="$indentTxt$rtCreateHeaderFooter" + unset stdOut errOut rtOut + eval "$( (eval $cmd) \ + 2> >(errOut=$(cat); typeset -p errOut) \ + > >(stdOut=$(cat); typeset -p stdOut); rtOut=$?; typeset -p rtOut )" + + # Ensure header/footer was generated successfully. + if [[ $rtOut -eq 0 ]]; then + # Save off header/footer. + if [[ ! -z $indentTxt ]]; then + headerFooterTxt="$indentTxt$stdOut" + else + headerFooterTxt=$stdOut + fi else - headerFooterTxt=$rtCreateHeaderFooter + printf "$errPrefix createHeaderFooter() failed to create header/footer text.\n" + exit 3 fi fi diff --git a/src/shell/functions/output/util/createHeaderFooter.sh b/src/shell/functions/output/util/createHeaderFooter.sh old mode 100644 new mode 100755 index 39a686d73..aebabc5ca --- a/src/shell/functions/output/util/createHeaderFooter.sh +++ b/src/shell/functions/output/util/createHeaderFooter.sh @@ -11,21 +11,19 @@ ##################### ## Local Variable(s) ## ##################### -# Used to return strings from local function(s). -rtTxt='' +# NoOp IFS='' read -r -d '' CREATE_HEADER_FOOTER_DOC <<"EOF" #/ DESCRIPTION: -#/ Returns text intended to be used as a header or footer in the 'rtTxt' local -#/ variable. +#/ Returns text intended to be used as a header or footer in std out. #/ #/ USAGE: createHeaderFooter [OPTIONS]... -l= #/ #/ NOTE(S): #/ - Method may not use the log function because this is used by that method. -#/ - This method is in the same directory as output because a local variable is used by -#/ this method to return a value to the output method when called by the output -#/ method. +#/ - This method is in the same directory as output because a local variable +#/ is used by this method to return a value to the output method when +#/ called by the output method. #/ #/ OPTION(S): #/ -c=, --char= @@ -33,16 +31,14 @@ IFS='' read -r -d '' CREATE_HEADER_FOOTER_DOC <<"EOF" #/ - Note: Default value: $DEFAULT_CHAR. #/ - Note: Some special characters may require two to be given: #/ -c="55"  _> % -#/ - Note: Some *other* special characters may not work at all (ex. back -#/ slash). +#/ - Note: Some *other* special characters may not work at all (ex. back slash). #/ (OPTIONAL) #/ -h, --help -#/ Print this help message. Function will return code of '0'. No processing will be -#/ done. +#/ Print this help message. Function will return code of '0'. No processing will be done. #/ (OPTIONAL) #/ -l=, --lineLength= -#/ Max number of characters in any line of message. Used to determine how long -#/ header/footer should be. +#/ Max number of characters in any line of message. Used to determine how +#/ long header/footer should be. #/ - Note: Line length only includes characters in message. #/ (REQUIRED) #/ --prefix @@ -51,15 +47,11 @@ IFS='' read -r -d '' CREATE_HEADER_FOOTER_DOC <<"EOF" #/ (REQUIRED/OPTIONAL) #/ #/ RETURN CODE(S): -#/ - 0: -#/ Returned when: -#/ - Help message is requested OR -#/ - Processing is successful. -#/ - 1: -#/ TODO: Returned when required option(s) are not provided. -#/ - 20: -#/ Returned when: -#/ - Provided option is invalid. +#/ - 0: Returned when: +#/ - Help message is requested and produced. +#/ - Processing is successful. +#/ - 140: Returned when given option name is invalid. +#/ - 142: TODO: Returned when required option(s) are not provided. #/ #/ EXAMPLE(S): #/ createHeaderFooter --help @@ -73,57 +65,58 @@ IFS='' read -r -d '' CREATE_HEADER_FOOTER_DOC <<"EOF" #/ - Display this message when required argument(s) are not provided. #/ - Move this function to its own file. EOF -function createHeaderFooter { - ############################### - ## Reset/Set Local Variable(s) ## - ############################### - # Tracks header/footer text. - rtTxt='' - # Tracks character used for formatting. - fChar=$DEFAULT_CHAR - # Tracks desired total length of header/footer. - declare -i len=2 + ############################### +## Reset/Set Local Variable(s) ## + ############################### +# Tracks header/footer text. +rtCreateHeaderFooter='' +# Tracks character used for formatting. +fChar=$DEFAULT_CHAR +# Tracks desired total length of header/footer. +declare -i len=2 - ##################### - ## Process Option(s) ## - ##################### - for fullArg in "${@}"; do - # Tracks value of current option. - declare arg=${fullArg#*=} + ##################### +## Process Option(s) ## + ##################### +for fullArg in "${@}"; do + # Tracks value of current option. + declare arg=${fullArg#*=} + + # Determine what option user gave. + case $fullArg in + --prefix) + rtCreateHeaderFooter+=' ' + len+=1 ;; + -l=*|--lineLength=*) + len+=$arg ;; + -c=*|--char=*) + # Track user desired formatting character(s). + fChar=$arg + # Update desired header/footer length to accommodate formatting character(s). + if [[ ${#fChar} -gt 1 ]]; then + len+=$(($((${#fChar}-1))*2)) + fi ;; + -h|--help) + echo "$CREATE_HEADER_FOOTER_DOC" + exit 0 ;; + *) + printf "$(date +'%Y/%m/%d %H:%M:%S %Z') ERROR createHeaderFooter: Caller provided invalid option: '$fullArg', see doc:\n" + echo "$CREATE_HEADER_FOOTER_DOC" + exit 140 ;; + esac +done - # Determine what option user gave. - case $fullArg in - --prefix) - rtTxt+=' ' - len+=1 ;; - -l=*|--lineLength=*) - len+=$arg ;; - -c=*|--char=*) - # Track user desired formatting character(s). - fChar=$arg - # Update desired header/footer length to accommodate formatting character(s). - if [[ ${#fChar} -gt 1 ]]; then - len+=$(($((${#fChar}-1))*2)) - fi ;; - -h|--help) - echo "$CREATE_HEADER_FOOTER_DOC" - exit 0 ;; - *) - printf "$(date +'%Y/%m/%d %H:%M:%S %Z') ERROR createHeaderFooter: Caller provided invalid option: '$fullArg', see doc:\n" - echo "$CREATE_HEADER_FOOTER_DOC" - exit 20 ;; - esac - done +## Build Header/Footer ## +while [[ ${#rtCreateHeaderFooter} -lt $len ]]; do + # When near the end, given formatting character(s) may need to be split up. + if [[ $((${#rtCreateHeaderFooter}+${#fChar})) -gt $len ]]; then + rtCreateHeaderFooter+=${fChar:0:$(($len-${#rtCreateHeaderFooter}))} + else + rtCreateHeaderFooter+=$fChar + fi +done +# Add final part of header. +rtCreateHeaderFooter+='\n' +echo "$rtCreateHeaderFooter" +exit 0 - ## Build Header/Footer ## - while [[ ${#rtTxt} -lt $len ]]; do - # When near the end, given formatting character(s) may need to be split up. - if [[ $((${#rtTxt}+${#fChar})) -gt $len ]]; then - rtTxt+=${fChar:0:$(($len-${#rtTxt}))} - else - rtTxt+=$fChar - fi - done - # Add final part of header. - rtTxt+='\n' -} diff --git a/src/shell/functions/shellName.sh b/src/shell/functions/shellName.sh index b787a22d5..c37f814aa 100755 --- a/src/shell/functions/shellName.sh +++ b/src/shell/functions/shellName.sh @@ -27,21 +27,15 @@ IFS='' read -r -d '' SHELL_NAME_DOC <<"EOF" #/   #/ OPTION(S): #/ -h, --help -#/ Print this help message. Function will return code of '0'. No processing will be -#/ done. +#/ Print this help message. Function will return code of '0'. No processing will be done. #/ (OPTIONAL) #/ #/ RETURN CODE(S): -#/ - 0: -#/ Returned when: -#/ - Help message is requested OR -#/ - Shell name has been found. -#/ - 20: -#/ Returned when: -#/ - Given option is invalid. -#/ - 21: -#/ Returned when: -#/ - Shell name couldn't be found for any reason. +#/ - 0: Returned when: +#/ - Help message is requested and produced. +#/ - Shell name has been found. +#/ - 3: Returned when shell name can't be found for any reason. +#/ - 140: Returned when given option name is invalid. #/ #/ EXAMPLE(S): #/ shellName @@ -65,7 +59,7 @@ for fullArg in "${@}"; do *) echo "Invalid given argument: '$fullArg', see doc:" echo "$SHELL_NAME_DOC" - exit 20 ;; + exit 140 ;; esac done @@ -90,6 +84,6 @@ if [[ "$SHELL" != "$shellName" && "$shellName" != "" ]]; then exit 0 else printf "Failed, couldn't determine shell name from \$SHELL ($SHELL).\n" - exit 21 + exit 3 fi