org.antlr.runtime.debug.DebugEventRepeater Class Reference

Inheritance diagram for org.antlr.runtime.debug.DebugEventRepeater:

Collaboration diagram for org.antlr.runtime.debug.DebugEventRepeater:

List of all members.

Public Member Functions

DebugEventRepeater (DebugEventListener listener)

void enterRule (String grammarFileName, String ruleName)

void exitRule (String grammarFileName, String ruleName)

void enterAlt (int alt)

void enterSubRule (int decisionNumber)

void exitSubRule (int decisionNumber)

void enterDecision (int decisionNumber)

void exitDecision (int decisionNumber)

void location (int line, int pos)

void consumeToken (Token token)

void consumeHiddenToken (Token token)

void LT (int i, Token t)

void mark (int i)

void rewind (int i)

void rewind ()

void beginBacktrack (int level)

void endBacktrack (int level, boolean successful)

void recognitionException (RecognitionException e)

void beginResync ()

void endResync ()

void semanticPredicate (boolean result, String predicate)

void commence ()

void terminate ()

void consumeNode (Object t)

void LT (int i, Object t)

void nilNode (Object t)

void errorNode (Object t)

void createNode (Object t)

void createNode (Object node, Token token)

void becomeRoot (Object newRoot, Object oldRoot)

void addChild (Object root, Object child)

void setTokenBoundaries (Object t, int tokenStartIndex, int tokenStopIndex)

Protected Attributes

DebugEventListener listener

Detailed Description

A simple event repeater (proxy) that delegates all functionality to the listener sent into the ctor. Useful if you want to listen in on a few debug events w/o interrupting the debugger. Just subclass the repeater and override the methods you want to listen in on. Remember to call the method in this class so the event will continue on to the original recipient.

See also:: DebugEventHub

Definition at line 42 of file DebugEventRepeater.java.

Constructor & Destructor Documentation

org.antlr.runtime.debug.DebugEventRepeater.DebugEventRepeater ( DebugEventListener listener )

Definition at line 45 of file DebugEventRepeater.java.

Member Function Documentation

void org.antlr.runtime.debug.DebugEventRepeater.enterRule	(	String	grammarFileName,
		String	ruleName
	)

The parser has just entered a rule. No decision has been made about which alt is predicted. This is fired AFTER init actions have been executed. Attributes are defined and available etc... The grammarFileName allows composite grammars to jump around among multiple grammar files.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 49 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.exitRule	(	String	grammarFileName,
		String	ruleName
	)

This is the last thing executed before leaving a rule. It is executed even if an exception is thrown. This is triggered after error reporting and recovery have occurred (unless the exception is not caught in this rule). This implies an "exitAlt" event. The grammarFileName allows composite grammars to jump around among multiple grammar files.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 50 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.enterAlt ( int alt )

Because rules can have lots of alternatives, it is very useful to know which alt you are entering. This is 1..n for n alts.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 51 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.enterSubRule ( int decisionNumber )

Track entry into any (...) subrule other EBNF construct

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 52 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.exitSubRule ( int decisionNumber )

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 53 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.enterDecision ( int decisionNumber )

Every decision, fixed k or arbitrary, has an enter/exit event so that a GUI can easily track what LT/consume events are associated with prediction. You will see a single enter/exit subrule but multiple enter/exit decision events, one for each loop iteration.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 54 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.exitDecision ( int decisionNumber )

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 55 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.location	(	int	line,
		int	pos
	)

To watch a parser move through the grammar, the parser needs to inform the debugger what line/charPos it is passing in the grammar. For now, this does not know how to switch from one grammar to the other and back for island grammars etc...

This should also allow breakpoints because the debugger can stop the parser whenever it hits this line/pos.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 56 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.consumeToken ( Token t )

An input token was consumed; matched by any kind of element. Trigger after the token was matched by things like match(), matchAny().

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 57 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.consumeHiddenToken ( Token t )

An off-channel input token was consumed. Trigger after the token was matched by things like match(), matchAny(). (unless of course the hidden token is first stuff in the input stream).

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 58 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.LT	(	int	i,
		Token	t
	)

