A modern, safe, powerful utility library for Bash script development.

• What is Lobash?
• Lobash Features
• Build Status
• ChangeLog
• FAQ
• Installation
• Prerequisites
  • Supported Platform
  • Supported Shells
  • Dependencies
• Usage
  • Build your lobash.bash
  • Edit your scripts and set shell options
  • Load lobash.bash in your scripts
  • Module Usages
• Advanced Usages
  • Export specific modules with config
• Command
  • lobash meta
  • lobash mod
• Who use Lobash
• Related Projects
• References
• Test
• Contributions
• Versioning
• Copyright and License

Due to its complex syntaxes with symbols, and Unix commands are different in platforms such like BSD and GNU utilities have different options and behaviors with same command name, 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 is a library not a command. It provides collections of functions to improve efficiency of shell development, and make it compatible with Bash 4.0+ and MacOS/Linux/Alpine/Busybox systems.

• Modular and easy to use. One module one Function.
• Rich Functions. Over 110+ modules provided.
• Robust and Safe. Over 600+ test cases tested.
• Fast. 0.058s to load Lobash completely.
• Compatible with MacOS/Linux/Alpine/Busybox systems.
• Compatible with Bash 4.0 and higher versions.

• Test Branch:

Available Lobash versions refer to Git Tags which named like "vX.Y.Z".

VERSION=v0.3.1
# 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

Most Lobash modules support Bash 4.0+. See module usages to find what modules not compatible with Bash 4.0.

✅💬 means Lobash can be used but not all features supported in shell. It will print notes to show what modules is not supported and it will be ignored when building Lobash file.

If you want use Lobash with Bash 4.3 and lower versions. Please read ./doc/with-lower-version-bash.md first.

Lobash not test with Bash 4.0 in MacOS. It seems a bug of Bash 4.0 in MacOS. Please contact me if you solved this problem. See this document.

Although most Linux distributions use Bash v4.3, and MacOS not installed Bash v4 by default, it is easily to upgrade Bash 4.4+ in most systems.

Make sure below dependencies have been installed.

• Linux commands:
  • sed/grep/mktemp/dirname/basename/cd/printf/echo/wc
  • sed: BSD and GNU are both supported

First, build your own lobash.bash file by ./build.

# Interactive build process, import all Lobash modules
./build
# Generated Lobash file: <lobash-dir>/dist/lobash.bash
# Or build Lobash to specific path
./build <target-path>

See ./doc/build.md for more details.

All Lobash modules are written and tested with the shell options:

• set -o errexit
• set -o nounset
• set -o pipefail
• shopt -s inherit_errexit

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
set -o nounset
set -o pipefail
(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 build lobash.bash with default PREFIX
l.ask 'Hello Lobash?'
# Call lobash.<module_name> when build lobash.bash with PREFIX=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.036s

See all module usages in ./doc/module-usages/

./build will export all modules by default. You can export specific modules with -c <config> option.

cp config.example config
# The "config" file is ignored by git
# Edit config, select BASH_MIN_VERSION and modules to export
./build -c ./config

While Lobash is a library for development, it also provides a command ./bin/lobash.

Enter ./bin/lobash show help.

> ./bin/lobash
Usage:
  lobash [help|-h|--help]
  lobash mod <module_name> [<sub_command_args>]...
  lobash meta <module_name>
Sub-Command:
  help       Show help
  mod        Invoke a Lobash module
  mods       Show available module names
  meta       Query metadatas of Lobash module
  github     Open Lobash github page in your browser
Description:
The "lobash mod" command is only used for certain scenarios. Many modules not work as command.

> ./bin/lobash meta normalize
Module: normalize
Usage: l.normalize <path>
Description:
  - Normalize the given path which can be an unexisted path.
  - Trailing `/` always be removed.
Dependent: split, join
Deprecated: false
Since: 0.1.0
Bash: 4.0
Status: tested

Note: The "lobash mod" command is only used for certain scenarios. Many modules not work as command.

> ./bin/lobash mod ask 'Is it OK?'
Is it OK? ([Y]es/No)
YES

• adoyle-h/dotfiles
• Contact me to add your project to list.

• shell-general-colors: shell colors
• bats-core: test framework

• pure-bash-bible
• https://www.gnu.org/software/bash/manual/
• https://mywiki.wooledge.org/BashFAQ

See ./doc/test.md for more details.

Any suggestions and contributions are always welcome. Please open an issue to talk with me.

Please read ./doc/contribution.md before make a Pull Request.

The versioning follows the rules of SemVer 2.0.0.

For more information on SemVer, please visit https://semver.org/ .

Copyright 2019 ADoyle (adoyle.h@gmail.com) Some Rights Reserved.

The project is licensed under the Apache License Version 2.0.

See the LICENSE file for the specific language governing permissions and limitations under the License.

See the NOTICE file distributed with this work for additional information regarding copyright ownership.