[1] | 1 | A N T L R |
---|
| 2 | ====================================================================== |
---|
| 3 | *SOFTWARE RIGHTS* |
---|
| 4 | |
---|
| 5 | ANTLR 1989-2006 Developed by Terence Parr @ University of San Francisco |
---|
| 6 | |
---|
| 7 | We reserve no legal rights to the ANTLR--it is fully in the |
---|
| 8 | public domain. An individual or company may do whatever |
---|
| 9 | they wish with source code distributed with ANTLR or the |
---|
| 10 | code generated by ANTLR, including the incorporation of |
---|
| 11 | ANTLR, or its output, into commerical software. |
---|
| 12 | |
---|
| 13 | We encourage users to develop software with ANTLR. However, |
---|
| 14 | we do ask that credit is given to us for developing |
---|
| 15 | ANTLR. By "credit", we mean that if you use ANTLR or |
---|
| 16 | incorporate any source code into one of your programs |
---|
| 17 | (commercial product, research project, or otherwise) that |
---|
| 18 | you acknowledge this fact somewhere in the documentation, |
---|
| 19 | research report, etc... If you like ANTLR and have |
---|
| 20 | developed a nice tool with the output, please mention that |
---|
| 21 | you developed it using ANTLR. In addition, we ask that the |
---|
| 22 | headers remain intact in our source code. As long as these |
---|
| 23 | guidelines are kept, we expect to continue enhancing this |
---|
| 24 | system and expect to make other tools available as they are |
---|
| 25 | completed. |
---|
| 26 | |
---|
| 27 | The primary ANTLR guy: |
---|
| 28 | |
---|
| 29 | Terence Parr |
---|
| 30 | parrt@cs.usfca.edu |
---|
| 31 | parrt@antlr.org |
---|
| 32 | |
---|
| 33 | ______________________________________________________________________ |
---|
| 34 | |
---|
| 35 | WELCOME TO ANTLR! |
---|
| 36 | |
---|
| 37 | If you have problems or think you have found a bug in ANTLR, see the |
---|
| 38 | section BUGS in the ANTLR manual. |
---|
| 39 | |
---|
| 40 | Please consult the INSTALL.txt file for information on tested |
---|
| 41 | configurations. If you have a comment about an already tested |
---|
| 42 | configuration, or have tried ANTKR on a new configuration, please let |
---|
| 43 | us know as described in INSTALL.txt. Free software only works if we |
---|
| 44 | all help out. |
---|
| 45 | |
---|
| 46 | Finally, we cannot guarantee that this release will not completely |
---|
| 47 | wipe out all of your work from your system. We do some simple testing |
---|
| 48 | before each release, but you are completely on your own. We recommend |
---|
| 49 | testing this release on a source repository that is not critical to |
---|
| 50 | your work. |
---|
| 51 | |
---|
| 52 | THIS SOFTWARE IS SUPPLIED COMPLETELY "AS IS". |
---|
| 53 | NO WARRANTY.... |
---|
| 54 | |
---|
| 55 | Thanks for your support! |
---|
| 56 | |
---|
| 57 | -The ANTLR Team- |
---|
| 58 | |
---|
| 59 | ______________________________________________________________________ |
---|
| 60 | |
---|
| 61 | WHAT IS ANTLR? |
---|
| 62 | |
---|
| 63 | ANTLR, (AN)other (T)ool for (L)anguage (R)ecognition - formerly known |
---|
| 64 | as PCCTS - is a language tool that provides a framework for |
---|
| 65 | constructing recognizers, compilers, and translators from grammatical |
---|
| 66 | descriptions containing actions in the following languages: |
---|
| 67 | |
---|
| 68 | Java, |
---|
| 69 | C++, |
---|
| 70 | C# or |
---|
| 71 | Python |
---|
| 72 | |
---|
| 73 | (You can use PCCTS 1.xx to generate C-based parsers). |
---|
| 74 | |
---|
| 75 | Computer language translation has become a common task. While |
---|
| 76 | compilers and tools for traditional computer languages (such as C or |
---|
| 77 | Java) are still being built, their number is dwarfed by the thousands |
---|
| 78 | of mini-languages for which recognizers and translators are being |
---|
| 79 | developed. Programmers construct translators for database formats, |
---|
| 80 | graphical data files (e.g., PostScript, AutoCAD), text processing |
---|
| 81 | files (e.g., HTML, SGML). ANTLR is designed to handle all of your |
---|
| 82 | translation tasks. |
---|
| 83 | |
---|
| 84 | Prof. Terence Parr has been working on ANTLR since 1989 and, together |
---|
| 85 | with his colleagues, has made a number of fundamental contributions |
---|
| 86 | to parsing theory and language tool construction, leading to the |
---|
| 87 | resurgence of LL(k)-based recognition tools. |
---|
| 88 | |
---|
| 89 | Have a look at the history section at the end of this document on |
---|
| 90 | how ANTLR has evolved over time. For most up-to-date informaton |
---|
| 91 | read http://www.antlr.org/history.html. |
---|
| 92 | ______________________________________________________________________ |
---|
| 93 | |
---|
| 94 | UPGRADING? |
---|
| 95 | |
---|
| 96 | See |
---|
| 97 | |
---|
| 98 | http://www.antlr.org/blog/CHANGES-2.7.7.txt |
---|
| 99 | |
---|
| 100 | for a description of features new in this version. There are no |
---|
| 101 | incompatibilties known to a previous 2.7.x installation. If you found |
---|
| 102 | a problem please let us know. |
---|
| 103 | |
---|
| 104 | ______________________________________________________________________ |
---|
| 105 | |
---|
| 106 | |
---|
| 107 | INSTALLATION? |
---|
| 108 | |
---|
| 109 | Please read the INSTALL.txt file for installation instructions. The |
---|
| 110 | brief summary is: |
---|
| 111 | |
---|
| 112 | $ ./configure |
---|
| 113 | $ make |
---|
| 114 | $ make test # optional |
---|
| 115 | $ su root # optional |
---|
| 116 | $ make install |
---|
| 117 | |
---|
| 118 | ______________________________________________________________________ |
---|
| 119 | |
---|
| 120 | ANTLR IS INSTALLED - WHAT'S NEXT? |
---|
| 121 | |
---|
| 122 | Please read "doc/getting-started.html" on what you are supposed to |
---|
| 123 | do. Here's a very brief summary for the impatient: |
---|
| 124 | |
---|
| 125 | ANTLR is a command line tool. To run ANTLR you need to have JAVA |
---|
| 126 | installed. The basic steps are: |
---|
| 127 | |
---|
| 128 | a. write a grammar file - mygrammar.g |
---|
| 129 | |
---|
| 130 | b. run ANTLR like |
---|
| 131 | |
---|
| 132 | $ CLASSPATH=antlr.jar |
---|
| 133 | |
---|
| 134 | $ java antlr.Tool mygrammar.g |
---|
| 135 | |
---|
| 136 | c. write a driver program using source code generated by ANTLR, ie. |
---|
| 137 | Main.java, main.cpp, Main.cs or main.py |
---|
| 138 | |
---|
| 139 | d. link generated code, your driver code, ANTLR's core library and |
---|
| 140 | any additional library you are using together to get an |
---|
| 141 | executable |
---|
| 142 | |
---|
| 143 | f. run the executable on arbitrary input to be parsed |
---|
| 144 | |
---|
| 145 | For a set of standard examples have a look into directory "examples" |
---|
| 146 | and appropriate subdirectories. |
---|
| 147 | |
---|
| 148 | ______________________________________________________________________ |
---|
| 149 | |
---|
| 150 | WANT TO KNOW MORE? |
---|
| 151 | |
---|
| 152 | The documentation is in the "doc" subdirectory and "index.html" is |
---|
| 153 | the main entry point. |
---|
| 154 | |
---|
| 155 | Further information available at |
---|
| 156 | |
---|
| 157 | http://www.antlr.org |
---|
| 158 | |
---|
| 159 | ______________________________________________________________________ |
---|
| 160 | |
---|
| 161 | WHO CONTRIBUTED TO THIS MESS? |
---|
| 162 | |
---|
| 163 | Project Lead and Supreme Dictator Terence Parr, University of San |
---|
| 164 | Franciso |
---|
| 165 | |
---|
| 166 | Help with initial coding John Lilly, Empathy Software |
---|
| 167 | |
---|
| 168 | C++ code generator by Peter Wells and Ric Klaren |
---|
| 169 | |
---|
| 170 | C# code generation by Micheal Jordan, Kunle Odutola and Anthony |
---|
| 171 | Oguntimehin. |
---|
| 172 | |
---|
| 173 | Python's universe has been extended by Wolfgang Häfelinger and Marq |
---|
| 174 | Kole |
---|
| 175 | |
---|
| 176 | Substantial intellectual effort donated by Loring Craymer, Monty |
---|
| 177 | Zukowski, Jim Coker, Scott Stanchfield, John Mitchell, Chapman |
---|
| 178 | Flack (UNICODE, streams) |
---|
| 179 | |
---|
| 180 | Source changes for Eclipse and NetBeans by Marco van Meegen and |
---|
| 181 | Brian Smith |
---|
| 182 | |
---|
| 183 | Infrastructure support from Perforce - The world's best source |
---|
| 184 | code control system |
---|
| 185 | |
---|
| 186 | |
---|
| 187 | ______________________________________________________________________ |
---|
| 188 | |
---|
| 189 | WANNA KNOW ABOUT ANTLR's HISTORY? |
---|
| 190 | |
---|
| 191 | The PCCTS project began as a parser-generator project for a graduate |
---|
| 192 | course at Purdue University in the Fall of 1988 taught by Hank Dietz |
---|
| 193 | "translator-writing systems". Under the guidance of Professor Dietz, |
---|
| 194 | the parser generator, ANTLR (originally called YUCC), continued after |
---|
| 195 | the termination of the course and eventually became the subject of |
---|
| 196 | Terence Parrs Masters thesis. Originally, lexical analysis was |
---|
| 197 | performed via a simple scanner generator which was soon replaced by |
---|
| 198 | Will Cohens DLG in the Fall of 1989 (DFA-based lexical-analyzer |
---|
| 199 | generator, also an offshoot of the graduate translation course). |
---|
| 200 | |
---|
| 201 | The alpha version of ANTLR was totally rewritten resulting in 1.00B. |
---|
| 202 | Version 1.00B was released via an internet newsgroup (comp.compilers) |
---|
| 203 | posting in February of 1990 and quickly gathered a large following. |
---|
| 204 | 1.00B generated only LL(1) parsers, but allowed the merged |
---|
| 205 | description of lexical and syntactic analysis. It had rudimentary |
---|
| 206 | attribute handling similar to that of YACC and did not incorporate |
---|
| 207 | rule parameters or return values; downward inheritance was very |
---|
| 208 | awkward. 1.00B-generated parsers terminated upon the first syntax |
---|
| 209 | error. Lexical classes (modes) were not allowed and DLG did not have |
---|
| 210 | an interactive mode. |
---|
| 211 | |
---|
| 212 | Upon starting his Ph.D. at Purdue in the Fall of 1990, Terence Parr |
---|
| 213 | began the second total rewrite of ANTLR. The method by which grammars |
---|
| 214 | may be practically analyzed to generate LL(k) lookahead information |
---|
| 215 | was discovered in August of 1990 just before Terence's return to |
---|
| 216 | Purdue. Version 1.00 incorporated this algorithm and included the AST |
---|
| 217 | mechanism, lexical classes, error classes, and automatic error |
---|
| 218 | recovery; code quality and portability were higher. In February of |
---|
| 219 | 1992 1.00 was released via an article in SIGPLAN Notices. Peter Dahl, |
---|
| 220 | then Ph.D. candidate, and Professor Matt O'Keefe (both at the |
---|
| 221 | University of Minnesota) tested this version extensively. Dana |
---|
| 222 | Hoggatt (Micro Data Base Systems, Inc.) tested 1.00 heavily. |
---|
| 223 | |
---|
| 224 | Version 1.06 was released in December 1992 and represented a large |
---|
| 225 | feature enhancement over 1.00. For example, rudimentary semantic |
---|
| 226 | predicates were introduced, error messages were significantly |
---|
| 227 | improved for k>1 lookahead and ANTLR parsers could indicate that |
---|
| 228 | lookahead fetches were to occur only when necessary for the parse |
---|
| 229 | (normally, the lookahead "pipe" was constantly full). Russell Quong |
---|
| 230 | joined the project in the Spring of 1992 to aid in the semantic |
---|
| 231 | predicate design. Beginning and advanced tutorials were created and |
---|
| 232 | released as well. A makefile generator was included that sets up |
---|
| 233 | dependencies and such correctly for ANTLR and DLG. Very few 1.00 |
---|
| 234 | incompatibilities were introduced (1.00 was quite different from |
---|
| 235 | 1.00B in some areas). |
---|
| 236 | |
---|
| 237 | Version 1.10 was released on August 31, 1993 after Terences release |
---|
| 238 | from Purdue and incorporated bug fixes, a few feature enhancements |
---|
| 239 | and a major new capability -- an arbitrary lookahead operator |
---|
| 240 | (syntactic predicate), "(a)?b". This feature was codesigned with |
---|
| 241 | Professor Russell Quong also at Purdue. To support infinite |
---|
| 242 | lookahead, a preprocessor flag, ZZINF_LOOK, was created that forced |
---|
| 243 | the ANTLR() macro to tokenize all input prior to parsing. Hence, at |
---|
| 244 | any moment, an action or predicate could see the entire input |
---|
| 245 | sentence. The predicate mechanism of 1.06 was extended to allow |
---|
| 246 | multiple predicates to be hoisted; the syntactic context of a |
---|
| 247 | predicate could also be moved along with the predicate. |
---|
| 248 | |
---|
| 249 | In February of 1994, SORCERER was released. This tool allowed the |
---|
| 250 | user to parse child-sibling trees by specifying a grammar rather than |
---|
| 251 | building a recursive-descent tree walker by hand. Aaron Sawdey at The |
---|
| 252 | University of Minnesota became a second author of SORCERER after the |
---|
| 253 | initial release. On April 1, 1994, PCCTS 1.20 was released. This was |
---|
| 254 | the first version to actively support C++ output. It also included |
---|
| 255 | important fixes regarding semantic predicates and (..)+ subrules. |
---|
| 256 | This version also introduced token classes, the "not" operator, and |
---|
| 257 | token ranges. |
---|
| 258 | |
---|
| 259 | On June 19, 1994, SORCERER 1.00B9 was released. Gary Funck of |
---|
| 260 | Intrepid Technology joined the SORCERER team and provided very |
---|
| 261 | valuable suggestions regarding the "transform" mode of SORCERER. |
---|
| 262 | |
---|
| 263 | On August 8, 1994, PCCTS 1.21 was released. It mainly cleaned up the |
---|
| 264 | C++ output and included a number of bug fixes. |
---|
| 265 | |
---|
| 266 | From the 1.21 release forward, the maintenance and support of all |
---|
| 267 | PCCTS tools was picked up by Parr Research Corporation. |
---|
| 268 | |
---|
| 269 | A sophisticated error handling mechanism called "parser exception |
---|
| 270 | handling" was released for version 1.30. 1.31 fixed a few bugs. |
---|
| 271 | |
---|
| 272 | Release 1.33 is the version corresponding to the initial book release. |
---|
| 273 | |
---|
| 274 | ANTLR 2.0.0 came out around May 1997 and was partially funded so |
---|
| 275 | Terence hired John Lilley, a maniac coder and serious ANTLR hacker, |
---|
| 276 | to build much of the initial version. Terence did the grammar |
---|
| 277 | analyzer, naturally. |
---|
| 278 | |
---|
| 279 | John Mitchell, Jim Coker, Scott Stanchfield, and Monty Zukowski |
---|
| 280 | donate lots of brain power to ANTLR 2.xx in general. |
---|
| 281 | |
---|
| 282 | ANTLR 2.1.0, July 1997, mainly improved parsing performance, |
---|
| 283 | decreased parser memory requirements, and added a lot of cool lexer |
---|
| 284 | features including a case-insensitivity option. |
---|
| 285 | |
---|
| 286 | ANTLR 2.2.0, December 1997, saw the introduction of the new |
---|
| 287 | http://www.antlr.org website. This release also added grammar |
---|
| 288 | inheritance, enhanced AST support, and enhanced lexical translation |
---|
| 289 | support (each lexical rule now was considered to return a Token |
---|
| 290 | object even when referenced by another lexical rule). |
---|
| 291 | |
---|
| 292 | ANTLR 2.3.0, June 1998, was the first version to have Peter Wells |
---|
| 293 | C++ code generator. |
---|
| 294 | |
---|
| 295 | ANTLR 2.4.0, September 1998, introduced the ParseView parser debugger |
---|
| 296 | by Scott Stanchfield. This version also had a semi-functional -html |
---|
| 297 | option to generate HTML from your grammar for reading purposes. Scott |
---|
| 298 | and Terence updated the file I/O to be JDK 1.1. |
---|
| 299 | |
---|
| 300 | ANTLR 2.5.0, November 1998, introduced the filter option for the lexer |
---|
| 301 | that lets ANTLR behave like SED or AWK. |
---|
| 302 | |
---|
| 303 | ANTLR 2.6.0, March 1999, introduced token streams. Chapman Flack, |
---|
| 304 | Purdue Graduate student, pounded me at the right moment about streams, |
---|
| 305 | nudging me in the right direction. |
---|
| 306 | |
---|
| 307 | MageLang Institute currently provides support and continues |
---|
| 308 | development of ANTLR. |
---|
| 309 | |
---|
| 310 | MageLang becomes jGuru.com as we quit doing Java training and start |
---|
| 311 | building the jGuru Java developer's website. |
---|
| 312 | |
---|
| 313 | 2.7.0 released January 19, 2000 had the following enhancements: |
---|
| 314 | |
---|
| 315 | * Nongreedy subrules |
---|
| 316 | * Heterogeneous trees |
---|
| 317 | * Element options. To support heterogeneous trees, elements such |
---|
| 318 | as token references may now include options. |
---|
| 319 | * Exception hierarchy redesign |
---|
| 320 | * XML serialization |
---|
| 321 | * Improved C++ code generator |
---|
| 322 | * New Sather code generator |
---|
| 323 | |
---|
| 324 | 2.7.1 released October 1, 2000 had the following enhancements |
---|
| 325 | |
---|
| 326 | * ANTLR now allows UNICODE characters because Terence made case- |
---|
| 327 | statement expressions more efficient ;) See the unicode example |
---|
| 328 | in the distribution and the brief blurb in the documentation. |
---|
| 329 | * Massively improved C++ code generator (Thanks to Ric Klaren). |
---|
| 330 | * Added automatic column setting support. |
---|
| 331 | * Ter added throws to tree and regular parsers . |
---|
| 332 | |
---|
| 333 | 2.7.2 release January 19, 2003 was mainly a bug fix release, |
---|
| 334 | |
---|
| 335 | * but also included a C# code generator by Micheal Jordan, Kunle |
---|
| 336 | Odutola and Anthony Oguntimehin. :) |
---|
| 337 | * I (who, Ter?) added an antlr.build.Tool 'cause I hate ANT. This |
---|
| 338 | release does UNICODE properly now. Added limited lexical lookahead |
---|
| 339 | hoisting. Sather code generator disappears. Source changes for |
---|
| 340 | Eclipse and NetBeans by Marco van Meegen and Brian Smith. |
---|
| 341 | |
---|
| 342 | 2.7.3 released March 22, 2004 was mainly a bug fix release, |
---|
| 343 | |
---|
| 344 | * but included the parse-tree/derivation code to aid in debugging |
---|
| 345 | * plus the cool TokenStreamRewriteEngine that makes rewriting or |
---|
| 346 | tweaking input files particularly easy. |
---|
| 347 | |
---|
| 348 | 2.7.4 released May 9, 2004 was mainly a bug fix release. |
---|
| 349 | |
---|
| 350 | 2.7.5 release Xmas 2004 had the following enhancements: |
---|
| 351 | |
---|
| 352 | * A Python code generator has been implemented and contributed |
---|
| 353 | by Wolfang Haefelinger and Marq Kole. |
---|
| 354 | |
---|
| 355 | * A new make/autoconf framework as been contributed by Wolfgang |
---|
| 356 | Haefelinger |
---|
| 357 | |
---|
| 358 | * A MSI based installer has been contributed by Wolfgang Haefelinger. |
---|
| 359 | |
---|
| 360 | 2.7.6 release xmas 2005 was mainly a bug fix release. |
---|
| 361 | |
---|
| 362 | * Scott Stanchfield added file/line information for Java target and |
---|
| 363 | cleaned up a bunch of classloader stuff. |
---|
| 364 | |
---|
| 365 | * Added stuff to support Prashant Deva's cool ANTLRStudio. |
---|
| 366 | |
---|
| 367 | 2.7.7 release September 7, 2006 was a bug fix release. |
---|
| 368 | |
---|
| 369 | ====================================================================== |
---|
| 370 | README.txt - last update September 6th, 2006 |
---|