___         ___         ___
     _____       /  /\       /  /\       /__/|
    /  /::\     /  /::\     /  /:/_     |  |:|
   /  /:/\:\   /  /:/\:\   /  /:/ /\    |  |:|
  /  /:/~/::\ /  /:/~/::\ /  /:/ /::\ __|  |:|
 /__/:/ /:/\:/__/:/ /:/\:/__/:/ /:/\:/__/\_|:|____
 \  \:\/:/~/:\  \:\/:/__\\  \:\/:/~/:\  \:\/:::::/
  \  \::/ /:/ \  \::/     \  \::/ /:/ \  \::/~~~~
   \  \:\/:/   \  \:\      \__\/ /:/   \  \:\
    \  \::/     \  \:\       /__/:/     \  \:\
     \__\/       \__\/       \__\/       \__\/

bask

A framework for command-centric Bash scripts.

Features

Some basic features available automatically:

• Strict Mode,
• Help template, printable with -h or --help,
• _debug printing with --debug flag,
• _exit_1 and _warn functions with error message printing,
• Option normalization (eg, -ab -c -> -a -b -c) and option parsing,
• Automatic arbitrary command loading,
• A simple approach for specifying per-command help with describe,
• Built-in commands for help, version, and command listing,
• Conventions for distinguishing between functions and program commands,
• Useful utility functions.

Installation

Homebrew

To install with Homebrew:

brew tap xwmx/taps
brew install bask

npm

To install with npm:

npm install --global bask.sh

bpkg

To install with bpkg:

bpkg install xwmx/bask

Manual

To install manually, simply add the bask script to your $PATH. If
you already have a ~/bin directory, you can use the following command:

curl -L https://raw.github.com/xwmx/bask/master/bask \
  -o ~/bin/bask && chmod +x ~/bin/bask

Usage

bask can be used primarily in two ways: with with scripts that source (or,
in other words, inherit from) the bask program, or with Baskfiles defining
functions for the current context.

Bask Scripts

To generate a new bask script, meaning a script that
inherits the bask foundation, use add an argument to the new
command specifying the script name:

bask new <script name>

This generates a script that sources the bask command. You can add
bash functions in this script and they will be automatically set as
sub-commands available as arguments to the program. Additionally, you
can easily document the programs using the built-in describe function.
The help / usage / description information set here is available in the
via the built-in help command.

Baskfiles

A Baskfile is a file containing bash functions and optional
descriptions that can be run using the bask command directly, and can
be defined on a project-by-project basis. This can be useful for defining
task-centric commands within a particular scope where a full program
would be unnecessary.

A Baskfile is similar to a Makefile
or a Rakefile) and looks like
this:

# Baskfile
describe "hello" <<HEREDOC
Usage:
  bask hello
Description:
  Print a greeting.
HEREDOC
hello() {
  echo "Hello from bask!"
}

To generate a new Baskfile, use bask new with no arguments:

bask new

When you run the bask program, it first looks in the
current directory for a Baskfile and sources it if one is present. If it
doesn’t find a Baskfile in the current directory, it traverses the
parent directories, sourcing the first Baskfile it encounters.

Commands

Commands in bask are simply Bash functions with optional descriptions.
Defined functions will be automatically loaded and displayed as part of
the usage information when the parent command is run. Command-specific
usage information can be set with the describe function, and this usage
information will be made automatically available to the parent program’s
help command.

Example command group structure:

describe example ""  # Optional. A short description for the command.
example() { : }  # The command called by the user.

For usage formatting conventions see:

• http://docopt.org/
• http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html

Example Command Groups

Micro Example

describe micro "Usage: $_ME micro"
micro() {
  echo "Hello, World!"
}

Simple Example

describe simple <<HEREDOC
Usage:
  $_ME simple [<name>]
Description:
  Print the greeting, "Hello, World!"
HEREDOC
simple() {
  local _name="${1:-World}"
  printf "Hello, %s!\n" "${_name}"
}

Complex Example

describe complex <<HEREDOC
Usage:
  $_ME complex [<name>] [--farewell]
Options:
  --farewell  Print "Goodbye, World!"
Description:
  Print the greeting, "Hello, World!"
HEREDOC
complex() {
  local _greeting="Hello"
  local _name="World"
  for __arg in "${@:-}"
  do
    case "${__arg}" in
      --farewell)
        _greeting="Goodbye"
        ;;
      -*)
        _exit_1 printf "Unexpected option: %s\n" "${__arg}"
        ;;
      *)
        if [[ "${_name}" == "World" ]] && [[ -n "${__arg:-}" ]]
        then
          _name="${__arg}"
        fi
        ;;
    esac
  done
  printf "%s, %s!\n" "${_greeting}" "${_name}"
}

Optional Vim Configuration

In order to enable Baskfile syntax highlighting in Vim, add the
following line to your .vimrc.

autocmd BufRead,BufNewFile Baskfile call SetFileTypeSH("bash")