add source code that does not have location annotations.
[IRC.git] / Robust / JavaGrammar / README
1 This package contains CUP grammars for the Java programming language.
2
3 Copyright (C) 2002 C. Scott Ananian
4 This code is free software; you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by the
6 Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.  See the file COPYING for more details.
8
9 Directory structure:
10  Parse/         contains the Java grammars.
11   java10.cup    contains a Java 1.0 grammar.
12   java11.cup    contains a Java 1.1 grammar.
13   java12.cup    contains a Java 1.2 grammar. [added 11-feb-1999]
14   java14.cup    contains a Java 1.4 grammar. [added 10-apr-2002]
15   java15.cup    contains a Java 1.5 Java grammar. [added 12-apr-2002]
16                 [last updated 28-jul-2003; Java 1.5 spec not yet final.]
17   Lexer.java    interface description for a lexer.
18
19  Lex/           contains a simple but complete Java lexer.
20   Lex.java      main class
21   Sym.java      a copy of Parse/Sym.java containing symbolic constants.
22
23  Main/
24   Main.java     a simple testing skeleton for the parser/lexer.
25
26 The grammar in Parse/ should be processed by CUP into Grm.java.
27 There are much better ways to write lexers for java, but the
28 implementation in Lex/ seemed to be the easiest at the time.  The
29 lexer implemented here may not be as efficient as a table-driven lexer,
30 but adheres to the java specification exactly.
31
32   -- C. Scott Ananian <cananian@alumni.princeton.edu> 3-Apr-1998
33                                                 [revised 12-apr-2002]
34                                                 [revised 28-jul-2003]
35
36 UPDATE: Fixed a lexer bug: '5.2' is a double, not a float.  Thanks to
37 Ben Walter <bwalter@mit.edu> for spotting this.
38
39   -- C. Scott Ananian <cananian@alumni.princeton.edu> 14-Jul-1998
40
41 UPDATE: Fixed a couple of minor bugs.
42 1) Lex.EscapedUnicodeReader wasn't actually parsing unicode escape sequences
43    properly because we didn't implement read(char[], int, int).
44 2) Grammar fixes: int[].class, Object[].class and all array class
45    literals were not being parsed.  Also special void.class literal
46    inadvertantly omitted from the grammar.
47 Both these problems have been fixed.
48
49   -- C. Scott Ananian <cananian@alumni.princeton.edu> 11-Feb-1999
50
51 UPDATE: Fixed another lexer bug: Large integer constants such as
52 0xFFFF0000 were being incorrectly flagged as 'too large for an int'.
53 Also, by the Java Language Specification, "\477" is a valid string
54 literal (it is the same as "\0477": the character '\047' followed by
55 the character '7').  The lexer handles this case correctly now.
56
57 Created java12.cup with grammar updated to Java 1.2.  Features
58 added include the 'strictfp' keyword and the various new inner class
59 features at http://java.sun.com/docs/books/jls/nested-class-clarify.html.
60
61 Also added slightly better position/error reporting to all parsers.
62
63   -- C. Scott Ananian <cananian@alumni.princeton.edu> 11-Feb-1999
64
65 UPDATE: fixed some buglets with symbol/error position reporting.
66
67   -- C. Scott Ananian <cananian@alumni.princeton.edu> 13-Sep-1999
68
69 UPDATE: multi-line comments were causing incorrect character position
70 reporting.  If you were using the character-position-to-line-number
71 code in Lexer, you would never have noticed this problem.  Thanks to
72 William Young <youngwr@rose-hulman.edu> for pointing this out.
73
74   -- C. Scott Ananian <cananian@alumni.princeton.edu> 27-Oct-1999
75
76 UPDATE: extended grammar to handle the 'assert' statement added in
77 Java 1.4.  Also fixed an oversight: a single SEMICOLON is a valid
78 ClassBodyDeclaration; this was added to allow trailing semicolons
79 uniformly on class declarations.  This wasn't part of the original
80 JLS, but was revised in to conform with the actual behavior of the
81 javac compiler.  I've added this to all the grammars from 1.0-1.4
82 to conform to javac behavior; let me know if you've got a good
83 reason why this production shouldn't be in early grammars.
84
85 Also futzed with the Makefile some to allow building a 'universal'
86 driver which will switch between java 1.0/1.1/1.2/1.4 on demand.
87 This helps me test the separate grammars; maybe you'll find a
88 use for this behavior too.
89
90   -- C. Scott Ananian <cananian@alumni.princeton.edu> 10-Apr-2002
91
92 NEW: added a grammar for the JSR-14 "Adding Generics to the Java
93 Programming Language" Java variant.  Calling this java15.cup, since
94 this JSR currently seems to be destined for inclusion in Java 1.5.
95 This grammar is very very tricky!  I need to use a lexer trick to
96 handle type casts to parameterized types, which otherwise do not
97 seem to be LALR(1).
98   -- C. Scott Ananian <cananian@alumni.princeton.edu> 12-Apr-2002
99
100 UPDATE: various bug fixes to all grammars, in reponse to bugs reported
101 by Eric Blake <ebb9@email.byu.edu> and others.
102  a) TWEAK: added 'String' type to IDENTIFIER terminal to match Number types
103     given to numeric literals. (all grammars)
104  b) BUG FIX: added SEMICOLON production to interface_member_declaration to
105     allow optional trailing semicolons, in accordance with the JLS (for
106     java 1.2-and-later grammars) and Sun practice (for earlier grammars).
107     The 10-Apr-2002 release did not address this problem completely, due
108     to an oversight. (all grammars)
109  c) BUG FIX: '<primary>.this(...);' is not a legal production;
110     '<name>.super(...);' and '<name>.new <identifier>(...' ought to be.
111     In particular, plain identifiers ought to be able to qualify instance
112     creation and explicit constructor invocation.
113     (fix due to Eric Blake; java 1.2 grammar and following)
114  d) BUG FIX: parenthesized variables on the left-hand-side of an assignment
115     ought to be legal, according to JLS2.  For example, this code is
116     legal:
117        class Foo { void m(int i) { (i) = 1; } }
118     (fix due to Eric Blake; java 1.2 grammar and following)
119  e) BUG FIX: array access of anonymous arrays ought to be legal, according
120     to JLS2.  For example, this is legal code:
121        class Foo { int i = new int[]{0}[0]; }
122     (fix due to Eric Blake; java 1.2 grammar and following)
123  f) BUG FIX: nested parameterized types ought to be legal, for example:
124        class A<T> { class B<S> { }  A<String>.B<String> c; }
125     (bug found by Eric Blake; jsr-14 grammar only)
126  g) TWEAK: test cases were added for these issues.
127
128 In addition, it should be clarified that the 'java15.cup' grammar is
129 really only for java 1.4 + jsr-14; recent developments at Sun indicate
130 that "Java 1.5" is likely to include several additional language changes
131 in addition to JSR-14 parameterized types; see JSR-201 for more details.
132 I will endeavor to add these features to 'java15.cup' as soon as their
133 syntax is nailed down.
134   -- C. Scott Ananian <cananian@alumni.princeton.edu> 13-Apr-2003
135
136 UPDATE: Updated the 'java15.cup' grammar to match the latest specifications
137 (and their corrections) for Java 1.5.  This grammar matches the 2.2
138 prototype of JSR-14 + JSR-201 capabilities, with some corrections for
139 mistakes in the released specification and expected future features of
140 Java 1.5 (in particular, arrays of parameterized types bounded by
141 wildcards).  Reimplemented java15.cup to use a refactoring originally
142 due to Eric Blake which eliminates our previous need for "lexer lookahead"
143 (see release notes for 12-April-2002).  Added new 'enum' and '...' tokens
144 to the lexer to accomodate Java 1.5.  New test cases added for the
145 additional language features.
146   -- C. Scott Ananian <cananian@alumni.princeton.edu> 28-Jul-2003