Bash-Util-Lib - Bash Utility Library

A library of bash utility functions (from output colors to parameter processing) for use in small projects.

Install

The library can be installed using the following methods.

GIT Submodules

If the library is being used inside of a GIT project, then GIT submodules can be utilized. The following commands should be executed from within the root directory of your GIT project.

To download the master branch of the library into the ./deps/bash-util-lib directory:
```
git submodule add -b master https://github.com/WSI-Services/bash-util-lib.git deps/bash-util-lib
```
NOTE: The library branch master and path ./deps/bash-util-lib may be changed to satisfy your projects requirements. To lock in a specific library version, a library tagged release version may be used in lue of the branch name.

To change the branch used of the library:

git submodule set-branch --branch v0.1.1 deps/bash-util-lib

To update changes to the library:

git submodule update --rebase --remote

Once the submodule is added or updated, make sure to commit changes to your repository.

git add .gitmodules deps/bash-util-lib
git commit -m 'Added/updated bash-util-lib submodule'

GIT Clone

If you'd rather not use GIT submodules, GIT clone may be used to download the library to the desired location. The following commands should be executed from within the root directory of your GIT project.

To download the master branch of the library into the ./deps/bash-util-lib directory:
```
git clone -b master https://github.com/WSI-Services/bash-util-lib.git deps/bash-util-lib
```
NOTE: The library branch master and path ./deps/bash-util-lib may be changed to satisfy your projects requirements. To lock in a specific library version, a library tagged release version may be used in lue of the branch name.

To change the branch used of the library:

cd deps/bash-util-lib
git checkout v0.1.1

To update changes to the library:
```
cd deps/bash-util-lib
git pull
```

Direct Download

If GIT isn't installed, you may download an archive of the library. The following commands should be executed from within the root directory of your project.

To download the master branch archive of the library into the project root directory:
```
wget https://github.com/WSI-Services/bash-util-lib/archive/master.zip
```
NOTE: The library branch master may be changed to satisfy your projects requirements. To lock in a specific library version, a library tagged release version may be used in lue of the branch name.

To extract the library archive into the ./deps directory:

unzip -q master.zip -d deps
rm master.zip
mv deps/bash-util-lib-master deps/bash-util-lib

To update changes to the library:
```
rm -Rf deps/bash-util-lib
```
Perform the download process with the correct branch and the extract process to replace the previous library.

Bash Package

If you have the Bash Package Manager (ie: bpkg) you can download the associated wsi-services/bash-util-lib package:

bpkg install wsi-services/bash-util-lib

Usage

Bash utility functions can be used by sourcing the library file in your script. To access the functions within the library, you should import the main bash library as follows.

source "deps/bash-util/bash-util-lib.sh"

Library Functions

This bash utility library provides functions to simplify writing and running bash scripts. This section lists the available functions and usage of them.

`es`

Output escape sequence with provided control code if ES_USE environment variable is true

Arguments

Name	Type	Description
`CONTROL_CODE`	string	Argument to pass to escape sequence

Exit Codes

Code	Description
`0`	Command control code output sequence
`1`	Command control code failed

Standard Out

Specified escape sequence control code

Example:

printf "Message: $(es 1m)%s$(es 0m)\n" "Output Message"

Output:

Message: Output Message

Environment Variables

Variable	Default	Description
`ES_USE`	`true`	Value as to whether to use escape sequence commands

`es_color`

Output escape sequence with provided color code for foreground or background

Arguments

Name	Type	Description
`COLOR`	string	escape sequence color integer
`FG_BG`	string	Background color if starts with 'b' or foreground if starts with 'f', not specified, or anything else

Exit Codes

Code	Description
`0`	Command control code turned off or failed
`1`	Command control code turned on and output sequence

Standard Out

Specified escape sequence color code output

Example:

printf "Message: $(es_color 31)%s$(es 0m)\n" "Output Message"

Output:

Message: Output Message

`es_color_rgb`

Output escape sequence with provided red, green, blue color code for foreground or background

Arguments

