Table of Contents
Determines whether or not a program is available on the system PATH.
@param [String]program name@return 0if program is found on system PATH@return 1if program is not found
PATHindirectly used to search for the program
Basic usage, when used as a conditional check:
if check_cmd git; then
echo "Found Git"
fiTracks a directory for later cleanup in a trap handler.
This function can be called immediately after a temp directory is created,
before a directory is created, or long after a directory exists. When used in
combination with trap_cleanup_directories, all directories registered by
calling cleanup_directory will be removed if they exist when
trap_cleanup_directories is invoked.
@param [String]path to directory@return 0if successful@return 1if a temp file could not be created
__CLEANUP_DIRECTORIES__used to track the collection of directories to clean up whose value is a file. If not declared or set, this function will set it up.
Basic usage:
dir="$(mktemp_directory)"
cleanup_directory "$dir"
# do work on directory, etc.Tracks a file for later cleanup in a trap handler.
This function can be called immediately after a temp file is created, before a
file is created, or long after a file exists. When used in combination with
trap_cleanup_files, all files registered by calling cleanup_file will be
removed if they exist when trap_cleanup_files is invoked.
@param [String]path to file@return 0if successful@return 1if a temp file could not be created
__CLEANUP_FILES__used to track the collection of files to clean up whose value is a file. If not declared or set, this function will set it up.
Basic usage:
file="$(mktemp_file)"
cleanup_file "$file"
# do work on file, etc.Prints an error message to standard error and exits with a non-zero exit code.
@param [String]warning text@stderrwarning text message
TERMused to determine whether or not the terminal is capable of printing colored output.
This function calls exit and will not return.
Basic usage:
die "No program to download tarball"Downloads the contents at the given URL to the given local file.
This implementation attempts to use the curl program with a fallback to the
wget program and a final fallback to the ftp program. The first download
program to succeed is used and if all fail, this function returns a non-zero
code.
@param [String]download URL@param [String]destination file@return 0if a download was successful@return 1if a download was not successful
At least one of curl, wget, or ftp must be compiled with SSL/TLS support
to be able to download from https sources.
Basic usage:
download http://example.com/file.txt /tmp/file.txtIndents the output from a command while preserving the command's exit code.
In minimal/POSIX shells there is no support for set -o pipefail which means
that the exit code of the first command in a shell pipeline won't be addressable
in an easy way. This implementation uses a temp file to ferry the original
command's exit code from a subshell back into the main function. The output can
be aligned with a pipe to sed as before but now we have an implementation
which mimics a set -o pipefail which should work on all Bourne shells. Note
that the set -o errexit is disabled during the command's invocation so that
its exit code can be captured.
Based on implementation from Stack Overflow
@param [String[]]command and arguments@returnthe exit code of the command which was executed
In order to preserve the output order of the command, the stdout and stderr
streams are combined, so the command will not emit its stderr output to the
caller's stderr stream.
Basic usage:
indent cat /my/fileCompletes printing an informational, detailed step to standard out which has no
output, started with info_start.
@stdoutinformational heading text@return 0if successful
TERMused to determine whether or not the terminal is capable of printing colored output.
Basic usage:
info_endPrints an informational, detailed step to standard out which has no output.
@param [String]informational text@stdoutinformational heading text@return 0if successful
TERMused to determine whether or not the terminal is capable of printing colored output.
Basic usage:
info_start "Copying file"Prints an informational, detailed step to standard out.
@param [String]informational text@stdoutinformational heading text@return 0if successful
TERMused to determine whether or not the terminal is capable of printing colored output.
Basic usage:
info "Downloading tarball"Creates a temporary directory and prints the name to standard output.
Most system use the first no-argument version, however Mac OS X 10.10 (Yosemite) and older don't allow the no-argument version, hence the second fallback version.
All tested invocations will create a file in each platform's suitable temporary directory.
@param [optional, String]parent directory@stdoutpath to temporary directory@return 0if successful
Basic usage:
dir="$(mktemp_directory)"
# use directoryWith a custom parent directory:
dir="$(mktemp_directory $HOME)"
# use directoryCreates a temporary file and prints the name to standard output.
Most systems use the first no-argument version, however Mac OS X 10.10 (Yosemite) and older don't allow the no-argument version, hence the second fallback version.
All tested invocations will create a file in each platform's suitable temporary directory.
@param [optional, String]parent directory@stdoutpath to temporary file@return 0if successful
Basic usage:
file="$(mktemp_file)"
# use fileWith a custom parent directory:
dir="$(mktemp_file "$HOME")"
# use filePrints an error message and exits with a non-zero code if the program is not available on the system PATH.
@param [String]program name@stderra warning message is printed if program cannot be found
PATHindirectly used to search for the program
If the program is not found, this function calls exit and will not return.
Basic usage, when used as a guard or prerequisite in a function:
need_cmd gitPrints program version information to standard out.
The minimal implementation will output the program name and version, separated
with a space, such as my-program 1.2.3. However, if the Git program is
detected and the current working directory is under a Git repository, then more
information will be displayed. Namely, the short Git SHA and author commit date
will be appended in parenthesis at end of the line. For example,
my-program 1.2.3 (abc123 2000-01-02). Alternatively, if the Git commit
information is known ahead of time, it can be provided via optional arguments.
If verbose mode is enable by setting the optional third argument to a true,
then a detailed version report will be appended to the single line "simple
mode". Assuming that the Git program is available and the current working
directory is under a Git repository, then three extra lines will be emitted:
release: 1.2.3the version stringcommit-hash: abc...the full Git SHA of the current commitcommit-date: 2000-01-02the author commit date of the current commit
If Git is not found and no additional optional arguments are provided, then only
the release: 1.2.3 line will be emitted for verbose mode.
Finally, if the Git repository is not "clean", that is if it contains
uncommitted or modified files, a -dirty suffix will be added to the short and
long Git SHA refs to signal that the implementation may not perfectly correspond
to a SHA commit.
@param [String]program name@param [String]version string@param [optional, String]verbose mode set if value if"true"@param [optional, String]short Git SHA@param [optional, String]long Git SHA@param [optional, String]commit/version date@stdoutversion information@return 0if successful
Note that the implementation for this function was inspired by Rust's
cargo version.
Basic usage:
print_version "my-program" "1.2.3"An optional third argument puts the function in verbose mode and more detail is output to standard out:
print_version "my-program" "1.2.3" "true"An empty third argument is the same as only providing two arguments (i.e. non-verbose):
print_version "my-program" "1.2.3" ""Prints a section-delimiting header to standard out.
@param [String]section heading text@stdoutsection heading text@return 0if successful
TERMused to determine whether or not the terminal is capable of printing colored output.
Basic usage:
section "Building project"Sets up state to track directories for later cleanup in a trap handler.
This function is typically used in combination with cleanup_directory and
trap_cleanup_directories.
@return 0if successful@return 1if a temp file could not be created
__CLEANUP_DIRECTORIES__used to track the collection of directories to clean up whose value is a file. If not declared or set, this function will set it up.__CLEANUP_DIRECTORIES_SETUP__used to track if the__CLEANUP_DIRECTORIES__variable has been set up for the current process
Basic usage:
setup_cleanup_directoriesUsed with cleanup_directory, setup_traps, and
trap_cleanup_directories:
setup_cleanup_directories
setup_traps trap_cleanup_directories
dir="$(mktemp_directory)"
cleanup_directory "$dir"
# do work on directory, etc.Sets up state to track files for later cleanup in a trap handler.
This function is typically used in combination with cleanup_file and
trap_cleanup_files.
@return 0if successful@return 1if a temp file could not be created
__CLEANUP_FILES__used to track the collection of files to clean up whose value is a file. If not declared or set, this function will set it up.__CLEANUP_FILES_SETUP__used to track if the__CLEANUP_FILES__variable has been set up for the current process
Basic usage:
setup_cleanup_filesUsed with cleanup_file, setup_traps, and trap_cleanup_files:
setup_cleanup_files
setup_traps trap_cleanup_files
file="$(mktemp_file)"
cleanup_file "$file"
# do work on file, etc.Sets up state to track files and directories for later cleanup in a trap handler.
This function is typically used in combination with cleanup_file and
cleanup_directory as well as trap_cleanups.
@return 0if successful@return 1if the setup was not successful
Basic usage:
setup_cleanupsUsed with cleanup_directory, cleanup_file, setup_traps, and
trap_cleanups:
setup_cleanups
setup_traps trap_cleanups
file="$(mktemp_file)"
cleanup_file "$file"
# do work on file, etc.
dir="$(mktemp_directory)"
cleanup_directory "$dir"
# do work on directory, etc.Sets up traps for EXIT and common signals with the given cleanup function.
In addition to EXIT, the HUP, INT, QUIT, ALRM, and TERM signals are
also covered.
This implementation was based on a very nice, portable signal handling thread thanks to an implementation on Stack Overflow.
@param [String]name of function to run with traps
Basic usage with a simple "hello world" cleanup function:
hello_trap() {
echo "Hello, trap!"
}
setup_traps hello_trapIf the cleanup is simple enough to be a one-liner, you can provide the command as the single argument:
setup_traps "echo 'Hello, World!'"Removes any tracked directories registered via cleanup_directory.
@return 0whether or not an error has occurred
__CLEANUP_DIRECTORIES__used to track the collection of files to clean up whose value is a file. If not declared or set, this function will assume there is no work to do.
Basic usage:
trap trap_cleanup_directories 1 2 3 15 ERR EXIT
dir="$(mktemp_directory)"
cleanup_directory "$dir"
# do work on directory, etc.Removes any tracked files registered via cleanup_file.
@return 0whether or not an error has occurred
__CLEANUP_FILES__used to track the collection of files to clean up whose value is a file. If not declared or set, this function will assume there is no work to do.
Basic usage:
trap trap_cleanup_files 1 2 3 15 ERR EXIT
file="$(mktemp_file)"
cleanup_file "$file"
# do work on file, etc.Removes any tracked files and directories registered via cleanup_file and
cleanup_directory respectively.
@return 0whether or not an error has occurred
Basic usage:
trap trap_cleanups 1 2 3 15 ERR EXITUsed with setup_traps:
setup_traps trap_cleanupsPrints a warning message to standard out.
@param [String]warning text@stdoutwarning heading text@return 0if successful
TERMused to determine whether or not the terminal is capable of printing colored output.
Basic usage:
warn "Could not connect to service"