gitweb.ps.run Git - toc/blob - antlr4-cpp-runtime-4.9.2-source/runtime/src/ANTLRErrorListener.h

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