ANTLRErrorStrategy.h

/* Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
 * Use of this file is governed by the BSD 3-clause license that
 * can be found in the LICENSE.txt file in the project root.
 */

#pragma once

#include "Token.h"

namespace antlr4 {

  /// <summary>
  /// The interface for defining strategies to deal with syntax errors encountered
  /// during a parse by ANTLR-generated parsers. We distinguish between three
  /// different kinds of errors:
  ///
  /// <ul>
  /// <li>The parser could not figure out which path to take in the ATN (none of
  /// the available alternatives could possibly match)</li>
  /// <li>The current input does not match what we were looking for</li>
  /// <li>A predicate evaluated to false</li>
  /// </ul>
  ///
  /// Implementations of this interface report syntax errors by calling
  /// <seealso cref="Parser#notifyErrorListeners"/>.
  /// <p/>
  /// TODO: what to do about lexers
  /// </summary>
  class ANTLR4CPP_PUBLIC ANTLRErrorStrategy {
  public:

    /// <summary>
    /// Reset the error handler state for the specified {@code recognizer}. </summary>
    /// <param name="recognizer"> the parser instance </param>
    virtual ~ANTLRErrorStrategy();

    virtual void reset(Parser *recognizer) = 0;

    /**
     * This method is called when an unexpected symbol is encountered during an
     * inline match operation, such as {@link Parser#match}. If the error
     * strategy successfully recovers from the match failure, this method
     * returns the {@link Token} instance which should be treated as the
     * successful result of the match.
     *
     * <p>This method handles the consumption of any tokens - the caller should
     * <b>not</b> call {@link Parser#consume} after a successful recovery.</p>
     *
     * <p>Note that the calling code will not report an error if this method
     * returns successfully. The error strategy implementation is responsible
     * for calling {@link Parser#notifyErrorListeners} as appropriate.</p>
     *
     * @param recognizer the parser instance
     * @throws RecognitionException if the error strategy was not able to
     * recover from the unexpected input symbol
     */
    virtual Token* recoverInline(Parser *recognizer) = 0;

    /// <summary>
    /// This method is called to recover from exception {@code e}. This method is
    /// called after <seealso cref="#reportError"/> by the default exception handler
    /// generated for a rule method.
    /// </summary>
    /// <seealso cref= #reportError
    /// </seealso>
    /// <param name="recognizer"> the parser instance </param>
    /// <param name="e"> the recognition exception to recover from </param>
    /// <exception cref="RecognitionException"> if the error strategy could not recover from
    /// the recognition exception </exception>
    virtual void recover(Parser *recognizer, std::exception_ptr e) = 0;