Name	Type	Description
`R`	integer	Red color integer
`G`	integer	Green color integer
`B`	integer	Blue color integer
`FG_BG`	string	Background color if starts with 'b' or foreground if starts with 'f', not specified, or anything else

Exit Codes

Code	Description
`0`	Command control code turned off or failed
`1`	Command control code turned on and output sequence

Standard Out

Specified escape sequence color code output

Example:

printf "Message: $(es_color_rgb 255 0 0)%s$(es 0m)\n" "Output Message"

Output:

Message: Output Message

`es_color_hex`

Output escape sequence with provided HEX color code for foreground or background

Arguments

Name	Type	Description
`HEX`	string	escape sequence color in HEX
`FG_BG`	string	Background color if starts with 'b' or foreground if starts with 'f', not specified, or anything else

Exit Codes

Code	Description
`0`	Command control code turned off or failed
`1`	Command control code turned on and output sequence

Standard Out

Specified escape sequence color code output

Example:

printf "Message: $(es_color_hex ff0000)%s$(es 0m)\n" "Output Message"

Output:

Message: Output Message

`es_attrib`

Output escape sequence with provided text attribute control code

Arguments

Name	Type	Description
`CONTROL_CODE`	string	escape sequence text attribute control code

Code	Description
strike	Strike-through text
hidden	Hidden text
swap	Swap foreground and background colors
blink	Slow blink
underline	Underline text
italic	Italic text
fait	Faint text
bold	Bold text
reset	Reset text formatting and colors

Exit Codes

Code	Description
`0`	Command control code turned off or failed
`1`	Command control code turned on and output sequence

Standard Out

Specified escape sequence text attribute control code output

Example:

printf "Message: $(es_attrib bold)%s$(es_attrib reset)\n" "Output Message"

Output:

Message: Output Message

`es_erase`

Output escape sequence with provided erase control code

Arguments

Name	Type	Description
`CONTROL_CODE`	string	escape sequence erase control code

Code	Description
eol	Erase from cursor position to end of line
sol	Erase from cursor position to start of line
cur	Erase the entire current line
bottom	Erase from the current line to the bottom of the screen
top	Erase from the current line to the top of the screen
clear	Clear the screen

Exit Codes

Code	Description
`0`	Command control code turned off or failed
`1`	Command control code turned on and output sequence

Standard Out

Specified escape sequence text attribute control code output

Example:

printf "Message: %b\n" "Output$(es_erase sol) Message"

Output:

                Message

`es_cursor`

Output escape sequence with provided cursor control code

Arguments

Name	Type	Description
`CONTROL_CODE`	string	Escape sequence cursor control code
`VAL1`	integer	Optional value for CONTROL_CODE
`VAL2`	integer	Optional value for CONTROL_CODE

Code	Description
abs	Move cursor to absolute position (LINE;COLUMN)
up	Move cursor up N lines (NUM)
down	Move cursor down N lines (NUM)
right	Move cursor right N columns (NUM)
left	Move cursor left N columns (NUM)
save	Save cursor position
restore	Restore cursor position
home	Move cursor to home position (0,0)

Exit Codes

Code	Description
`0`	Command control code turned off or failed
`1`	Command control code turned on and output sequence

Standard Out

Specified escape sequence cursor control code output

Example:

printf "Message: %b\n" "Output$(es_cursor left 6) Message"

Output:

Message:  Message

`nc`

Call ncurses tput command with provided arguments if command exists (CMD_TPUT) and NC_USE environment variable is true

Arguments

Name	Type	Description
`@`	array	Arguments to pass to ncurses command `tput`

Exit Codes

Code	Description
`0`	Command `tput` exists and succeeded
`1`	Command `tput` missing or failed

Standard Out

Specified ncurses tput output

Example:

printf "Message: $(nc bold)%s$(nc sgr0)\n" "Output Message"

Output:

Message: Output Message

Environment Variables

Variable	Default	Description
`CMD_TPUT`	`$(which tput)`	Path to `tput` command utility
`NC_USE`	`true`	Value as to whether to use ncurses commands
`NC_BOLD`	`$(nc bold)`	ncurses command for text bold
`NC_UNDERLINE`	`$(nc sgr 0 1)`	ncurses command for text underline
`NC_RESET`	`$(nc sgr0)`	ncurses command for text reset

