diff options
Diffstat (limited to 'doc/bash-style.cli')
| -rw-r--r-- | doc/bash-style.cli | 36 |
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: |