1<?php
2
3declare(strict_types=1);
4
5namespace Antlr\Antlr4\Runtime;
6
7/**
8 * A source of tokens must provide a sequence of tokens via {@see TokenSource::nextToken()}
9 * and also must reveal it's source of characters; {@see CommonToken}'s text
10 * is computed from a {@see CharStream}; it only store indices into
11 * the char stream.
12 *
13 * Errors from the lexer are never passed to the parser. Either you want to keep
14 * going or you do not upon token recognition error. If you do not want
15 * to continue lexing then you do not want to continue parsing. Just throw
16 * an exception not under {@see RecognitionException} and PHP will naturally
17 * toss you all the way out of the recognizers. If you want to continue lexing
18 * then you should not throw an exception to the parser--it has already requested
19 * a token. Keep lexing until you get a valid one. Just report errors and
20 * keep going, looking for a valid token.
21 */
22interface TokenSource
23{
24    /**
25     * Return a {@see Token} object from your input stream (usually a
26     * {@see CharStream}). Do not fail/return upon lexing error; keep chewing
27     * on the characters until you get a good one; errors are not passed through
28     * to the parser.
29     */
30    public function nextToken() : ?Token;
31
32    /**
33     * Get the line number for the current position in the input stream.
34     * The first line in the input is line 1.
35     *
36     * @return int The line number for the current position in the input stream,
37     *             or 0 if the current token source does not track line numbers.
38     */
39    public function getLine() : int;
40
41    /**
42     * Get the index into the current line for the current position in
43     * the input stream. The first character on a line has position 0.
44     *
45     * @return int The line number for the current position in the input stream,
46     *             or -1 if the current token source does not track
47     *             character positions.
48     */
49    public function getCharPositionInLine() : int;
50
51    /**
52     * Get the {@see CharStream} from which this token source is currently
53     * providing tokens.
54     *
55     * @return CharStream The {@see CharStream} associated with the current
56     *                    position in the input, or `null` if no input stream
57     *                    is available for the token source.
58     */
59    public function getInputStream() : ?IntStream;
60
61    /**
62     * Gets the name of the underlying input source. This method returns
63     * a non-null, non-empty string. If such a name is not known, this method
64     * returns {@see IntStream::UNKNOWN_SOURCE_NAME}.
65     */
66    public function getSourceName() : string;
67
68    /**
69     * Set the {@see TokenFactory} this token source should use for creating
70     * {@see Token} objects from the input.
71     *
72     * @param TokenFactory $factory The {@see TokenFactory} to use
73     *                              for creating tokens.
74     */
75    public function setTokenFactory(TokenFactory $factory) : void;
76
77    /**
78     * Gets the {@see TokenFactory} this token source is currently using
79     * f objects from the input.
80     *
81     * @return TokenFactory The {@see TokenFactory} currently used
82     *                      by this token source.
83     */
84    public function getTokenFactory() : TokenFactory;
85}
86