Migrated source code from Simantics SVN

[simantics/platform.git] / bundles / org.simantics.databoard / cpp / DataBoardTest / libantlr3c-3.2 / README

ANTLR v3.0.1 C Runtime\r
ANTLR 3.0.1\r
January 1, 2008\r
\r
At the moment, the use of the C runtime engine for the parser is not generally\r
for the inexperienced C programmer. However this is mainly because of the lack\r
of documentation on use, which will be corrected shortly. The C runtime\r
code itself is however well documented with doxygen style comments and a \r
reasonably experienced C programmer should be able to piece it together. You\r
can visit the documentation at: http://www.antlr.org/api/C/index.html\r
\r
The general make up is that everything is implemented as a pseudo class/object\r
initialized with pointers to its 'member' functions and data. All objects are \r
(usually) created by factories, which auto manage the memory allocation and\r
release and generally make life easier. If you remember this rule, everything\r
should fall in to place.\r
\r
Jim Idle - Portland Oregon, Jan 2008\r
jimi     idle ws\r
\r
===============================================================================\r
\r
Terence Parr, parrt at cs usfca edu\r
ANTLR project lead and supreme dictator for life\r
University of San Francisco\r
\r
INTRODUCTION \r
\r
Welcome to ANTLR v3!  I've been working on this for nearly 4 years and it's\r
almost ready!  I plan no feature additions between this beta and first\r
3.0 release.  I have lots of features to add later, but this will be\r
the first set.  Ultimately, I need to rewrite ANTLR v3 in itself (it's\r
written in 2.7.7 at the moment and also needs StringTemplate 3.0 or\r
later).\r
\r
You should use v3 in conjunction with ANTLRWorks:\r
\r
    http://www.antlr.org/works/index.html \r
\r
WARNING: We have bits of documentation started, but nothing super-complete\r
yet.  The book will be printed May 2007:\r
\r
http://www.pragmaticprogrammer.com/titles/tpantlr/index.html\r
\r
but we should have a beta PDF available on that page in Feb 2007.\r
\r
You also have the examples plus the source to guide you.\r
\r
See the new wiki FAQ:\r
\r
    http://www.antlr.org/wiki/display/ANTLR3/ANTLR+v3+FAQ\r
\r
and general doc root:\r
\r
    http://www.antlr.org/wiki/display/ANTLR3/ANTLR+3+Wiki+Home\r
\r
Please help add/update FAQ entries.\r
\r
I have made very little effort at this point to deal well with\r
erroneous input (e.g., bad syntax might make ANTLR crash).  I will clean\r
this up after I've rewritten v3 in v3.\r
\r
Per the license in LICENSE.txt, this software is not guaranteed to\r
work and might even destroy all life on this planet:\r
\r
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR\r
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\r
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\r
DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,\r
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\r
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\r
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\r
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,\r
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING\r
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\r
POSSIBILITY OF SUCH DAMAGE.\r
\r
EXAMPLES\r
\r
ANTLR v3 sample grammars:\r
\r
    http://www.antlr.org/download/examples-v3.tar.gz\r
\r
contains the following examples: LL-star, cminus, dynamic-scope,\r
fuzzy, hoistedPredicates, island-grammar, java, python, scopes,\r
simplecTreeParser, treeparser, tweak, xmlLexer.\r
\r
Also check out Mantra Programming Language for a prototype (work in\r
progress) using v3:\r
\r
    http://www.linguamantra.org/\r
\r
----------------------------------------------------------------------\r
\r
What is ANTLR?\r
\r
ANTLR stands for (AN)other (T)ool for (L)anguage (R)ecognition and was\r
originally known as PCCTS.  ANTLR is a language tool that provides a\r
framework for constructing recognizers, compilers, and translators\r
from grammatical descriptions containing actions.  Target language list:\r
\r
http://www.antlr.org/wiki/display/ANTLR3/Code+Generation+Targets\r
\r
----------------------------------------------------------------------\r
\r
How is ANTLR v3 different than ANTLR v2?\r
\r
See migration guide:\r
    http://www.antlr.org/wiki/display/ANTLR3/Migrating+from+ANTLR+2+to+ANTLR+3\r
\r
ANTLR v3 has a far superior parsing algorithm called LL(*) that\r
handles many more grammars than v2 does.  In practice, it means you\r
can throw almost any grammar at ANTLR that is non-left-recursive and\r
unambiguous (same input can be matched by multiple rules); the cost is\r
perhaps a tiny bit of backtracking, but with a DFA not a full parser.\r
You can manually set the max lookahead k as an option for any decision\r
though.  The LL(*) algorithm ramps up to use more lookahead when it\r
needs to and is much more efficient than normal LL backtracking. There\r
is support for syntactic predicate (full LL backtracking) when LL(*)\r
fails.\r
\r
Lexers are much easier due to the LL(*) algorithm as well.  Previously\r
these two lexer rules would cause trouble because ANTLR couldn't\r
distinguish between them with finite lookahead to see the decimal\r
point:\r
\r
INT : ('0'..'9')+ ;\r
FLOAT : INT '.' INT ;\r
\r
The syntax is almost identical for features in common, but you should\r
note that labels are always '=' not ':'.  So do id=ID not id:ID.\r
\r
You can do combined lexer/parser grammars again (ala PCCTS) both lexer\r
and parser rules are defined in the same file.  See the examples.\r
Really nice.  You can reference strings and characters in the grammar\r
and ANTLR will generate the lexer for you.\r
\r
The attribute structure has been enhanced.  Rules may have multiple\r
return values, for example.  Further, there are dynamically scoped\r
attributes whereby a rule may define a value usable by any rule it\r
invokes directly or indirectly w/o having to pass a parameter all the\r
way down.\r
\r
ANTLR v3 tree construction is far superior--it provides tree rewrite\r
rules where the right hand side is simply the tree grammar fragment\r
describing the tree you want to build:\r
\r
formalArgs\r
        :       typename declarator (',' typename declarator )*\r
                -> ^(ARG typename declarator)+\r
        ;\r
\r
That builds tree sequences like:\r
\r
^(ARG int v1) ^(ARG int v2)\r
\r
ANTLR v3 also incorporates StringTemplate:\r
\r
      http://www.stringtemplate.org\r
\r
just like AST support.  It is useful for generating output.  For\r
example this rule creates a template called 'import' for each import\r
definition found in the input stream:\r
\r
grammar Java;\r
options {\r
  output=template;\r
}\r
...\r
importDefinition\r
    :   'import' identifierStar SEMI\r
        -> import(name={$identifierStar.st},\r
                begin={$identifierStar.start},\r
                end={$identifierStar.stop})\r
    ;\r
\r
The attributes are set via assignments in the argument list.  The\r
arguments are actions with arbitrary expressions in the target\r
language.  The .st label property is the result template from a rule\r
reference.  There is a nice shorthand in actions too:\r
\r
    %foo(a={},b={},...) ctor\r
    %({name-expr})(a={},...) indirect template ctor reference\r
    %{string-expr} anonymous template from string expr\r
    %{expr}.y = z; template attribute y of StringTemplate-typed expr to z\r
    %x.y = z; set template attribute y of x (always set never get attr)\r
              to z [languages like python without ';' must still use the\r
              ';' which the code generator is free to remove during code gen]\r
              Same as '(x).setAttribute("y", z);'\r
\r
For ANTLR v3 I decided to make the most common tasks easy by default\r
rather.  This means that some of the basic objects are heavier weight\r
than some speed demons would like, but they are free to pare it down\r
leaving most programmers the luxury of having it "just work."  For\r
example, to read in some input, tweak it, and write it back out\r
preserving whitespace, is easy in v3.\r
\r
The ANTLR source code is much prettier.  You'll also note that the\r
run-time classes are conveniently encapsulated in the\r
org.antlr.runtime package.\r
\r
----------------------------------------------------------------------\r
\r
How do I install this damn thing?\r
\r
Just untar and you'll get:\r
\r
antlr-3.0b6/README.txt (this file)\r
antlr-3.0b6/LICENSE.txt\r
antlr-3.0b6/src/org/antlr/...\r
antlr-3.0b6/lib/stringtemplate-3.0.jar (3.0b6 needs 3.0)\r
antlr-3.0b6/lib/antlr-2.7.7.jar\r
antlr-3.0b6/lib/antlr-3.0b6.jar\r
\r
Then you need to add all the jars in lib to your CLASSPATH.\r
\r
----------------------------------------------------------------------\r
\r
How do I use ANTLR v3?\r
\r
[I am assuming you are only using the command-line (and not the\r
ANTLRWorks GUI)].\r
\r
Running ANTLR with no parameters shows you:\r
\r
ANTLR Parser Generator   Early Access Version 3.0b6 (Jan 31, 2007) 1989-2007\r
usage: java org.antlr.Tool [args] file.g [file2.g file3.g ...]\r
  -o outputDir          specify output directory where all output is generated\r
  -lib dir              specify location of token files\r
  -report               print out a report about the grammar(s) processed\r
  -print                print out the grammar without actions\r
  -debug                generate a parser that emits debugging events\r
  -profile              generate a parser that computes profiling information\r
  -nfa                  generate an NFA for each rule\r
  -dfa                  generate a DFA for each decision point\r
  -message-format name  specify output style for messages\r
  -X                    display extended argument list\r
