L_lib.sh

Labrador Bash library. Collection of functions and libraries that I deem useful for working with Bash.

• Documentation
• Installation
• Usage
• Features
• Conventions
• License

Installation

Package Managers

Install L_lib using your preferred Bash package manager:

Basher

basher install Kamilcuk/L_lib

bpkg

bpkg install Kamilcuk/L_lib

Shpkg

shpkg install Kamilcuk/L_lib

Manual Installation

The library is one file. Download the latest release from GitHub and put in your PATH:

mkdir -vp ~/.local/bin/
wget -O ~/.local/bin/L_lib.sh https://raw.githubusercontent.com/Kamilcuk/L_lib/refs/heads/v1/bin/L_lib.sh
export PATH=~/.local/bin:$PATH

Pip

pip install L_lib

Basher

basher install Kamilcuk/L_lib

Usage

You can use the library in scripts with:

. L_lib.sh -s

Unless -n, sourcing the library will enable extglob and patsub_replacement and, if set -e is set and there is no ERR trap, it will also register a ERR trap that will print a nice traceback on unhandled error.

For example, a simple script using the library could look like:

#!/bin/bash
. L_lib.sh -s
L_log "Starting script"
L_info "This is an info message"

You can test the library ad-hoc:

bash <(wget -qO- https://raw.githubusercontent.com/Kamilcuk/L_lib/refs/heads/v1/bin/L_lib.sh) L_setx L_log 'Hello world'

Features

Below is a selection of the library's features. The library contains much more.

• Argument parsing in Bash with short, long options, sub-parsers, sub-functions support and shell completion L_argparse
• Logging library with levels and configurable output and filtering L_log_configure L_info L_logrun L_run
• Pretty function stack printing usually on ERR trap L_print_traceback
• Execute an action on EXIT, any terminating signal or RETURN trap of any function L_finally
• Create temporary directory and cd to it for the duration of a function with auto removal after return L_with_cd L_with_cd_tmpdir
• Create unidirectional connected two file descriptors L_pipe
• Create and manage multiple processes with separate file descriptors for standard input and standard output L_proc_popen L_proc_communicate L_proc_kill
• Temporary enable or disable shell features set -x for the duration of a command L_setx L_unsetx L_extglob
• Easily sort a Bash arrays containing any characters L_sort
• Failure handling utilities L_assert L_die L_check L_panic
• Variables holding color codes depending on terminal support L_color_detect $L_RED $L_BLUE
• Checking Bash features and version $L_BASH_VERSION $L_HAS_BASH4_0 $L_HAS_COMPGEN_V $L_HAS_WAIT_N
• Waiting on multiple PIDs with a timeout ignoring signals and collecting all exit codes L_wait
• Simplify storing exit status of a command into a variable L_exit_to L_exit_to_10
• Help with path operations, with PATH or PYTHONPATH manipulation L_path_stem L_dir_is_empty L_path_append L_path_relative_to
• String utilities L_strip L_strupper L_strstr L_html_escape L_urlencode
• Split string without remote execution and understand $'' sequences L_str_split
• Template output L_percent_format L_fstring
• JSON escape L_json_escape
• Cache commands execution with TTL in memory or file L_cache L_cache_decorate
• Easy writing function utilities by supporting -v <var> option or extracting comment before function L_handle_v_scalar L_func_help L_func_usage_error L_decorate
• All with support for any Bash versions from 3.2 to latest with portability functions L_readarray L_epochrealtime_usec L_compgen -V

Talk to me

Kindly feel free to have conversations and ask questions on GitHub discussion.

Report bugs using GitHub issue.

Contributing

Contributions are welcome! You can run the tests locally with make test or check static analysis with make shellcheck. Please submit pull requests to the main repository.

Conventions

• L_* prefix for public symbols.
• _L_* prefix for private symbols, including local variables in functions taking a name-reference.
• Upper case used for global scope read-only variables.
• Lower case used for functions and user mutable variables.
• Snake case for everything.
• The option -v <var> is used to store the result in a variable instead of printing it.
  • This follows the convention of printf -v <var>.
  • Without the -v option, the function outputs the elements on lines to standard output.
  • Associated function with _v suffix store the result in a hardcoded scratch variable L_v.
• Return 2 on usage error, return 124 on timeout.

License

GPL-3.0