13447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein/* 23447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein [The "BSD license"] 33447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein Copyright (c) 2005-2009 Terence Parr 43447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein All rights reserved. 53447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 63447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein Redistribution and use in source and binary forms, with or without 73447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein modification, are permitted provided that the following conditions 83447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein are met: 93447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 1. Redistributions of source code must retain the above copyright 103447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein notice, this list of conditions and the following disclaimer. 113447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2. Redistributions in binary form must reproduce the above copyright 123447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein notice, this list of conditions and the following disclaimer in the 133447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein documentation and/or other materials provided with the distribution. 143447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 3. The name of the author may not be used to endorse or promote products 153447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein derived from this software without specific prior written permission. 163447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 173447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 183447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 193447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 203447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 213447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 223447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 233447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 243447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 253447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 263447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 273447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 283447a5916aa62f44de24cc441fc9987116ddff52Andrew Sappersteinpackage org.antlr.runtime.debug; 293447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 303447a5916aa62f44de24cc441fc9987116ddff52Andrew Sappersteinimport org.antlr.runtime.RecognitionException; 313447a5916aa62f44de24cc441fc9987116ddff52Andrew Sappersteinimport org.antlr.runtime.Token; 323447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 333447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein/** All debugging events that a recognizer can trigger. 343447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 353447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * I did not create a separate AST debugging interface as it would create 363447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * lots of extra classes and DebugParser has a dbg var defined, which makes 373447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * it hard to change to ASTDebugEventListener. I looked hard at this issue 383447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * and it is easier to understand as one monolithic event interface for all 393447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * possible events. Hopefully, adding ST debugging stuff won't be bad. Leave 403447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * for future. 4/26/2006. 413447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 423447a5916aa62f44de24cc441fc9987116ddff52Andrew Sappersteinpublic interface DebugEventListener { 433447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Moved to version 2 for v3.1: added grammar name to enter/exit Rule */ 443447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public static final String PROTOCOL_VERSION = "2"; 453447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 463447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** serialized version of true */ 473447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public static final int TRUE = 1; 483447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public static final int FALSE = 0; 493447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 503447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** The parser has just entered a rule. No decision has been made about 513447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * which alt is predicted. This is fired AFTER init actions have been 523447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * executed. Attributes are defined and available etc... 533447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * The grammarFileName allows composite grammars to jump around among 543447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * multiple grammar files. 553447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 563447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void enterRule(String grammarFileName, String ruleName); 573447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 583447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Because rules can have lots of alternatives, it is very useful to 593447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * know which alt you are entering. This is 1..n for n alts. 603447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 613447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void enterAlt(int alt); 623447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 633447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** This is the last thing executed before leaving a rule. It is 643447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * executed even if an exception is thrown. This is triggered after 653447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * error reporting and recovery have occurred (unless the exception is 663447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * not caught in this rule). This implies an "exitAlt" event. 673447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * The grammarFileName allows composite grammars to jump around among 683447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * multiple grammar files. 693447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 703447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void exitRule(String grammarFileName, String ruleName); 713447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 723447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Track entry into any (...) subrule other EBNF construct */ 733447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void enterSubRule(int decisionNumber); 743447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 753447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void exitSubRule(int decisionNumber); 763447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 773447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Every decision, fixed k or arbitrary, has an enter/exit event 783447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * so that a GUI can easily track what LT/consume events are 793447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * associated with prediction. You will see a single enter/exit 803447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * subrule but multiple enter/exit decision events, one for each 813447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * loop iteration. 823447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 833447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void enterDecision(int decisionNumber, boolean couldBacktrack); 843447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 853447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void exitDecision(int decisionNumber); 863447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 873447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** An input token was consumed; matched by any kind of element. 883447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * Trigger after the token was matched by things like match(), matchAny(). 893447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 903447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void consumeToken(Token t); 913447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 923447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** An off-channel input token was consumed. 933447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * Trigger after the token was matched by things like match(), matchAny(). 943447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * (unless of course the hidden token is first stuff in the input stream). 953447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 963447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void consumeHiddenToken(Token t); 973447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 983447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Somebody (anybody) looked ahead. Note that this actually gets 993447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * triggered by both LA and LT calls. The debugger will want to know 1003447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * which Token object was examined. Like consumeToken, this indicates 1013447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * what token was seen at that depth. A remote debugger cannot look 1023447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * ahead into a file it doesn't have so LT events must pass the token 1033447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * even if the info is redundant. 1043447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 1053447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void LT(int i, Token t); 1063447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 1073447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** The parser is going to look arbitrarily ahead; mark this location, 1083447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * the token stream's marker is sent in case you need it. 1093447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 1103447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void mark(int marker); 1113447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 1123447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** After an arbitrairly long lookahead as with a cyclic DFA (or with 1133447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * any backtrack), this informs the debugger that stream should be 1143447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * rewound to the position associated with marker. 1153447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 1163447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void rewind(int marker); 1173447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 1183447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Rewind to the input position of the last marker. 1193447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * Used currently only after a cyclic DFA and just 1203447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * before starting a sem/syn predicate to get the 1213447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * input position back to the start of the decision. 1223447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * Do not "pop" the marker off the state. mark(i) 1233447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * and rewind(i) should balance still. 1243447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 1253447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void rewind(); 1263447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 1273447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void beginBacktrack(int level); 1283447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 1293447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void endBacktrack(int level, boolean successful); 1303447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 1313447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** To watch a parser move through the grammar, the parser needs to 1323447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * inform the debugger what line/charPos it is passing in the grammar. 1333447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * For now, this does not know how to switch from one grammar to the 1343447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * other and back for island grammars etc... 1353447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 1363447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * This should also allow breakpoints because the debugger can stop 1373447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * the parser whenever it hits this line/pos. 1383447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 1393447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void location(int line, int pos); 1403447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 1413447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** A recognition exception occurred such as NoViableAltException. I made 1423447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * this a generic event so that I can alter the exception hierachy later 1433447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * without having to alter all the debug objects. 1443447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 1453447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * Upon error, the stack of enter rule/subrule must be properly unwound. 1463447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * If no viable alt occurs it is within an enter/exit decision, which 1473447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * also must be rewound. Even the rewind for each mark must be unwount. 1483447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * In the Java target this is pretty easy using try/finally, if a bit 1493447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * ugly in the generated code. The rewind is generated in DFA.predict() 1503447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * actually so no code needs to be generated for that. For languages 1513447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * w/o this "finally" feature (C++?), the target implementor will have 1523447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * to build an event stack or something. 1533447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 1543447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * Across a socket for remote debugging, only the RecognitionException 1553447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * data fields are transmitted. The token object or whatever that 1563447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * caused the problem was the last object referenced by LT. The 1573447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * immediately preceding LT event should hold the unexpected Token or 1583447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * char. 1593447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 1603447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * Here is a sample event trace for grammar: 1613447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 1623447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * b : C ({;}A|B) // {;} is there to prevent A|B becoming a set 1633447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * | D 1643447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * ; 1653447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 1663447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * The sequence for this rule (with no viable alt in the subrule) for 1673447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * input 'c c' (there are 3 tokens) is: 1683447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 1693447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * commence 1703447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * LT(1) 1713447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * enterRule b 1723447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * location 7 1 1733447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * enter decision 3 1743447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * LT(1) 1753447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * exit decision 3 1763447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * enterAlt1 1773447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * location 7 5 1783447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * LT(1) 1793447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * consumeToken [c/<4>,1:0] 1803447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * location 7 7 1813447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * enterSubRule 2 1823447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * enter decision 2 1833447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * LT(1) 1843447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * LT(1) 1853447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * recognitionException NoViableAltException 2 1 2 1863447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * exit decision 2 1873447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * exitSubRule 2 1883447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * beginResync 1893447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * LT(1) 1903447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * consumeToken [c/<4>,1:1] 1913447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * LT(1) 1923447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * endResync 1933447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * LT(-1) 1943447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * exitRule b 1953447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * terminate 1963447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 1973447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void recognitionException(RecognitionException e); 1983447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 1993447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Indicates the recognizer is about to consume tokens to resynchronize 2003447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * the parser. Any consume events from here until the recovered event 2013447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * are not part of the parse--they are dead tokens. 2023447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 2033447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void beginResync(); 2043447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2053447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Indicates that the recognizer has finished consuming tokens in order 2063447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * to resychronize. There may be multiple beginResync/endResync pairs 2073447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * before the recognizer comes out of errorRecovery mode (in which 2083447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * multiple errors are suppressed). This will be useful 2093447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * in a gui where you want to probably grey out tokens that are consumed 2103447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * but not matched to anything in grammar. Anything between 2113447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * a beginResync/endResync pair was tossed out by the parser. 2123447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 2133447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void endResync(); 2143447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2153447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** A semantic predicate was evaluate with this result and action text */ 2163447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void semanticPredicate(boolean result, String predicate); 2173447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2183447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Announce that parsing has begun. Not technically useful except for 2193447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * sending events over a socket. A GUI for example will launch a thread 2203447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * to connect and communicate with a remote parser. The thread will want 2213447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * to notify the GUI when a connection is made. ANTLR parsers 2223447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * trigger this upon entry to the first rule (the ruleLevel is used to 2233447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * figure this out). 2243447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 2253447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void commence(); 2263447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2273447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Parsing is over; successfully or not. Mostly useful for telling 2283447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * remote debugging listeners that it's time to quit. When the rule 2293447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * invocation level goes to zero at the end of a rule, we are done 2303447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * parsing. 2313447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 2323447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void terminate(); 2333447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2343447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2353447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein // T r e e P a r s i n g 2363447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2373447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Input for a tree parser is an AST, but we know nothing for sure 2383447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * about a node except its type and text (obtained from the adaptor). 2393447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * This is the analog of the consumeToken method. Again, the ID is 2403447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * the hashCode usually of the node so it only works if hashCode is 2413447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * not implemented. If the type is UP or DOWN, then 2423447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * the ID is not really meaningful as it's fixed--there is 2433447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * just one UP node and one DOWN navigation node. 2443447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * @param t 2453447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 2463447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void consumeNode(Object t); 2473447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2483447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** The tree parser lookedahead. If the type is UP or DOWN, 2493447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * then the ID is not really meaningful as it's fixed--there is 2503447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * just one UP node and one DOWN navigation node. 2513447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 2523447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void LT(int i, Object t); 2533447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2543447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2553447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein // A S T E v e n t s 2563447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2573447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** A nil was created (even nil nodes have a unique ID... 2583447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * they are not "null" per se). As of 4/28/2006, this 2593447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * seems to be uniquely triggered when starting a new subtree 2603447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * such as when entering a subrule in automatic mode and when 2613447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * building a tree in rewrite mode. 2623447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 2633447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * If you are receiving this event over a socket via 2643447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * RemoteDebugEventSocketListener then only t.ID is set. 2653447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 2663447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void nilNode(Object t); 2673447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2683447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Upon syntax error, recognizers bracket the error with an error node 2693447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * if they are building ASTs. 2703447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * @param t 2713447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 2723447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void errorNode(Object t); 2733447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2743447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Announce a new node built from token elements such as type etc... 2753447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 2763447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * If you are receiving this event over a socket via 2773447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * RemoteDebugEventSocketListener then only t.ID, type, text are 2783447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * set. 2793447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 2803447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void createNode(Object t); 2813447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2823447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Announce a new node built from an existing token. 2833447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 2843447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * If you are receiving this event over a socket via 2853447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * RemoteDebugEventSocketListener then only node.ID and token.tokenIndex 2863447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * are set. 2873447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 2883447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void createNode(Object node, Token token); 2893447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 2903447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Make a node the new root of an existing root. See 2913447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 2923447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * Note: the newRootID parameter is possibly different 2933447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * than the TreeAdaptor.becomeRoot() newRoot parameter. 2943447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * In our case, it will always be the result of calling 2953447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * TreeAdaptor.becomeRoot() and not root_n or whatever. 2963447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 2973447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * The listener should assume that this event occurs 2983447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * only when the current subrule (or rule) subtree is 2993447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * being reset to newRootID. 3003447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 3013447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * If you are receiving this event over a socket via 3023447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * RemoteDebugEventSocketListener then only IDs are set. 3033447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 3043447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * @see org.antlr.runtime.tree.TreeAdaptor.becomeRoot() 3053447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 3063447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void becomeRoot(Object newRoot, Object oldRoot); 3073447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 3083447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Make childID a child of rootID. 3093447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 3103447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * If you are receiving this event over a socket via 3113447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * RemoteDebugEventSocketListener then only IDs are set. 3123447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 3133447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * @see org.antlr.runtime.tree.TreeAdaptor.addChild() 3143447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 3153447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void addChild(Object root, Object child); 3163447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein 3173447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein /** Set the token start/stop token index for a subtree root or node. 3183447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * 3193447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * If you are receiving this event over a socket via 3203447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein * RemoteDebugEventSocketListener then only t.ID is set. 3213447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein */ 3223447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein public void setTokenBoundaries(Object t, int tokenStartIndex, int tokenStopIndex); 3233447a5916aa62f44de24cc441fc9987116ddff52Andrew Sapperstein} 324