\r
For example, consider how to make the LL-star example from the examples\r
tarball you can get at http://www.antlr.org/download/examples-v3.tar.gz\r
\r
$ cd examples/java/LL-star\r
$ java org.antlr.Tool simplec.g\r
$ jikes *.java\r
\r
For input:\r
\r
char c;\r
int x;\r
void bar(int x);\r
int foo(int y, char d) {\r
  int i;\r
  for (i=0; i<3; i=i+1) {\r
    x=3;\r
    y=5;\r
  }\r
}\r
\r
you will see output as follows:\r
\r
$ java Main input\r
bar is a declaration\r
foo is a definition\r
\r
What if I want to test my parser without generating code?  Easy.  Just\r
run ANTLR in interpreter mode.  It can't execute your actions, but it\r
can create a parse tree from your input to show you how it would be\r
matched.  Use the org.antlr.tool.Interp main class.  In the following,\r
I interpret simplec.g on t.c, which contains "int x;"\r
\r
$ java org.antlr.tool.Interp simplec.g WS program t.c\r
( <grammar SimpleC>\r
  ( program\r
    ( declaration\r
      ( variable\r
        ( type [@0,0:2='int',<14>,1:0] )\r
        ( declarator [@2,4:4='x',<2>,1:4] )\r
        [@3,5:5=';',<5>,1:5]\r
      )\r
    )\r
  )\r
)\r
\r
where I have formatted the output to make it more readable.  I have\r
told it to ignore all WS tokens.\r
\r
----------------------------------------------------------------------\r
\r
How do I rebuild ANTLR v3?\r
\r
Make sure the following two jars are in your CLASSPATH\r
\r
antlr-3.0b6/lib/stringtemplate-3.0.jar\r
antlr-3.0b6/lib/antlr-2.7.7.jar\r
junit.jar [if you want to build the test directories]\r
\r
then jump into antlr-3.0b6/src directory and then type:\r
\r
$ javac -d . org/antlr/Tool.java org/antlr/*/*.java org/antlr/*/*/*.java\r
\r
Takes 9 seconds on my 1Ghz laptop or 4 seconds with jikes.  Later I'll\r
have a real build mechanism, though I must admit the one-liner appeals\r
to me.  I use Intellij so I never type anything actually to build.\r
\r
There is also an ANT build.xml file, but I know nothing of ANT; contributed\r
by others (I'm opposed to any tool with an XML interface for Humans).\r
\r
-----------------------------------------------------------------------\r
C# Target Notes\r
\r
1. Auto-generated lexers do not inherit parent parser's @namespace\r
   {...} value.  Use @lexer::namespace{...}.\r
\r
-----------------------------------------------------------------------\r
\r
CHANGES\r
\r
March 17, 2007\r
\r
* Jonathan DeKlotz updated C# templates to be 3.0b6 current\r
\r
March 14, 2007\r
\r
* Manually-specified (...)=> force backtracking eval of that predicate.\r
  backtracking=true mode does not however.  Added unit test.\r
\r
March 14, 2007\r
\r
* Fixed bug in lexer where ~T didn't compute the set from rule T.\r
\r
* Added -Xnoinlinedfa make all DFA with tables; no inline prediction with IFs\r
\r
* Fixed http://www.antlr.org:8888/browse/ANTLR-80.\r
  Sem pred states didn't define lookahead vars.\r
\r
* Fixed http://www.antlr.org:8888/browse/ANTLR-91.  \r
  When forcing some acyclic DFA to be state tables, they broke.\r
  Forcing all DFA to be state tables should give same results.\r
\r
March 12, 2007\r
\r
* setTokenSource in CommonTokenStream didn't clear tokens list.\r
  setCharStream calls reset in Lexer.\r
\r
* Altered -depend.  No longer printing grammar files for multiple input\r
  files with -depend.  Doesn't show T__.g temp file anymore. Added\r
  TLexer.tokens.  Added .h files if defined.\r
\r
February 11, 2007\r
\r
* Added -depend command-line option that, instead of processing files,\r
  it shows you what files the input grammar(s) depend on and what files\r
  they generate. For combined grammar T.g:\r
\r
  $ java org.antlr.Tool -depend T.g\r
\r
  You get:\r
\r
  TParser.java : T.g\r
  T.tokens : T.g\r
  T__.g : T.g\r
\r
  Now, assuming U.g is a tree grammar ref'd T's tokens:\r
\r
  $ java org.antlr.Tool -depend T.g U.g\r
\r
  TParser.java : T.g\r
  T.tokens : T.g\r
  T__.g : T.g\r
  U.g: T.tokens\r
  U.java : U.g\r
  U.tokens : U.g\r
\r
  Handles spaces by escaping them.  Pays attention to -o, -fo and -lib.\r
  Dir 'x y' is a valid dir in current dir.\r
\r
  $ java org.antlr.Tool -depend -lib /usr/local/lib -o 'x y' T.g U.g\r
  x\ y/TParser.java : T.g\r
  x\ y/T.tokens : T.g\r
  x\ y/T__.g : T.g\r
  U.g: /usr/local/lib/T.tokens\r
  x\ y/U.java : U.g\r
  x\ y/U.tokens : U.g\r
\r
  You have API access via org.antlr.tool.BuildDependencyGenerator class:\r
  getGeneratedFileList(), getDependenciesFileList().  You can also access\r
  the output template: getDependencies().  The file\r
  org/antlr/tool/templates/depend.stg contains the template.  You can\r
  modify as you want.  File objects go in so you can play with path etc...\r
\r
February 10, 2007\r
\r
* no more .gl files generated.  All .g all the time.\r
\r
* changed @finally to be @after and added a finally clause to the\r
  exception stuff.  I also removed the superfluous "exception"\r
  keyword.  Here's what the new syntax looks like:\r
\r
  a\r
  @after { System.out.println("ick"); }\r
    : 'a'\r
    ;        \r
    catch[RecognitionException e] { System.out.println("foo"); }\r
    catch[IOException e] { System.out.println("io"); }\r
    finally { System.out.println("foobar"); }\r
\r
  @after executes after bookkeeping to set $rule.stop, $rule.tree but\r
  before scopes pop and any memoization happens.  Dynamic scopes and\r
  memoization are still in generated finally block because they must\r
  exec even if error in rule.  The @after action and tree setting\r
  stuff can technically be skipped upon syntax error in rule.  [Later\r
  we might add something to finally to stick an ERROR token in the\r
  tree and set the return value.]  Sequence goes: set $stop, $tree (if\r
  any), @after (if any), pop scopes (if any), memoize (if needed),\r
  grammar finally clause.  Last 3 are in generated code's finally\r
  clause.\r
\r
3.0b6 - January 31, 2007\r
\r
January 30, 2007\r
\r
* Fixed bug in IntervalSet.and: it returned the same empty set all the time\r
  rather than new empty set.  Code altered the same empty set.\r
\r
* Made analysis terminate faster upon a decision that takes too long;\r
  it seemed to keep doing work for a while.  Refactored some names\r
  and updated comments.  Also made it terminate when it realizes it's\r
  non-LL(*) due to recursion.  just added terminate conditions to loop\r
  in convert().\r
\r
* Sometimes fatal non-LL(*) messages didn't appear; instead you got\r
  "antlr couldn't analyze", which is actually untrue.  I had the\r
  order of some prints wrong in the DecisionProbe.\r
\r
* The code generator incorrectly detected when it could use a fixed,\r
  acyclic inline DFA (i.e., using an IF).  Upon non-LL(*) decisions\r
  with predicates, analysis made cyclic DFA.  But this stops\r
  the computation detecting whether they are cyclic.  I just added\r
  a protection in front of the acyclic DFA generator to avoid if\r
  non-LL(*).  Updated comments.\r
\r
January 23, 2007\r
\r
* Made tree node streams use adaptor to create navigation nodes.\r
  Thanks to Emond Papegaaij.\r
\r
January 22, 2007\r
\r
* Added lexer rule properties: start, stop\r
\r
January 1, 2007\r
\r
* analysis failsafe is back on; if a decision takes too long, it bails out\r
  and uses k=1\r
\r
January 1, 2007\r
\r
* += labels for rules only work for output option; previously elements\r
  of list were the return value structs, but are now either the tree or\r
  StringTemplate return value.  You can label different rules now\r
  x+=a x+=b.\r
\r
December 30, 2006\r
\r
* Allow \" to work correctly in "..." template.\r
\r
December 28, 2006\r
\r
* errors that are now warnings: missing AST label type in trees.\r
  Also "no start rule detected" is warning.\r
\r
* tree grammars also can do rewrite=true for output=template.\r
  Only works for alts with single node or tree as alt elements.\r
  If you are going to use $text in a tree grammar or do rewrite=true\r
  for templates, you must use in your main:\r
\r
  nodes.setTokenStream(tokens);\r
\r
* You get a warning for tree grammars that do rewrite=true and\r
  output=template and have -> for alts that are not simple nodes\r
  or simple trees.  new unit tests in TestRewriteTemplates at end.\r
\r
December 27, 2006\r
\r
* Error message appears when you use -> in tree grammar with\r
  output=template and rewrite=true for alt that is not simple\r
  node or tree ref.\r
\r
* no more $stop attribute for tree parsers; meaningless/useless.\r
  Removed from TreeRuleReturnScope also.\r
\r
* rule text attribute in tree parser must pull from token buffer.\r
  Makes no sense otherwise.  added getTokenStream to TreeNodeStream\r
  so rule $text attr works.  CommonTreeNodeStream etc... now let\r
  you set the token stream so you can access later from tree parser.\r
  $text is not well-defined for rules like\r
\r
     slist : stat+ ;\r
\r
  because stat is not a single node nor rooted with a single node.\r
  $slist.text will get only first stat.  I need to add a warning about\r
  this...\r
\r
* Fixed http://www.antlr.org:8888/browse/ANTLR-76 for Java.\r
  Enhanced TokenRewriteStream so it accepts any object; converts\r
  to string at last second.  Allows you to rewrite with StringTemplate\r
  templates now :)\r
\r
* added rewrite option that makes -> template rewrites do replace ops for\r
  TokenRewriteStream input stream.  In output=template and rewrite=true mode\r
  same as before 'cept that the parser does\r
\r
    ((TokenRewriteStream)input).replace(\r
              ((Token)retval.start).getTokenIndex(),\r
              input.LT(-1).getTokenIndex(),\r
              retval.st);\r
\r
  after each rewrite so that the input stream is altered.  Later refs to\r
  $text will have rewrites.  Here's a sample test program for grammar Rew.\r
\r
        FileReader groupFileR = new FileReader("Rew.stg");\r
        StringTemplateGroup templates = new StringTemplateGroup(groupFileR);\r
        ANTLRInputStream input = new ANTLRInputStream(System.in);\r
        RewLexer lexer = new RewLexer(input);\r
        TokenRewriteStream tokens = new TokenRewriteStream(lexer);\r
        RewParser parser = new RewParser(tokens);\r
        parser.setTemplateLib(templates);\r
        parser.program();\r
        System.out.println(tokens.toString());\r
        groupFileR.close();\r
\r
December 26, 2006\r
\r
* BaseTree.dupTree didn't dup recursively.\r
\r
December 24, 2006\r
\r
* Cleaned up some comments and removed field treeNode\r
  from MismatchedTreeNodeException class.  It is "node" in\r
  RecognitionException.\r
\r
* Changed type from Object to BitSet for expecting fields in\r
  MismatchedSetException and MismatchedNotSetException\r
\r
* Cleaned up error printing in lexers and the messages that it creates.\r
\r
* Added this to TreeAdaptor:\r
        /** Return the token object from which this node was created.\r
         *  Currently used only for printing an error message.\r
         *  The error display routine in BaseRecognizer needs to\r
         *  display where the input the error occurred. If your\r
         *  tree of limitation does not store information that can\r
         *  lead you to the token, you can create a token filled with\r
         *  the appropriate information and pass that back.  See\r
         *  BaseRecognizer.getErrorMessage().\r
         */\r
        public Token getToken(Object t);\r
