A modern, safe, powerful utility/library for Bash script development.
Due to its complex syntaxes and symbols, and Unix commands different options and behaviors in same name (such like GNU sed and BSD sed are different),
Bash script development is complex and fallible.
Javascript has a powerful library Lodash for simplifying development. So I build Lobash to do similar works for shell development.
Lobash provides collections of functions to improve efficiency of shell development. It is compatible with Bash 4.0+ and MacOS/Linux/Alpine/Busybox systems.
It is implemented with pure bash script. (Except l.now function. It uses perl functions.)
- Modular and easy to use. One module one Function.
- Semantic functions instead of recondite bash expressions, substitutions, expansions.
- Rich Functions. Over 140+ modules provided.
- 15 Categories: Arithmetic, Array, Color, Condition, Console, Debug, File, Path, Prompt, String, System, Terminal, Time, Util, Variable.
- Each function is documented.
- Robust and Safe. Over 700+ test cases passed in Github Actions.
- Fast. 0.058s to load Lobash completely.
- Compatible with MacOS/Linux/Alpine/Busybox systems.
- Compatible with Bash 4.0 and higher versions.
If a function needs to pass much arguments and combine much functions to accomplish this, it does not conform to the design philosophy of Lobash.
For example, a logger library could be as simple as l.log() { echo "$1" >> "$2"; }, calling l.log "message" "/var/log/file" to append a log.
It could also be complex. With many features such as Colorful Highlights, Formatting, Caller Location, Log Level, Log Storages, Log Rotation.
Lobash provides the simplest and easy-to-use functions. For complex features, please search for other projects. Here are a few recommended projects.
- ebash: implements many complex features.
- Logger: b-log or bash-logger
- Colors: shell-general-colors
A function has only input and output, no side effects. When the same input is given, it will always return the same output.
Lobash does not modify global variables. No internal variables are created to store intermediate state (ideally).
However, Lobash will modify user-passed variables to store the result of the computation in it. e.g., l.parse_params.
Bash's syntaxes and behaviors are too weird. Lobash provides semantic functions that implement a single feature to keep it simple.
Lobash helps to reduce the mental burden on developers.
Read tags for versions. The versions follow the rules of Semantic Versioning 2.0.0.
| Supported | Platform | Version | Main Reasons |
|---|---|---|---|
| ✅ | MacOS | * | - |
| ✅ | Linux | * | - |
| ✅ | Busybox | * | - |
| ✅ | Alpine | * | - |
| ❔ | BSD | - | Not tested yet. Maybe not support. |
| 🚫 | Windows | - | Never and ever supported. |
| Supported | Shell | Version | Descriptions |
|---|---|---|---|
| ✅ | Bash | v5 and higher | Completely supported |
| ✅ | Bash | v4.4 | Completely supported |
| ✅💬 | Bash | v4.3 | - |
| ✅💬 | Bash | v4.2 | - |
| ✅💬 | Bash | v4.1 | - |
| ✅💬 | Bash | v4.0 | - |
| 🚫 | Bash | v3 | Associative array is not supported until v4.0 |
| 🚫 | POSIX sh | * | local keyword not supported |
| 🚫 | Zsh | * | - |
| 🚫 | Fish | * | - |
Most Lobash modules support Bash 4.0 and higher versions. Some modules are not compatible with Bash version earlier than 4.4. See the list.
Each module annotates a Bash label in module usages.
Bash: 4.2+ means compatible with Bash 4.2 and higher versions.
✅💬 means Lobash is compatible but not all modules supported in shell. It will print notes to show what modules is not supported and ignored when building Lobash.
If you use Lobash with Bash 4.0~4.3. Please read ./docs/with-lower-version-bash.md first. It's very important.
Lobash not test with Bash 4.0 in MacOS and Linux. It seems a bug of Bash 4.0. Please contact me if you solved this problem. Read this document.
Although most Linux distributions use Bash v4.3 at the least, and MacOS installed Bash v3.2 by default, it is easily to upgrade Bash 4.4+ in most systems.
Bash below 4.4 have a lot of bugs. It's strongly advised to upgrade to Bash 4.4 or above.
Make sure below dependencies have been installed in your system.
- Linux commands:
- sed/grep/mktemp/dirname/basename/cd/printf/echo/wc
- sed: BSD and GNU are both compatible with Lobash
Available Lobash versions refer to Git Tags which named like "vX.Y.Z".
VERSION=v0.7.0 # or VERSION=develop, but develop branch is unstable.
# Download source codes
git clone --depth 1 --branch $VERSION https://github.com/adoyle-h/lobash.git
cd lobash
# This step is optional. Clone submodules only if you want to run test cases.
git submodule update --init --recursive --progress
# Copy it to somewhere in your path
sudo ln -s "$PWD/build" /usr/local/bin/lobash-genlobash-gen -h show help.
First, build your own lobash.bash file by lobash-gen.
# Interactive build process, import all Lobash modules
lobash-gen
# Generated file: ./lobash.bash
# Or build Lobash to specific path
lobash-gen <target-path>
# Generated file: <target-path>Read ./docs/build.md for more details.
All Lobash modules are written and tested with the shell options:
set -o errexitset -o nounsetset -o pipefailshopt -s inherit_errexit(inherit_errexitis a new feature in Bash v4.4)
If you do not understand the meanings of these shell options, please read this article.
Lobash not enable these options by default. Make sure the same shell options enabled before call Lobash functions in your scripts. Otherwise there may be unexpected behaviors with it.
Second, load your own lobash.bash file in your scripts and all Lobash functions will be imported to current shell environment.
#!/usr/bin/env bash
set -o errexit -o nounset -o pipefail -o errtrace # You can remove "-o errtrace" if you do not use l.trap_error.
(shopt -p inherit_errexit &>/dev/null) && shopt -s inherit_errexit
# It will load all Lobash modules
source <path-to-lobash.bash>
# Call l.<module_name> when "lobash-gen"
l.ask 'Hello Lobash?'
# Call lobash.<module_name> when "lobash-gen -p lobash_"
# lobash_ask 'Hello Lobash?'Load lobash.bash is fast, nearly 0.058s in fact.
time source ./dist/lobash.bash
real 0m0.058s
user 0m0.022s
sys 0m0.036sRead all module usages in ./docs/module-usages/.
Read all module examples in ./example/modules and test cases.
Available modules list in config.example.
lobash-gen will export all modules by default. You can export specific modules with -c <config> option.
You can also set PREFIX, BASH_MIN_VERSION in config.
cp config.example config
# The "config" file is ignored by git
# Edit config
lobash-gen -c ./config- one.bash
- Contact me to add your project to list.
- shell-general-colors: shell colors
- bats-core: test framework
- Other shell projects created by me.
Before opening new Issue/Discussion/PR and posting any comments, please read ./docs/CONTRIBUTING.md.
Copyright 2019-2024 ADoyle (adoyle.h@gmail.com). Some Rights Reserved. The project is licensed under the Apache License Version 2.0.
Read the LICENSE file for the specific language governing permissions and limitations under the License.
Read the NOTICE file distributed with this work for additional information regarding copyright ownership.
