[antlr-interest] v3.0 debug interface

Terence Parr parrt at cs.usfca.edu
Mon Mar 21 18:26:22 PST 2005


Howdy,

I am working on the debug interface so that parsers trigger events.  
The GUI can listen for these events (initially in Java and then 
marshaled over a socket to support non-Java languages) and do cool 
displays etc...  The debugger will be able to tell the parser to 
Thread.wait() in order to implement breakpoints etc...

Anyway, I've been thinking hard about what events we need to trigger.  
Most of my thoughts are driven by the ways in which I intend to use a 
debugger.  Also I've take some ideas from David Wigg (who suggested I 
fire events for alternatives not just rules) and Scott Stanchfield (who 
did the ParseView debugger).

The code generator adds the appropriate triggers upon -debug 
command-line option.  All but the location() triggers are functioning.  
Currently, I'm going to have the GUI launch the parser with a 
TokenStream but later your apps will be able to create an instance of 
the GUI and pass it to the parser as the debug event listener. :)   By 
default, the parser compiles but doesn't emit any debug output; I'll 
probably change that so it mimics the -traceParser 2.x feature.

BTW, I've kept this interface as small as possible.  Some of the 
functionality I want in the debugger is not obviously possible from 
this interface, but in fact with a little work the debugger will be 
able to do amazing things!

So, here it is so far...I'm happy to receive feedback.  I expect that 
this will change a lot as Jean builds the GUI on top.

Ter
-------------------------------
package org.antlr.runtime;

public interface ANTLRDebugInterface {
	/** 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...
	 */
	public void enterRule(String ruleName);

	/** 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.
	 */
	public void enterAlt(int alt);

	/** 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.  This implies an
	 *  "exitAlt" event.
	 */
	public void exitRule(String ruleName);

	/** Track entry into any (...) subrule other EBNF construct */
	public void enterSubRule();

	public void exitSubRule();

	/** An input token was consumed; matched by any kind of element.
	 *  Trigger after the token was matched by things like match(), 
matchAny().
	 */
	public void consumeToken(Token t);

	/** 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.
	 */
	public void location(int line, int pos);

	/** 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.
	 */
	public void recognitionException(RecognitionException e);

	/** Indicates that the parser was in an error state and has now 
recovered
	 *  in that a token, t, was successfully matched.  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 an 
exception
	 *  and recovered() was tossed out by the parser.
	 */
	public void recovered(Token t);
}

--
CS Professor & Grad Director, University of San Francisco
Creator, ANTLR Parser Generator, http://www.antlr.org
Cofounder, http://www.jguru.com





More information about the antlr-interest mailing list