Common Bash Library

A library of bash functions for common tasks.

common

assert_eq

Assert that two input argument strings are equal.

Arguments:

• $1: First input argument string (required)
• $2: Second input argument string (required)

Returns:

• 0 - Success (strings are equal)
• 1 - Failure (exit if strings are not equal)
• 2 - Failure (incorrect usage of function)

Usage:

assert_eq "test" "test"

assert_pass

Assert that input argument is 0.

Arguments:

• $1: Return code to check (required)

Returns:

• 0 - Success (input argument is 0)
• 1 - Failure (exit if input argument is not 0)
• 2 - Failure (incorrect usage of function)

Usage:

assert_pass 0

assert_fail

Assert that input argument is not 0.

Arguments:

• $1: Return code to check (required)

Returns:

• 0 - Success (input argument is not 0)
• 1 - Failure (exit if input argument is 0)
• 2 - Failure (incorrect usage of function)

Usage:

assert_fail 1

check_env_vars

Checks if environment variables are set.

Environment Variables:

• VERBOSE: If set to true, print verbose output (optional, defaults to false)

Arguments:

• $1..n: environment variables to check

Returns:

• 0 - Success (all environment variables are set)
• 1 - Failure (if any of the environment variables are not set)
• 2 - Failure (incorrect usage of function)

Usage:

check_env_vars PATH HOME

check_required_bins

Checks if binary exists by running command -v <binary>.

Environment Variables:

• VERBOSE: If set to true, print verbose output (optional, defaults to false)

Arguments:

• $1..n: binaries to check

Returns:

• 0 - Success (all binaries are found)
• 1 - Failure (if any of the binaries are not found)
• 2 - Failure (incorrect usage of function)

Usage:

check_required_bins git jq

install_jq

Installs jq binary.

Environment Variables:

• VERBOSE: If set to true, print verbose output (optional, defaults to false)

Arguments:

• $1: version of jq to install (optional, defaults to latest). Example format of valid version is "1.8.1"
• $2: location to install jq to (optional, defaults to /usr/local/bin)
• $3: if set to true, skips installation if jq is already detected (optional, defaults to true)
• $4: the exact url to download jq from (optional, defaults to https://github.com/jqlang/jq/releases/latest/download/jq-${os}-${arch})

Returns:

• 0 - Success (jq installed successfully)
• 1 - Failure (installation failed)
• 2 - Failure (incorrect usage of function)

Usage:

install_jq "latest" "/usr/local/bin" "true"

is_boolean

Determine if value is a boolean.

Arguments:

• $1: value to check (required)

Returns:

• 0 - Success (value is a boolean - true, True, false or False)
• 1 - Failure (value is not a boolean)
• 2 - Failure (incorrect usage of function)

Usage:

is_boolean "true"

return_mac_architecture

Returns the architecture of the MacOS.

Arguments: n/a

Returns:

• 0 - Success
  • "amd64" - if the OS is macOS and the CPU is Intel
  • "arm64" - if the OS is macOS and the CPU is Apple Silicon
• 2 - Failure (Did not detect MacOS)

Usage:

arch=$(return_mac_architecture)

ibmcloud/iam

generate_iam_bearer_token

Generates an IBM Cloud IAM bearer token from an API key.

Environment Variables:

• IBMCLOUD_API_KEY: IBM Cloud API key (required)
• IBMCLOUD_IAM_API_ENDPOINT: IBM Cloud IAM API endpoint (optional, defaults to https://iam.cloud.ibm.com)

Arguments: n/a

Returns:

• 0 - Success (token printed to stdout)
• 1 - Failure (error message printed to stderr)

Usage:

IBMCLOUD_API_KEY=XXX; token=$(generate_iam_bearer_token)

Usage

Sourcing the Library

To use these functions in your bash scripts, source the library:

source /path/to/common.sh

Running Tests

The library includes built-in unit tests. To run them, execute this script:

tests/run-tests.sh

NOTE: Some unit tests are configured to make api calls. These are disabled by default, but can be enabled by setting MAKE_API_CALLS=true. This will require setting environment variable IBMCLOUD_API_KEY with a valid IBM Cloud API key.