antlr.v4.runtime.ANTLRErrorStrategy source code

1 /*
2  * Copyright (c) 2012-2018 The ANTLR Project. All rights reserved.
3  * Use of this file is governed by the BSD 3-clause license that
4  * can be found in the LICENSE.txt file in the project root.
5  */
6 
7 module antlr.v4.runtime.ANTLRErrorStrategy;
8 
9 import antlr.v4.runtime.RecognitionException;
10 import antlr.v4.runtime.Parser;
11 import antlr.v4.runtime.Token;
12 
13 /**
14  * The interface for defining strategies to deal with syntax errors encountered
15  * during a parse by ANTLR-generated parsers. We distinguish between three
16  * different kinds of errors:
17  *
18  * <ul>
19  * <li>The parser could not figure out which path to take in the ATN (none of
20  * the available alternatives could possibly match)</li>
21  *  <li>The current input does not match what we were looking for</li>
22  *  <li>A predicate evaluated to false</li>
23  *  </ul>
24  *
25  * Implementations of this interface report syntax errors by calling
26  * {@link Parser#notifyErrorListeners}.
27  *
28  * <p>TODO: what to do about lexers</p>
29  */
30 interface ANTLRErrorStrategy
31 {
32 
33     /**
34      * Reset the error handler state for the specified {@code recognizer}.
35      *  @param recognizer the parser instance
36      */
37     public void reset(Parser recognizer);
38 
39     /**
40      * This method is called when an unexpected symbol is encountered during an
41      * inline match operation, such as {@link Parser#match}. If the error
42      * strategy successfully recovers from the match failure, this method
43      * returns the {@link Token} instance which should be treated as the
44      * successful result of the match.
45      *
46      * <p>This method handles the consumption of any tokens - the caller should
47      * <b>not</b> call {@link Parser#consume} after a successful recovery.</p>
48      *
49      * <p>Note that the calling code will not report an error if this method
50      * returns successfully. The error strategy implementation is responsible
51      * for calling {@link Parser#notifyErrorListeners} as appropriate.</p>
52      *
53      *  @param recognizer the parser instance
54      *  @throws RecognitionException if the error strategy was not able to
55      * recover from the unexpected input symbol
56      */
57     public Token recoverInline(Parser recognizer);
58 
59     /**
60      * This method is called to recover from exception {@code e}. This method is
61      * called after {@link #reportError} by the default exception handler
62      * generated for a rule method.
63      *
64      *  @see #reportError
65      *
66      *  @param recognizer the parser instance
67      *  @param e the recognition exception to recover from
68      *  @throws RecognitionException if the error strategy could not recover from
69      * the recognition exception
70      */
71     public void recover(Parser recognizer, RecognitionException e);
72 
73     /**
74      * This method provides the error handler with an opportunity to handle
75      * syntactic or semantic errors in the input stream before they result in a
76      * {@link RecognitionException}.
77      *
78      * <p>The generated code currently contains calls to {@link #sync} after
79      * entering the decision state of a closure block ({@code (...)*} or
80      * {@code (...)+}).</p>
81      *
82      * <p>For an implementation based on Jim Idle's "magic sync" mechanism, see
83      * {@link DefaultErrorStrategy#sync}.</p>
84      *
85      *  @see DefaultErrorStrategy#sync
86      *
87      *  @param recognizer the parser instance
88      *  @throws RecognitionException if an error is detected by the error
89      * strategy but cannot be automatically recovered at the current state in
90      * the parsing process
91      */
92     public void sync(Parser recognizer);
93 
94     /**
95      * Tests whether or not {@code recognizer} is in the process of recovering
96      * from an error. In error recovery mode, {@link Parser#consume} adds
97      * symbols to the parse tree by calling
98      * {@link ParserRuleContext#addErrorNode(Token)} instead of
99      * {@link ParserRuleContext#addChild(Token)}.
100      *
101      *  @param recognizer the parser instance
102      *  @return {@code true} if the parser is currently recovering from a parse
103      * error, otherwise {@code false}
104      */
105     public bool inErrorRecoveryMode(Parser recognizer);
106 
107     /**
108      * This method is called by when the parser successfully matches an input
109      * symbol.
110      *
111      *  @param recognizer the parser instance
112      */
113     public void reportMatch(Parser recognizer);
114 
115     /**
116      * Report any kind of {@link RecognitionException}. This method is called by
117      * the default exception handler generated for a rule method.
118      *
119      *  @param recognizer the parser instance
120      *  @param e the recognition exception to report
121      */
122     public void reportError(Parser recognizer, RecognitionException e);
123 
124 }