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

Improved english (#43)

Browse Source 
* Not completely done yet

* Not completely done yet either

* Update README.md

* One of two ways

* Prefer `source` over `.` for readability

* Use backticks where possible

* Update FAQ.md
This commit is contained in:
Kevin van Zonneveld 2016-06-28 15:14:24 +02:00 committed by GitHub
parent 35b51072b3
commit 34e437b23c
2 changed files with 64 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
FAQ.md
View File

@ -22,34 +22,34 @@ A 'cli' is a [command-line interface](https://en.wikipedia.org/wiki/Command-line
## How do I incorporate BASH3 Boilerplate into my own project?
You can incorporate BASH3 Boilerplate into your project one of three ways:
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 for unwanted things
1. Download [main.sh](https://github.com/kvz/bash3boilerplate/blob/master/main.sh) and start pressing the delete-key to remove unwanted things
Once the `main.sh` has been tailor-made for your project you could either append your own script in the same file, or source it:
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 dot (`.`) include feature, e.g.
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.:
```bash
#!/usr/bin/env bash
. main.sh
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](https://github.com/kvz/bash3boilerplate/blob/master/main.sh) in your script or at the command line:
```bash
#!/usr/bin/env bash
. main.sh
source main.sh
```
## How do I add a command-line flag?
1. Copy the line 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. 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 the "Required." text if the flag is optional.
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. 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 the `Required.` text, if the flag is optional.
## How do I access the value of a command-line argument?
To evaluate the value of an argument, append the corresponding single-character flag to the text `$arg_`. For example, if the [read block]
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 +63,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, `${__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}`, and the current directory of the administrator running the script, accessible via `$(pwd)`.
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)`.
## How do I submit an issue report?
@ -71,20 +71,20 @@ Please visit our [Issues](https://github.com/kvz/bash3boilerplate/issues) page.
## How can I contribute to this project?
Please fork this repository. Then create a branch containing your suggested changes and submit a pull request based on the master branch
of <https://github.com/kvz/bash3boilerplate/>. We're a welcoming bunch, happy to accept your contributions!
Please fork this repository. After that, create a branch containing your suggested changes and submit a pull request based on the master branch
of <https://github.com/kvz/bash3boilerplate/>. We are always more than happy to accept your contributions!
## 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" as a reference to
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".
Somewhat inconsistent – but true to Unix ancestry – the abbreviation for our project is "b3bp".
## How can I locally develop and preview the b3bp website?
You should have a working Node.js >=10 and Ruby >=2 install on your workstation. Afterwards, you can run:
You should have a working Node.js >=10 and Ruby >=2 install on your workstation. When that is the case, you can run:
```bash
npm run web:preview
@ -94,36 +94,36 @@ This will install and start all required services and automatically open a webbr
The source mainly consists of:
- `./README.md` Front page
- `./FAQ.md` FAQ page
- `./CHANGELOG.md` Changelog page
- `./website/_layouts/default.html` Design in which all pages are rendered
- `./website/public/app.js` Main JS file
- `./website/public/style.css` Main CSS file
- `./README.md` (Front page)
- `./FAQ.md` (FAQ page)
- `./CHANGELOG.md` (changelog page)
- `./website/_layouts/default.html` (the design in which all pages are rendered)
- `./website/public/app.js` (main JS file)
- `./website/public/style.css` (main CSS file)
The rest is dark magic you should probably steer clear from : )
The rest is dark magic from which you should probably steer clear. : )
Any changes should be proposed as PRs. Anything added to `master` is automatically deployed using a combination of Travis CI and GitHub Pages.
## You're saying you are portable - why won't b3bp code run in dash / busybox / posh / ksh / mksh / zsh?
## You are saying you are portable, but why won't b3bp code run in dash / busybox / posh / ksh / mksh / zsh?
When we say _portable_, we mean across Bash versions. Bash is widespread and most systems
offer at least version 3 of it. Make sure you have that available, and b3bp will work for you.
offer at least version 3 of it. Make sure you have that available and b3bp will work for you.
We run automated tests to make sure that it will, here's proof for the following platforms:
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)`
This portability however does not mean 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?
We used to offer a magic `__os` variable, but quickly [discovered](https://github.com/kvz/bash3boilerplate/issues/38) that it would be hard
to create a satisfactory abstraction that is correct, covers enough use-cases,
and still has a relatively small footprint in `main.sh`.
We used to offer a magic `__os` variable, but we quickly [discovered](https://github.com/kvz/bash3boilerplate/issues/38) that it would be hard
to create a satisfactory abstraction that is not only correct, but also covers enough use-cases,
while still having a relatively small footprint in `main.sh`.
For simple OS detection, we recommend using the `${OSTYPE}` variable available in Bash as
is demoed in [this stackoverflow post](http://stackoverflow.com/a/8597411/151666):

61
README.md
View File

@ -29,23 +29,22 @@ they are reusable as-is in most scripts.
## Goals
Delete-Key-**Friendly**. We propose using [`main.sh`](http://bash3boilerplate.sh/main.sh)
as a base and removing the parts you don't need, rather than introducing packages, includes, compilers, etc.
This may feel a bit archaic at first, but that is exactly the strength of Bash scripts that we want to embrace.
Delete-Key-**Friendly**. In stead 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're targeting Bash 3 (OSX still ships
with 3 for instance). If you're going to ask people to install
**Portable**. We are targeting Bash 3 (OSX still ships
with 3, for instance). If you are going to ask people to install
Bash 4 first, you might as well pick a more advanced language as a
dependency.
## Features
- Conventions so that after a while, all your scripts will follow the same, battle-tested structure
- Safe by default (break on error, pipefail, etc)
- Conventions that will make sure that all your scripts follow the same, battle-tested structure
- Safe by default (break on error, pipefail, etc.)
- Configuration by environment variables
- Simple command-line argument parsing that requires no external dependencies. Definitions are parsed from help info, so there is no duplication
- Simple command-line argument parsing that requires no external dependencies. Definitions are parsed from help info, ensuring there will be no duplication
- 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
- 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?
@ -54,15 +53,15 @@ dependency.
- [Sourcery Institute](http://www.sourceryinstitute.org)
- [Computational Brain Anatomy Laboratory](http://cobralab.ca/)
We're looking for endorsement! Are you also using b3bp? [Let us know](https://github.com/kvz/bash3boilerplate/issues/new?title=I%20use%20b3bp) and get listed.
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 3 different ways you can install b3bp:
There are three different ways to install b3bp:
### option 1: Download the main template
Use curl or wget to download the source, save as your script, and start deleting the unwanted bits, and adding your own logic.
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.
```bash
wget http://bash3boilerplate.sh/main.sh
@ -71,22 +70,22 @@ vim main.sh
### option 2: Clone the entire project
Besides `main.sh`, this will get you the entire b3bp repository including a few extra functions that we keep in the `./src` directory.
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.
```bash
git clone git@github.com:kvz/bash3boilerplate.git
```
### option 3: Require via npm
### option 3: Require via npm0
As of `v1.0.3`, b3bp can also be installed as a Node module so you can define it as a dependency in `package.json` via:
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:
```bash
npm init
npm install --save --save-exact bash3boilerplate
```
Although this option introduces a Node.js dependency, this does allow for easy version pinning and distribution in environments that already have this prerequisite. But, this is optional and nothing prevents you from ignoring this possibility.
Even though this option introduces a Node.js dependency, it does allow for easy version pinning and distribution in environments that already have this prerequisite. This is, however, entirely optional and nothing prevents you from ignoring this possibility.
## Changelog
@ -94,11 +93,11 @@ Please see the [CHANGELOG.md](./CHANGELOG.md) file.
## Best practices
As of `v1.0.3`, b3bp adds some nice re-usable libraries in `./src`. In order to make the snippets in `./src` more useful, we recommend these guidelines.
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.
### Function packaging
It's nice to have a Bash package that can be used in the terminal and also be invoked as a command line function. To achieve this the exporting of your functionality *should* follow this pattern:
It is nice to have a Bash package that can not only be used in the terminal, but also invoked as a command line function. In order to achieve this, the exporting of your functionality *should* follow this pattern:
```bash
if [ "${BASH_SOURCE[0]}" != "${0}" ]; then
@ -109,7 +108,7 @@ else
fi
```
This allows a user to `source` your script or invoke as a script.
This allows a user to `source` your script or invoke it as a script.
```bash
# Running as a script
@ -123,23 +122,23 @@ $ my_script some more args --blah
### Scoping
1. In functions, use `local` before every variable declaration
1. Use `UPPERCASE_VARS` to indicate environment variables that can be controlled outside your script
1. Use `__double_underscore_prefixed_vars` to indicate global variables that are solely controlled inside your script, with the exception of arguments which are already prefixed with `arg_`, and functions, over which b3bp poses no restrictions.
1. In functions, use `local` before every variable declaration.
1. Use `UPPERCASE_VARS` to indicate environment variables that can be controlled outside your script.
1. Use `__double_underscore_prefixed_vars` to indicate global variables that are solely controlled inside your script, with the exception of arguments that are already prefixed with `arg_`, as well as functions, over which b3bp poses no restrictions.
### Coding style
1. Use two spaces for tabs
1. Use long options (`logger --priority` vs `logger -p`). If you're on cli, abbreviations make sense for efficiency. but when you're writing reusable scripts a few extra keystrokes will pay off in readability and avoid ventures into man pages in the future 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.
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 a single equal sign when checking `if [ "${NAME}" = "Kevin" ]`; double or triple signs are not needed.
### Safety and Portability
1. Use `{}` to enclose your variables in. Otherwise Bash will try to access the `$ENVIRONMENT_app` variable in `/srv/$ENVIRONMENT_app`, whereas you probably intended `/srv/${ENVIRONMENT}_app`. Since it's easy to miss cases like this, we recommend making enclosing a habit.
1. Use `set` rather than relying on a shebang like `#!/usr/bin/env bash -e` as that is neutralized when someone runs your script as `bash yourscript.sh`
1. Use `#!/usr/bin/env bash` as it is more portable than `#!/bin/bash`.
1. Use `${BASH_SOURCE[0]}` if you refer to current file even if it is sourced by a parent script. Otherwise 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}`.
1. Use `{}` to enclose your variables. Otherwise, Bash will try to access the `$ENVIRONMENT_app` variable in `/srv/$ENVIRONMENT_app`, whereas you probably intended `/srv/${ENVIRONMENT}_app`. Since it is easy to miss cases like this, we recommend that you make enclosing a habit.
1. Use `set`, rather than relying on a shebang like `#!/usr/bin/env bash -e`, since that is neutralized when someone runs your script as `bash yourscript.sh`.
1. Use `#!/usr/bin/env bash`, as it is more portable than `#!/bin/bash`.
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
@ -163,4 +162,4 @@ Please see the [FAQ.md](./FAQ.md) file.
Copyright (c) 2013 Kevin van Zonneveld and [contributors](https://github.com/kvz/bash3boilerplate#authors).
Licensed under [MIT](https://raw.githubusercontent.com/kvz/bash3boilerplate/master/LICENSE).
You are not obligated to bundle the LICENSE file with your b3bp projects as long
as you leave these references intact in header comments of your source files.
as you leave these references intact in the header comments of your source files.