Somebody (anybody) looked ahead. Note that this actually gets triggered by both LA and LT calls. The debugger will want to know which Token object was examined. Like consumeToken, this indicates what token was seen at that depth. A remote debugger cannot look ahead into a file it doesn't have so LT events must pass the token even if the info is redundant.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 59 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.mark ( int marker )

The parser is going to look arbitrarily ahead; mark this location, the token stream's marker is sent in case you need it.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 60 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.rewind ( int marker )

After an arbitrairly long lookahead as with a cyclic DFA (or with any backtrack), this informs the debugger that stream should be rewound to the position associated with marker.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 61 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.rewind ( )

Rewind to the input position of the last marker. Used currently only after a cyclic DFA and just before starting a sem/syn predicate to get the input position back to the start of the decision. Do not "pop" the marker off the state. mark(i) and rewind(i) should balance still.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 62 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.beginBacktrack ( int level )

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 63 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.endBacktrack	(	int	level,
		boolean	successful
	)

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 64 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.recognitionException ( RecognitionException e )

A recognition exception occurred such as NoViableAltException. I made this a generic event so that I can alter the exception hierachy later without having to alter all the debug objects.

Upon error, the stack of enter rule/subrule must be properly unwound. If no viable alt occurs it is within an enter/exit decision, which also must be rewound. Even the rewind for each mark must be unwount. In the Java target this is pretty easy using try/finally, if a bit ugly in the generated code. The rewind is generated in DFA.predict() actually so no code needs to be generated for that. For languages w/o this "finally" feature (C++?), the target implementor will have to build an event stack or something.

Across a socket for remote debugging, only the RecognitionException data fields are transmitted. The token object or whatever that caused the problem was the last object referenced by LT. The immediately preceding LT event should hold the unexpected Token or char.

Here is a sample event trace for grammar:

b : C ({;}A|B) // {;} is there to prevent A|B becoming a set | D ;

The sequence for this rule (with no viable alt in the subrule) for input 'c c' (there are 3 tokens) is:

commence LT(1) enterRule b location 7 1 enter decision 3 LT(1) exit decision 3 enterAlt1 location 7 5 LT(1) consumeToken [c/<4>,1:0] location 7 7 enterSubRule 2 enter decision 2 LT(1) LT(1) recognitionException NoViableAltException 2 1 2 exit decision 2 exitSubRule 2 beginResync LT(1) consumeToken [c/<4>,1:1] LT(1) endResync LT(-1) exitRule b terminate

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 65 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.beginResync ( )

Indicates the recognizer is about to consume tokens to resynchronize the parser. Any consume events from here until the recovered event are not part of the parse--they are dead tokens.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 66 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.endResync ( )

Indicates that the recognizer has finished consuming tokens in order to resychronize. There may be multiple beginResync/endResync pairs before the recognizer comes out of errorRecovery mode (in which multiple errors are suppressed). This will be useful in a gui where you want to probably grey out tokens that are consumed but not matched to anything in grammar. Anything between a beginResync/endResync pair was tossed out by the parser.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 67 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.semanticPredicate	(	boolean	result,
		String	predicate
	)

A semantic predicate was evaluate with this result and action text

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 68 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.commence ( )

Announce that parsing has begun. Not technically useful except for sending events over a socket. A GUI for example will launch a thread to connect and communicate with a remote parser. The thread will want to notify the GUI when a connection is made. ANTLR parsers trigger this upon entry to the first rule (the ruleLevel is used to figure this out).

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 69 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.terminate ( )

Parsing is over; successfully or not. Mostly useful for telling remote debugging listeners that it's time to quit. When the rule invocation level goes to zero at the end of a rule, we are done parsing.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 70 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.consumeNode ( Object t )

Input for a tree parser is an AST, but we know nothing for sure about a node except its type and text (obtained from the adaptor). This is the analog of the consumeToken method. Again, the ID is the hashCode usually of the node so it only works if hashCode is not implemented. If the type is UP or DOWN, then the ID is not really meaningful as it's fixed--there is just one UP node and one DOWN navigation node.

Parameters:

