summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2021-01-13 16:54:47 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2021-01-13 16:54:47 +0200
commit3651965a5be8847ac54abf0b385dcbe479a7a972 (patch)
tree463d39c6f1997ac4658176399c8e058acc85e95b
parent86bd5f8016919d971b7289811465426d28cf0a31 (diff)
Proofreading changes to Bash style guide
-rw-r--r--doc/bash-style.cli36
1 files changed, 19 insertions, 17 deletions
diff --git a/doc/bash-style.cli b/doc/bash-style.cli
index 435dfe3..a76053a 100644
--- a/doc/bash-style.cli
+++ b/doc/bash-style.cli
@@ -176,7 +176,7 @@ if [ -z \"$file\" ]; then
fi
if [ ! -d \"$file\" ]; then
- fail \"'$file' does not exist or is not a directory\"
+ error \"'$file' does not exist or is not a directory\"
fi
\
@@ -257,8 +257,7 @@ while [ \"$#\" -gt 0 ]; do
...
*)
- shift
- files=(\"${files[@]}\" \"$1\")
+ files+=(\"$1\")
shift
;;
esac
@@ -439,7 +438,7 @@ foo | readarray -t r
In this case, if the function can fail, then the failure should be explicitly
checked for (either by examining \c{PIPESTATUS} or via the lack of the
-result), since the error trap will not be triggered (unless the \c{pipefail}
+result), since the \c{ERR} trap will not be triggered (unless the \c{pipefail}
shell option is set; see \l{#error-handing Error Handling} for details). For
example:
@@ -508,7 +507,7 @@ For more information on returning data from functions, see
\h1#error-handing|Error Handling|
-Our scripts use the error trap to automatically terminate the script in case
+Our scripts use the \c{ERR} trap to automatically terminate the script in case
any command fails. This is also propagated to functions and subshells by
specifying the \c{errtrace} shell option.
@@ -518,7 +517,7 @@ 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
+In particular, without \c{pipefail}, a non-zero exit 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
@@ -550,7 +549,7 @@ 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.
+Furthermore, in certain contexts, the above-mentioned \c{ERR} trap is ignored.
Quoting from the Bash manual:
\i{The \c{ERR} trap is not executed if the failed command is part of the
@@ -579,10 +578,9 @@ 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:
+the \c{ERR} trap is executed inside all the subshell commands of a pipeline
+provided the \c{errtrace} option is specified. As a result, the above code
+can be made to work using the pipe trick:
\
cleanup /no/such/dir | cat
@@ -592,19 +590,23 @@ 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.|
+\N|If \c{cleanup}'s \c{cd} fails, the \c{ERR} trap will be executed in the
++subshell, causing it to exit with an error status which the parent shell then
++makes available in \c{PIPESTATUS}.
+
+If the \c{pipefail} shell option is set, then the explicit \c{PIPESTATUS}
+check is not necessary since the function failure will trigger the \c{ERR}
+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.
+\c{ERR} 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
+the global state. The pipe trick can also be used 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,
@@ -635,7 +637,7 @@ 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.|
+that the inherited \c{ERR} 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: