YYFAIL: deprecate.

* NEWS (2.4.2): Document deprecation and the phase-out plan.
* data/lalr1.java (parser::YYStack::YYFAIL): Add comment about
deprecation.
* data/yacc.c (YYFAIL): Likewise, and suppress warnings about
YYFAIL from GCC cpp's -Wunused-macros.
* doc/bison.texinfo (Java Action Features): Remove YYFAIL
documentation.
(LocalWords): Remove YYFAIL.

ChangeLog

@@ -1,3 +1,15 @@
+2009-12-21  Joel E. Denny  <jdenny@clemson.edu>
+
+	YYFAIL: deprecate.
+	* NEWS (2.4.2): Document deprecation and the phase-out plan.
+	* data/lalr1.java (parser::YYStack::YYFAIL): Add comment about
+	deprecation.
+	* data/yacc.c (YYFAIL): Likewise, and suppress warnings about
+	YYFAIL from GCC cpp's -Wunused-macros.
+	* doc/bison.texinfo (Java Action Features): Remove YYFAIL
+	documentation.
+	(LocalWords): Remove YYFAIL.
+
 2009-12-20  Joel E. Denny  <jdenny@clemson.edu>
 
 	tests: cleanup.

NEWS

@@ -243,6 +243,45 @@ Bison News
   Bison's Java feature as a whole including its current usage of %code
   is still considered experimental.
 