\r
December 23, 2006\r
\r
* made BaseRecognizer.displayRecognitionError nonstatic so people can\r
  override it. Not sure why it was static before.\r
\r
* Removed state/decision message that comes out of no \r
  viable alternative exceptions, as that was too much.\r
  removed the decision number from the early exit exception\r
  also.  During development, you can simply override\r
  displayRecognitionError from BaseRecognizer to add the stuff\r
  back in if you want.\r
\r
* made output go to an output method you can override: emitErrorMessage()\r
\r
* general cleanup of the error emitting code in BaseRecognizer.  Lots\r
  more stuff you can override: getErrorHeader, getTokenErrorDisplay,\r
  emitErrorMessage, getErrorMessage.\r
\r
December 22, 2006\r
\r
* Altered Tree.Parser.matchAny() so that it skips entire trees if\r
  node has children otherwise skips one node.  Now this works to\r
  skip entire body of function if single-rooted subtree:\r
  ^(FUNC name=ID arg=ID .)\r
\r
* Added "reverse index" from node to stream index.  Override\r
  fillReverseIndex() in CommonTreeNodeStream if you want to change.\r
  Use getNodeIndex(node) to find stream index for a specific tree node.\r
  See getNodeIndex(), reverseIndex(Set tokenTypes),\r
  reverseIndex(int tokenType), fillReverseIndex().  The indexing\r
  costs time and memory to fill, but pulling stuff out will be lots\r
  faster as it can jump from a node ptr straight to a stream index.\r
\r
* Added TreeNodeStream.get(index) to make it easier for interpreters to\r
  jump around in tree node stream.\r
\r
* New CommonTreeNodeStream buffers all nodes in stream for fast jumping\r
  around.  It now has push/pop methods to invoke other locations in\r
  the stream for building interpreters.\r
\r
* Moved CommonTreeNodeStream to UnBufferedTreeNodeStream and removed\r
  Iterator implementation.  moved toNodesOnlyString() to TestTreeNodeStream\r
\r
* [BREAKS ANY TREE IMPLEMENTATION]\r
  made CommonTreeNodeStream work with any tree node type.  TreeAdaptor\r
  now implements isNil so must add; trivial, but does break back\r
  compatibility.\r
\r
December 17, 2006\r
\r
* Added traceIn/Out methods to recognizers so that you can override them;\r
  previously they were in-line print statements. The message has also\r
  been slightly improved.\r
\r
* Factored BuildParseTree into debug package; cleaned stuff up. Fixed\r
  unit tests.\r
\r
December 15, 2006\r
\r
* [BREAKS ANY TREE IMPLEMENTATION]\r
  org.antlr.runtime.tree.Tree; needed to add get/set for token start/stop\r
  index so CommonTreeAdaptor can assume Tree interface not CommonTree\r
  implementation.  Otherwise, no way to create your own nodes that satisfy\r
  Tree because CommonTreeAdaptor was doing \r
\r
        public int getTokenStartIndex(Object t) {\r
                return ((CommonTree)t).startIndex;\r
        }\r
\r
  Added to Tree:\r
\r
        /**  What is the smallest token index (indexing from 0) for this node\r
         *   and its children?\r
         */\r
        int getTokenStartIndex();\r
\r
        void setTokenStartIndex(int index);\r
\r
        /**  What is the largest token index (indexing from 0) for this node\r
         *   and its children?\r
         */\r
        int getTokenStopIndex();        \r
\r
        void setTokenStopIndex(int index);\r
\r
December 13, 2006\r
 \r
* Added org.antlr.runtime.tree.DOTTreeGenerator so you can generate DOT\r
  diagrams easily from trees.\r
\r
        CharStream input = new ANTLRInputStream(System.in);\r
        TLexer lex = new TLexer(input);\r
        CommonTokenStream tokens = new CommonTokenStream(lex);\r
        TParser parser = new TParser(tokens);\r
        TParser.e_return r = parser.e();\r
        Tree t = (Tree)r.tree;\r
        System.out.println(t.toStringTree());\r
        DOTTreeGenerator gen = new DOTTreeGenerator();\r
        StringTemplate st = gen.toDOT(t);\r
        System.out.println(st);\r
\r
* Changed the way mark()/rewind() work in CommonTreeNode stream to mirror\r
  more flexible solution in ANTLRStringStream.  Forgot to set lastMarker\r
  anyway.  Now you can rewind to non-most-recent marker.\r
\r
December 12, 2006\r
\r
* Temp lexer now end in .gl (T__.gl, for example)\r
\r
* TreeParser suffix no longer generated for tree grammars\r
\r
* Defined reset for lexer, parser, tree parser; rewinds the input stream also\r
\r
December 10, 2006\r
\r
* Made Grammar.abortNFAToDFAConversion() abort in middle of a DFA.\r
\r
December 9, 2006\r
\r
* fixed bug in OrderedHashSet.add().  It didn't track elements correctly.\r
\r
December 6, 2006\r
\r
* updated build.xml for future Ant compatibility, thanks to Matt Benson.\r
\r
* various tests in TestRewriteTemplate and TestSyntacticPredicateEvaluation\r
  were using the old 'channel' vs. new '$channel' notation.\r
  TestInterpretedParsing didn't pick up an earlier change to CommonToken.\r
  Reported by Matt Benson.\r
\r
* fixed platform dependent test failures in TestTemplates, supplied by Matt\r
  Benson.\r
\r
November 29, 2006\r
\r
*  optimized semantic predicate evaluation so that p||!p yields true.\r
\r
November 22, 2006\r
\r
* fixed bug that prevented var = $rule.some_retval from working in anything\r
  but the first alternative of a rule or subrule.\r
\r
* attribute names containing digits were not allowed, this is now fixed,\r
  allowing attributes like 'name1' but not '1name1'.\r
