remove YYFAIL from lalr1.java and yacc.c

[Joel E. Denny]

I propose we remove the YYFAIL feature from all skeletons as of release 
2.5.  My rationale is as follows:

1. YYFAIL only appears in two skeletons, and removing it from them should 
not create a legitimate backward incompatibility:

a. YYFAIL appears in yacc.c but is not documented for yacc.c.  Comments in 
yacc.c describe it as follows:

  /* Like YYERROR except do call yyerror.  This remains here temporarily
     to ease the transition to the new meaning of YYERROR, for GCC.
     Once GCC version 2 has supplanted version 1, this can go.  */

In other words, we've been planning to get rid of it for a long while.  
(However, is there any evidence that users actually use it?  Do we need to 
poll them or warn them somehow?)

b. YYFAIL is documented for lalr1.java, but that skeleton is still labeled 
as experimental, so we're free to change its interface.

2. YYFAIL's invocation of yyerror is not useful:

a. If verbose error messages are not enabled, then it's easy for the user 
to just report the simple "syntax error" himself before invoking YYERROR. 
"semantic error" or a more specific message would really be more 
appropriate anyway because any syntactic analysis (at least in one sense) 
cannot predict YYERROR and YYFAIL invocations.  That includes the 
syntactic analysis done for verbose error messages....

b. If verbose error messages are enabled, the expected token list it 
reports is almost certainly wrong because YYFAIL rejects some tokens from 
that list.  The expected token list might even include the token reported 
as unexpected!  For example, try the input "b" for this grammar:

  start: {         } 'a'
       | { YYFAIL; } 'b'
       ;

The output is:

  syntax error, unexpected 'b', expecting 'b'

Of course, expected token lists are broken anyway by state merging and 
default reductions (that's why 'a' is missing in this example), but my 
upcoming lookahead correction technique will address that issue for LALR 
and IELR, and canonical LR already addresses it:

  syntax error, unexpected 'b', expecting 'a' or 'b'

3. Unlike YYERROR, YYFAIL does not pop the RHS of the production.  Not 
popping could be dangerous if the semantic action already freed or 
otherwise used some of the RHS values.  Moreover, it's inconsistent with 
the documented way in which Bison normally handles the RHS.  That is, 
YYERROR, YYABORT, and YYACCEPT all pop the RHS so that their values won't 
be freed or reused later.

4. There's one other difference between YYFAIL and YYERROR: if the parser 
has not shifted a token since the error token, YYFAIL will discard the 
lookahead before popping the stack again.  In other words, YYFAIL acts 
more like a subsequent syntax error, but YYERROR restarts error recovery. 
It's not clear to me yet which approach is better, but the inconsistency 
is just another undocumented point of confusion.  If the user really needs 
to remove the lookahead before invoking YYERROR, yyclearin should be 
provided.

5. Bison development and user documentation would be easier if all 
skeletons made the same decision about whether to support YYFAIL.