Expand error handling section, other tweaks in Bash style guide

1 files changed, 223 insertions, 23 deletions

diff --git a/doc/bash-style.cli b/doc/bash-style.cli
index ef81af2..1b32b1a 100644
--- a/doc/bash-style.cli
+++ b/doc/bash-style.cli
@@ -52,9 +52,17 @@ for x in ...; do
 done
 \
 
-For \c{if} use \c{[ ]} for basic tests and \c{[[ ]]} only if the previous form
-is not sufficient. Use \c{test} for filesystem tests (presence of files,
-etc). Do use \c{elif}.
+Do use \c{elif} instead of nested \c{else} and \c{if}.
+
+For \c{if} use \c{[ ]} for basic tests and \c{[[ ]]} if the previous form is
+not sufficient or hairy. In particular, \c{[[ ]]} results in cleaner code
+for complex expressions, for example:
+
+\
+if [[ \"$foo\" && (\"$bar\" || \"$baz\") ]]; then
+  ...
+fi
+\
 
 \h1#struct|Structure|
 
@@ -73,7 +81,8 @@ usage=\"usage: $0 <OPTIONS>\"
 
 owd=\"$(pwd)\"
 trap \"{ cd '$owd'; exit 1; }\" ERR
-set -o errtrace # Trap in functions.
+set -o errtrace   # Trap in functions and subshells.
+shopt -s lastpipe # Execute last pipeline command in current shell.
 
 function info () { echo \"$*\" 1>&2; }
 function error () { info \"$*\"; exit 1; }
@@ -155,7 +164,7 @@ done
 \
 
 If the value you are expecting from the command line is a directory path,
-the always strip the trailing slash (as shown above for the \c{-t} option).
+then always strip the trailing slash (as shown above for the \c{-t} option).
 
 \h#struct-opt-arg-valid|OPTIONS-ARGUMENTS-VALIDATION|
 
@@ -201,19 +210,18 @@ list=\"$(basename \"$1\")\"
 \
 
 We also quote values that are \i{strings} as opposed to options/file names,
-paths, or integers. If setting a variable that will contain one of these
-unquoted values, try to give it a name that reflects its type (e.g.,
-\c{foo_file} rather than \c{foo_name}). Prefer single quotes for \c{sed}
+paths, enum-like values, or integers. Prefer single quotes for \c{sed}
 scripts, for example:
 
 \
-proto=\"https\"
-quiet=\"y\"
-verbosity=1
-dir=/etc
-out=/dev/null
-file=manifest
-seds='s%^./%%'
+url=\"https://example.org\"  # String.
+quiet=y                    # Enum-like.
+verbosity=1                # Integer.
+dir=/etc                   # Directory path.
+out=/dev/null              # File path.
+file=manifest              # File name.
+option=--quiet             # Option name.
+seds='s%^./%%'             # sed script.
 \
 
 Note that quoting will inhibit globbing so you may end up with expansions
@@ -279,11 +287,85 @@ echo \"files: ${files[@]}\"  # $1='files: one', $2='2 two', $3='three'
 echo \"files: ${files[*]}\"  # $1='files: one 2 two three'
 \
 
-\h1#trap|Trap|
+\h1#subshell|Subshell|
+
+Bush executes certain constructs in \i{subshells} and some of these constructs
+may not be obvious:
+
+\ul|
+
+\li|Explicit subshell: \c{(...)}|
+
+\li|Pipeline: \c{...|...}|
+
+\li|Command substitution: \c{$(...)}|
+
+\li|Process substitution: \c{<(...)}, \c{>(...)}|
+
+\li|Background: \c{...&}, \c{coproc ...}|
+
+|
+
+Naturally, a subshell cannot modify any state in the parent shell, which
+sometimes leads to counter-intuitive behavior, for example:
+
+\
+lines=()
+
+... | while read l; do
+  lines+=(\"$l\")
+done
+\
+
+At the end of the loop, \c{lines} will remain empty since the loop body is
+executed in a subshell. One way to resolve this is to use the program
+substitution instead of the pipeline:
+
+\
+lines=()
+
+while read l; do
+  lines+=(\"$l\")
+done < <(...)
+\
+
+This, however, results in an unnatural, backwards-looking (compared to the
+pipeline) code. Instead, we can request the last command of the pipeline to be
+executed in the parent shell with the \c{lastpipe} shell option, for example:
+
+\
+shopt -s lastpipe
+
+lines=()
+
+... | while read l; do
+  lines+=(\"$l\")
+done
+\
+
+\N|The \c{lastpipe} shell option is inherited by functions and subshells.|
+
+
+\h1#error-handing|Error Handling|
 
 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:
+any command fails. This is also propagated to functions and subshells by
+specifying the \c{errtrace} shell option.
+
+\N|While the \c{pipefail} and \c{nounset} options may also seem like a good
+idea, they have subtle, often latent pitfalls that make them more trouble than
+they are worth (see \l{https://mywiki.wooledge.org/BashPitfalls#pipefail
+\c{pipefail} pitfalls}, \l{https://mywiki.wooledge.org/BashPitfalls#nounset
+\c{nounset} pitfalls}).
+
+In particular, without \c{pipefail}, non-zero exist of any command in the
+pipeline except the last is ignored. As a result, the pipeline needs to be
+designed to work correctly in such cases, normally by relying on the input (or
+lack thereof) to the last command to convey the failure. Alternatively, the
+exit status of the pipeline commands can be explicitly checked using the
+\c{PIPESTATUS} array.|
+
+If you need to check the exit status of a command, use \c{if}, for example:
 
 \
 if grep \"foo\" /tmp/bar; then
@@ -304,12 +386,130 @@ if v=\"$(...)\"; then
 fi
 \
 
-If you need to ignore the exit status, you can use \c{|| true}, for example:
+But keep in mind that in Bash a failure is often indistinguishable from a
+true/false result. For example, in the above \c{grep} command, the result will
+be the same whether there is no match or if the file does not exist.
+
+Furthermore, in certain contexts, the above-mentioned error trap is ignored.
+Quoting from the Bash manual:
+
+\i{The \c{ERR} trap is not executed if the failed command is part of the
+command list immediately following an \c{until} or \c{while} keyword, part of
+the test following the \c{if} or \c{elif} reserved words, part of a command
+executed in a \c{&&} or \c{||} list except the command following the final
+\c{&&} or \c{||}, any command in a pipeline but the last, or if the command’s
+return status is being inverted using \c{!}. These are the same conditions
+obeyed by the \c{errexit} (\c{-e}) option.}
+
+To illustrate the gravity of this point, consider the following example:
 
 \
-foo || true
+function cleanup()
+{
+  cd \"$1\"
+  rm -f *
+}
+
+if ! cleanup /no/such/dir; then
+  ...
+fi
 \
 
+Here, the \c{cleanup()} function will continue executing (and may succeed)
+even if the \c{cd} command has failed.
+
+Note, however, that notwithstanding the above statement from the Bash manual,
+the trap is executed in all the commands of a pipeline provided the
+\c{errtrace} option is specified (presumably because commands of a pipeline
+are said to execute in subshells). As a result, the above code can be made to
+work using the pipe trick:
+
+\
+cleanup /no/such/dir | cat
+
+if [ \"${PIPESTATUS[0]}\" -ne 0 ]; then
+  ...
+fi
+\
+
+\N|If the \c{pipefail} shell option is set, then the explicit \c{PIPESTATUS}
+check is not necessary since the function failure will trigger the error trap
+in the current shell.|
+
+The recommendation is then to avoid calling functions in contexts where the
+error trap is ignored resorting to the pipe trick where that's not possible.
+And to be mindful of the potential ambiguity between the true/false result and
+failure for other commands. The use of the \c{&&} and \c{||} command
+expressions is best left to the interactive shell.
+
+\N|The pipe trick cannot be used if the function needs to modify the global
+state. Such a function, however, can return the exit status also as part of
+the global state. The pipe trick can also be used to to ignore the exit status
+of a command (provided \c{pipefail} is not set).|
+
+The pipe trick can also be used to distinguish between different exit codes,
+for example:
+
+\
+function foo()
+{
+  bar  # If this command fails, the function returns 1.
+
+  if ... ; then
+    return 2
+  fi
+}
+
+foo | cat
+
+case \"${PIPESTATUS[0]}\" in
+  0)
+    ;;
+  1)
+    exit 1
+    ;;
+  2)
+    ...
+    ;;
+esac
+\
+
+\N|In such functions it makes sense to keep exit code 1 to mean failure so
+that the inherited error trap can be re-used.|
+
+This technique can be further extended to implement functions that both
+return multiple exit codes and produce output, for example:
+
+\
+function foo()
+{
+  bar  # If this command fails, the function returns 1.
+
+  if ... ; then
+    return 2
+  fi
+
+  echo result
+}
+
+foo | readarray -t r
+
+case \"${PIPESTATUS[0]}\" in
+  0)
+    echo \"${r[0]}\"
+    ;;
+  1)
+    exit 1
+    ;;
+  2)
+    ...
+    ;;
+esac
+\
+
+\N|We use \c{readarray} instead of \c{read} since the latter fails if the left
+hand side of the pipeline does not produce anything.|
+
 
 \h1#bool|Boolean|
 
@@ -347,8 +547,8 @@ 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.
+# Prepare a distribution of the specified packages and place it
+# into the specified directory.
 #
 function dist() # <pkg> <dir>
 {
@@ -367,7 +567,7 @@ function dist()
 
 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 cause the error to be ignore. For example:
+will cause the error to be ignored. For example:
 
 \
 function dist()