[separator=—] = Bashmatic® — BASH-based DSL helpers for humans, sysadmins, and fun. // vim: ft=asciidoc :author: Version v3.6.1 :doctype: book :source-highlighter: rouge :rouge-style: base16.monokai :toclevels: 5 :toc: :sectnums: 9 :icons: font :license: MIT

== CI Matrix

.CI Matrix [width="80%",cols=">.^s,<.^m,^.^s",frame="topbot",options="header,footer"] |========================== | | Badges | FOSSA Scanning | FOSSSA | image:https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkigster%2Fbashmatic.svg?type=shield[License Status,link=https://app.fossa.com/projects/git%2Bgithub.com%2Fkigster%2Fbashmatic?ref=badge_shield] .7+<.>| image:https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkigster%2Fbashmatic.svg?type=large[FOSSA License Scan,link=https://app.fossa.com/projects/git%2Bgithub.com%2Fkigster%2Fbashmatic?ref=badge_large] | CI Tests | image:https://github.com/kigster/bashmatic/actions/workflows/tests.yml/badge.svg[Test,link=https://github.com/kigster/bashmatic/actions/workflows/tests.yml] | CI Install | image:https://github.com/kigster/bashmatic/actions/workflows/install.yml/badge.svg[Install,link=https://github.com/kigster/bashmatic/actions/workflows/install.yml] | ShellCheck | image:https://github.com/kigster/bashmatic/actions/workflows/lint.yml/badge.svg[Lint,link=https://github.com/kigster/bashmatic/actions/workflows/lint.yml] | Gitter | image:https://badges.gitter.im/kigster/bashmatic.svg[link="https://gitter.im/kigster/bashmatic?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"] |==========================

== Introduction

Bashmatic® is a BASH framework, meaning it's a collection of BASH functions (almost 900 of them) that, we hope, make BASH programming easier, more enjoyable, and more importantly, fun - due to the library's focus on providing the developer with a constant feedback about what is happening, while a script that uses Bashmatic's helpers is running.

== Please Donate

https://liberapay.com/kigster/donate[image:https://liberapay.com/assets/widgets/donate.svg[Donate using Liberapay,height=30]]   https://liberapay.com/kigster/donate[image:https://img.shields.io/liberapay/goal/kigster.svg?logo=liberapay[https://img.shields.io/liberapay/goal/kigster,height=30]]

[TIP]

We suggest that you learn about Bashmatic from the https://github.com/kigster/bashmatic/blob/main/README.pdf[PDF version of this document] which is much better for print.

• We recently began providing function documentation using a fork of shdoc utility. You can find the auto-generated documentation in the https://github.com/kigster/bashmatic/blob/main/doc/USAGE.md[USAGE] file, or its https://github.com/kigster/bashmatic/blob/main/doc/USAGE.pdf[PDF] version.

• There is also an auto-generated file listing the source of every function and module. You can find it https://github.com/kigster/bashmatic/blob/main/doc/FUNCTIONS.adoc[FUNCTIONS].

• Additionally please checkout the https://github.com/kigster/bashmatic/blob/main/doc/CHANGELOG.md[CHANGELOG] and the https://github.com/kigster/bashmatic/blob/main/doc/LICENSE.adoc[LICENSE]. ====

==== After you install the library (the default location is ~/.bashmatic), realize that you have a choice of either:

• Automatically sourcing the library (and all 900+ functions) from your shell 'dotfiles' like ~/.bash_profile by adding this line: source ~/.bashmatic/init.sh. On a recent M1 Apple laptop this adds about 100ms total.
• OR, can skip it during your login initialization, and only load it at the top of the scripts that use the library. ====

[CAUTION] Both approaches are absolutely valid and have their pros and cons. Loading bashmatic in your dotfiles could be a bit risky. One way or another we'll soon provide ways to verify that bashmatic you download is the safe and correct version, every time.

All we'll say on this matter is that we manage the optimize the hell out of the sourcing the library. Here is an example:

image::doc/img/bashmatic-init.png[Init,width=85%,align=center,border=5,margin=10]

== Programming Style: Modern BASH + DSL

Bashmatic®'s programming style is heavily influenced by Ruby's DSL languages. If you take a quick look at the https://github.com/kigster/bashmatic/blob/main/lib/is.sh[is.sh] script, it defines a bunch of DSL functions that can be chained with && and || to create a compact and self-documenting code like this:

icon:arrow-circle-down[3x, color="purple"]

[source,bash]

An example of a DSL-like function

function bashmatic.auto-update() { local dir="${1:-"${BASHMATIC_HOME"}}" is.a-directory "${dir}" && { file.exists-and-newer-than "${dir}/.last-update" 30 && return 0 ( cd ${BASHMATIC_HOME} &&
git.is-it-time-to-update &&
git.sync-remote ) } }

check if the function is defined and call it

is.a-function.invoke bashmatic.auto-update "$@"

To use it in your own scripts, you'll want to first study the Examples provided below, and take advantage of ach module available under lib.

Final note, - once Bashmatic is installed and loaded by your shell init files, you can type is.<tab><tab> to see what functions are available to you that start with is. Each module under lib typically defines public functions starting with the name of the file. Such as, functions in array.sh typically start with array.<something>.<action>

Bashmatic® offers a huge range of ever-growing helper functions for running commands, auto-retrying, repeatable, runtime-measuring execution framework with the key function run. There are helpers for every occasion, from drawing boxes, lines, headers, to showing progress bars, getting user input, installing packages, and much more.

NOTE: A good portion of the helpers within Bashmatic® are written for OS-X, although many useful functions will also work under linux. Our entire test suite runs on Ubuntu. There is an effort underway to convert Homebrew-specific functions to OS-neutral helpers such as package.install that would work equally well on linux.

Start exploring Bashmatic® below with our examples section. When you are ready, the complete entire set of pubic functions (nearly 500 of those) can be found in the https://github.com/kigster/bashmatic/blob/main/doc/FUNCTIONS.adoc[functions index page].

And, finally, don't worry, Bashmatic® is totally open source and free to use and extend. We just like the way it looks with a little ® :)

== Compatibility

• BASH version 4+
• BASH version 3 (partial compatibility, some functions are disabled)
• ZSH – as of recent update, Bashmatic is almost 90% compatible with ZSH.

Not Currently Supported

• FISH (although you could use Bashmatic via the bin/bashmatic script helper or its executables)

== Project Motivation

This project was born out of a simple realization made by several very senior and highly experienced engineers, that:

• It is often easier to use BASH for writing things like universal installers, a.k.a. setup scripts, uploaders, wrappers for all sorts of functionality, such as NPM, rbenv, installing gems, rubies, using AWS, deploying code, etc.

• BASH function's return values lend themselves nicely to a compact DSL (https://en.wikipedia.org/wiki/Domain-specific_language[domain specific language]) where multiple functions can be chained by logical AND && and OR || to provide a very compact execution logic. Most importantly, we think that this logic is extremely easy to read and understand.

Despite the above points, it is also generally accepted that:

• A lot of BASH scripts are very poorly written and hard to read and understand.
• It's often difficult to understand what the hell is going on while the script is running, because either its not outputting anything useful, OR it's outputting way too much.
• When BASH errors occur, shit generally hits the fan and someone decides that they should rewrite the 20-line BASH script in C{pp} or Go, because, well, it's a goddamn BASH script and it ain't working.

TIP: Bashmatic's goal is to make BASH programming both fun, consistent, and provide plenty of visible output to the user so that there is no mystery as to what is going on.

== Installing Bashmatic

Perhaps the easiest way to install Bashmatic® is using curl as shown below.

First, make sure that you have Curl installed, run which curl to see. Then copy/paste this command into your Terminal.

=== 1. Automated Install

icon:arrow-down[3x, color="yellow"]

[source,bash]

bash -c "$(curl -fsSL https://bashmatic.re1.re); bashmatic-install -q"

icon:arrow-up[3x, color="yellow"]

Where:

• -q stands for "quiet";
• -v for "verbose"

TIP: The URL https://bashmatic.re1.re redirects to the HEAD of the https://raw.githubusercontent.com/kigster/bashmatic/main/bin/bashmatic-install[bin/bashmatic-install] script in the Github Bashmatic Repo. We use this URL so that we retain the ability to redirect the installation to a different script in the future, if need be.

=== 2. Automated Install, More Explicit

If you prefer to be able to examine the script before executing code piped straight off the Internet, I don't blame you. You are cautious and smart.

For folks like you, here is a slightly more secure way of doing the same thing:

[source,bash]

export script="/tmp/install" curl -fsSL https://bashmatic.re1.re > /tmp/install chmod 755 /tmp/install

At this point you can examine /tmp/install

/tmp/install --help /tmp/install --verbose --debug # install with extra info

This method allows you to examine the /tmp/install script before running it.

Below are some of the explanations

==== Installing a Particular Version or a Branch

You can install a branch or a tag of Bashmatic by passing -b / --git-branch <tag|branch> flag.

==== Customizing the Installer Script

You can pass flags to the bashmatic-install functi