t

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 74 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.LT	(	int	i,
		Object	t
	)

The tree parser lookedahead. If the type is UP or DOWN, then the ID is not really meaningful as it's fixed--there is just one UP node and one DOWN navigation node.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 75 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.nilNode ( Object t )

A nil was created (even nil nodes have a unique ID... they are not "null" per se). As of 4/28/2006, this seems to be uniquely triggered when starting a new subtree such as when entering a subrule in automatic mode and when building a tree in rewrite mode.

If you are receiving this event over a socket via RemoteDebugEventSocketListener then only t.ID is set.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 79 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.errorNode ( Object t )

Upon syntax error, recognizers bracket the error with an error node if they are building ASTs.

Parameters:

t

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 80 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.createNode ( Object t )

Announce a new node built from token elements such as type etc...

If you are receiving this event over a socket via RemoteDebugEventSocketListener then only t.ID, type, text are set.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 81 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.createNode	(	Object	node,
		Token	token
	)

Announce a new node built from an existing token.

If you are receiving this event over a socket via RemoteDebugEventSocketListener then only node.ID and token.tokenIndex are set.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 82 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.becomeRoot	(	Object	newRoot,
		Object	oldRoot
	)

Make a node the new root of an existing root. See

Note: the newRootID parameter is possibly different than the TreeAdaptor.becomeRoot() newRoot parameter. In our case, it will always be the result of calling TreeAdaptor.becomeRoot() and not root_n or whatever.

The listener should assume that this event occurs only when the current subrule (or rule) subtree is being reset to newRootID.

If you are receiving this event over a socket via RemoteDebugEventSocketListener then only IDs are set.

See also:: org.antlr.runtime.tree.TreeAdaptor.becomeRoot()

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 83 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.addChild	(	Object	root,
		Object	child
	)

Make childID a child of rootID.

If you are receiving this event over a socket via RemoteDebugEventSocketListener then only IDs are set.

See also:: org.antlr.runtime.tree.TreeAdaptor.addChild()

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 84 of file DebugEventRepeater.java.

void org.antlr.runtime.debug.DebugEventRepeater.setTokenBoundaries	(	Object	t,
		int	tokenStartIndex,
		int	tokenStopIndex
	)

Set the token start/stop token index for a subtree root or node.

If you are receiving this event over a socket via RemoteDebugEventSocketListener then only t.ID is set.

Implements org.antlr.runtime.debug.DebugEventListener.

Definition at line 85 of file DebugEventRepeater.java.

Member Data Documentation

DebugEventListener org.antlr.runtime.debug.DebugEventRepeater.listener [protected]

Definition at line 43 of file DebugEventRepeater.java.

The documentation for this class was generated from the following file:

/Users/parrt/antlr/code/antlr/main/runtime/Java/src/org/antlr/runtime/debug/DebugEventRepeater.java


Public Member Functions
	DebugEventRepeater (DebugEventListener listener)
void	enterRule (String grammarFileName, String ruleName)
void	exitRule (String grammarFileName, String ruleName)
void	enterAlt (int alt)
void	enterSubRule (int decisionNumber)
void	exitSubRule (int decisionNumber)
void	enterDecision (int decisionNumber)
void	exitDecision (int decisionNumber)
void	location (int line, int pos)
void	consumeToken (Token token)
void	consumeHiddenToken (Token token)
void	LT (int i, Token t)
void	mark (int i)
void	rewind (int i)
void	rewind ()
void	beginBacktrack (int level)
void	endBacktrack (int level, boolean successful)
void	recognitionException (RecognitionException e)
void	beginResync ()
void	endResync ()
void	semanticPredicate (boolean result, String predicate)
void	commence ()
void	terminate ()
void	consumeNode (Object t)
void	LT (int i, Object t)
void	nilNode (Object t)
void	errorNode (Object t)
void	createNode (Object t)
void	createNode (Object node, Token token)
void	becomeRoot (Object newRoot, Object oldRoot)
void	addChild (Object root, Object child)
void	setTokenBoundaries (Object t, int tokenStartIndex, int tokenStopIndex)
Protected Attributes
DebugEventListener	listener