\r
November 19, 2006\r
\r
* Removed LeftRecursionMessage and apparatus because it seems that I check\r
  for left recursion upfront before analysis and everything gets specified as\r
  recursion cycles at this point.\r
\r
November 16, 2006\r
\r
* TokenRewriteStream.replace was not passing programName to next method.\r
\r
November 15, 2006\r
\r
* updated DOT files for DFA generation to make smaller circles.\r
\r
* made epsilon edges italics in the NFA diagrams.\r
\r
3.0b5 - November 15, 2006\r
\r
The biggest thing is that your grammar file names must match the grammar name\r
inside (your generated class names will also be different) and we use\r
$channel=HIDDEN now instead of channel=99 inside lexer actions.\r
Should be compatible other than that.   Please look at complete list of\r
changes.\r
\r
November 14, 2006\r
\r
* Force token index to be -1 for CommonIndex in case not set.\r
\r
November 11, 2006\r
\r
* getUniqueID for TreeAdaptor now uses identityHashCode instead of hashCode.\r
\r
November 10, 2006\r
\r
* No grammar nondeterminism warning now when wildcard '.' is final alt.\r
  Examples:\r
\r
        a : A | B | . ;\r
\r
        A : 'a'\r
          | .\r
          ;\r
\r
        SL_COMMENT\r
            : '//' (options {greedy=false;} : .)* '\r'? '\n'\r
            ;\r
\r
        SL_COMMENT2\r
            : '//' (options {greedy=false;} : 'x'|.)* '\r'? '\n'\r
            ;\r
\r
\r
November 8, 2006\r
\r
* Syntactic predicates did not get hoisting properly upon non-LL(*) decision.  Other hoisting issues fixed.  Cleaned up code.\r
\r
* Removed failsafe that check to see if I'm spending too much time on a single DFA; I don't think we need it anymore.\r
\r
November 3, 2006\r
\r
* $text, $line, etc... were not working in assignments. Fixed and added\r
  test case.\r
\r
* $label.text translated to label.getText in lexer even if label was on a char\r
\r
November 2, 2006\r
\r
* Added error if you don't specify what the AST type is; actions in tree\r
  grammar won't work without it.\r
\r
  $ cat x.g\r
  tree grammar x;\r
  a : ID {String s = $ID.text;} ;\r
\r
  ANTLR Parser Generator   Early Access Version 3.0b5 (??, 2006)  1989-2006\r
  error: x.g:0:0: (152) tree grammar x has no ASTLabelType option\r
\r
November 1, 2006\r
\r
* $text, $line, etc... were not working properly within lexer rule.\r
\r
October 32, 2006\r
\r
* Finally actions now execute before dynamic scopes are popped it in the\r
  rule. Previously was not possible to access the rules scoped variables\r
  in a finally action.\r
\r
October 29, 2006\r
\r
* Altered ActionTranslator to emit errors on setting read-only attributes\r
  such as $start, $stop, $text in a rule. Also forbid setting any attributes\r
  in rules/tokens referenced by a label or name.\r
  Setting dynamic scopes's attributes and your own parameter attributes\r
  is legal.\r
\r
October 27, 2006\r
\r
* Altered how ANTLR figures out what decision is associated with which\r
  block of grammar.  Makes ANTLRWorks correctly find DFA for a block.\r
\r
October 26, 2006\r
\r
* Fixed bug where EOT transitions led to no NFA configs in a DFA state,\r
  yielding an error in DFA table generation.\r
\r
* renamed action.g to ActionTranslator.g\r
  the ActionTranslator class is now called ActionTranslatorLexer, as ANTLR\r
  generates this classname now. Fixed rest of codebase accordingly.\r
\r
* added rules recognizing setting of scopes' attributes to ActionTranslator.g\r
  the Objective C target needed access to the right-hand side of the assignment\r
  in order to generate correct code\r
\r
* changed ANTLRCore.sti to reflect the new mandatory templates to support the above\r
  namely: scopeSetAttributeRef, returnSetAttributeRef and the ruleSetPropertyRef_*\r
  templates, with the exception of ruleSetPropertyRef_text. we cannot set this attribute\r
\r
October 19, 2006\r
\r
* Fixed 2 bugs in DFA conversion that caused exceptions.\r
  altered functionality of getMinElement so it ignores elements<0.\r
\r
October 18, 2006\r
\r
* moved resetStateNumbersToBeContiguous() to after issuing of warnings;\r
  an internal error in that routine should make more sense as issues\r
  with decision will appear first.\r
\r
* fixed cut/paste bug I introduced when fixed EOF in min/max\r
  bug. Prevented C grammar from working briefly.\r
\r
October 17, 2006\r
\r
* Removed a failsafe that seems to be unnecessary that ensure DFA didn't\r
  get too big.  It was resulting in some failures in code generation that\r
  led me on quite a strange debugging trip.\r
\r
October 16, 2006\r
\r
* Use channel=HIDDEN not channel=99 to put tokens on hidden channel.\r
\r
October 12, 2006\r
\r
* ANTLR now has a customizable message format for errors and warnings,\r
  to make it easier to fulfill requirements by IDEs and such.\r
  The format to be used can be specified via the '-message-format name'\r
  command line switch. The default for name is 'antlr', also available\r
  at the moment is 'gnu'. This is done via StringTemplate, for details\r
  on the requirements look in org/antlr/tool/templates/messages/formats/\r
\r
* line numbers for lexers in combined grammars are now reported correctly.\r
\r
September 29, 2006\r
\r
* ANTLRReaderStream improperly checked for end of input.\r
\r
September 28, 2006\r
\r
* For ANTLRStringStream, LA(-1) was off by one...gave you LA(-2).\r
\r
3.0b4 - August 24, 2006\r
\r
* error when no rules in grammar.  doesn't crash now.\r
\r
* Token is now an interface.\r
\r
* remove dependence on non runtime classes in runtime package.\r
\r
* filename and grammar name must be same Foo in Foo.g.  Generates FooParser,\r
  FooLexer, ...  Combined grammar Foo generates Foo$Lexer.g which generates\r
  FooLexer.java.  tree grammars generate FooTreeParser.java\r
\r
August 24, 2006\r
\r
* added C# target to lib, codegen, templates\r
\r
August 11, 2006\r
\r
* added tree arg to navigation methods in treeadaptor\r
\r
August 07, 2006\r
\r
* fixed bug related to (a|)+ on end of lexer rules.  crashed instead\r
  of warning.\r
\r
* added warning that interpreter doesn't do synpreds yet\r
\r
* allow different source of classloader:\r
ClassLoader cl = Thread.currentThread().getContextClassLoader();\r
if ( cl==null ) {\r
    cl = this.getClass().getClassLoader();\r
}\r
\r
\r
July 26, 2006\r
\r
* compressed DFA edge tables significantly.  All edge tables are\r
  unique. The transition table can reuse arrays.  Look like this now:\r
\r
     public static readonly DFA30_transition0 =\r
        new short[] { 46, 46, -1, 46, 46, -1, -1, -1, -1, -1, -1, -1,...};\r
         public static readonly DFA30_transition1 =\r
        new short[] { 21 };\r
      public static readonly short[][] DFA30_transition = {\r
          DFA30_transition0,\r
          DFA30_transition0,\r
          DFA30_transition1,\r
          ...\r
      };\r
\r
* If you defined both a label like EQ and '=', sometimes the '=' was\r
  used instead of the EQ label.\r
\r
* made headerFile template have same arg list as outputFile for consistency\r
\r
* outputFile, lexer, genericParser, parser, treeParser templates\r
  reference cyclicDFAs attribute which was no longer used after I\r
  started the new table-based DFA.  I made cyclicDFADescriptors\r
  argument to outputFile and headerFile (only).  I think this is\r
  correct as only OO languages will want the DFA in the recognizer.\r
  At the top level, C and friends can use it.  Changed name to use\r
  cyclicDFAs again as it's a better name probably.  Removed parameter\r
  from the lexer, ...  For example, my parser template says this now:\r
\r
    <cyclicDFAs:cyclicDFA()> <! dump tables for all DFA !>\r
\r
* made all token ref token types go thru code gen's\r
  getTokenTypeAsTargetLabel()\r
\r
* no more computing DFA transition tables for acyclic DFA.\r
\r
July 25, 2006\r
\r
* fixed a place where I was adding syn predicates into rewrite stuff.\r
\r
* turned off invalid token index warning in AW support; had a problem.\r
\r
* bad location event generated with -debug for synpreds in autobacktrack mode.\r
\r
July 24, 2006\r
\r
* changed runtime.DFA so that it treats all chars and token types as\r
  char (unsigned 16 bit int).  -1 becomes '\uFFFF' then or 65535.\r
\r
* changed MAX_STATE_TRANSITIONS_FOR_TABLE to be 65534 by default\r
  now. This means that all states can use a table to do transitions.\r