+** YYFAIL is deprecated and will eventually be removed.
+
+  YYFAIL has existed for many years as an undocumented feature of
+  deterministic parsers in C generated by Bison.  Previously, it was
+  documented for Bison's experimental Java parsers.  YYFAIL is no longer
+  documented for Java parsers and is formally deprecated in both cases.
+  Users are strongly encouraged to migrate to YYERROR, which is
+  specified by POSIX.
+
+  Like YYERROR, you can invoke YYFAIL from a semantic action in order to
+  induce a syntax error.  The most obvious difference from YYERROR is
+  that YYFAIL will automatically invoke yyerror to report the syntax
+  error so that you don't have to.  However, there are several other
+  subtle differences between YYERROR and YYFAIL, and YYFAIL suffers from
+  inherent flaws when %error-verbose or `#define YYERROR_VERBOSE' is
+  used.  For a more detailed discussion, see:
+
+    http://lists.gnu.org/archive/html/bison-patches/2009-12/msg00024.html
+
+  The upcoming Bison 2.5 will remove YYFAIL from Java parsers, but
+  deterministic parsers in C will continue to implement it.  However,
+  because YYFAIL is already flawed, it seems futile to try to make new
+  Bison features compatible with it.  Thus, during parser generation,
+  Bison 2.5 will produce a warning whenever it discovers YYFAIL in a
+  rule action.  In a later release, YYFAIL will be disabled for
+  %error-verbose and `#define YYERROR_VERBOSE'.  Eventually, YYFAIL will
+  be removed altogether.
+
+  There exists at least one case where Bison 2.5's YYFAIL warning will
+  be a false positive.  Some projects add phony uses of YYFAIL and other
+  Bison-defined macros for the sole purpose of suppressing C
+  preprocessor warnings (from GCC cpp's -Wunused-macros, for example).
+  To avoid Bison's future warning, such YYFAIL uses can be moved to the
+  epilogue (that is, after the second `%%') in the Bison input file.  In
+  this release (2.4.2), Bison already generates its own code to suppress
+  C preprocessor warnings for YYFAIL, so projects can remove their own
+  phony uses of YYFAIL if compatibility with Bison releases prior to
+  2.4.2 is not necessary.
+
 ** Internationalization.
 
   Fix a regression introduced in Bison 2.4: Under some circumstances,

data/lalr1.java

@@ -352,7 +352,8 @@ b4_lexer_if([[
 
   /**
    * Returned by a Bison action in order to print an error message and start
-   * error recovery.  */
+   * error recovery.  Formally deprecated in Bison 2.4.2's NEWS entry, where
+   * a plan to phase it out is discussed.  */
   public static final int YYFAIL = 3;
 
   private static final int YYNEWSTATE = 4;

data/yacc.c

@@ -609,9 +609,18 @@ static const ]b4_int_type_for([b4_toknum])[ yytoknum[] =
 
 /* 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.  */
+   Once GCC version 2 has supplanted version 1, this can go.  However,
+   YYFAIL appears to be in use.  Nevertheless, it is formally deprecated
+   in Bison 2.4.2's NEWS entry, where a plan to phase it out is
+   discussed.  */
 
 #define YYFAIL		goto yyerrlab
+#if defined YYFAIL
+  /* This is here to suppress warnings from the GCC cpp's
+     -Wunused-macros.  Normally we don't worry about that warning, but
+     some users do, and we want to make it easy for users to remove
+     YYFAIL uses, which will produce warnings from Bison 2.5.  */
+#endif
 
 #define YYRECOVERING()  (!!yyerrstatus)
 

doc/bison.texinfo

@@ -9925,11 +9925,6 @@ Start error recovery without printing an error message.
 @xref{Error Recovery}.
 @end deffn
 
-@deffn {Statement} {return YYFAIL;}
-Print an error message and start error recovery.
-@xref{Error Recovery}.
-@end deffn
-
 @deftypefn {Function} {boolean} recovering ()
 Return whether error recovery is being done. In this state, the parser
 reads token until it reaches a known state, and then restarts normal
@@ -11330,5 +11325,5 @@ grammatically indivisible.  The piece of text it represents is a token.
 @c LocalWords: superclasses boolean getErrorVerbose setErrorVerbose deftypecv
 @c LocalWords: getDebugStream setDebugStream getDebugLevel setDebugLevel url
 @c LocalWords: bisonVersion deftypecvx bisonSkeleton getStartPos getEndPos
-@c LocalWords: getLVal defvar YYFAIL deftypefn deftypefnx gotos msgfmt
+@c LocalWords: getLVal defvar deftypefn deftypefnx gotos msgfmt
 @c LocalWords: subdirectory Solaris nonassociativity

src/parse-gram.h

@@ -1,4 +1,4 @@
-/* A Bison parser, made by GNU Bison 2.4.434-7439c.  */
+/* A Bison parser, made by GNU Bison 2.4.456-ea2e.  */
 
 /* Interface for Bison's Yacc-like parsers in C
 
@@ -31,7 +31,7 @@
    This special exception was added by the Free Software Foundation in
    version 2.2 of Bison.  */
 /* "%code requires" blocks.  */
-/* Line 1624 of yacc.c  */
+/* Line 1640 of yacc.c  */
 #line 202 "src/parse-gram.y"
 
 # ifndef PARAM_TYPE
@@ -46,7 +46,7 @@
 # endif
 
 
-/* Line 1624 of yacc.c  */
+/* Line 1640 of yacc.c  */
 #line 51 "src/parse-gram.h"
 
 /* Tokens.  */
@@ -173,7 +173,7 @@
 #if ! defined YYSTYPE && ! defined YYSTYPE_IS_DECLARED
 typedef union YYSTYPE
 {
-/* Line 1624 of yacc.c  */
+/* Line 1640 of yacc.c  */
 #line 88 "src/parse-gram.y"
 
   assoc assoc;
@@ -186,13 +186,13 @@ typedef union YYSTYPE
   uniqstr uniqstr;
   unsigned char character;
 
-/* Line 1624 of yacc.c  */
+/* Line 1640 of yacc.c  */
 #line 226 "src/parse-gram.y"
 
   param_type param;
 
 
-/* Line 1624 of yacc.c  */
+/* Line 1640 of yacc.c  */
 #line 197 "src/parse-gram.h"
 } YYSTYPE;
 # define YYSTYPE_IS_TRIVIAL 1