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