\r
* was not making synpreds on (C)* type loops with backtrack=true\r
\r
* was copying tree stuff and actions into synpreds with backtrack=true\r
\r
* was making synpreds on even single alt rules / blocks with backtrack=true\r
\r
3.0b3 - July 21, 2006\r
\r
* ANTLR fails to analyze complex decisions much less frequently.  It\r
  turns out that the set of decisions for which ANTLR fails (times\r
  out) is the same set (so far) of non-LL(*) decisions.  Morever, I'm\r
  able to detect this situation quickly and report rather than timing\r
  out. Errors look like:\r
\r
  java.g:468:23: [fatal] rule concreteDimensions has non-LL(*)\r
    decision due to recursive rule invocations in alts 1,2.  Resolve\r
    by left-factoring or using syntactic predicates with fixed k\r
    lookahead or use backtrack=true option.\r
\r
  This message only appears when k=*.\r
\r
* Shortened no viable alt messages to not include decision\r
  description:\r
\r
[compilationUnit, declaration]: line 8:8 decision=<<67:1: declaration\r
: ( ( fieldDeclaration )=> fieldDeclaration | ( methodDeclaration )=>\r
methodDeclaration | ( constructorDeclaration )=>\r
constructorDeclaration | ( classDeclaration )=> classDeclaration | (\r
interfaceDeclaration )=> interfaceDeclaration | ( blockDeclaration )=>\r
blockDeclaration | emptyDeclaration );>> state 3 (decision=14) no\r
viable alt; token=[@1,184:187='java',<122>,8:8]\r
\r
  too long and hard to read.\r
\r
July 19, 2006\r
\r
* Code gen bug: states with no emanating edges were ignored by ST.\r
  Now an empty list is used.\r
\r
* Added grammar parameter to recognizer templates so they can access\r
  properties like getName(), ...\r
\r
July 10, 2006\r
\r
* Fixed the gated pred merged state bug.  Added unit test.\r
\r
* added new method to Target: getTokenTypeAsTargetLabel()\r
\r
July 7, 2006\r
\r
* I was doing an AND instead of OR in the gated predicate stuff.\r
  Thanks to Stephen Kou!\r
\r
* Reduce op for combining predicates was insanely slow sometimes and\r
  didn't actually work well.  Now it's fast and works.\r
\r
* There is a bug in merging of DFA stop states related to gated\r
  preds...turned it off for now.\r
\r
3.0b2 - July 5, 2006\r
\r
July 5, 2006\r
\r
* token emission not properly protected in lexer filter mode.\r
\r
* EOT, EOT DFA state transition tables should be init'd to -1 (only\r
  was doing this for compressed tables).  Fixed.\r
\r
* in trace mode, exit method not shown for memoized rules\r
\r
* added -Xmaxdfaedges to allow you to increase number of edges allowed\r
  for a single DFA state before it becomes "special" and can't fit in\r
  a simple table.\r
\r
* Bug in tables.  Short are signed so min/max tables for DFA are now\r
  char[].  Bizarre.\r
\r
July 3, 2006\r
\r
* Added a method to reset the tool error state for current thread.\r
  See ErrorManager.java\r
\r
* [Got this working properly today] backtrack mode that let's you type\r
  in any old crap and ANTLR will backtrack if it can't figure out what\r
  you meant.  No errors are reported by antlr during analysis.  It\r
  implicitly adds a syn pred in front of every production, using them\r
  only if static grammar LL(*) analysis fails.  Syn pred code is not\r
  generated if the pred is not used in a decision.\r
\r
  This is essentially a rapid prototyping mode.\r
\r
* Added backtracking report to the -report option\r
\r
* Added NFA->DFA conversion early termination report to the -report option\r
\r
* Added grammar level k and backtrack options to -report\r
\r
* Added a dozen unit tests to test autobacktrack NFA construction.\r
\r
* If you are using filter mode, you must manually use option\r
  memoize=true now.\r
\r
July 2, 2006\r
\r
* Added k=* option so you can set k=2, for example, on whole grammar,\r
  but an individual decision can be LL(*).\r
\r
* memoize option for grammars, rules, blocks.  Remove -nomemo cmd-line option\r
\r
* but in DOT generator for DFA; fixed.\r
\r
* runtime.DFA reported errors even when backtracking\r
\r
July 1, 2006\r
\r
* Added -X option list to help\r
\r
* Syn preds were being hoisted into other rules, causing lots of extra\r
  backtracking.\r
\r
June 29, 2006\r
\r
* unnecessary files removed during build.\r
\r
* Matt Benson updated build.xml\r
\r
* Detecting use of synpreds in analysis now instead of codegen.  In\r
  this way, I can avoid analyzing decisions in synpreds for synpreds\r
  not used in a DFA for a real rule.  This is used to optimize things\r
  for backtrack option.\r
\r
* Code gen must add _fragment or whatever to end of pred name in\r
  template synpredRule to avoid having ANTLR know anything about\r
  method names.\r
\r
* Added -IdbgST option to emit ST delimiters at start/stop of all\r
  templates spit out.\r
\r
June 28, 2006\r
\r
* Tweaked message when ANTLR cannot handle analysis.\r
\r
3.0b1 - June 27, 2006\r
\r
June 24, 2006\r
\r
* syn preds no longer generate little static classes; they also don't\r
  generate a whole bunch of extra crap in the rules built to test syn\r
  preds.  Removed GrammarFragmentPointer class from runtime.\r
\r
June 23-24, 2006\r
\r
* added output option to -report output.\r
\r
* added profiling info:\r
  Number of rule invocations in "guessing" mode\r
  number of rule memoization cache hits\r
  number of rule memoization cache misses\r
\r
* made DFA DOT diagrams go left to right not top to bottom\r
\r
* I try to recursive overflow states now by resolving these states\r
  with semantic/syntactic predicates if they exist.  The DFA is then\r
  deterministic rather than simply resolving by choosing first\r
  nondeterministic alt.  I used to generated errors:\r
\r
~/tmp $ java org.antlr.Tool -dfa t.g\r
ANTLR Parser Generator   Early Access Version 3.0b2 (July 5, 2006)  1989-2006\r
t.g:2:5: Alternative 1: after matching input such as A A A A A decision cannot predict what comes next due to recursion overflow to b from b\r
t.g:2:5: Alternative 2: after matching input such as A A A A A decision cannot predict what comes next due to recursion overflow to b from b\r
\r
  Now, I uses predicates if available and emits no warnings.\r
\r
* made sem preds share accept states.  Previously, multiple preds in a\r
decision forked new accepts each time for each nondet state.\r
\r
June 19, 2006\r
\r
* Need parens around the prediction expressions in templates.\r
\r
* Referencing $ID.text in an action forced bad code gen in lexer rule ID.\r
\r
* Fixed a bug in how predicates are collected.  The definition of\r
  "last predicated alternative" was incorrect in the analysis.  Further,\r
  gated predicates incorrectly missed a case where an edge should become\r
  true (a tautology).\r
\r
* Removed an unnecessary input.consume() reference in the runtime/DFA class.\r
\r
June 14, 2006\r
\r
* -> ($rulelabel)? didn't generate proper code for ASTs.\r
\r
* bug in code gen (did not compile)\r
a : ID -> ID\r
  | ID -> ID\r
  ;\r
