Re: man bash does not list 'in' as a builtin command

[Robert Elz]

    Date:        Mon, 25 Nov 2019 19:13:19 -0800
    From:        Peter Benjamin <pete@peterbenjamin.com>
    Message-ID:  
<14db6b9f69f249db60a0f92df80339d88efba152.camel@peterbenjamin.com>

  | Only those RESERVED WORDS when tried at the CLI, alone, that generate a
  | 'confusing' error message,

It is possible for someone to be confused by any message, it depends
upon their state of mind and expectations - and the longer the message
the more likely it is to confuse.

With that in mind the message in question isn't really confusing at all.
It says that's a syntax error (syntax is the rules of the language, so it
means that the rules for the sh language have been violated), and it tells
you that "in" was where it detected the error, which gives you somewhere
to look - and the first place would be the language definition in the man
page.

If you want to see what happens when you use a builtin command incorrectly
try entering (just)
        getopts
and see what the error message from that one looks like.   That's perfectly
good syntax as far as the shell is concerned (no different than "ls" or
"df" as a word alone as a command) but doesn't meet the requirements of
the getopts command (it requires args).

  | Just change the error message, to include the words "See 'man bash'
  | RESERVED WORDS".

That might be possible, but as I understand it, the bash parser is
written in yacc (or bison) and error handling with those parsers is
not nearly as easy as one might hope.

Further, while looking at the reserved words section was the solution for
your issue - normally this kind of error tends to mean something different,
and the right place to look is in the grammar.   Parser error handling code
would need to be made absurdly complex to distinguish the cases.

  | And perhaps in the RESERVED WORDS section, include a sentence like:
  |
  |    These words should not be used as a custom script name as bash will
  | output an error message that is not easily deciphered.

The message is actually quite clear.   And there is no reason that you
cannot have a script called "in" - you just have to execute it differently
(as ./in or $HOME/bin/in or \in or similar).   Doing so would be unconventional
but it is certainly neither impossible nor incorrect.

  |    Bash found the custom script name 'in' in the PATH, but this word is
  | a RESERVED WORD, not to be used as a script name.

It is never going to be looking in PATH at the point it detects that error.
I haven't looked at the code for bash, but I can assure you that PATH
searches there, for an obscure and rare error just is not worth the bother.

Further, as above, there is no reason not to use one as a script name if
you really want to do that.

  | Of course, that means during the syntax error processing,

With a parser generator (like yacc or bison) what you get told is
"the following token cannot occur where it was used" and not much other
info tends to be available.

  | Hmm, I reread again the RESERVED WORD list, to see if 'in' is the only
  | one that can not be 'first.'

It is the one that never occurs in the command name position, yes.
But plenty of others also generate syntax errors, as they can only
be used in specific contexts

Try entering any of these lines, and see what bash says:

        }
        then
        do
        done
        fi
        else
        esac

It might look familiar.

But it is not just reserved words which generates this kind of error
try also these example lines (lots more similar exist)

        )
        |
        >>>>
        ><

Familiar error?  No reserved words involved, but it from the parser
it is the exact same problem, detected in the exact same way.

Or perhaps

        ls | | grep foo

Recognise that error message?

  | It did not occur to me, that bash would be programmed to generate an
  | error message, when 'in' was first, as it can never, ever be first.

That is exactly why it generated the error message - you did something that
was against the rules of the language (ie: a syntax error).

It is possible to program a shell so that "in" is only treated as a
reserved word when the context where it might appear occurs.  The
NetBSD sh (currently) acts that way:

        [jinx]{2}$ in foo
        in: not found

(I do not have a script, or function, or executable, called "in", if I
did it would have been executed).

This is contrary to the requirements of POSIX, and is something I keep
contemplating fixing (and "in" is truly a one off special case for this).
But as it is is harming no-one (almost no-one knows it works that way,
so people don't abuse it) so correcting this isn't high priority (and
see below for an opinion on fixing what does not really need fixing.)

  | My thought the bash command line parser would be coded such to only
  | generate syntax errors based upon the first word's required syntax.

"reserved" words can only be used where the grammar permits them
(but note, that in shells, only the command word position is usually
eligible to be a reserved word, there's nothing wrong with
        echo get out of here, do something else for yourself
the "in" there is not a reserved word (nor are "do" "else" or "for").
There are a couple of exceptions to the command word rule, being "case" and
"for" statements, which allow (or require) reserved words in other positions.

  | And so, to conclude this overly long email, I conclude this issue has
  | been before the bash experts for a long time.  And if I went looking,
  | in the bash forums, I would find a set of posts, dealing with the issue
  | of this special word "in", and it's unique role in bash.  And policy
  | consistency would be a focus of those forum threads.

Dream on.

  | I see the issue as one of: Is there a volunteer who can step up to make
  | code changes and man page edits,

I see the issue as finished.   You will never be confused by this again.

I don't recall it as any kind of common problem - as best as I can remember
no-one has ever submitted a bug report about anything like this for the
NetBSD sh.   Not one ever, in decades (and we have had some weird "bug"
reports over that period).

So, I'd submit that nothing needs doing.   While doc and code can almost
always be improved, attempts to do so quite often lead to the opposite
result.   Unless there is something really wrong, or missing, it is
generally best to leave well enough alone.   This one is well enough.

  | That's one man's opinion.  He is not changing it.

That's fine, and it is well known what is said about opinions.   This
message is another.

kre