Re: local failure

[John Passaro]

I think the underlying question here is not exactly "how do I gather this
from the docs" as much as it is "how was I supposed to know about this and
act on it before I had to debug it?" The bash manual is always "adequate"
in the sense that almost any question can be answered by carefully
consulting it -- but that doesn't help the person who either is unpracticed
at the occasionally arcane art of *reading* the bash manual, or who doesn't
even know they need to ask a question (let alone how to articulate it).
I've been consulting the bash manual for nearly a decade but I still find
myself in this position every now and then.

That's why I want to plug linting your shell scripts, preferably in your
text editor. You'll catch a lot of problems before they happen and just get
better at shell scripting. My preferred tool, ShellCheck (
https://github.com/koalaman/shellcheck), alerted me to this problem a
couple of years ago, and lots, lots, lots more. It incorporates into Vim
easily via the plugin "Syntastic"; I'm sure it's easy to incorporate for
other text editors as well.

On Sun, May 31, 2020 at 12:37 PM Robert Elz <kre@munnari.oz.au> wrote:

>     Date:        Sun, 31 May 2020 10:29:27 +0100
>     From:        Laurent Picquet <lpicquet@gmail.com>
>     Message-ID:  <CAH+roKX-H_PjDu+UBPDiVUQjnd2eKK0E=L1r=
> 0wg33X5paJpEg@mail.gmail.com>
>
>   | This behaviour is not fully documented
>
> Nothing is ever "fully" documented, as it is always possible to
> write even more text about anything at all - and if that were done
> then it is clear that what existed before was not "full".
>
> So, instead of "fully documented" let's use "adequately documented"
> and for that it is.
>
> But you do need to understand how things fit together to follow.
>
> First, the exit status is only ever set as the result of executing
> a command - and only a command in the current execution environment.
>
>        ?      Expands to the exit status of the most recently executed
>               foreground pipeline.
>
> [elsewhere it is noted that a simple command is a degenerate pipeline,
> so is a compound command for that matter.]
>
> "local" is such a command, and like all such commands, its exit status
> is documented...
>
>         The return status is 0 unless local is used outside a
>         function, an invalid name is supplied, or name is a readonly
>         variable.
>
> (that text has been previously quoted in this thread).
>
> Command substitutions execute in a different shell execution environment
> (nothing that happens in one has any effect upon the shell that contains
> them - except that stdout from the command substitution is inserted into
> the current command line (and then potentially subject to field splitting,
> pathname expansion, ...) -- it becomes a part of some other command.
>
> There is one exception to the case that only commands in the current
> execution environment ever set the exit status, which is documented in
> bash(1) as ...
>
>        If there is a command name left after expansion, execution proceeds
> as
>        described below.  Otherwise, the command exits.  If one of the
>        expansions contained a command substitution, the exit status of the
>        command is the exit status of the last command substitution
> performed.
>        If there were no command substitutions, the command exits with a
> status
>        of zero.
>
> None that neither redirects nor variable assignments are commands (but
> almost everything else that you would write in a sh script is, including
> "local").   The "as described below" involves locating the command, running
> it, and obtaining its exit status - and is what is done when there is a
> command.
>
> When there isn't - which is what happens when all there was was
> variable assignments &/or redirects - then, and only then, does the:
>
>         If one of the expansions contained a command substitution, the
>         exit status of the command is the exit status of the last command
>         substitution performed.
>
> This is the only way that the exit status of a command substitution can
> ever be observed in the parent shell.   But you have to read the entire
> man page to observe that nowhere else is the status of a command
> substitution
> ever reported.
>
> So, the doc is all there, and it is possible to work out what happens.
>
> As above, it is always possible to write more - but write too much, and
> instead of a manual page, what would be left would be a tutorial, or
> perhaps
> even a book (but there's already one, perhaps more than one, of those).
>
> There is certainly nothing special about the local command in this context,
> any command where there happens to be a command substitution on the command
> line somewhere works exactly the same way, so it would be wrong to make any
> special note of this in the doc for "local" without also putting the same
> extra info in the descriptions of every other command.
>
> kre
>
>
>