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 | }
|