`nc_color`

Output ncurses color code for foreground or background

Arguments

Name	Type	Description
`COLOR`	string	ncurses color in HEX
`FG_BG`	string	Background color if starts with 'b' or foreground if starts with 'f', not specified, or anything else

Exit Codes

Code	Description
`0`	Command `tput` exists
`1`	Command `tput` missing

Standard Out

Specified ncurses tput color code output

Example:

printf "Message: $(nc_color 031)%s$(nc sgr0)" "Output Message"

Output:

Message: Output Message

`nc_color_from_hex`

Output ncurses color index integer from HEX

Arguments

Name	Type	Description
`HEX`	string	HEX color code (RRGGBB) without number sign

Exit Codes

Code	Description
`0`	HEX value provided
`1`	HEX value not provided

Standard Out

Specified ncurses color index integer

Example:
nc_color_from_hex ff0000
Output:
196

`nc_color_hex`

Output ncurses color code in HEX for foreground or background

Arguments

Name	Type	Description
`COLOR`	string	ncurses color in HEX
`FG_BG`	string	Background color if starts with 'b' or foreground if starts with 'f', not specified, or anything else

Exit Codes

Code	Description
`0`	Command `tput` exists
`1`	Command `tput` missing

Standard Out

Specified ncurses tput color code output

Example:

printf "Message: $(nc_color_hex ff0000)%s$(nc sgr0)" "Output Message"

Output:

Message: Output Message

Environment Variables

Variable	Default	Description
`NC_BLACK`	`$(nc_color_hex 000000)`	ncurses command for text color black foreground
`NC_RED`	`$(nc_color_hex ff0000)`	ncurses command for text color red foreground
`NC_GREEN`	`$(nc_color_hex 00ff00)`	ncurses command for text color green foreground
`NC_YELLOW`	`$(nc_color_hex ffff00)`	ncurses command for text color yellow foreground
`NC_BLUE`	`$(nc_color_hex 0000ff)`	ncurses command for text color blue foreground
`NC_MAGENTA`	`$(nc_color_hex ff00ff)`	ncurses command for text color magenta foreground
`NC_CYAN`	`$(nc_color_hex 00ffff)`	ncurses command for text color cyan foreground
`NC_WHITE`	`$(nc_color_hex ffffff)`	ncurses command for text color white foreground
`NC_BLACK_BG`	`$(nc_color_hex 000000 b)`	ncurses command for text color black background
`NC_RED_BG`	`$(nc_color_hex ff0000 b)`	ncurses command for text color red background
`NC_GREEN_BG`	`$(nc_color_hex 00ff00 b)`	ncurses command for text color green background
`NC_YELLOW_BG`	`$(nc_color_hex ffff00 b)`	ncurses command for text color yellow background
`NC_BLUE_BG`	`$(nc_color_hex 0000ff b)`	ncurses command for text color blue background
`NC_MAGENTA_BG`	`$(nc_color_hex ff00ff b)`	ncurses command for text color magenta background
`NC_CYAN_BG`	`$(nc_color_hex 00ffff b)`	ncurses command for text color cyan background
`NC_WHITE_BG`	`$(nc_color_hex ffffff b)`	ncurses command for text color white background

`exit_err`

Output provided error message, optionally additional message, and exit with provided code

Arguments

Name	Type	Description
`ERR_CODE`	integer	Exit code
`ERR_MSG`	string	Message to output
`ADD_MSG`	string	[OPTIONAL] Additional message to output

Exit Codes

Code	Description
`?`	Provided `ERR_CODE` argument

Standard Error

Provided ERR_CODE and ERR_MSG using the EXIT_ERR_MSG_ERROR format; and optional UTIL_SCRIPT_CMD (if set) using the EXIT_ERR_MSG_COMMAND format

Standard Out

If provided, additional message ADD_MSG using the EXIT_ERR_MSG_ADDITIONAL format

