1 /*
2 * Copyright (c) 2012-2020 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 moduleantlr.v4.runtime.ANTLRErrorStrategy;
8 9 importantlr.v4.runtime.RecognitionException;
10 importantlr.v4.runtime.Parser;
11 importantlr.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 interfaceANTLRErrorStrategy31 {
32 33 /**
34 * Reset the error handler state for the specified {@code recognizer}.
35 * @param recognizer the parser instance
36 */37 publicvoidreset(Parserrecognizer);
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 publicTokenrecoverInline(Parserrecognizer);
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 publicvoidrecover(Parserrecognizer, RecognitionExceptione);
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 publicvoidsync(Parserrecognizer);
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 publicboolinErrorRecoveryMode(Parserrecognizer);
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 publicvoidreportMatch(Parserrecognizer);
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 publicvoidreportError(Parserrecognizer, RecognitionExceptione);
123 124 }