Consolidate the 4 prologue alternative directives (%code, %requires,

%provides, and %code-top) into a single %code directive with an
optional qualifier field.  Discussed at
<http://lists.gnu.org/archive/html/bison-patches/2007-01/msg00012.html>.
* NEWS (2.3a+): Rewrite the existing entry for the prologue
alternatives.
* doc/bison.texinfo (Prologue Alternatives): Update.
(Decl Summary): Update to %code "requires" and %code "provides".
(Calc++ Parser): Update to %code "requires".
(Bison Symbols): Remove entries for %requires, %provides, and
%code-top.  Rewrite %code entry, and add a %code "QUALIFIER" entry.
* data/bison.m4 (b4_user_provides, b4_user_requires): Remove as these
are replaced by b4_percent_code_provides and b4_percent_code_requires,
which are skeleton-specific.
(b4_check_percent_code_qualifiers): New.  A skeleton can use this to
declare what %code qualifiers it supports and to complain if any other
qualifiers were used in the grammar.
* data/glr.cc: Update to use b4_user_code([b4_percent_code_requires])
and b4_user_code([b4_percent_code_provides]) in place of
b4_user_requires and b4_user_provides.
* data/glr.c, data/lalr1.cc, data/push.c, data/yacc.c: Likewise.
Add b4_user_code([b4_percent_code_top]) and
b4_user_code([b4_percent_code]).
Invoke b4_check_percent_code_qualifiers.
* src/parse-gram.y (PERCENT_CODE_TOP, PERCENT_PROVIDES,
PERCENT_REQUIRES): Remove.
(grammar_declaration): Remove RHS's for %code-top, %provides, and
%requires.  Rewrite the %code RHS as the unqualified form defining the
muscle b4_percent_code.  Add another RHS for the qualified %code form,
which defines muscles of the form b4_percent_code_QUALIFIER and the
b4_used_percent_code_qualifiers muscle.
* src/scan-gram.l (PERCENT_CODE_TOP, PERCENT_PROVIDES,
PERCENT_REQUIRES): Remove.
* tests/actions.at (_AT_CHECK_PRINTER_AND_DESTRUCTOR): Update to use
%code "requires" and %code "provides".
* tests/input.at (Reject bad %code qualifiers): New.

data/bison.m4

@@ -184,8 +184,6 @@ m4_define([b4_define_user_code],
 # b4_user_initial_action
 # b4_user_post_prologue
 # b4_user_pre_prologue
-# b4_user_provides
-# b4_user_requires
 # b4_user_stype
 # ----------------------
 # Macros that issue user code, ending with synclines.
@@ -193,8 +191,38 @@ b4_define_user_code([actions])
 b4_define_user_code([initial_action])
 b4_define_user_code([post_prologue])
 b4_define_user_code([pre_prologue])
-b4_define_user_code([provides])
-b4_define_user_code([requires])
 b4_define_user_code([stype])
 
-
+# b4_check_percent_code_qualifiers([VAILD_QUALIFIER], [VALID_QUALIFIER], ...)
+# ---------------------------------------------------------------------------
+# Complain if any %code qualifier used in the grammar is not a valid qualifier.
+#
+# b4_used_percent_code_qualifiers must expand to a comma-delimited list of the
+# %code qualifiers used in the grammar.  The list as a whole must be quoted,
+# but individual qualifiers in it must not be.  Qualifiers will not be
+# M4-expanded.  Whitespace will not be stripped from the qualifiers.  Any
+# qualifier that is the empty string will be correctly parsed as such.  If
+# b4_used_percent_code_qualifiers expands to the empty string, then the list
+# contains one qualifier that is the empty string.  If
+# b4_used_percent_code_qualifiers is undefined, then the list contains no
+# qualifiers.  Multiple occurrences of the same qualifier are fine.
+#
+# Each VALID_QUALIFIER will be M4-expanded once to define a valid qualifier.  A
+# VALID_QUALIFIER that expands to the empty string will correctly define the
+# empty string as a valid qualifier.  If b4_used_percent_code_qualifiers is
+# invoked with empty parens, then there is one valid qualifier and it is the
+# empty string.  To specify that there are no valid qualifiers, invoke
+# b4_check_percent_code_qualifiers without parens.  Multiple occurrences of the
+# same valid qualifier are fine.
+#
+# Qualifiers and valid qualifiers must not contain the characters `,' or `&'.
+m4_define([b4_check_percent_code_qualifiers],
+[m4_ifdef([b4_used_percent_code_qualifiers], [
+m4_foreach([b4_qualifier],
+           m4_dquote(m4_substr(m4_split(m4_translit(m4_dquote([,]b4_used_percent_code_qualifiers), [,], [&]), [[&]]), 4)),
+           [m4_if(m4_index(m4_if($#, 0, [], [[,]m4_quote($*)[,]]),
+                           [,]m4_defn([b4_qualifier])[,]),
+                  [-1],
+                  [m4_fatal([`]m4_defn([b4_qualifier])[' is not a recognized %code qualifier.])])
+           ])
+])])