Java skeleton bug fixes, new features, and documentation

[Di-an JAN]

This patch for the Java skeleton fixes several bugs, addes some new
features and adds tables of declarations and action features to the
manual.  I have no copyright assignment so we'll have to do something
about that if you want to accept this patch.

BUGS FIXED

* The parse class name is "b4_prefixParser" instead of "YYParser"
  if "%name-prefix" or "%define parser_class_name" is not used.

* Handle multiple %lex-param's correctly: commas confused m4.

* Fix "%define stype": Java error about ... ? "(null") : (not Object)
  that neither is a subtype of the other.

* Fix "%define location_class": one Location was not converted.

* Fix Javadoc.

* Fix documentation to match actual behavior and generated code.

* Fix throws specifications:  Exceptions listed in "%define throws"
  and thrown from actions are not listed with yyaction().

NEW FEATURES

* "%define extends" and  "implements"

* "%define final" and "strictfp" in addition to "public" and "abstract".

* New documentation: table of declarations and action features.

* New tests for specific features:
  1. Lumped into 6 tests (202-207) w/ 4, 11, 3, 9, 32 (2*4*4 loops), 2 inputs
     testing *interactions* of things that might be problematic.
     I can also have them reported as 61 separate tests.
  2. These used grep on the generated code in addition to Java compile.
     And use grep to make sure no [mb]4_ remains unexpanded.
     It's probably possible to write purely Java compile/run tests
     but it could get rather complicated.

CHANGED BEHAVIORS

* Add "%define lex_throws" to parse(), not as the default of "%define throws"

throws specs are needed when using user code:

parser action   --> yyaction()       --> parse()
%initial-action --> parse()
yylex()         --> yylex()  --> parse()

There are also uses of the other members of Lexer and Position,
but they are unlikely to throw exceptions.

Obviously, parse() gets excptions from both "throws" and "lex_throws"
and there's no reason to make users duplicate "lex_throws" in "throws".
Also, yyaction() needs "throws".
There's probably no need for "initial_action_throws", etc.

                        BEFORE                  AFTER

yylex()                 lex_throws              lex_throws
parse()                 throws                  lex_throws, throws
yyaction()              (none)                  throws

default lex_throws      java.io.IOException     java.io.IOException
default throws          (lex_throws)            (none)

Tested with "make -k check" and "make pdf" on Cygwin with one expected
failure.  See
http://lists.gnu.org/archive/html/bug-bison/2008-07/msg00008.html

2008-09-29  Di-an Jan  <address@hidden>

        Support all Java parser class modifiers.
        * data/java.m4 (b4_percent_define_get3): New.
        (b4_final_if, b4_strictfp_if): New.
        * data/lalr1.java (final, strictfp, extends, implements): Support.
        * doc/bison.texinfo (final, strictfp, extends, implements): Add
        documentation.
        * tests/java.at (AT_CHECK_JAVA_MINIMAL): New.
        (AT_CHECK_JAVA_MINIMAL_W_LEXER): New.
        (AT_CHECK_JAVA_GREP): New.
        (Java parser class modifiers): New test.
        (Java parser class extends and implements): New test.

        Model exception propagation better with throws and lex_throws.
        * data/java.m4 (b4_list2): New.
        (throws): Change default.
        * data/lalr1.java (yyaction): Add throws.
        (parse): Add lex_throws in addition to throws.
        * doc/bison.texinfo (throws, lex_throws): Add documentation.
        * tests/java.at (Java throws specifications): New test.

        Improve documentation for Java parsers.
        * doc/bison.texinfo (Java Parsers): Add subsections.
        Don't quote first argument of %define.
        (Java Bison Interface): Document output files.  Move documentation
        of parser class and merge into Java Parser Interface.  Document
        features that error out.  Document directives with no effect.
        Move note about Javadoc higher.
        (Java Semantic Values): Explicitly mention stype.
        Document that generic types cannot be used.
        (Java Location Values): Use @deftypeivar.  Document constructors.
        Correct return value for toString.
        (Java Parser Interface): List undocumented constants/fields.
        Move documentation of fields added by %parse-param closer to list
        of members.  Document that token names are added as fields.
        Document constructors accurately.  Remove error method.
        (Java Scanner Interface): Move note on %pure-parser to Java Bison
        Interface.  Describe %code lexer and yylex accutately.
        Remove documentation that does not match the code.
        (Java Action Features): New.
        (Java Differences): Add reference.  Add item on semantic values.
        Add note about @{ ... @}.  Clarify %% epilogue placement.
        (Java Declarations Summary): New.

        Fix Java skeleton.
        * data/java.m4 (b4_prefix): Correct quoting for m4_define_default.
        (b4_remove_comma): Quote test argument.
        * data/lalr1.java: (Location constructor): Correct Javadoc markup
        and parameter name.
        (yylloc): Add opening m4 quote after b4_location_if.
        (Lexer.yyerror): Fix Javadoc and m4 quoting.
        (YYParser constructor): Correct Javadoc parameter name.
        (yyerror): Use user-supplied name for Location.
        (yy_symbol_print): Convert branch of conditional expr to string.
        * tests/java.at (Java parser class and package names): New test.
        (Java %parse-param and %lex-param): New test.
        (Java stype, position_class and location_class): New test.

java1.patch
Description: Text document