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.ANTLRErrorListener; 8 9 import antlr.v4.runtime.InterfaceParser; 10 import antlr.v4.runtime.RecognitionException; 11 import antlr.v4.runtime.InterfaceRecognizer; 12 import antlr.v4.runtime.atn.ATNSimulator; 13 import antlr.v4.runtime.atn.ATNConfigSet; 14 import antlr.v4.runtime.dfa.DFA; 15 import antlr.v4.runtime.misc; 16 17 /** 18 * How to emit recognition errors. 19 */ 20 interface ANTLRErrorListener(U, V) 21 { 22 23 /** 24 * Upon syntax error, notify any interested parties. This is not how to 25 * recover from errors or compute error messages. {@link ANTLRErrorStrategy} 26 * specifies how to recover from syntax errors and how to compute error 27 * messages. This listener's job is simply to emit a computed message, 28 * though it has enough information to create its own message in many cases. 29 * 30 * <p>The {@link RecognitionException} is non-null for all syntax errors except 31 * when we discover mismatched token errors that we can recover from 32 * in-line, without returning from the surrounding rule (via the single 33 * token insertion and deletion mechanism).</p> 34 * 35 * @param recognizer 36 * What parser got the error. From this 37 * object, you can access the context as well 38 * as the input stream. 39 * @param offendingSymbol 40 * The offending token in the input token 41 * stream, unless recognizer is a lexer (then it's null). If 42 * no viable alternative error, {@code e} has token at which we 43 * started production for the decision. 44 * @param line 45 * The line number in the input where the error occurred. 46 * @param charPositionInLine 47 * The character position within that line where the error occurred. 48 * @param msg 49 * The message to emit. 50 * @param e 51 * The exception generated by the parser that led to 52 * the reporting of an error. It is null in the case where 53 * the parser was able to recover in line without exiting the 54 * surrounding rule. 55 */ 56 public void syntaxError(InterfaceRecognizer recognizer, Object offendingSymbol, int line, 57 int charPositionInLine, string msg, RecognitionException e); 58 59 /** 60 * This method is called by the parser when a full-context prediction 61 * results in an ambiguity. 62 * 63 * <p>Each full-context prediction which does not result in a syntax error 64 * will call either {@link #reportContextSensitivity} or 65 * {@link #reportAmbiguity}.</p> 66 * 67 * <p>When {@code ambigAlts} is not null, it contains the set of potentially 68 * viable alternatives identified by the prediction algorithm. When 69 * {@code ambigAlts} is null, use {@link ATNConfigSet#getAlts} to obtain the 70 * represented alternatives from the {@code configs} argument.</p> 71 * 72 * <p>When {@code exact} is {@code true}, <em>all</em> of the potentially 73 * viable alternatives are truly viable, i.e. this is reporting an exact 74 * ambiguity. When {@code exact} is {@code false}, <em>at least two</em> of 75 * the potentially viable alternatives are viable for the current input, but 76 * the prediction algorithm terminated as soon as it determined that at 77 * least the <em>minimum</em> potentially viable alternative is truly 78 * viable.</p> 79 * 80 * <p>When the {@link PredictionMode#LL_EXACT_AMBIG_DETECTION} prediction 81 * mode is used, the parser is required to identify exact ambiguities so 82 * {@code exact} will always be {@code true}.</p> 83 * 84 * <p>This method is not used by lexers.</p> 85 * 86 * @param recognizer the parser instance 87 * @param dfa the DFA for the current decision 88 * @param startIndex the input index where the decision started 89 * @param stopIndex the input input where the ambiguity was identified 90 * @param exact {@code true} if the ambiguity is exactly known, otherwise 91 * {@code false}. This is always {@code true} when 92 * {@link PredictionMode#LL_EXACT_AMBIG_DETECTION} is used. 93 * @param ambigAlts the potentially ambiguous alternatives, or {@code null} 94 * to indicate that the potentially ambiguous alternatives are the complete 95 * set of represented alternatives in {@code configs} 96 * @param configs the ATN configuration set where the ambiguity was 97 * identified 98 */ 99 public void reportAmbiguity(InterfaceParser recognizer, DFA dfa, int startIndex, int stopIndex, 100 bool exact, BitSet ambigAlts, ATNConfigSet configs); 101 102 /** 103 * This method is called when an SLL conflict occurs and the parser is about 104 * to use the full context information to make an LL decision. 105 * 106 * <p>If one or more configurations in {@code configs} contains a semantic 107 * predicate, the predicates are evaluated before this method is called. The 108 * subset of alternatives which are still viable after predicates are 109 * evaluated is reported in {@code conflictingAlts}.</p> 110 * 111 * <p>This method is not used by lexers.</p> 112 * 113 * @param recognizer the parser instance 114 * @param dfa the DFA for the current decision 115 * @param startIndex the input index where the decision started 116 * @param stopIndex the input index where the SLL conflict occurred 117 * @param conflictingAlts The specific conflicting alternatives. If this is 118 * {@code null}, the conflicting alternatives are all alternatives 119 * represented in {@code configs}. At the moment, conflictingAlts is non-null 120 * (for the reference implementation, but Sam's optimized version can see this 121 * as null). 122 * @param configs the ATN configuration set where the SLL conflict was 123 * detected 124 */ 125 public void reportAttemptingFullContext(InterfaceParser recognizer, DFA dfa, int startIndex, int stopIndex, 126 BitSet conflictingAlts, ATNConfigSet configs); 127 128 /** 129 * This method is called by the parser when a full-context prediction has a 130 * unique result. 131 * 132 * <p>Each full-context prediction which does not result in a syntax error 133 * will call either {@link #reportContextSensitivity} or 134 * {@link #reportAmbiguity}.</p> 135 * 136 * <p>For prediction implementations that only evaluate full-context 137 * predictions when an SLL conflict is found (including the default 138 * {@link ParserATNSimulator} implementation), this method reports cases 139 * where SLL conflicts were resolved to unique full-context predictions, 140 * i.e. the decision was context-sensitive. This report does not necessarily 141 * indicate a problem, and it may appear even in completely unambiguous 142 * grammars.</p> 143 * 144 * <p>{@code configs} may have more than one represented alternative if the 145 * full-context prediction algorithm does not evaluate predicates before 146 * beginning the full-context prediction. In all cases, the final prediction 147 * is passed as the {@code prediction} argument.</p> 148 * 149 * <p>Note that the definition of "context sensitivity" in this method 150 * differs from the concept in {@link DecisionInfo#contextSensitivities}. 151 * This method reports all instances where an SLL conflict occurred but LL 152 * parsing produced a unique result, whether or not that unique result 153 * matches the minimum alternative in the SLL conflicting set.</p> 154 * 155 * <p>This method is not used by lexers.</p> 156 * 157 * @param recognizer the parser instance 158 * @param dfa the DFA for the current decision 159 * @param startIndex the input index where the decision started 160 * @param stopIndex the input index where the context sensitivity was 161 * finally determined 162 * @param prediction the unambiguous result of the full-context prediction 163 * @param configs the ATN configuration set where the unambiguous prediction 164 * was determined 165 */ 166 public void reportContextSensitivity(InterfaceParser recognizer, DFA dfa, int startIndex, int stopIndex, 167 int prediction, ATNConfigSet configs); 168 169 }