[antlr-interest] v3.0 debug interface

[Scott Stanchfield]

Ter's proposing a unicast observer pattern, rather than multicast (as Ter's
assuming only a single listener). I would prefer a multicast as well, as
this will make hooking up views way easier, and different people can
contribute views independently. Daisy chaining doesn't allow that.

The debugger(s) will need some sort of notification/registration mechanism.
In Eclipse, this is easy (plugin registration makes it easy, and we can
define an ANTLR launcher that looks for registered debuggers and attaches
them as listeners to a parser).

If there was a good chance that people would want to wire a debugger to
ANTLR in a JavaBean builder, I'd agree that having it follow the JavaBean
event model (using EventListener and EventObject) would be a good idea. I
don't think that's likely, so I'd avoid the extra event object creation, and
because of that, skip the EventListener extension.

I hadn't had a chance to chime in until now, so here's my 2c...

I'd like to be notified of:
* which parser sent the information (we could be debugging multiple parsers
at once with a single debugger...) for all methods
* predicate evaluation (and success/failure)
* whether we're guessing or not
* la(k)/lt(k) evaluation
* enterAlt needs a ruleName as well
* parsing completed successfully
* text or a token was matched
* newline was triggered
* have location indicate the file we're in
* I'd prefer to be notified of rules by number rather than name - a
debuggable parser can provide a rule-name lookup method or public static
array of rule names



These features will allow a debugger to show the user exactly what's going
on during the scan/parse by highlighting source, displaying messages, and so
forth.


Here's what I've got for ANTLR 2.7.6's parser listener. I've simplified it
significantly from previous versions. Note the lack of event objects in this
version; I felt they were a waste. Still an observer pattern.

public interface ParserListener {
	public static final int TOKEN=0;
	public static final int BITSET=1;
	public static final int CHAR=2;
	public static final int CHAR_BITSET=3;
	public static final int STRING=4;
	public static final int CHAR_RANGE=5;
	public static final int VALIDATING=6;
	public static final int PREDICTING=7;

	public void semanticPredicateEvaluated(DebuggingParser parser,
boolean validating, int condition, boolean result, int guessing);
	public void parserMatch(DebuggingParser parser, int type, int value,
Object targetValue, String text, int guessing, boolean inverse, boolean
matched);
	public void parserMatch(DebuggingParser parser, int type, String
value, Object targetValue, String text, int guessing, boolean inverse,
boolean matched);
	public void reportError(DebuggingParser parser, Throwable
throwable);
	public void reportError(DebuggingParser parser, String text);
	public void reportWarning(DebuggingParser parser, String text);
	public void parserConsume(DebuggingParser parser, int value, int
guessing);
	public void parserLA(DebuggingParser parser, int amount, int value);
	public void parserLT(DebuggingParser parser, int amount, Token
value);
	public void enterRule(DebuggingParser parser, int ruleNum, int
guessing, int data);
	public void exitRule(DebuggingParser parser, int ruleNum, int
guessing, int data);
	public void syntacticPredicateStarted(DebuggingParser parser, int
guessing);
	public void syntacticPredicateFinished(DebuggingParser parser, int
guessing, boolean succeeded);
	public void doneParsing(DebuggingParser parser);

	public void hitNewLine(DebuggingParser parser, int line);
}	


I've also got an input buffer listener so we can display that:

public interface InputBufferListener {
	public void inputBufferConsume(InputBuffer inputBuffer, char c);
	public void inputBufferLA(InputBuffer inputBuffer, char c, int
lookaheadAmount);
	public void inputBufferMark(InputBuffer inputBuffer, int position);
	public void inputBufferRewind(InputBuffer inputBuffer, int
position);
	public void doneParsing(InputBuffer inputBuffer);
}


Later,
-- Scott