proposal: simplify prologue alternatives into %code

[Joel E. Denny]

Last month, Hans Aberg, Jeff Inman, and I discussed the prologue 
alternative directives currently implemented in Bison CVS: %code, 
%requires, %provides, and %code-top.  That discussion convinced me that 
these directives could use another revision.  I'd like to implement the 
following proposal, which I believe is close to what Hans proposed.  It 
should simplify Bison internals, it should be more flexible when 
developing new skeletons, and I think it should be a bit more intuitive 
for the user.  Comments from anyone are welcome:

1. %code {CODE}

This would be an "unqualified" %code directive.  It would insert verbatim 
code at a default location in the output.  For C/C++ skeletons, that 
location would be in the parser source code file after the contents of the 
header file (this is what %{CODE%} appearing after the first %union does).  
For the Java skeleton, that location would be inside the parser class.

2. %code "QUALIFIER" {CODE}

This would be a "qualified" %code directive.  When the user wants to 
specify location-sensitive code that does not belong at the default 
location, he should use this.  The QUALIFIER's could be skeleton-specific 
and/or target-language-specific.  For example:

a. For C/C++ skeletons, the qualifiers "requires", "provides", and "top" 
would replace the directives %requires, %provides, and %code-top.  I've 
always felt that %code-top was an ugly but necessary wart for C/C++.  I 
especially like the idea of demoting it from a distinct grammar directive 
to a language-specific qualifier.

b. What Java user thinks "requires" means "imports"?  Yes, it makes sense 
when you think about it, but isn't "imports" more obvious and easier to 
remember?  Similarly, what Java user thinks "provides" means "additional 
package-visible classes", which the epilogue handles anyway?  I wonder if 
"requires" should be eliminated for Java.  In any case, I think these Java 
issues demonstrate why it would be nice if the prologue alternatives were 
not distinct grammar directives: developers of new skeletons wouldn't feel 
as compelled to try to force their new square pegs into our old round 
holes.

3. I think we should keep the Prologue Alternatives section in the Bison 
manual as a C/C++-specific discussion.  If for no other reason, it'll 
hopefully keep us from ever again having to repeat the discussion of why 
the traditional Yacc prologues are broken.  However, most users will 
probably instead prefer the kind of concise summaries that are reasonable 
in Appendix A of the manual.  Unfortunately, due to alphabetical ordering, 
the current prologue alternative directives are scattered throughout that 
appendix.  The two versions of %code I'm proposing wouldn't suffer the 
same fate.  Moreover, the qualified %code's description would contain a 
list of qualifiers, what target languages they're meant for, and where 
exactly they place code.  That should be a nice reference for the user.

4. %code "QUALIFIER" {CODE} would not be the same as %define "NAME" 
{CODE}.  The word "define" implies that the latter directive should 
*overwrite* any existing definition of NAME (and perhaps warn the user).  
I propose that the former directive would *append* to any code already 
associated with QUALIFIER; this would mimic the behavior of %{CODE%} and 
of the existing prologue alternative directives.  If we agree to have 
%code "QUALIFIER" {CODE}, I wonder if we really need to keep %define 
"NAME" {CODE}.

5. Hans suggested we drop the quotes around "QUALIFIER" or "NAME".  I 
think that idea may have some merit, but lets debate this detail only 
after resolving the larger issues here.