Problem is repeated ref to ID from left side.  Juergen pointed this out.\r
\r
* use of tokenVocab with missing file yielded exception\r
\r
* (A|B)=> foo yielded an exception as (A|B) is a set not a block. Fixed.\r
\r
* Didn't set ID1= and INT1= for this alt:\r
  | ^(ID INT+ {System.out.print(\"^(\"+$ID+\" \"+$INT+\")\");})\r
\r
* Fixed so repeated dangling state errors only occur once like:\r
t.g:4:17: the decision cannot distinguish between alternative(s) 2,1 for at least one input sequence\r
\r
* tracking of rule elements was on (making list defs at start of\r
  method) with templates instead of just with ASTs.  Turned off.\r
\r
* Doesn't crash when you give it a missing file now.\r
\r
* -report: add output info: how many LL(1) decisions.\r
\r
June 13, 2006\r
\r
* ^(ROOT ID?) Didn't work; nor did any other nullable child list such as\r
  ^(ROOT ID* INT?).  Now, I check to see if child list is nullable using\r
  Grammar.LOOK() and, if so, I generate an "IF lookahead is DOWN" gate\r
  around the child list so the whole thing is optional.\r
\r
* Fixed a bug in LOOK that made it not look through nullable rules.\r
\r
* Using AST suffixes or -> rewrite syntax now gives an error w/o a grammar\r
  output option.  Used to crash ;)\r
\r
* References to EOF ended up with improper -1 refs instead of EOF in output.\r
\r
* didn't warn of ambig ref to $expr in rewrite; fixed.\r
list\r
     :  '[' expr 'for' type ID 'in' expr ']'\r
        -> comprehension(expr={$expr.st},type={},list={},i={})\r
        ;\r
\r
June 12, 2006\r
\r
* EOF works in the parser as a token name.\r
\r
* Rule b:(A B?)*; didn't display properly in AW due to the way ANTLR\r
  generated NFA.\r
\r
* "scope x;" in a rule for unknown x gives no error.  Fixed.  Added unit test.\r
\r
* Label type for refs to start/stop in tree parser and other parsers were\r
  not used.  Lots of casting.  Ick. Fixed.\r
\r
* couldn't refer to $tokenlabel in isolation; but need so we can test if\r
  something was matched.  Fixed.\r
\r
* Lots of little bugs fixed in $x.y, %... translation due to new\r
  action translator.\r
\r
* Improperly tracking block nesting level; result was that you couldn't\r
  see $ID in action of rule "a : A+ | ID {Token t = $ID;} | C ;"\r
\r
* a : ID ID {$ID.text;} ; did not get a warning about ambiguous $ID ref.\r
\r
* No error was found on $COMMENT.text:\r
\r
COMMENT\r
    :   '/*' (options {greedy=false;} : . )* '*/'\r
        {System.out.println("found method "+$COMMENT.text);}\r
    ;\r
\r
  $enclosinglexerrule scope does not exist.  Use text or setText() here.\r
\r
June 11, 2006\r
\r
* Single return values are initialized now to default or to your spec.\r
\r
* cleaned up input stream stuff.  Added ANTLRReaderStream, ANTLRInputStream\r
  and refactored.  You can specify encodings now on ANTLRFileStream (and\r
  ANTLRInputStream) now.\r
\r
* You can set text local var now in a lexer rule and token gets that text.\r
  start/stop indexes are still set for the token.\r
\r
* Changed lexer slightly.  Calling a nonfragment rule from a\r
  nonfragment rule does not set the overall token.\r
\r
June 10, 2006\r
\r
* Fixed bug where unnecessary escapes yield char==0 like '\{'.\r
\r
* Fixed analysis bug.  This grammar didn't report a recursion warning:\r
x   : y X\r
    | y Y\r
    ;\r
y   : L y R\r
    | B\r
    ;\r
  The DFAState.equals() method was messed up.\r
\r
* Added @synpredgate {...} action so you can tell ANTLR how to gate actions\r
  in/out during syntactic predicate evaluation.\r
\r
* Fuzzy parsing should be more efficient.  It should backtrack over a rule\r
  and then rewind and do it again "with feeling" to exec actions.  It was\r
  actually doing it 3x not 2x.\r
\r
June 9, 2006\r
\r
* Gutted and rebuilt the action translator for $x.y, $x::y, ...\r
  Uses ANTLR v3 now for the first time inside v3 source. :)\r
  ActionTranslator.java\r
\r
* Fixed a bug where referencing a return value on a rule didn't work\r
  because later a ref to that rule's predefined properties didn't\r
  properly force a return value struct to be built.  Added unit test.\r
\r
June 6, 2006\r
\r
* New DFA mechanisms.  Cyclic DFA are implemented as state tables,\r
  encoded via strings as java cannot handle large static arrays :(\r
  States with edges emanating that have predicates are specially\r
  treated.  A method is generated to do these states.  The DFA\r
  simulation routine uses the "special" array to figure out if the\r
  state is special.  See March 25, 2006 entry for description:\r
  http://www.antlr.org/blog/antlr3/codegen.tml.  analysis.DFA now has\r
  all the state tables generated for code gen.  CyclicCodeGenerator.java\r
  disappeared as it's unneeded code. :)\r
\r
* Internal general clean up of the DFA.states vs uniqueStates thing.\r
  Fixed lookahead decisions no longer fill uniqueStates.  Waste of\r
  time.  Also noted that when adding sem pred edges, I didn't check\r
  for state reuse.  Fixed.\r
\r
June 4, 2006\r
\r
* When resolving ambig DFA states predicates, I did not add the new states\r
  to the list of unique DFA states.  No observable effect on output except\r
  that DFA state numbers were not always contiguous for predicated decisions.\r
  I needed this fix for new DFA tables.\r
\r
3.0ea10 - June 2, 2006\r
\r
June 2, 2006\r
\r
* Improved grammar stats and added syntactic pred tracking.\r
\r
June 1, 2006\r
\r
* Due to a type mismatch, the DebugParser.recoverFromMismatchedToken()\r
  method was not called.  Debug events for mismatched token error\r
  notification were not sent to ANTLRWorks probably\r
\r
* Added getBacktrackingLevel() for any recognizer; needed for profiler.\r
\r
* Only writes profiling data for antlr grammar analysis with -profile set\r
\r
* Major update and bug fix to (runtime) Profiler.\r
\r
May 27, 2006\r
\r
* Added Lexer.skip() to force lexer to ignore current token and look for\r
  another; no token is created for current rule and is not passed on to\r
  parser (or other consumer of the lexer).\r
\r
* Parsers are much faster now.  I removed use of java.util.Stack for pushing\r
  follow sets and use a hardcoded array stack instead.  Dropped from\r
  5900ms to 3900ms for parse+lex time parsing entire java 1.4.2 source.  Lex\r
  time alone was about 1500ms.  Just looking at parse time, we get about 2x\r
  speed improvement. :)\r
\r
May 26, 2006\r
\r
* Fixed NFA construction so it generates NFA for (A*)* such that ANTLRWorks\r
  can display it properly.\r
\r
May 25, 2006\r
\r
* added abort method to Grammar so AW can terminate the conversion if it's\r
  taking too long.\r
\r
May 24, 2006\r
\r
* added method to get left recursive rules from grammar without doing full\r
  grammar analysis.\r
\r
* analysis, code gen not attempted if serious error (like\r
  left-recursion or missing rule definition) occurred while reading\r
  the grammar in and defining symbols.\r
\r
* added amazing optimization; reduces analysis time by 90% for java\r
  grammar; simple IF statement addition!\r
\r
3.0ea9 - May 20, 2006\r
\r
* added global k value for grammar to limit lookahead for all decisions unless\r
overridden in a particular decision.\r
\r
* added failsafe so that any decision taking longer than 2 seconds to create\r
the DFA will fall back on k=1.  Use -ImaxtimeforDFA n (in ms) to set the time.\r
\r
* added an option (turned off for now) to use multiple threads to\r
perform grammar analysis.  Not much help on a 2-CPU computer as\r
garbage collection seems to peg the 2nd CPU already. :( Gotta wait for\r
a 4 CPU box ;)\r
\r
* switched from #src to // $ANTLR src directive.\r
\r
* CommonTokenStream.getTokens() looked past end of buffer sometimes. fixed.\r
\r
* unicode literals didn't really work in DOT output and generated code. fixed.\r
\r
* fixed the unit test rig so it compiles nicely with Java 1.5\r
\r
* Added ant build.xml file (reads build.properties file)\r
\r
* predicates sometimes failed to compile/eval properly due to missing (...)\r
  in IF expressions.  Forced (..)\r
\r
* (...)? with only one alt were not optimized.  Was:\r
\r
        // t.g:4:7: ( B )?\r
        int alt1=2;\r
        int LA1_0 = input.LA(1);\r
        if ( LA1_0==B ) {\r
            alt1=1;\r
        }\r
        else if ( LA1_0==-1 ) {\r
            alt1=2;\r
        }\r
        else {\r
            NoViableAltException nvae =\r
                new NoViableAltException("4:7: ( B )?", 1, 0, input);\r
            throw nvae;\r
        }\r
\r
is now:\r
\r
        // t.g:4:7: ( B )?\r
        int alt1=2;\r
        int LA1_0 = input.LA(1);\r
        if ( LA1_0==B ) {\r
            alt1=1;\r
        }\r
\r
  Smaller, faster and more readable.\r
\r
* Allow manual init of return values now:\r
  functionHeader returns [int x=3*4, char (*f)()=null] : ... ;\r
\r
* Added optimization for DFAs that fixed a codegen bug with rules in lexer:\r
   EQ                    : '=' ;\r
   ASSIGNOP              : '=' | '+=' ;\r
  EQ is a subset of other rule.  It did not given an error which is\r
  correct, but generated bad code.\r
\r
* ANTLR was sending column not char position to ANTLRWorks.\r
\r
* Bug fix: location 0, 0 emitted for synpreds and empty alts.\r
\r
* debugging event handshake how sends grammar file name.  Added getGrammarFileName() to recognizers.  Java.stg generates it:\r
\r
    public String getGrammarFileName() { return "<fileName>"; }\r
\r
* tree parsers can do arbitrary lookahead now including backtracking.  I\r
  updated CommonTreeNodeStream.\r
\r
* added events for debugging tree parsers:\r
\r
        /** Input for a tree parser is an AST, but we know nothing for sure\r
         *  about a node except its type and text (obtained from the adaptor).\r
         *  This is the analog of the consumeToken method.  Again, the ID is\r
         *  the hashCode usually of the node so it only works if hashCode is\r
         *  not implemented.\r
         */\r
        public void consumeNode(int ID, String text, int type);\r
\r
        /** The tree parser looked ahead */\r
        public void LT(int i, int ID, String text, int type);\r
\r
        /** The tree parser has popped back up from the child list to the\r
         *  root node.\r
         */\r
        public void goUp();\r
\r
        /** The tree parser has descended to the first child of a the current\r
         *  root node.\r
         */\r
        public void goDown();\r
\r
* Added DebugTreeNodeStream and DebugTreeParser classes\r
\r
* Added ctor because the debug tree node stream will need to ask quesitons about nodes and since  nodes are just Object, it needs an adaptor to decode the nodes and get text/type info for the debugger.\r
\r
public CommonTreeNodeStream(TreeAdaptor adaptor, Tree tree);\r
\r
* added getter to TreeNodeStream:\r
        public TreeAdaptor getTreeAdaptor();\r
\r
* Implemented getText/getType in CommonTreeAdaptor.\r
\r
* Added TraceDebugEventListener that can dump all events to stdout.\r
\r
* I broke down and make Tree implement getText\r
\r
* tree rewrites now gen location debug events.\r
\r
* added AST debug events to listener; added blank listener for convenience\r
\r
* updated debug events to send begin/end backtrack events for debugging\r
\r
* with a : (b->b) ('+' b -> ^(PLUS $a b))* ; you get b[0] each time as\r
  there is no loop in rewrite rule itself.  Need to know context that\r
  the -> is inside the rule and hence b means last value of b not all\r
  values.\r
\r
* Bug in TokenRewriteStream; ops at indexes < start index blocked proper op.\r
\r
* Actions in ST rewrites "-> ({$op})()" were not translated\r
\r
* Added new action name:\r
\r
@rulecatch {\r
catch (RecognitionException re) {\r
    reportError(re);\r
    recover(input,re);\r
}\r
catch (Throwable t) {\r
    System.err.println(t);\r
}\r
}\r
Overrides rule catch stuff.\r
\r
* Isolated $ refs caused exception\r
\r
3.0ea8 - March 11, 2006\r
\r
* added @finally {...} action like @init for rules.  Executes in\r
  finally block (java target) after all other stuff like rule memoization.\r
  No code changes needs; ST just refs a new action:\r
      <ruleDescriptor.actions.finally>\r
\r
* hideous bug fixed: PLUS='+' didn't result in '+' rule in lexer\r
\r
* TokenRewriteStream didn't do toString() right when no rewrites had been done.\r
\r
* lexer errors in interpreter were not printed properly\r
\r
* bitsets are dumped in hex not decimal now for FOLLOW sets\r
\r
* /* epsilon */ is not printed now when printing out grammars with empty alts\r
\r
* Fixed another bug in tree rewrite stuff where it was checking that elements\r
  had at least one element.  Strange...commented out for now to see if I can remember what's up.\r
\r
* Tree rewrites had problems when you didn't have x+=FOO variables.  Rules\r
  like this work now:\r
\r
  a : (x=ID)? y=ID -> ($x $y)?;\r
\r
* filter=true for lexers turns on k=1 and backtracking for every token\r
  alternative.  Put the rules in priority order.\r
\r
* added getLine() etc... to Tree to support better error reporting for\r
  trees.  Added MismatchedTreeNodeException.\r
\r
* $templates::foo() is gone.  added % as special template symbol.\r
  %foo(a={},b={},...) ctor (even shorter than $templates::foo(...))\r
  %({name-expr})(a={},...) indirect template ctor reference\r
\r
  The above are parsed by antlr.g and translated by codegen.g\r
  The following are parsed manually here:\r
\r
  %{string-expr} anonymous template from string expr\r
  %{expr}.y = z; template attribute y of StringTemplate-typed expr to z\r
  %x.y = z; set template attribute y of x (always set never get attr)\r
            to z [languages like python without ';' must still use the\r
            ';' which the code generator is free to remove during code gen]\r
\r
* -> ({expr})(a={},...) notation for indirect template rewrite.\r
  expr is the name of the template.\r
\r
* $x[i]::y and $x[-i]::y notation for accesssing absolute scope stack\r
  indexes and relative negative scopes.  $x[-1]::y is the y attribute\r
  of the previous scope (stack top - 1).\r
\r
* filter=true mode for lexers; can do this now...upon mismatch, just\r
  consumes a char and tries again:\r
lexer grammar FuzzyJava;\r
options {filter=true;}\r
\r
FIELD\r
    :   TYPE WS? name=ID WS? (';'|'=')\r
        {System.out.println("found var "+$name.text);}\r
    ;\r
\r
* refactored char streams so ANTLRFileStream is now a subclass of\r
  ANTLRStringStream.\r
\r
* char streams for lexer now allowed nested backtracking in lexer.\r
\r
* added TokenLabelType for lexer/parser for all token labels\r
\r
* line numbers for error messages were not updated properly in antlr.g\r
  for strings, char literals and <<...>>\r
\r
* init action in lexer rules was before the type,start,line,... decls.\r
\r
* Tree grammars can now specify output; I've only tested output=templat\r
  though.\r
\r
* You can reference EOF now in the parser and lexer.  It's just token type\r
  or char value -1.\r
\r
* Bug fix: $ID refs in the *lexer* were all messed up.  Cleaned up the\r
  set of properties available...\r
\r
* Bug fix: .st not found in rule ref when rule has scope:\r
field\r
scope {\r
        StringTemplate funcDef;\r
}\r
    :   ...\r
        {$field::funcDef = $field.st;}\r
    ;\r
it gets field_stack.st instead\r
\r
* return in backtracking must return retval or null if return value.\r
\r
* $property within a rule now works like $text, $st, ...\r
\r
* AST/Template Rewrites were not gated by backtracking==0 so they\r
  executed even when guessing.  Auto AST construction is now gated also.\r
\r
* CommonTokenStream was somehow returning tokens not text in toString()\r
\r
* added useful methods to runtime.BitSet and also to CommonToken so you can\r
  update the text.  Added nice Token stream method:\r
\r
  /** Given a start and stop index, return a List of all tokens in\r
   *  the token type BitSet.  Return null if no tokens were found.  This\r
   *  method looks at both on and off channel tokens.\r
   */\r
  public List getTokens(int start, int stop, BitSet types);\r
\r
* literals are now passed in the .tokens files so you can ref them in\r
  tree parses, for example.\r
\r
* added basic exception handling; no labels, just general catches:\r
\r
a : {;}A | B ;\r
        exception\r
                catch[RecognitionException re] {\r
                        System.out.println("recog error");\r
                }\r
                catch[Exception e] {\r
                        System.out.println("error");\r
                }\r
\r
* Added method to TokenStream:\r
  public String toString(Token start, Token stop);\r
\r
* antlr generates #src lines in lexer grammars generated from combined grammars\r
  so error messages refer to original file.\r
\r
* lexers generated from combined grammars now use originally formatting.\r
\r
* predicates have $x.y stuff translated now.  Warning: predicates might be\r
  hoisted out of context.\r
\r
* return values in return val structs are now public.\r
\r
* output=template with return values on rules was broken.  I assume return values with ASTs was broken too.  Fixed.\r
\r
3.0ea7 - December 14, 2005\r
\r
* Added -print option to print out grammar w/o actions\r
\r
* Renamed BaseParser to be BaseRecognizer and even made Lexer derive from\r
  this; nice as it now shares backtracking support code.\r
\r
* Added syntactic predicates (...)=>.  See December 4, 2005 entry:\r
\r
  http://www.antlr.org/blog/antlr3/lookahead.tml\r
\r
  Note that we have a new option for turning off rule memoization during\r
  backtracking:\r
\r
  -nomemo        when backtracking don't generate memoization code\r
\r
* Predicates are now tested in order that you specify the alts.  If you\r
  leave the last alt "naked" (w/o pred), it will assume a true pred rather\r
  than union of other preds.\r
\r
* Added gated predicates "{p}?=>" that literally turn off a production whereas\r
disambiguating predicates are only hoisted into the predictor when syntax alone\r
is not sufficient to uniquely predict alternatives.\r
\r
A : {p}?  => "a" ;\r
B : {!p}? => ("a"|"b")+ ;\r
\r
* bug fixed related to predicates in predictor\r
lexer grammar w;\r
A : {p}? "a" ;\r
B : {!p}? ("a"|"b")+ ;\r
DFA is correct.  A state splits for input "a" on the pred.\r
Generated code though was hosed.  No pred tests in prediction code!\r
I added testLexerPreds() and others in TestSemanticPredicateEvaluation.java\r
\r
* added execAction template in case we want to do something in front of\r
  each action execution or something.\r
\r
* left-recursive cycles from rules w/o decisions were not detected.\r
\r
* undefined lexer rules were not announced! fixed.\r
\r
* unreachable messages for Tokens rule now indicate rule name not alt. E.g.,\r
\r
  Ruby.lexer.g:24:1: The following token definitions are unreachable: IVAR\r
\r
* nondeterminism warnings improved for Tokens rule:\r
\r
Ruby.lexer.g:10:1: Multiple token rules can match input such as ""0".."9"": INT, FLOAT\r
As a result, tokens(s) FLOAT were disabled for that input\r
\r
\r
* DOT diagrams didn't show escaped char properly.\r
\r
* Char/string literals are now all 'abc' not "abc".\r
\r
* action syntax changed "@scope::actionname {action}" where scope defaults\r
  to "parser" if parser grammar or combined grammar, "lexer" if lexer grammar,\r
  and "treeparser" if tree grammar.  The code generation targets decide\r
  what scopes are available.  Each "scope" yields a hashtable for use in\r
  the output templates.  The scopes full of actions are sent to all output\r
  file templates (currently headerFile and outputFile) as attribute actions.\r
  Then you can reference <actions.scope> to get the map of actions associated\r
  with scope and <actions.parser.header> to get the parser's header action\r
  for example.  This should be very flexible.  The target should only have\r
  to define which scopes are valid, but the action names should be variable\r
  so we don't have to recompile ANTLR to add actions to code gen templates.\r
\r
  grammar T;\r
  options {language=Java;}\r
  @header { package foo; }\r
  @parser::stuff { int i; } // names within scope not checked; target dependent\r
  @members { int i; }\r
  @lexer::header {head}\r
  @lexer::members { int j; }\r
  @headerfile::blort {...} // error: this target doesn't have headerfile\r
  @treeparser::members {...} // error: this is not a tree parser\r
  a\r
  @init {int i;}\r
    : ID\r
    ;\r
  ID : 'a'..'z';\r
\r
  For now, the Java target uses members and header as a valid name.  Within a\r
  rule, the init action name is valid.\r
\r
* changed $dynamicscope.value to $dynamicscope::value even if value is defined\r
  in same rule such as $function::name where rule function defines name.\r
\r
* $dynamicscope gets you the stack\r
\r
* rule scopes go like this now:\r
\r
  rule\r
  scope {...}\r
  scope slist,Symbols;\r
        : ...\r
        ;\r
\r
* Created RuleReturnScope as a generic rule return value.  Makes it easier\r
  to do this:\r
    RuleReturnScope r = parser.program();\r
    System.out.println(r.getTemplate().toString());\r
\r
* $template, $tree, $start, etc...\r
\r
* $r.x in current rule.  $r is ignored as fully-qualified name. $r.start works too\r
\r
* added warning about $r referring to both return value of rule and dynamic scope of rule\r
\r
* integrated StringTemplate in a very simple manner\r
\r
Syntax:\r
-> template(arglist) "..."\r
-> template(arglist) <<...>>\r
-> namedTemplate(arglist)\r
-> {free expression}\r
-> // empty\r
\r
Predicate syntax:\r
a : A B -> {p1}? foo(a={$A.text})\r
        -> {p2}? foo(a={$B.text})\r
        -> // return nothing\r
\r
An arg list is just a list of template attribute assignments to actions in curlies.\r
\r
There is a setTemplateLib() method for you to use with named template rewrites.\r
\r
Use a new option:\r
\r
grammar t;\r
options {output=template;}\r
...\r
\r
This all should work for tree grammars too, but I'm still testing.\r
\r
* fixed bugs where strings were improperly escaped in exceptions, comments, etc..  For example, newlines came out as newlines not the escaped version\r
\r
3.0ea6 - November 13, 2005\r
\r
* turned off -debug/-profile, which was on by default\r
\r
* completely refactored the output templates; added some missing templates.\r
\r
* dramatically improved infinite recursion error messages (actually\r
  left-recursion never even was printed out before).\r
\r
* wasn't printing dangling state messages when it reanalyzes with k=1.\r
\r
* fixed a nasty bug in the analysis engine dealing with infinite recursion.\r
  Spent all day thinking about it and cleaned up the code dramatically.\r
  Bug fixed and software is more powerful and I understand it better! :)\r