Example:

exit_err 12 "Missing value" "Extra data here"

Output:

Error [12]: Missing value
Extra data here

Environment Variables

Variable	Default	Description
`EXIT_ERR_MSG_ERROR`	`${NC_RED}Error [${NC_BOLD}%i${NC_RESET}${NC_RED}]${NC_RESET}: ${NC_BOLD}${NC_RED}%b${NC_RESET}\n`	Variable to store `printf` style string for error message
`EXIT_ERR_MSG_COMMAND`	`${NC_RED}Command failed${NC_RESET}: ${NC_BOLD}${NC_WHITE}%b${NC_RESET}\n`	Variable to store `printf` style string for command string
`EXIT_ERR_MSG_ADDITIONAL`	`%s\n`	Variable to store `printf` style string for additional string
`UTIL_SCRIPT_CMD`		Variable to hold command string

`file_find_line`

Output last line number in provided file which matches provided pattern

Arguments

Name	Type	Description
`FILE_NAME`	string	File to scan for pattern
`PATTERN`	string	Pattern to scan file for

Exit Codes

Code	Description
`0`	Lines found
`1`	Lines not found

Standard Out

Line number of last matching line pattern

Example:

file_find_line "/path/to/file.ext" "^#{2}\wSTART:\w${TAG}$"

Output:

`file_get_lines`

Output lines of provided file from provided start line till provided stop line

Arguments

Name	Type	Description
`FILE_NAME`	string	File to clip lines from
`START_LINE`	integer	Line number to begin clip
`STOP_LINE`	integer	Line number to end clip

Exit Codes

Code	Description
`0`	Lines found
`1`	Lines not found

Standard Out

Specified lines from file

Example:

file_get_lines "/path/to/file.ext" "24" "26"

Output:

## START: Test
function test { :; }
## STOP: Test

`string_expand`

Output provided input processed to expand variables

Arguments

Name	Type	Description
`INPUT`	string	Text to evaluate for expansion

Exit Codes

Code	Description
`0`	String expanded
`1`	String missing

Standard Out

Specified string expanded

Example:

string_expand "Output: \${STRING}"

Output:

Output: Test

`file_expand_lines`

Output text from section in file specified by provided patterns

Arguments

Name	Type	Description
`FILE_NAME`	string	File to clip lines from
`START_PATTERN`	string	Pattern of the start line to output
`STOP_PATTERN`	string	Pattern of the stop line to output

Exit Codes

Code	Description
`0`	Lines found and expanded
`1`	Lines not found

Standard Out

Specified lines from file expanded

Example:

file_expand_lines "/path/to/file.ext" "^#{2}\wSTART:\w${TAG}$" "^#{2}\wSTOP:\w${TAG}$"

Output:

function test { :; }

`grab_text_blob`

Output text from text blob in file specified by provided blob name

Arguments

Name	Type	Description
`BLOB_NAME`	string	Name of the blob of text to output
`FILE_NAME`	string	File to clip lines from

Exit Codes

Code	Description
`0`	Text blob found
`1`	Text blob not found

Standard Out

Specified text blob from file expanded

Example:

grab_text_blob "BLOB_TEST" "/path/to/file.ext"

Output:

Test text blob

`function_exists`

Returns status of function existing

Arguments

Name	Type	Description
`FUNCTION_NAME`	string	Name of function to check for

Exit Codes

Code	Description
`0`	Function exists
`1`	Function does not exist

Standard Out

Example:
function_exists "missing_test"
Exit Code: 1

`process_parameters`

Process call parameters

Arguments

Name	Type	Description
`PROCESS_ARG_FN`	string	Name of argument process function
`PROCESS_OPT_FN`	string	Name of option process function

Exit Codes

Code	Description
`0`	Processing successful
`1`	Provided arguments processing function does not exist
`2`	Provided options processing function does not exist
`?`	Processing options function return code

Environment Variables

Variable	Default	Description
`UTIL_ARRAY_SEPARATOR`	`$(printf '\n\t\v')`	Value to use to separate positional arguments
`UTIL_PARAM_POSITIONAL`		Variable to store positional arguments

