A modern, safe, powerful utility library for Bash script development.
- What is Lobash?
- Lobash Features
- Build Status
- Advanced Usages
- Who use Lobash
- Related Projects
- Copyright and License
What is Lobash?
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.
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.
||BSD||-||Not tested yet. Maybe not support.|
||Windows||-||Never and ever supported.|
||Bash||v5 and higher||Completely supported|
||Bash||v3||Associative array is not supported until v4.0|
||Zsh||*||Plan to implement it in another project|
Most Lobash modules support Bash 4.0+. See module usages to find what modules not compatible with Bash 4.0.
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: BSD and GNU are both supported
Available Lobash versions refer to Git Tags which named like "vX.Y.Z".
VERSION=v0.4.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 --progress
Build your lobash.bash
First, build your own
lobash.bash file by
# 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.
Edit your scripts and set shell options
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.
Load lobash.bash in your scripts
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 set -o errtrace # You can remove this line 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 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?'
lobash.bash is fast, nearly 0.058s in fact.
time source ./dist/lobash.bash real 0m0.058s user 0m0.022s sys 0m0.036s
See available modules and categories in config.example.
See all module usages in ./doc/module-usages/.
See all module examples in ./example/modules.
Export specific modules with config
./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 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
Who use Lobash
- Contact me to add your project to list.
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 http://semver.org/ .
Copyright and License
Copyright 2019 ADoyle ([email protected]) 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.