| 1 | /*!
|
| 2 | * Copyright 2016 The ANTLR Project. All rights reserved.
|
| 3 | * Licensed under the BSD-3-Clause license. See LICENSE file in the project root for license information.
|
| 4 | */
|
| 5 | import { Parser } from "./Parser";
|
| 6 | import { Token } from "./Token";
|
| 7 | import { RecognitionException } from "./RecognitionException";
|
| 8 | /**
|
| 9 | * The interface for defining strategies to deal with syntax errors encountered
|
| 10 | * during a parse by ANTLR-generated parsers. We distinguish between three
|
| 11 | * different kinds of errors:
|
| 12 | *
|
| 13 | * * The parser could not figure out which path to take in the ATN (none of
|
| 14 | * the available alternatives could possibly match)
|
| 15 | * * The current input does not match what we were looking for
|
| 16 | * * A predicate evaluated to false
|
| 17 | *
|
| 18 | * Implementations of this interface report syntax errors by calling
|
| 19 | * {@link Parser#notifyErrorListeners}.
|
| 20 | *
|
| 21 | * TODO: what to do about lexers
|
| 22 | */
|
| 23 | export interface ANTLRErrorStrategy {
|
| 24 | /**
|
| 25 | * Reset the error handler state for the specified `recognizer`.
|
| 26 | * @param recognizer the parser instance
|
| 27 | */
|
| 28 | reset(/*@NotNull*/ recognizer: Parser): void;
|
| 29 | /**
|
| 30 | * This method is called when an unexpected symbol is encountered during an
|
| 31 | * inline match operation, such as {@link Parser#match}. If the error
|
| 32 | * strategy successfully recovers from the match failure, this method
|
| 33 | * returns the {@link Token} instance which should be treated as the
|
| 34 | * successful result of the match.
|
| 35 | *
|
| 36 | * This method handles the consumption of any tokens - the caller should
|
| 37 | * *not* call {@link Parser#consume} after a successful recovery.
|
| 38 | *
|
| 39 | * Note that the calling code will not report an error if this method
|
| 40 | * returns successfully. The error strategy implementation is responsible
|
| 41 | * for calling {@link Parser#notifyErrorListeners} as appropriate.
|
| 42 | *
|
| 43 | * @param recognizer the parser instance
|
| 44 | * @ if the error strategy was not able to
|
| 45 | * recover from the unexpected input symbol
|
| 46 | */
|
| 47 | recoverInline(/*@NotNull*/ recognizer: Parser): Token;
|
| 48 | /**
|
| 49 | * This method is called to recover from exception `e`. This method is
|
| 50 | * called after {@link #reportError} by the default exception handler
|
| 51 | * generated for a rule method.
|
| 52 | *
|
| 53 | * @see #reportError
|
| 54 | *
|
| 55 | * @param recognizer the parser instance
|
| 56 | * @param e the recognition exception to recover from
|
| 57 | * @ if the error strategy could not recover from
|
| 58 | * the recognition exception
|
| 59 | */
|
| 60 | recover(/*@NotNull*/ recognizer: Parser, /*@NotNull*/ e: RecognitionException): void;
|
| 61 | /**
|
| 62 | * This method provides the error handler with an opportunity to handle
|
| 63 | * syntactic or semantic errors in the input stream before they result in a
|
| 64 | * {@link RecognitionException}.
|
| 65 | *
|
| 66 | * The generated code currently contains calls to {@link #sync} after
|
| 67 | * entering the decision state of a closure block (`(...)*` or
|
| 68 | * `(...)+`).
|
| 69 | *
|
| 70 | * For an implementation based on Jim Idle's "magic sync" mechanism, see
|
| 71 | * {@link DefaultErrorStrategy#sync}.
|
| 72 | *
|
| 73 | * @see DefaultErrorStrategy#sync
|
| 74 | *
|
| 75 | * @param recognizer the parser instance
|
| 76 | * @ if an error is detected by the error
|
| 77 | * strategy but cannot be automatically recovered at the current state in
|
| 78 | * the parsing process
|
| 79 | */
|
| 80 | sync(/*@NotNull*/ recognizer: Parser): void;
|
| 81 | /**
|
| 82 | * Tests whether or not `recognizer` is in the process of recovering
|
| 83 | * from an error. In error recovery mode, {@link Parser#consume} adds
|
| 84 | * symbols to the parse tree by calling
|
| 85 | * {@link Parser#createErrorNode(ParserRuleContext, Token)} then
|
| 86 | * {@link ParserRuleContext#addErrorNode(ErrorNode)} instead of
|
| 87 | * {@link Parser#createTerminalNode(ParserRuleContext, Token)}.
|
| 88 | *
|
| 89 | * @param recognizer the parser instance
|
| 90 | * @returns `true` if the parser is currently recovering from a parse
|
| 91 | * error, otherwise `false`
|
| 92 | */
|
| 93 | inErrorRecoveryMode(/*@NotNull*/ recognizer: Parser): boolean;
|
| 94 | /**
|
| 95 | * This method is called by when the parser successfully matches an input
|
| 96 | * symbol.
|
| 97 | *
|
| 98 | * @param recognizer the parser instance
|
| 99 | */
|
| 100 | reportMatch(/*@NotNull*/ recognizer: Parser): void;
|
| 101 | /**
|
| 102 | * Report any kind of {@link RecognitionException}. This method is called by
|
| 103 | * the default exception handler generated for a rule method.
|
| 104 | *
|
| 105 | * @param recognizer the parser instance
|
| 106 | * @param e the recognition exception to report
|
| 107 | */
|
| 108 | reportError(recognizer: Parser, e: RecognitionException): void;
|
| 109 | }
|