https://github.com/rdavid/shellbase
The framework is specifically designed for Unix shell scripts.
https://github.com/rdavid/shellbase
container docker linux podman posix redo shell unix
Last synced: 3 months ago
JSON representation
The framework is specifically designed for Unix shell scripts.
- Host: GitHub
- URL: https://github.com/rdavid/shellbase
- Owner: rdavid
- License: 0bsd
- Created: 2020-12-23T14:58:55.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2026-04-01T23:07:29.000Z (3 months ago)
- Last Synced: 2026-04-02T09:26:09.998Z (3 months ago)
- Topics: container, docker, linux, podman, posix, redo, shell, unix
- Language: Shell
- Homepage:
- Size: 999 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
// Settings:
:toc: macro
:!toc-title:
// URLs:
:img-hoc: https://hitsofcode.com/github/rdavid/shellbase?branch=master&label=hits%20of%20code
:img-license: https://img.shields.io/github/license/rdavid/shellbase?color=blue&labelColor=gray&logo=freebsd&logoColor=lightgray&style=flat
:img-releases: https://img.shields.io/github/v/release/rdavid/shellbase?color=blue&label=%20&logo=semver&logoColor=white&style=flat
:img-test-bsd: https://github.com/rdavid/shellbase/actions/workflows/test-bsd.yml/badge.svg
:img-test-lnx: https://github.com/rdavid/shellbase/actions/workflows/test-lnx.yml/badge.svg
:img-test-mac: https://github.com/rdavid/shellbase/actions/workflows/test-mac.yml/badge.svg
:url-actionlint: https://github.com/rhysd/actionlint
:url-base: https://github.com/rdavid/shellbase/blob/master/lib/base.sh
:url-checkmake: https://github.com/mrtazz/checkmake
:url-cv: http://cv.rabkin.co.il
:url-dotfiles: https://github.com/rdavid/dotfiles
:url-gento: https://github.com/rdavid/gento
:url-goredo: http://www.goredo.cypherpunks.su/INSTALL.html
:url-goredoer: https://github.com/rdavid/goredoer
:url-hadolint: https://github.com/hadolint/hadolint
:url-hoc: https://hitsofcode.com/view/github/rdavid/shellbase?branch=master
:url-license: https://github.com/rdavid/shellbase/blob/master/LICENSES/0BSD.txt
:url-pulse: https://github.com/rdavid/pulse
:url-redo: http://cr.yp.to/redo.html
:url-releases: https://github.com/rdavid/shellbase/releases
:url-reuse: https://github.com/fsfe/reuse-action
:url-sh0: https://mywiki.wooledge.org/BashPitfalls
:url-sh1: http://www.etalabs.net/sh_tricks.html
:url-sh2: https://mywiki.wooledge.org/SignalTrap
:url-sh3: https://www.grymoire.com/Unix/Sh.html
:url-shellcheck: https://github.com/koalaman/shellcheck
:url-shfmt: https://github.com/mvdan/sh
:url-test-bsd: https://github.com/rdavid/shellbase/actions/workflows/test-bsd.yml
:url-test-lnx: https://github.com/rdavid/shellbase/actions/workflows/test-lnx.yml
:url-test-mac: https://github.com/rdavid/shellbase/actions/workflows/test-mac.yml
:url-toolbox: https://github.com/rdavid/toolbox
:url-typos: https://github.com/crate-ci/typos
:url-vale: https://vale.sh
:url-yamllint: https://github.com/adrienverge/yamllint
= Shellbase
// The width is set to 79 characters, and the height is 8 lines. An ASCII art
// generator is used with the specific font Georgia 11 by Richard Sabey
// 9.2003:
// http://patorjk.com/software/taag/#p=display&f=Georgia11&t=shellbase
[,sh]
----
,, ,, ,, ,,
`7MM `7MM `7MM *MM
MM MM MM MM
,pP"Ybd MMpMMMb. .gP"Ya MM MM MM,dMMb. ,6"Yb. ,pP"Ybd .gP"Ya
8I `" MM MM ,M' Yb MM MM MM `Mb 8) MM 8I `" ,M' Yb
`YMMMa. MM MM 8M"""""" MM MM MM M8 ,pm9MM `YMMMa. 8M""""""
L. I8 MM MM YM. , MM MM MM. ,M9 8M MM L. I8 YM. ,
M9mmmP'.JMML JMML.`Mbmmd'.JMML..JMML.P^YbmdP' `Moo9^Yo.M9mmmP' `Mbmmd'
----
image:{img-test-bsd}[text bsd,link={url-test-bsd}]
image:{img-test-lnx}[text lnx,link={url-test-lnx}]
image:{img-test-mac}[test mac,link={url-test-mac}]
image:{img-hoc}[hits of code,link={url-hoc}]
image:{img-releases}[release,link={url-releases}]
image:{img-license}[license,link={url-license}]
toc::[]
== About
The `shellbase` framework serves as a foundation for Unix shell scripts.
It is mostly POSIX-compliant (`Portable Operating System Interface for uniX`),
which helps keep it compatible across Unix-like systems.
It offers essential services, including logging, validation helpers, signal
handling, garbage collection, and support for multiple instances.
`shellbase` defines global variables and functions.
All functions without the `base_` prefix are public and can be used by clients.
The public functions are, in alphabetical order:
{url-base}#L54[`aud_only`],
{url-base}#L98[`beroot`],
{url-base}#L103[`beuser`],
{url-base}#L114[`bomb`],
{url-base}#L120[`cheat`],
{url-base}#L132[`cmd_exists`],
{url-base}#L165[`chrono_get`],
{url-base}#L205[`chrono_sta`],
{url-base}#L216[`chrono_sto`],
{url-base}#L226[`cya`],
{url-base}#L236[`die`],
{url-base}#L246[`dng2jpg`],
{url-base}#L252[`echo`],
{url-base}#L274[`ellipsize`],
{url-base}#L292[`file_exists`],
{url-base}#L301[`gitlog`],
{url-base}#L325[`grbt`],
{url-base}#L337[`handle_pipefails`],
{url-base}#L343[`heic2jpg`],
{url-base}#L356[`inside`],
{url-base}#L363[`isempty`],
{url-base}#L387[`isfunc`],
{url-base}#L400[`isnumber`],
{url-base}#L408[`isreadable`],
{url-base}#L417[`isroot`],
{url-base}#L429[`issolid`],
{url-base}#L463[`iswritable`],
{url-base}#L477[`log`],
{url-base}#L486[`loge`],
{url-base}#L494[`logw`],
{url-base}#L503[`map_del`],
{url-base}#L523[`map_get`],
{url-base}#L545[`map_put`],
{url-base}#L557[`nmea2gpx`],
{url-base}#L576[`pdf2jpg`],
{url-base}#L581[`pdf2png`],
{url-base}#L600[`prettytable`],
{url-base}#L626[`prettyuptime`],
{url-base}#L649[`realdir`],
{url-base}#L658[`realpath`],
{url-base}#L671[`semver`],
{url-base}#L689[`should_continue`],
{url-base}#L745[`timestamp`],
{url-base}#L765[`tolog`],
{url-base}#L771[`tologe`],
{url-base}#L778[`tolower`],
{url-base}#L796[`totsout`],
{url-base}#L802[`tsout`],
{url-base}#L810[`url_exists`],
{url-base}#L834[`user_exists`],
{url-base}#L850[`validate_cmd`],
{url-base}#L857[`validate_var`],
{url-base}#L864[`var_exists`],
{url-base}#L898[`ver_ge`],
{url-base}#L906[`vid2aud`],
{url-base}#L920[`ytda`].
Global variables have the `BASE_` prefix and can be used by clients.
Clients should place temporary files under `$BASE_WIP`.
All functions starting with the `base_` prefix are internal and should not be
used by clients.
Names are listed in alphabetical order.
See
{url-dotfiles}[`dotfiles`],
{url-gento}[`gento`],
{url-pulse}[`pulse`], and
{url-toolbox}[`toolbox`]
as example projects that use this framework.
== Install
The artifact is a single non-executable POSIX-compliant shell script file
{url-base}[`base.sh`].
Install the file from the repository:
[,sh]
----
git clone git@github.com:rdavid/shellbase.git &&
./shellbase/app/install
----
Install the file from a release.
Some operating systems demand administrative rights to install to
`/usr/local/bin`; use `sudo` or `doas` before `tar`:
[,sh]
----
REL=0.9.20260404
SRC=https://github.com/rdavid/shellbase/archive/refs/tags/v$REL.tar.gz
curl --location --silent $SRC |
tar \
--directory /usr/local/bin \
--extract \
--gzip \
--strip-components=2 \
shellbase-$REL/lib/base.sh
----
== Using
Verify `/usr/local/bin` is in your `PATH`.
Then your script can use `shellbase`:
[,sh]
----
#!/bin/sh
# shellcheck disable=SC1091 # File not following.
. base.sh
log I\'m using the shellbase.
----
You can try `shellbase` without installation:
[,sh]
----
#!/bin/sh
REL=0.9.20260404
SRC=https://github.com/rdavid/shellbase/archive/refs/tags/v$REL.tar.gz
eval "$(
curl --location --silent $SRC |
tar \
--extract \
--gzip \
--to-stdout \
shellbase-$REL/lib/base.sh
)"
log I\'m using the shellbase.
----
{url-base}#L600[`prettytable`] example:
[,sh]
----
. base.sh
{
printf 'ID\tNAME\tTITLE\n'
printf '123456789\tJohn Foo\tDirector\n'
printf '12\tMike Bar\tEngineer\n'
} | prettytable
----
Output:
[,sh]
----
+-----------+----------+----------+
|ID |NAME |TITLE |
+-----------+----------+----------+
|123456789 |John Foo |Director |
|12 |Mike Bar |Engineer |
+-----------+----------+----------+
----
== Test
The project uses Daniel J. Bernstein's build system, {url-redo}[`redo`].
You can install Sergey Matveev's {url-goredo}[`goredo`] implementation.
`redo lint` applies the following linters to the source files:
{url-actionlint}[`actionlint`],
{url-checkmake}[`checkmake`],
{url-hadolint}[`hadolint`],
{url-reuse}[`reuse`],
{url-shellcheck}[`shellcheck`],
{url-shfmt}[`shfmt`],
{url-typos}[`typos`],
{url-vale}[`vale`],
{url-yamllint}[`yamllint`].
`redo test` runs unit tests across installed shells.
`redo test-container` runs the tests across various shells in containers.
The project uses {url-cv}[David Rabkin]'s {url-goredoer}[`goredoer`] to build
{url-goredo}[`goredo`].
== Links
- {url-sh0}[Bash Pitfalls]
- {url-sh1}[Rich’s sh (POSIX shell) tricks]
- {url-sh2}[Sending and Trapping Signals]
- {url-sh3}[Sh - the POSIX Shell]
== License
`shellbase` is copyright {url-cv}[David Rabkin] and available under a
{url-license}[Zero-Clause BSD license].