Example:

processArgs() {
    ARG1="$1"
    POS_ARG=""
    SHIFT_COUNT=0

    if [[ "${PASS_ARGS}" -gt 0 ]]; then
        POS_ARG="${ARG1}"
        SHIFT_COUNT=$((SHIFT_COUNT+1))
    else
        case "${ARG1}" in
            -a=*|--add=*) # display details for equals-separated option value
                export ARGS_DETAILS="${ARGS_DETAILS}${ARGS_DETAILS:+ }${ARG1#*=}"
                SHIFT_COUNT=$((SHIFT_COUNT+1))
                ;;
            -a|--add)     # display details for space-separated option value
                export ARGS_DETAILS="${ARGS_DETAILS}${ARGS_DETAILS:+ }$2"
                SHIFT_COUNT=$((SHIFT_COUNT+2))
                ;;
            -l|--list)    # list all
                export LISTING=1
                SHIFT_COUNT=$((SHIFT_COUNT+1))
                ;;
            --)           # pass following arguments
                export PASS_ARGS=1
                SHIFT_COUNT=$((SHIFT_COUNT+1))
                ;;
            *)            # unknown argument
                POS_ARG="${ARG1}"
                SHIFT_COUNT=$((SHIFT_COUNT+1))
                ;;
        esac
    fi

    if [[ -n "$POS_ARG" ]]; then
        # save argument in an array for later
        export UTIL_PARAM_POSITIONAL="${UTIL_PARAM_POSITIONAL}${UTIL_PARAM_POSITIONAL:+${UTIL_ARRAY_SEPARATOR}}${POS_ARG}"
    fi

    return "${SHIFT_COUNT}"
}

dispatchCommand() {
    COMMAND="$1"
    [[ $# -gt 0 ]] && shift

    case "${COMMAND}" in
        commands) command_commands "${@}" ;;
        version)  command_version  "${@}" ;;
        help|*)   command_help     "${@}" ;;
    esac
}

process_parameters "processArgs" "dispatchCommand" "${@}"

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
coverage		coverage
.gitignore		.gitignore
.shellcheckrc		.shellcheckrc
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
bash-util-lib-test.sh		bash-util-lib-test.sh
bash-util-lib.sh		bash-util-lib.sh
bpkg.json		bpkg.json
docker-compose.yml		docker-compose.yml
shunit2.assert.command-test		shunit2.assert.command-test

License

WSI-Services/bash-util-lib

Folders and files

Latest commit

History

Repository files navigation

Bash-Util-Lib - Bash Utility Library

Install

GIT Submodules

GIT Clone

Direct Download

Bash Package

Usage

Library Functions

es

Arguments

Exit Codes

Standard Out

Environment Variables

es_color

Arguments

Exit Codes

Standard Out

es_color_rgb

Arguments

Exit Codes

Standard Out

es_color_hex

Arguments

Exit Codes

Standard Out

es_attrib

Arguments

Exit Codes

Standard Out

es_erase

Arguments

Exit Codes

Standard Out

es_cursor

Arguments

Exit Codes

Standard Out

nc

Arguments

Exit Codes

Standard Out

Environment Variables

nc_color

Arguments

Exit Codes

Standard Out

nc_color_from_hex

Arguments

Exit Codes

Standard Out

nc_color_hex

Arguments

Exit Codes

Standard Out

Environment Variables

exit_err

Arguments

Exit Codes

Standard Error

Standard Out

Environment Variables

file_find_line

Arguments

Exit Codes

Standard Out

file_get_lines

Arguments

Exit Codes

Standard Out

string_expand

Arguments

Exit Codes

Standard Out

file_expand_lines

`es`

`es_color`

`es_color_rgb`

`es_color_hex`

`es_attrib`

`es_erase`

`es_cursor`

`nc`

`nc_color`

`nc_color_from_hex`

`nc_color_hex`

`exit_err`

`file_find_line`

`file_get_lines`

`string_expand`

`file_expand_lines`

`grab_text_blob`

`function_exists`

`process_parameters`