\r
* improved verbose DFA nodes; organized by alt\r
\r
* got much better random phrase generation.  For example:\r
\r
 $ java org.antlr.tool.RandomPhrase simple.g program\r
 int Ktcdn ';' method wh '(' ')' '{' return 5 ';' '}'\r
\r
* empty rules like "a : ;" generated code that didn't compile due to\r
  try/catch for RecognitionException.  Generated code couldn't possibly\r
  throw that exception.\r
\r
* when printing out a grammar, such as in comments in generated code,\r
  ANTLR didn't print ast suffix stuff back out for literals.\r
\r
* This never exited loop:\r
  DATA : (options {greedy=false;}: .* '\n' )* '\n' '.' ;\r
  and now it works due to new default nongreedy .*  Also this works:\r
  DATA : (options {greedy=false;}: .* '\n' )* '.' ;\r
\r
* Dot star ".*" syntax didn't work; in lexer it is nongreedy by\r
  default.  In parser it is on greedy but also k=1 by default.  Added\r
  unit tests.  Added blog entry to describe.\r
\r
* ~T where T is the only token yielded an empty set but no error\r
\r
* Used to generate unreachable message here:\r
\r
  parser grammar t;\r
  a : ID a\r
    | ID\r
    ;\r
\r
  z.g:3:11: The following alternatives are unreachable: 2\r
