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