ExternalVendorCode/bash3boilerplate
1
0
Fork 0
mirror of https://github.com/kvz/bash3boilerplate.git synced 2024-12-18 22:27:51 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Updated README and FAQ (#66)

Browse Source 
* updated TOC
* fixed typos
* link to bash3boilerplate.sh/main.sh instead of blob/master/main.sh
* updated links from e.g. blob/master/main.sh#L13 to
  blob/v2.1.0/main.sh#L13
This commit is contained in:
Manuel Streuhofer 2016-11-29 10:36:49 +01:00 committed by Kevin van Zonneveld
parent e7a0b2f412
commit 57ebf1569d
2 changed files with 55 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
FAQ.md
View File

@ -4,36 +4,45 @@
## Contents
* [What is a cli](#what-is-a-cli)?
* [What is a CLI](#what-is-a-cli)?
* [How do I incorporate BASH3 Boilerplate into my own project](#how-do-i-incorporate-bash3-boilerplate-into-my-own-project)?
* [How do I add a command-line flag](#how-do-i-add-a-command-line-flag)?
* [How do I access the value of a command-line argument](#how-do-i-access-the-value-of-a-command-line-argument)?
* [How do I incorporate BASH3 Boilerplate into my own project](#how-do-i-incorporate-bash3boilerplate-into-my-own-project)?
* [What is a magic variable](#what-is-a-magic-variable)?
* [How do I incorporate BASH3 Boilerplate into my own project](#how-do-i-incorporate-bash3boilerplate-into-my-own-project)?
* [How do I submit an issue report](#how-do-i-submit-an-issue-report)?
* [How can I contribute to this project](#how-can-i-contribute-to-this-project)?
* [Why are you typing BASH in all caps](#why-are-you-typing-bash-in-all-caps)?
* [How can I locally develop and preview the b3bp website](#how-can-i-locally-develop-and-preview-the-b3bp-website)?
* [You are saying you are portable, but why won't b3bp code run in dash / busybox / posh / ksh / mksh / zsh](#you-are-saying-you-are-portable-but-why-wont-b3bp-code-run-in-dash--busybox--posh--ksh--mksh--zsh)?
* [How do I do Operating System detection](#how-do-i-do-operating-system-detection)?
* [How do I access a potentially unset (environment) variable](#how-do-i-access-a-potentially-unset-environment-variable)?
<!--more-->
# Frequently Asked Questions
## What is a cli?
## What is a CLI?
A 'cli' is a [command-line interface](https://en.wikipedia.org/wiki/Command-line_interface).
A "CLI" is a [command-line interface](https://en.wikipedia.org/wiki/Command-line_interface).
## How do I incorporate BASH3 Boilerplate into my own project?
You can incorporate BASH3 Boilerplate into your project in one of two ways:
1. Copy the desired portions of [main.sh](https://github.com/kvz/bash3boilerplate/blob/master/main.sh) into your own script.
1. Download [main.sh](https://github.com/kvz/bash3boilerplate/blob/master/main.sh) and start pressing the delete-key to remove unwanted things
1. Copy the desired portions of [`main.sh`](http://bash3boilerplate.sh/main.sh) into your own script.
1. Download [`main.sh`](http://bash3boilerplate.sh/main.sh) and start pressing the delete-key to remove unwanted things
Once the `main.sh` has been tailor-made for your project, you can either append your own script in the same file, or source it in the following ways:
1. Copy [main.sh](https://github.com/kvz/bash3boilerplate/blob/master/main.sh) into the same directory as your script and then edit and embed it into your script using Bash's `source` include feature, e.g.:
1. Copy [`main.sh`](http://bash3boilerplate.sh/main.sh) into the same directory as your script and then edit and embed it into your script using Bash's `source` include feature, e.g.:
```bash
#!/usr/bin/env bash
source main.sh
```
1. Source [main.sh](https://github.com/kvz/bash3boilerplate/blob/master/main.sh) in your script or at the command line:
1. Source [`main.sh`](http://bash3boilerplate.sh/main.sh) in your script or at the command line:
```bash
#!/usr/bin/env bash
source main.sh
@ -41,16 +50,17 @@ source main.sh
## How do I add a command-line flag?
1. Copy the line from the main.sh [read block](https://github.com/kvz/bash3boilerplate/blob/master/main.sh#L53) that most resembles the desired behavior and paste the line into the same block.
1. Edit the single-character (e.g., `-d`) and, if present, the multi-character (e.g., `--debug`) versions of the flag in the copied line.
1. Copy the line from the `main.sh` [read block](https://github.com/kvz/bash3boilerplate/blob/v2.1.0/main.sh#L109-L115) that most resembles the desired behavior and paste the line into the same block.
1. Edit the single-character (e.g., `-d`) and, if present, the multi-character (e.g., `--debug`) versions of the flag in the copied line.
1. Omit the `[arg]` text in the copied line, if the desired flag takes no arguments.
1. Omit or edit the text after `Default:` to set or not set default values, respectively.
1. Omit or edit the text after `Default:` to set or not set default values, respectively.
1. Omit the `Required.` text, if the flag is optional.
## How do I access the value of a command-line argument?
To find out the value of an argument, append the corresponding single-character flag to the text `$arg_`. For example, if the [read block]
contains the line
```bash
-t --temp [arg] Location of tempfile. Default="/tmp/bar"
```
@ -63,7 +73,7 @@ __temp_file_name="${arg_t}"
## What is a magic variable?
The [magic variables](https://github.com/kvz/bash3boilerplate/blob/master/main.sh#L63) in `main.sh` are special in that they have a different value, depending on your environment. You can use `${__file}` to get a reference to your current script, and `${__dir}` to get a reference to the directory it lives in. This is not to be confused with the location of the calling script that might be sourcing the `${__file}`, which is accessible via `${0}`, or the current directory of the administrator running the script, accessible via `$(pwd)`.
The [magic variables](https://github.com/kvz/bash3boilerplate/blob/v2.1.0/main.sh#L26-L28) in `main.sh` are special in that they have a different value, depending on your environment. You can use `${__file}` to get a reference to your current script, and `${__dir}` to get a reference to the directory it lives in. This is not to be confused with the location of the calling script that might be sourcing the `${__file}`, which is accessible via `${0}`, or the current directory of the administrator running the script, accessible via `$(pwd)`.
## How do I submit an issue report?
@ -76,10 +86,10 @@ of <https://github.com/kvz/bash3boilerplate/>. We are always more than happy to
## Why are you typing BASH in all caps?
As an acronym, Bash stands for Bourne-again shell, and is usually written with one uppercase.
This project's name, however, is "BASH3 Boilerplate". It is a reference to
"[HTML5 Boilerplate](https://html5boilerplate.com/)", which was founded to serve a similar purpose,
only for crafting webpages.
As an acronym, Bash stands for Bourne-again shell, and is usually written with one uppercase.
This project's name, however, is "BASH3 Boilerplate". It is a reference to
"[HTML5 Boilerplate](https://html5boilerplate.com/)", which was founded to serve a similar purpose,
only for crafting webpages.
Somewhat inconsistent – but true to Unix ancestry – the abbreviation for our project is "b3bp".
## How can I locally develop and preview the b3bp website?
@ -112,11 +122,11 @@ offer at least version 3 of it. Make sure you have that available and b3bp will
We run automated tests to make sure that it will. Here is some proof for the following platforms:
- [Linux](https://travis-ci.org/kvz/bash3boilerplate/jobs/109804166#L91) `GNU bash, version 4.2.25(1)-release (x86_64-pc-linux-gnu)`
- [OSX](https://travis-ci.org/kvz/bash3boilerplate/jobs/109804167#L2453) `GNU bash, version 3.2.51(1)-release (x86_64-apple-darwin13)`
- [Linux](https://travis-ci.org/kvz/bash3boilerplate/jobs/109804166#L91-L94) `GNU bash, version 4.2.25(1)-release (x86_64-pc-linux-gnu)`
- [OSX](https://travis-ci.org/kvz/bash3boilerplate/jobs/109804167#L2453-L2455) `GNU bash, version 3.2.51(1)-release (x86_64-apple-darwin13)`
This portability, however, does not mean that we try to be compatible with
KornShell, Zsh, posh, yash, dash, or other shells. We allow syntax that would explode if
This portability, however, does not mean that we try to be compatible with
KornShell, Zsh, posh, yash, dash, or other shells. We allow syntax that would explode if
you pasted it in anything but Bash 3 and up.
## How do I do Operating System detection?
@ -148,7 +158,7 @@ fi
## How do I access a potentially unset (environment) variable?
The set -o nounset line in main.sh causes error termination when an unset environment variables is detected as unbound. There are multiple ways to avoid this.
The set -o nounset line in `main.sh` causes error termination when an unset environment variables is detected as unbound. There are multiple ways to avoid this.
Some code to illustrate:
@ -161,4 +171,4 @@ echo ${NAME2:=Damian} # echos Damian, $NAME2 is set to Damian
NAME3=${NAME3:-Damian}; echo ${NAME3} # echos Damian, $NAME3 is set to Damian
```
This subject is briefly touched on as well in the Safety and Portability section under point 5. b3bp currently uses [method 1](https://github.com/kvz/bash3boilerplate/blob/master/main.sh#L85) when we want to access a variable that could be undeclared, and [method 3](https://github.com/kvz/bash3boilerplate/blob/master/main.sh#L46) when we also want to set a default to an undeclared variable, because we feel it is more readable than method 2. We feel `:=` is easily overlooked, and not very beginner friendly. Method 3 seems more explicit in that regard in our humble opinion.
This subject is briefly touched on as well in the [Safety and Portability section under point 5](README.md#safety-and-portability). b3bp currently uses [method 1](https://github.com/kvz/bash3boilerplate/blob/v2.1.0/main.sh#L252) when we want to access a variable that could be undeclared, and [method 3](https://github.com/kvz/bash3boilerplate/blob/v2.1.0/main.sh#L31) when we also want to set a default to an undeclared variable, because we feel it is more readable than method 2. We feel `:=` is easily overlooked, and not very beginner friendly. Method 3 seems more explicit in that regard in our humble opinion.

40
README.md
View File

@ -9,8 +9,9 @@
* [Features](#features)
* [Installation](#installation)
* [Changelog](#changelog)
* [Best Practices](#best-practices)
* [Frequently Asked Questions](#frequently-asked-questions)
* [Best Practices](#best-practices)
* [Who uses b3bp](#who-uses-b3bp)
* [Authors](#authors)
* [License](#license)
@ -27,9 +28,11 @@ When hacking up Bash scripts, there are often things such as logging or command-
Here's an attempt to bundle those things in a generalized way so that
they are reusable as-is in most scripts.
We call it "BASH3 Boilerplate" or b3bp for short.
## Goals
Delete-Key-**Friendly**. Instead of introducing packages, includes, compilers, etc., we propose using [`main.sh`](http://bash3boilerplate.sh/main.sh) as a base and removing the parts you don't need.
Delete-Key-**Friendly**. Instead of introducing packages, includes, compilers, etc., we propose using [`main.sh`](http://bash3boilerplate.sh/main.sh) as a base and removing the parts you don't need.
While this may feel a bit archaic at first, it is exactly the strength of Bash scripts that we should want to embrace.
**Portable**. We are targeting Bash 3 (OSX still ships
@ -46,20 +49,11 @@ dependency.
- Helpful magic variables like `__file` and `__dir`
- Logging that supports colors and is compatible with [Syslog Severity levels](http://en.wikipedia.org/wiki/Syslog#Severity_levels), as well as the [twelve-factor](http://12factor.net/) guidelines
## Who uses b3bp?
- [Transloadit](https://transloadit.com)
- [OpenCoarrays](http://www.opencoarrays.org)
- [Sourcery Institute](http://www.sourceryinstitute.org)
- [Computational Brain Anatomy Laboratory](http://cobralab.ca/)
We are looking for endorsements! Are you also using b3bp? [Let us know](https://github.com/kvz/bash3boilerplate/issues/new?title=I%20use%20b3bp) and get listed.
## Installation
There are three different ways to install b3bp:
### option 1: Download the main template
### Option 1: Download the main template
Use curl or wget to download the source and save it as your script. Then you can start deleting the unwanted bits, and adding your own logic.
@ -68,7 +62,7 @@ wget http://bash3boilerplate.sh/main.sh
vim main.sh
```
### option 2: Clone the entire project
### Option 2: Clone the entire project
Besides `main.sh`, this will also get you the entire b3bp repository. This includes a few extra functions that we keep in the `./src` directory.
@ -76,7 +70,7 @@ Besides `main.sh`, this will also get you the entire b3bp repository. This inclu
git clone git@github.com:kvz/bash3boilerplate.git
```
### option 3: Require via npm0
### Option 3: Require via npm
As of `v1.0.3`, b3bp can also be installed as a Node module, meaning you can define it as a dependency in `package.json` via:
@ -91,6 +85,10 @@ Even though this option introduces a Node.js dependency, it does allow for easy
Please see the [CHANGELOG.md](./CHANGELOG.md) file.
## Frequently Asked Questions
Please see the [FAQ.md](./FAQ.md) file.
## Best practices
As of `v1.0.3`, b3bp offers some nice re-usable libraries in `./src`. In order to make the snippets in `./src` more useful, we recommend the following guidelines.
@ -129,7 +127,7 @@ $ my_script some more args --blah
### Coding style
1. Use two spaces for tabs.
1. Use long options (`logger --priority` vs `logger -p`). If you are on cli, abbreviations make sense for efficiency. Nevertheless, when you are writing reusable scripts, a few extra keystrokes will pay off in readability and avoid ventures into man pages in the future, either by you or your collaborators. Similarly, we prefer `set -o nounset` over `set -u`.
1. Use long options (`logger --priority` vs `logger -p`). If you are on the CLI, abbreviations make sense for efficiency. Nevertheless, when you are writing reusable scripts, a few extra keystrokes will pay off in readability and avoid ventures into man pages in the future, either by you or your collaborators. Similarly, we prefer `set -o nounset` over `set -u`.
1. Use a single equal sign when checking `if [ "${NAME}" = "Kevin" ]`; double or triple signs are not needed.
### Safety and Portability
@ -140,15 +138,21 @@ $ my_script some more args --blah
1. Use `${BASH_SOURCE[0]}` if you refer to current file, even if it is sourced by a parent script. In other cases, use `${0}`.
1. Use `:-` if you want to test variables that could be undeclared. For instance, with `if [ "${NAME:-}" = "Kevin" ]`, `$NAME` will evaluate to `Kevin` if the variable is empty. The variable itself will remain unchanged. The syntax to assign a default value is `${NAME:=Kevin}`.
## Frequently Asked Questions
## Who uses b3bp?
Please see the [FAQ.md](./FAQ.md) file.
- [Transloadit](https://transloadit.com)
- [OpenCoarrays](http://www.opencoarrays.org)
- [Sourcery Institute](http://www.sourceryinstitute.org)
- [Computational Brain Anatomy Laboratory](http://cobralab.ca/)
We are looking for endorsements! Are you also using b3bp? [Let us know](https://github.com/kvz/bash3boilerplate/issues/new?title=I%20use%20b3bp) and get listed.
## Authors
- [Kevin van Zonneveld](http://kvz.io)
- [Izaak Beekman](https://izaakbeekman.com/)
- [Alexander Rathai](mailto:<Alexander.Rathai@gmail.com>)
- [Manuel Streuhofer](https://github.com/mstreuhofer)
- [Alexander Rathai](mailto:Alexander.Rathai@gmail.com)
- [Dr. Damian Rouson](http://www.sourceryinstitute.org/) (documentation, feedback)
- [@jokajak](https://github.com/jokajak) (documentation)
- [Gabriel A. Devenyi](http://staticwave.ca/) (feedback)