Bashful

Bashful: A collection of handy helper functions for creating and unit-testing powerful and flexible Bash scripts.

Overview

Bashful "modules" are Bash scripts that can be included directly within a calling Bash script. Modules are grouped by, and named, according to the functionality contained within:

Module Name	Purpose
bashful	Provides functions to: track and determine whether Bashful modules have been loaded; inspect the state of variables and functions; write output to STDOUT and STDERR.
error	Provides functions to generate error messages for common error scenarios.
list	Provides functions to join, split, and translate lists of strings.
litest	Provides a framework to execute one or more unit tests or performance tests for Bash script functions, reporting success, failure, and timing.
match	Provides functions to match wildcards within strings, and retrieve values for matching keys within a list of key/value pairs.
opts	Provides a framework to allow Bash scripts to support short and long command-line option switches, by executing callbacks when encountering switches.
path	Provides functions to inspect and normalize filesystem paths.
sanitize	Provides an additional layer of safety when executing Bash scripts, by: disabling aliases or functions whose name conflicts with built-in keywords; and enabling shell options that perform additional safety checks.
seq	Provides functions to generate permutations of sequences and sets.
ssh-spec	Provides functions to parse an advanced syntax that describes SSH connections, and the possible certificates and jump servers they might use.
text	Provides functions to trim and escape text representations.

How to Load Modules

NOTE: All examples within this section assume that the Bashful library is located within a subdirectory named bashful relative to the calling script.

Sourcing vs. Executing

Bashful modules are expected to be included within calling scripts by using the source or . keywords. An error will be generated if Bashful modules are executed as scripts.

Including bashful

Most Bashful modules require that bashful.inc.sh is loaded first:

source "${0%/*}/bashful/bashful.inc.sh" || exit 1

Helpful Bashful Variables

After loading bashful, the following helpful variables are available to facilitate the loading of other modules and scripts:

Variable Name	Purpose
BASHFUL_VERSION	The Bashful version number
BASHFUL_PATH	The path in which Bashful modules are located
SCRIPT_INVOKED_NAME	The path and name of the calling script
SCRIPT_NAME	The name of the calling script
SCRIPT_INVOKED_PATH	The path of the calling script
SCRIPT_RUN_DATE	The date and time at which the script included Bashful
SCRIPT_DEBUG_LEVEL	A script debugging level variable that can be used to determine whether certain types of output get echoed to the TTY

Conditionally Loading Modules

It is a best practice to only load a Bashful module if it hasn't already been loaded. Nonetheless, each Bashful module checks to see if it has already been loaded, and if it has, returns out of the module without re-executing the logic within.

To conditionally load bashful, first check to see if the variable BASHFUL_VERSION is empty:

[[ -n "${BASHFUL_VERSION:-}" ]] || \
    source "${0%/*}/bashful/bashful.inc.sh" || exit 1

Once bashful has been loaded, the function isModuleLoaded can be executed to verify whether a specific module has been loaded. In the following example, the module opts will be loaded conditionally :

isModuleLoaded 'opts' || \
    source "${BASHFUL_PATH}/bashful-opts.inc.sh" || exit 1

Verifying Module Dependencies

Bashful modules track dependencies so that calling scripts can fail themselves if required modules haven't been loaded. To do so, execute the function verifyBashfulDependencies:

verifyBashfulDependencies || exit

Using sanitize

sanitize can be sourced by scripts to help protect against situations in which user-defined functions and aliases interfere with built-in Bash keywords. Additional shell safety options are also enabled. Sanitization is entirely optional, and does not require bashful.inc.sh to have been loaded first.

The calling script should execute the following statements to sanitize the script environment:

source "${0%/*}/bashful/bashful-sanitize.inc.sh" || exit 1

To be extra cautious against scenarios where the source keyword may have been overridden, execute the following statements:

POSIXLY_CORRECT=1 && builtin unset -f builtin source unset POSIXLY_CORRECT
source "${0%/*}/bashful/bashful-sanitize.inc.sh" || exit 1

Bashful Unit Tests

Bashful comes with the following unit test scripts to verify the majority of functionality within its modules:

Script Name	Purpose
tests/all.sh	Executes every unit test script within Bashful
tests/list.sh	Executes unit test cases for the list module
tests/match.sh	Executes unit test cases for the match module
tests/seq.sh	Executes unit test cases for the seq module
tests/sshs.sh	Executes unit test cases for the ssh-spec module
tests/text.sh	Executes unit test cases for the text module

Module Dependencies

Module Name	Script	Requires	Required By
bashful	bashful.inc.sh	None	error, opts
error	bashful-error.inc.sh	bashful	None
list	bashful-list.inc.sh	text	match, seq, ssh-spec
litest	bashful-litest.inc.sh	None	None
match	bashful-match.inc.sh	list, text	ssh-spec
opts	bashful-opts.inc.sh	bashful	None
path	bashful-path.inc.sh	None	None
sanitize	bashful-sanitize.inc.sh	None	None
seq	bashful-seq.inc.sh	list	ssh-spec
ssh-spec	bashful-ssh-spec.inc.sh	list, match, seq	None
text	bashful-text.inc.sh	None	list, match

Functionality from version 1.1.2 of bash-script-lib has been migrated to this project.

Copyright 2009-2016 Dejay Clayton. All rights reserved.