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