// file      : doc/bash-style.cli
// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

"\title=Bash Style Guide"

// NOTES
//
// - Maximum <pre> line is 70 characters.
//

"\h1|Contents|"
"\$TOC$"

"
\h1#intro|Introduction|

Bash works best for simple tasks. Needing arrays, arithmetic, and so on, is
usually a good indication that the task at hand is too complex for Bash.

Most of the below rules can be broken if there is a good reason for it.
Besides making things consistent, rules free you from having to stop and think
every time you encounter a particular situation. But if it feels that the
prescribed way is clearly wrong, then it probably makes sense to break it.
You just need to be clear on why you are doing it.

See also \l{https://google.github.io/styleguide/shell.xml Google's Bash Style
Guide}; we agree with quite a few (but not all) items in there. In particular,
it provides a lot more rationale compared to this guide.

\h1#style|Style|

Don't use any extensions for your scripts. That is, call it just \c{foo}
rather than \c{foo.sh} or \c{foo.bash}. Use lower-case letters and dash
to separate words, for example \c{foo-bar}.

Indentation is two spaces (not tabs). Maximum line length is 79 characters
(excluding newline). Use blank lines between logical blocks to improve
readability.

Variable and function names should use lower-case letters with underscores
separating words.

For \c{if}/\c{while} and \c{for}/\c{do} the corresponding \c{then} or \c{do}
is written on the same line after a semicolon, for example:

\
if [ ... ]; then
fi

for x in ...; do
done
\

For \c{if} use \c{[ ]} for basic tests and \c{[[ ]]} only if the previous form
is not sufficient. Never use \c{test}. Do use \c{elif}.

\h1#struct|Structure|

The overall structure of the script should be as follows:

\
#! /usr/bin/env bash

# <SUMMARY>
#
# [<FUNCTIONALITY-DESCRIPTION>]
#
# [<OPTIONS-DESCRIPTION>]
#
usage=\"usage: $0 <OPTIONS>\"

owd=\"$(pwd)\"
trap \"{ cd '$owd'; exit 1; }\" ERR
set -o errtrace # Trap in functions.

function info () { echo \"$*\" 1>&2; }
function error () { info \"$*\"; exit 1; }

[<OPTIONS-ARGUMENTS-DEFAULTS>]

[<OPTIONS-ARGUMENTS-PARSING>]

[<OPTIONS-ARGUMENTS-VALIDATION>]

<FUNCTIONALITY>
\

\h#struct-summary|SUMMARY|

One-two sentences describing what the script does.

\h#struct-func-desc|FUNCTIONALITY-DESCRIPTION|

More detailed functionality description for more complex scripts.

\h#struct-opt-desc|OPTIONS-DESCRIPTION|

Description of command line options. For example:

\
# -q
#   Run quiet.
#
# -t <dir>
#   Specify the alternative toolchain installation directory.
\

\h#struct-opt|OPTIONS|

Command line options summary. For example:

\
usage=\"usage: $0 [-q] [-t <dir>] <file>\"
\

\h#struct-opt-arg-default|OPTIONS-ARGUMENTS-DEFAULTS|

Set defaults to variables that will contain option/argument values. For
example:

\
quiet=\"n\"
tools=\"/usr/local\"
file=
\

\h#struct-opt-arg-parse|OPTIONS-ARGUMENTS-PARSING|

Parse the command line options/arguments. For example:

\
while [ \"$#\" -gt 0 ]; do
  case \"$1\" in
    -q)
      quiet=\"y\"
      shift
      ;;
    -t)
      shift
      tools=\"${1%/}\"
      shift
      ;;
    *)
      if [ -n \"$1\" ]; then
        error \"$usage\"
      fi

      file=\"$1\"
      shift
      ;;
  esac
done
\

\h#struct-opt-arg-valid|OPTIONS-ARGUMENTS-VALIDATION|

Validate option/argument values. For example:

\
if [ -z \"$file\" ]; then
  error \"$usage\"
fi

if [ ! -d \"$file\" ]; then
  fail \"'$file' does not exist or is not a directory\"
fi
\

\h#struct-func|FUNCTIONALITY|

Implement script logic. For diagnostics use the \c{info()} and \c{error()}
functions defined above (so that it goes to stderr, not stdout). If using
functions, then define them just before use.

\h1#quote|Quoting|

We quote every variable expansion, no exceptions. For example:

\
if [ -n \"$foo\" ]; then
  ...
fi
\

We also quote every variable assignment:

\
quiet=\"y\"
\

This also applies to command substitution (which we always write as
\c{$(foo arg)} rather than \c{`foo arg`}), for example:

\
list=\"$(cat foo)\"
\

Note that a command substitution creates a new quoting context, for example:

\
list=\"$(basename \"$1\")\"
\

Note that quoting will inhibit globbing so you may end up with expansions
along these lines:

\
rm -f \"$dir/$name\".*
\

If you have multiple values (e.g., program arguments) that may contain spaces,
don't try to handle them with quoting and use arrays instead. Here is a
typical example of a space-aware argument handling:

\
files=()

while [ \"$#\" -gt 0 ]; do
  case \"$1\" in

    ...

    *)
      shift
      files=(\"${files[@]}\" \"$1\")
      shift
      ;;
  esac
done

rm -f \"${files[@]}\"
\

In the same vein, never write:

\
cmd $*
\

Instead always write:

\
cmd \"$@\"
\

\h1#trap|Trap|

Our scripts use the error trap to automatically terminate the script in case
any command fails. If you need to check the exit status of a command, use
\c{if}, for example:

\
if grep \"foo\" \"bar\"; then
  info \"found\"
fi

if ! grep \"foo\" \"bar\"; then
  info \"not found\"
fi
\

If you need to ignore the exit status, you can use \c{|| true}, for example:

\
foo || true
\

\h1#function|Functions|

If a function takes arguments, provide a brief usage after the function
header, for example:

\
function dist() # <pkg> <dir>
{
  ...
}
\

For non-trivial/obvious functions also provide a short description of its
functionality/purpose, for example:

\
# Prepare a distribution of the specified packages and place it into the
# specified directory.
#
function dist() # <pkg> <dir>
{
  ...
}
\

Inside functions use local variables, for example:

\
function dist()
{
  local x=\"foo\"
}
\

If the evaluation of the value may fail (e.g., it contains a program
substitution), then place the assignment on a separate line since \c{local}
will ignore the error. For example

\
function dist()
{
  local b
  b=\"$(basename \"$2\")\"
}
\
"