Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/richbl/a-bash-template

A bash template (BaT) designed to make script development and command line argument management more robust, easier to implement, and easier to maintain
https://github.com/richbl/a-bash-template

bash bash-script bash-template dependency-checker json parsing script shell shell-script template

Last synced: 20 days ago
JSON representation

A bash template (BaT) designed to make script development and command line argument management more robust, easier to implement, and easier to maintain

Host: GitHub
URL: https://github.com/richbl/a-bash-template
Owner: richbl
License: gpl-3.0
Created: 2016-04-13T02:08:47.000Z (over 8 years ago)
Default Branch: master
Last Pushed: 2023-02-28T02:43:07.000Z (almost 2 years ago)
Last Synced: 2023-08-24T15:27:29.493Z (over 1 year ago)
Topics: bash, bash-script, bash-template, dependency-checker, json, parsing, script, shell, shell-script, template
Language: Shell
Homepage:
Size: 66.4 KB
Stars: 36
Watchers: 2
Forks: 7
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# A-Bash-Template

**A-Bash-Template** (`bash_template.sh`) is a [bash](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29) script that really does nothing at all: **it's a template.** But it does make scripting--particularly parameter passing--much easier, more organized, and more consistent.

## What's a Bash Template (BaT)?

**A-Bash-Template** is designed to make script development and command line argument management more robust, easier to implement, and easier to maintain and update/upgrade. This BaT includes the following features:

- **Dependencies Checker**: a routine that checks all external file and program dependencies (*e.g.* this script relies on [jq](https://stedolan.github.io/jq/) for JSON parsing, so its availability is checked immediately upon script execution)
- **Configuration Details in JSON**: arguments and script details--such as script description and syntax--are stored in the [JSON](http://www.json.org/) file format (*i.e.*, `config.json`)
- **JSON Wrapper Functions**: JSON queries (using [jq](https://stedolan.github.io/jq/)) handled through template wrapper functions
- **Automated Script Banner**: a script banner function automates banner generation, reading directly from `config.json`
- **Automated Arguments Management**: command line arguments are automatically parsed and tested for completeness using both short and long-format argument syntax (*e.g.* `-u|--username`)
- **Support for [Optional] Arguments**: optional command line arguments are permissible and managed through the JSON configuration file
- **Structured Modular Library**: template functions organized into libraries (see the [bash-lib](https://github.com/richbl/bash-lib) project for specific library details) to minimize code footprint in the main script and permit easier maintenance and extensions/add-ons support

### Dependencies Checker

The dependencies checker is a routine that checks that all external file and program dependencies are met. For example, `bash_template.sh` itself relies on one external program for proper execution: [jq](https://stedolan.github.io/jq/), used for parsing its own JSON configuration file (`config.json`).

In this instance, to configure dependency checking in `bash_template.sh`, the array variable `REQ_PROGRAMS` is set to `('jq')`. The script then calls into the `check_dependencies` function in the `args` library (found in the `./lib` folder).

### Script Configuration in JSON

Script details, such as the script description, version and script syntax, and all command line argument options--both required and optional--are stored in a single JSON file called `config.json` located in the `./data` folder.

The JSON file used in **A-Bash-Template** is displayed below:

{
"details":
{
"title": "A bash template (BaT) to ease argument parsing and management",
"syntax": "bash_template.sh -a alpha -b bravo [-c charlie] -d delta",
"version": "1.1.1"
},
"arguments":
[
{
"short_form": "-a",
"long_form": "--alpha",
"text_string": "alpha",
"description": "alpha (something descriptive)",
"required": true
},
{
"short_form": "-b",
"long_form": "--bravo",
"text_string": "bravo",
"description": "bravo (something descriptive)",
"required": true
},
{
"short_form": "-c",
"long_form": "--charlie",
"text_string": "charlie",
"description": "charlie (this is optional)",
"required": false
},
{
"short_form": "-d",
"long_form": "--delta",
"text_string": "delta",
"description": "delta (something descriptive)",
"required": true
}
]
}

### Automated Script Banner

The informational banner that displays details about how to use the script is generated using configuration details held in the JSON file. A call to `display_banner` in the `./lib/general` library displays the following:

By default, `display_banner` is called when the script is run.

### Command Line Parsing and Completeness Testing

When **A-Bash-Template** is run, it parses the command line to identify command line argument values (*e.g.* `--password = pass123`), and also checks to see whether all required arguments have been set. If command line arguments are missing, the script will report it:

$ ./bash_template.sh -a one

Error: bravo argument (-b|--bravo) missing.
Error: delta argument (-d|--delta) missing.

> **Note**: The optional argument (-c|--charlie) did not get flagged as an omission since it's an optional argument and not a required argument.

## Requirements

- An operational [bash](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29) environment (bash 4.3.2 used during initial development)
- One additional external program:
- [jq](https://stedolan.github.io/jq/), used for parsing the `config.json` file

While this package was originally written and tested under Linux (Ubuntu 15.10 and bash 4.3.2), there should be no reason why this won't work with other shells or other Unix-like operating systems.

## Basic Usage

**A-Bash-Template** is run through a command line interface, so all of the command options are made available there.

Here's the default response when running `bash_template.sh` with no arguments:

$ ./bash_template.sh

Error: bravo argument (-a|--alpha) missing.
Error: bravo argument (-b|--bravo) missing.
Error: delta argument (-d|--delta) missing.

In this example, the program responds by indicating that the required script arguments must be set before proper operation.

> **Note**: The optional argument (-c|--charlie) did not get flagged as an omission, since it's an optional argument, and not a required argument.

When arguments are correctly passed, the script provides feedback on the success (or failure) of the script:

$ ./bash_template.sh -a one -b two -c three -d four

alpha is one
bravo is two
charlie is three
delta is four

## Custom Configuration: Look for `[user-config]`

Since **A-Bash-Template** is a BaT, the real value is to permit custom code to become well-integrated to complete whatever is the required intent of the script. The design and structure of the template accounts for this, and only localized changed are necessary.

To make custom configuration changes easier, search for the comment string `[user-config]` throughout the script sources (there are only a few). These comments provide additional guidance on what should be changed and why.

## Yes, We Are [Dogfooding](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) the A-Bash-Template Project

Of course we are! Otherwise, what value does a BaT offer if it doesn't get used often enough to warrant the time to develop a BaT?

All of our bash scripts have been written to use this project. It's cut our development time, and made it easier to provide updates and added functionality without having to spend time reinventing the wheel every time. Check out all of our projects here on [Github](https://github.com/richbl).

## IMPORTANT: This Project Uses Git Submodules

This project uses [Git submodule project(s)](https://git-scm.com/book/en/v2/Git-Tools-Submodules) (located in the `bash-lib` folder) to keep this project up-to-date without manual intervention.

**Be sure to clone this project with the `--recursive` switch** (`git clone --recursive https://github.com/richbl/this_project`) so any submodule project(s) will be automatically cloned as well. If you clone into this project without this switch, you'll likely see empty submodule project folders (depending on your version of Git).