1<?php
2
3declare(strict_types=1);
4
5namespace Antlr\Antlr4\Runtime;
6
7/**
8 * An {@see IntStream} whose symbols are {@see Token} instances.
9 */
10interface TokenStream extends IntStream
11{
12    /**
13     * Get the {@see Token} instance associated with the value returned
14     * by {@see TokenStream::LA()}. This method has the same pre- and post-conditions
15     * as {@see IntStream::LA()}. In addition, when the preconditions
16     * of this method are met, the return value is non-null and the value
17     * of `LT($k)->getType() === LA($k)`.
18     *
19     * @see IntStream::LA()
20     */
21    public function LT(int $k) : ?Token;
22
23    /**
24     * Gets the {@see Token} at the specified `index` in the stream.
25     * When the preconditions of this method are met, the return value is non-null.
26     *
27     * The preconditions for this method are the same as the preconditions
28     * of {@see IntStream::seek()}. If the behavior of {@see TokenStream::seek()}
29     * is unspecified for the current state and given `index`, then the behavior
30     * of this method is also unspecified.
31     *
32     * The symbol referred to by `index` differs from {@see TokenStream::seek()} only
33     * in the case of filtering streams where `index` lies before the end
34     * of the stream. Unlike {@see TokenStream::seek()}, this method does not adjust
35     * `index` to point to a non-ignored symbol.
36     */
37    public function get(int $index) : Token;
38
39    /**
40     * Gets the underlying {@see TokenSource} which provides tokens for this stream.
41     */
42    public function getTokenSource() : TokenSource;
43
44    /**
45     * Return the text of all tokens within the specified `interval`.
46     * This method behaves like the following code (including potential exceptions
47     * for violating preconditions of {@see TokenStream::get()}, but may be optimized
48     * by the specific implementation.
49     *
50     *     $stream = ...;
51     *     $text = '';
52     *     for ($i = $interval->a; $i <= $interval->b; $i++) {
53     *         $text += $stream->get($i)->getText();
54     *     }
55     *
56     * @param Interval $interval The interval of tokens within this stream
57     *                           to get text for.
58     *
59     * @return string The text of all tokens within the specified interval
60     *                in this stream.
61     */
62    public function getTextByInterval(Interval $interval) : string;
63
64    /**
65     * Return the text of all tokens in the stream. This method behaves like
66     * the following code, including potential exceptions from the calls
67     * to {@see IntStream::size()} and {@see TokenStream::getText()}, but may
68     * be optimized by the specific implementation.
69     *
70     *     $stream = ...;
71     *     $text = $stream->getText(new Interval(0, $stream->size()));
72     *
73     * @return string The text of all tokens in the stream.
74     */
75    public function getText() : string;
76
77    /**
78     * Return the text of all tokens in the source interval of the specified context.
79     * This method behaves like the following code, including potential exceptions
80     * from the call to {@see TokenStream::getText()}, but may be optimized
81     * by the specific implementation.
82     *
83     * If `ctx.getSourceInterval()` does not return a valid interval of tokens
84     * provided by this stream, the behavior is unspecified.
85     *
86     *     $stream = ...;
87     *     $text = $stream->getText($ctx->getSourceInterval());
88     *
89     * @param RuleContext $context The context providing the source interval
90     *                             of tokens to get text for.
91     *
92     * @return string The text of all tokens within the source interval of `context`.
93     */
94    public function getTextByContext(RuleContext $context) : string;
95
96    /**
97     * Return the text of all tokens in this stream between `start` and `stop`
98     * (inclusive).
99     *
100     * If the specified `start` or `stop` token was not provided by this stream,
101     * or if the `stop` occurred before the `start` token, the behavior
102     * is unspecified.
103     *
104     * For streams which ensure that the {@see Token::getTokenIndex()} method
105     * is accurate for all of its provided tokens, this method behaves like
106     * the following code. Other streams may implement this method in other ways
107     * provided the behavior is consistent with this at a high level.
108     *
109     *     $stream = ...;
110     *     $text = '';
111     *     for ($i = $start->getTokenIndex(); $i <= $stop->getTokenIndex(); $i++) {
112     *         $text += $stream->get($i)->getText();
113     *     }
114     *
115     * @param Token $start The first token in the interval to get text for.
116     * @param Token $stop  The last token in the interval to get text for (inclusive).
117     *
118     * @return string The text of all tokens lying between the specified
119     *                `start` and `stop` tokens.
120     */
121    public function getTextByTokens(?Token $start, ?Token $stop) : string;
122}
123