@renault-digital/bash-base

Welcome to bash-base

Goal

No more spending time searching the special ways of bash for basic operations like "how to replace a string in bash", then compare, choose, and test among many potential solutions.

Bash-base does this for you, you can just call the function here which is well tested and stable, and only focus you on the high level logic. Writing your script with less time, but more readability.

Available on GitHub, NPM and Docker Hub.

Test coverage report

Quick start

Creat a sample script example_docker.sh with the following content:

#!/usr/bin/env bash

source <(docker run renaultdigital/bash-base)
SHORT_DESC='an example shell script to show how to use bash-base '

args_parse $# "$@" firstName sex
args_valid_or_read firstName '^[A-Za-z ]{2,}$' "Your first name (only letters)"
args_valid_or_select_pipe sex 'Mr.|Mrs' "Your sex"

confirm_to_continue firstName sex
print_success "Hello $sex $(string_upper_first "$firstName"), nice to meet you."

Assign the execute right to it:

chmod +x example_docker.sh

Run it:

Installation

1. Import from docker hub

# One line to import & download if not yet:
source <(docker run --rm renaultdigital/bash-base)

Others

# To specify a version
source <(docker run --rm renaultdigital/bash-base:1.0.2)
# Update or uninstall
docker rmi -f renaultdigital/bash-base

2. Install from NPM

# Install the latest
npm i -g @renault-digital/bash-base

Others

# To specify a version
npm i @renault-digital/bash-base@1.6.0
# One line to import & install if not yet:
source bash-base 2>/dev/null || npm i -g @renault-digital/bash-base && source bash-base
# Verify the installation
man bash-base
# Uninstall
npm uninstall -g @renault-digital/bash-base

3. Install with basher

# Install from master branch
basher install renault-digital/bash-base

Others

• The officially supported version is bash-base v2.0.0 and later.

# To specify a version
basher install renault-digital/bash-base@v1.0.2
# Verify the installation
man bash-base
# Uninstall
basher uninstall renault-digital/bash-base

4. Web installer

# Install the latest
curl -fsSL https://git.io/bashbase-i | bash

Others

• The directory installed is ~/.bash-base.
• https://git.io/bashbase-i is redirected to install.sh
• this way, your script will access github to check whether a newer version published each time it launched. For CI, it is recommended to use a specific version to avoid unexpected failures.

# or with wget
wget -O- https://git.io/bashbase-i | bash
# Verify the installation
man bash-base
# Uninstall all versions
curl -fsSL https://git.io/bashbase-i | bash -s uninstall

To specify a version:

curl -fsSL https://git.io/bashbase-i | bash -s v1.0.2
# Verify the installation
man bash-base.v1.0.2

Check if all functions of bash-base is compatible with current environment when install:

curl -fsSL https://git.io/bashbase-i | bash -s latest verify
curl -fsSL https://git.io/bashbase-i | bash -s v1.0.2 verify

One line to import & install if not yet:

source bash-base 2>/dev/null || curl -fsSL https://git.io/bashbase-i | bash
source bash-base 2>/dev/null || curl -fsSL https://git.io/bashbase-i | bash -s latest verify

source bash-base.v1.0.2 2>/dev/null || curl -fsSL https://git.io/bashbase-i | bash -s v1.0.2
source bash-base.v1.0.2 2>/dev/null || curl -fsSL https://git.io/bashbase-i | bash -s v1.0.2 verify

5. Import from GitHub, no install

# Import latest version:
source <(curl -fsSL https://git.io/bashbase)

Others

• This way, your script need to access GitHub each time it launched.

# or with eval
eval "$(curl -fsSL https://git.io/bashbase)"
# To specify a version
source <(curl -fsSL https://raw.githubusercontent.com/renault-digital/bash-base/v1.0.2/bin/bash-base)
# Verify the import
string_trim ' hello '

6. Download archive

See GitHub releases or NPM tarball URLs

How to config

1. LOG_LEVEL

The possible values are:

• $LOG_LEVEL_ERROR or 4: enable the output of print_error/print_header
• $LOG_LEVEL_WARN or 3: enable the output of print_warn/print_args/print_success and those by level ERROR
• $LOG_LEVEL_INFO or 2: enable print_info and those by level ERROR, WARN
• $LOG_LEVEL_DEBUG or 1: enable print_debug and those by level ERROR, WARN, INFO

LOG_LEVEL=${LOG_LEVEL:-$LOG_LEVEL_INFO}

The default value $LOG_LEVEL_INFO will be used if no config existed. you can override this default value in shell script, OS environment or ci/cd pipeline variables:

export LOG_LEVEL=$LOG_LEVEL_DEBUG 
or
export LOG_LEVEL=1

2. SHORT_DESC

SHORT_DESC='a bash script using bash-base'

redefine it to show your script short description in the 'NAME' field of generated response for -h argument.

3. USAGE

USAGE=''

redefine it in your script only if the generated response for -h argument is not good for you.

All Functions

See reference

Usage Examples

See example folder, including the use case of Makefile

Specfile (test file)

See spec folder

Latest Update

See change log

Contributing

See How to contribute

License

MIT.

Changelog

2.3.2 (2021-12-23)

Bug Fixes

• shellcheck lint (d708b3b)