Awesome
Bash Common Helpers
This repository contains Bash utility functions I use in my Bash (and Zsh)
scripts regularly. These functions are provided through a small library
called bash-common-helpers
. The library saves the trouble to redefine
commonly used helper functions every time you write a shell script – be it
a simple, quickly written script or a more elaborate utility. Especially in the
first case, the library may save a great part of the development time.
Overview
The library currently provides the following helper functions:
Script Initialization
cmn_init
– supposed to be called at the beginning of every script. Makes scripts more robust by setting various shell options.cmn_assert_running_as_root
– makes sure that the script is run as root.
Printing to the Screen
cmn_echo_info
– prints informative message in green letters.cmn_echo_important
– prints message of higher importance in yellow letters.cmn_echo_warn
– prints warning in red letters.
Error Handling
cmn_die
– writes message in red letters to standard error and exits.
Availability of Commands and Files
cmn_assert_command_is_available
– makes sure that the given command is available.cmn_assert_file_exists
– makes sure that the given regular file exists.cmn_assert_file_does_not_exist
– makes sure that the given file does not exist.
User Interaction
cmn_ask_to_continue
– asks the user whether to continue or not.cmn_ask_for_password
– prompts the user for a password. Instead of echoing the entered characters, asterisks (*
) are printed.cmn_ask_for_password_twice
– asks the user for her password twice and checks if both inputs match.
File Utilities
cmn_replace_in_files
– replaces given string in files. The function uses perl to provide a robust implementation.
Parsing INI Files
cmn_parse_ini_file
– parses INI file using Ruediger Meier's "simple INI file parser".cmn_assert_ini_variables_exist
– makes sure that the given INI variables exist and provides feedback to the user if not.
Note prefix cmn_
which is supposed to avoid clashes with the names of
functions defined in your script or in any other included script.
Installation
In a nutshell: just make a clone of this repository on your harddisk and load the library by sourcing it.
For instance, go to directory ~/local/lib
and clone the repository there. In
this case, the library files will end up in directory
~/local/lib/bash-common-helpers
.
Now, you have to source
the main library file in your scripts. This basically
reads and executes the commands in the library files in your script's context
and thus makes all the library helper functions available to your script.
Using an Environment Variable
I prefer to set an environment variable that refers to the library path and
to use that variable to source
the library file in my scripts. This way, when
I move the library on my hard disk, I do not have to adapt all my scripts but
the environment variable only.
To set the environment variable, add the following line to your .bashrc
,
.zshrc
, or whatever rcfile file you are using:
export BASH_COMMON_HELPERS_LIB="~/local/lib/bash-common-helpers/bash-common-helpers.sh"
Then, use the following header in your scripts:
#!/bin/bash
# BEGIN: Read functions from bash-common-helpers library.
if [[ -z "${BASH_COMMON_HELPERS_LIB}" ]]; then
echo "Required environment variable is not set: BASH_COMMON_HELPERS_LIB"
exit 1
fi
if [[ ! -f "${BASH_COMMON_HELPERS_LIB}" ]]; then
echo "Required file does not exist: ${BASH_COMMON_HELPERS_LIB}"
exit 2
fi
source "${BASH_COMMON_HELPERS_LIB}"
cmn_init || exit 3
# END: Read functions from bash-common-helpers library.
# Your actual script starts here.
cmn_echo_info "Could source lib file successfully."
Using Path to Library Directly
Of course, you can omit the above environment variable and refer to the library directly:
#!/bin/bash
# BEGIN: Read functions from bash-common-helpers library.
BASH_COMMON_HELPERS_LIB="~/local/lib/bash-common-helpers/bash-common-helpers.sh"
if [[ ! -f "${BASH_COMMON_HELPERS_LIB}" ]]; then
echo "Required file does not exist: ${BASH_COMMON_HELPERS_LIB}"
exit 1
fi
source "${BASH_COMMON_HELPERS_LIB}"
cmn_init || exit 2
# END: Read functions from bash-common-helpers library.
# Your actual script starts here.
cmn_echo_info "Could source lib file successfully."
Documentation
For the documentation of the library, please refer to the source code: each function in the library has an explaining comment which is written above it. That comment contains the purpose of the function as well as an example which shows how to call the function.
Credits
Many functions have their roots in various web pages, blog posts, and lastly in answers provided by the phenomenal Stack Exchange Q&A communities. Whenever possible, I refer to the most relevant source in the documentation of the functions.
Function cmn_parse_ini_file
uses Ruediger Meier's "simple INI file parser"
which is available at GitHub.
Actually, the library includes that parser for reasons of convenience.
Last but not least, the library contains valuable knowledge and experience of coworkers who showed my one or two tricks.
License
Released under the MIT License (MIT) – see file LICENSE in this software's repository.