\r
  In fact it should really be an error; now it generates:\r
\r
  no start rule in grammar t (no rule can obviously be followed by EOF)\r
\r
  Per next change item, ANTLR cannot know that EOF follows rule 'a'.\r
\r
* added error message indicating that ANTLR can't figure out what your\r
  start rule is.  Required to properly generate code in some cases.\r
\r
* validating semantic predicates now work (if they are false, they\r
  throw a new FailedPredicateException\r
\r
* two hideous bug fixes in the IntervalSet, which made analysis go wrong\r
  in a few cases.  Thanks to Oliver Zeigermann for finding lots of bugs\r
  and making suggested fixes (including the next two items)!\r
\r
* cyclic DFAs are now nonstatic and hence can access instance variables\r
\r
* labels are now allowed on lexical elements (in the lexer)\r
\r
* added some internal debugging options\r
\r
* ~'a'* and ~('a')* were not working properly; refactored antlr.g grammar\r
\r
3.0ea5 - July 5, 2005\r
\r
* Using '\n' in a parser grammar resulted in a nonescaped version of '\n' in the token names table making compilation fail.  I fixed this by reorganizing/cleaning up portion of ANTLR that deals with literals.  See comment org.antlr.codegen.Target.\r
\r
* Target.getMaxCharValue() did not use the appropriate max value constant.\r
\r
* ALLCHAR was a constant when it should use the Target max value def.  set complement for wildcard also didn't use the Target def.  Generally cleaned up the max char value stuff.\r
\r
* Code gen didn't deal with ASTLabelType properly...I think even the 3.0ea7 example tree parser was broken! :(\r
\r
* Added a few more unit tests dealing with escaped literals\r
\r
3.0ea4 - June 29, 2005\r
\r
* tree parsers work; added CommonTreeNodeStream.  See simplecTreeParser\r
  example in examples-v3 tarball.\r
\r
* added superClass and ASTLabelType options\r
\r
* refactored Parser to have a BaseParser and added TreeParser\r
\r
* bug fix: actions being dumped in description strings; compile errors\r
  resulted\r
\r
3.0ea3 - June 23, 2005\r
\r
Enhancements\r
\r
* Automatic tree construction operators are in: ! ^ ^^\r
\r
* Tree construction rewrite rules are in\r
        -> {pred1}? rewrite1\r
        -> {pred2}? rewrite2\r
        ...\r
        -> rewriteN\r
\r
  The rewrite rules may be elements like ID, expr, $label, {node expr}\r
  and trees ^( <root> <children> ).  You have have (...)?, (...)*, (...)+\r
  subrules as well.\r
\r
  You may have rewrites in subrules not just at outer level of rule, but\r
  any -> rewrite forces auto AST construction off for that alternative\r
  of that rule.\r
\r
  To avoid cycles, copy semantics are used:\r
\r
  r : INT -> INT INT ;\r
\r
  means make two new nodes from the same INT token.\r
\r
  Repeated references to a rule element implies a copy for at least one\r
  tree:\r
\r
  a : atom -> ^(atom atom) ; // NOT CYCLE! (dup atom tree)\r
\r
* $ruleLabel.tree refers to tree created by matching the labeled element.\r
\r
* A description of the blocks/alts is generated as a comment in output code\r
\r
* A timestamp / signature is put at top of each generated code file\r
\r
3.0ea2 - June 12, 2005\r
\r
Bug fixes\r
\r
* Some error messages were missing the stackTrace parameter\r
\r
* Removed the file locking mechanism as it's not cross platform\r
\r
* Some absolute vs relative path name problems with writing output\r
  files.  Rules are now more concrete.  -o option takes precedence\r
  // -o /tmp /var/lib/t.g => /tmp/T.java\r
  // -o subdir/output /usr/lib/t.g => subdir/output/T.java\r
  // -o . /usr/lib/t.g => ./T.java\r
  // -o /tmp subdir/t.g => /tmp/subdir/t.g\r
  // If they didn't specify a -o dir so just write to location\r
  // where grammar is, absolute or relative\r
\r
* does error checking on unknown option names now\r
\r
* Using just language code not locale name for error message file.  I.e.,\r
  the default (and for any English speaking locale) is en.stg not en_US.stg\r
  anymore.\r
\r
* The error manager now asks the Tool to panic rather than simply doing\r
  a System.exit().\r
\r
* Lots of refactoring concerning grammar, rule, subrule options.  Now\r
  detects invalid options.\r
\r
3.0ea1 - June 1, 2005\r
\r
Initial early access release\r
\r