Package org.antlr.v4.runtime

Interface ANTLRErrorStrategy

All Known Implementing Classes:

BailErrorStrategy, DefaultErrorStrategy, GrammarParserInterpreter.BailButConsumeErrorStrategy

public interface ANTLRErrorStrategy

The interface for defining strategies to deal with syntax errors encountered during a parse by ANTLR-generated parsers. We distinguish between three different kinds of errors:

• The parser could not figure out which path to take in the ATN (none of the available alternatives could possibly match)
• The current input does not match what we were looking for
• A predicate evaluated to false

Implementations of this interface report syntax errors by calling Parser.notifyErrorListeners(java.lang.String).

TODO: what to do about lexers

Method Summary

Modifier and Type	Method	Description
boolean	inErrorRecoveryMode(Parser recognizer)	Tests whether or not recognizer is in the process of recovering from an error.
default boolean	isReportMatchRequired()	Whether a successful match must call reportMatch(org.antlr.v4.runtime.Parser) and consult inErrorRecoveryMode(org.antlr.v4.runtime.Parser) instead of Parser's cached recovery flag.
default boolean	isSyncRequired()	Whether generated parsers must invoke sync(org.antlr.v4.runtime.Parser) at decision and loop sites.
void	recover(Parser recognizer, RecognitionException e)	This method is called to recover from exception e.
Token	recoverInline(Parser recognizer)	This method is called when an unexpected symbol is encountered during an inline match operation, such as Parser.match(int).
void	reportError(Parser recognizer, RecognitionException e)	Report any kind of RecognitionException.
void	reportMatch(Parser recognizer)	This method is called when the parser successfully matches an input symbol, unless isReportMatchRequired() is false and the parser is not already recovering.
void	reset(Parser recognizer)	Reset the error handler state for the specified recognizer.
void	sync(Parser recognizer)	This method provides the error handler with an opportunity to handle syntactic or semantic errors in the input stream before they result in a RecognitionException.

Method Details

reset

void reset(@NotNull
 Parser recognizer)

Reset the error handler state for the specified recognizer.

Parameters:

recognizer - the parser instance

recoverInline

@NotNull
Token recoverInline(@NotNull
 Parser recognizer)
             throws RecognitionException

This method is called when an unexpected symbol is encountered during an inline match operation, such as Parser.match(int). If the error strategy successfully recovers from the match failure, this method returns the Token instance which should be treated as the successful result of the match.

This method handles the consumption of any tokens - the caller should not call Parser.consume() after a successful recovery.

Note that the calling code will not report an error if this method returns successfully. The error strategy implementation is responsible for calling Parser.notifyErrorListeners(java.lang.String) as appropriate.

Parameters:

recognizer - the parser instance

Throws:

RecognitionException - if the error strategy was not able to recover from the unexpected input symbol

recover

void recover(@NotNull
 Parser recognizer,
 @NotNull
 RecognitionException e)
      throws RecognitionException

This method is called to recover from exception e. This method is called after reportError(org.antlr.v4.runtime.Parser, org.antlr.v4.runtime.RecognitionException) by the default exception handler generated for a rule method.

Parameters:

recognizer - the parser instance

e - the recognition exception to recover from

Throws:

RecognitionException - if the error strategy could not recover from the recognition exception

See Also:

• reportError(org.antlr.v4.runtime.Parser, org.antlr.v4.runtime.RecognitionException)

sync

void sync(@NotNull
 Parser recognizer)
   throws RecognitionException

This method provides the error handler with an opportunity to handle syntactic or semantic errors in the input stream before they result in a RecognitionException.

The generated code currently contains calls to sync(org.antlr.v4.runtime.Parser) after entering the decision state of a closure block ((...)* or (...)+).

For an implementation based on Jim Idle's "magic sync" mechanism, see DefaultErrorStrategy.sync(org.antlr.v4.runtime.Parser).

Parameters:

recognizer - the parser instance

Throws:

RecognitionException - if an error is detected by the error strategy but cannot be automatically recovered at the current state in the parsing process

See Also:

• DefaultErrorStrategy.sync(org.antlr.v4.runtime.Parser)

isSyncRequired

default boolean isSyncRequired()

Whether generated parsers must invoke sync(org.antlr.v4.runtime.Parser) at decision and loop sites. false means sync(org.antlr.v4.runtime.Parser) is a documented no-op and the generated _sync() helper may skip the virtual call.

The default is true. Strategies whose sync(org.antlr.v4.runtime.Parser) is empty (notably BailErrorStrategy) return false. A subclass that overrides sync(org.antlr.v4.runtime.Parser) to do work must also return true here.

Since:

4.13.2.14

inErrorRecoveryMode

boolean inErrorRecoveryMode(@NotNull
 Parser recognizer)

Tests whether or not recognizer is in the process of recovering from an error. In error recovery mode, Parser.consume() adds symbols to the parse tree by calling Parser.createErrorNode(ParserRuleContext, Token) then ParserRuleContext.addErrorNode(ErrorNode) instead of Parser.createTerminalNode(ParserRuleContext, Token).

Parameters:

recognizer - the parser instance

Returns:

true if the parser is currently recovering from a parse error, otherwise false

isReportMatchRequired

default boolean isReportMatchRequired()

Whether a successful match must call reportMatch(org.antlr.v4.runtime.Parser) and consult inErrorRecoveryMode(org.antlr.v4.runtime.Parser) instead of Parser's cached recovery flag. false means DefaultErrorStrategy.reportMatch(org.antlr.v4.runtime.Parser) is a no-op except while the strategy is already recovering, so generated match sites may skip the virtual call.

The default is true (a strategy that implements this interface directly keeps the historical "every match reports" contract). DefaultErrorStrategy returns false. A subclass that overrides reportMatch(org.antlr.v4.runtime.Parser) or inErrorRecoveryMode(org.antlr.v4.runtime.Parser) and needs those methods on the success path must return true here, the same way a sync(org.antlr.v4.runtime.Parser) override must return true from isSyncRequired().

Since:

4.13.2.18

reportMatch

void reportMatch(@NotNull
 Parser recognizer)

This method is called when the parser successfully matches an input symbol, unless isReportMatchRequired() is false and the parser is not already recovering.

Parameters:

recognizer - the parser instance

reportError

void reportError(@NotNull
 Parser recognizer,
 @NotNull
 RecognitionException e)

Report any kind of RecognitionException. This method is called by the default exception handler generated for a rule method.

Parameters:

recognizer - the parser instance

e - the recognition exception to report