1<?php
2
3declare(strict_types=1);
4
5namespace Antlr\Antlr4\Runtime;
6
7/**
8 * A simple stream of symbols whose values are represented as integers. This
9 * interface provides marked ranges with support for a minimum level of
10 * buffering necessary to implement arbitrary lookahead during prediction.
11 * For more information on marked ranges, see {@see IntStream::mark()}.
12 *
13 * Initializing Methods: Some methods in this interface have unspecified
14 * behavior if no call to an initializing method has occurred after the stream
15 * was constructed. The following is a list of initializing methods:
16 *
17 * @see IntStream::LA()
18 * @see IntStream::consume()
19 * @see IntStream::size()
20 */
21interface IntStream
22{
23    /**
24     * The value returned by {@see IntStream::LA()} when the end of the stream is
25     * reached.
26     */
27    public const EOF = -1;
28
29    /**
30     * During lookahead operations, this "token" signifies we hit rule end ATN state
31     * and did not follow it despite needing to.
32     */
33    public const EPSILON = -2;
34
35    /**
36     * The value returned by {@see IntStream::getSourceName()} when the actual
37     * name of the underlying source is not known.
38     */
39    public const UNKNOWN_SOURCE_NAME = '<unknown>';
40
41    /**
42     * Consumes the current symbol in the stream. This method has the following
43     * effects:
44     *
45     * - Forward movement: The value of {@see IntStream::index()} before calling
46     *    this method is less than the value of `index` after calling this method.
47     * - Ordered lookahead: The value of `LA(1)` before calling this method
48     *    becomes the value of `LA(-1)` after calling this method.
49     *
50     * Note that calling this method does not guarantee that `index()` is
51     * incremented by exactly 1, as that would preclude the ability to implement
52     * filtering streams (e.g. {@see CommonTokenStream} which distinguishes
53     * between "on-channel" and "off-channel" tokens).
54     */
55    public function consume() : void;
56
57    /**
58     * Gets the value of the symbol at offset `i` from the current
59     * position. When `i === 1`, this method returns the value of the current
60     * symbol in the stream (which is the next symbol to be consumed). When
61     * `i === -1`, this method returns the value of the previously read symbol
62     * in the stream. It is not valid to call this method with `i === 0`, but
63     * the specific behavior is unspecified because this method is frequently
64     * called from performance-critical code.
65     *
66     * This method is guaranteed to succeed if any of the following are true:
67     *
68     * - `i > 0`
69     * - `i === -1` and {@see IntStream::index index()} returns a value greater
70     *    than the value of `index` after the stream was constructed and `LA(1)
71     *    was called in that order. Specifying the current `index` relative
72     *    to the index after the stream was created allows for filtering
73     *    implementations that do not return every symbol from the underlying
74     *    source. Specifying the call to `LA(1)` allows for lazily initialized
75     *    streams.
76     * - `LA(i)` refers to a symbol consumed within a marked region that has
77     *    not yet been released.
78     *
79     * If `i` represents a position at or beyond the end of the stream,
80     * this method returns {@see IntStream::EOF()}.
81     *
82     * The return value is unspecified if `i < 0` and fewer than `-i` calls to
83     * {@see IntStream::consume consume()} have occurred from the beginning of
84     * the stream before calling this method.
85     */
86    public function LA(int $i) : int;
87
88    /**
89     * A mark provides a guarantee that {@see IntStream::seek seek()} operations
90     * will be valid over a "marked range" extending from the index where `mark`
91     * was called to the current {@see IntStream::index index()}. This allows
92     * the use of streaming input sources by specifying the minimum buffering
93     * requirements to support arbitrary lookahead during prediction.
94     *
95     * The returned mark is an opaque handle (type `int`) which is passed to
96     * {@see IntStream::release release()} when the guarantees provided by
97     * the marked range are no longer necessary. When calls to `mark`/`release`
98     * are nested, the marks must be released in reverse order of which they
99     * were obtained. Since marked regions are used during performance-critical
100     * sections of prediction, the specific behavior of invalid usage is unspecified
101     * (i.e. a mark is not released, or a mark is released twice, or marks are
102     * not released in reverse order from which they were created).
103     *
104     * The behavior of this method is unspecified if no call to an
105     * {@see IntStream::initializing()} method has occurred after this stream was
106     * constructed.
107     *
108     * This method does not change the current position in the input stream.
109     *
110     * The following example shows the use of {@see IntStream::mark()},
111     * {@see IntStream::release(mark)}, {@see IntStream::index()}, and
112     * {@see IntStream::seek(index)} as part of an operation to safely work within a
113     * marked region, then restore the stream position to its original value and
114     * release the mark.
115     *
116     *     $stream = ...;
117     *     $index = -1;
118     *     $mark = $stream->mark();
119     *     try {
120     *         $index = $stream->index();
121     *         // perform work here...
122     *     } finally {
123     *         if ($index !== -1) {
124     *             $stream->seek($index);
125     *         }
126     *
127     *         $stream->release($mark);
128     *     }
129     *
130     * @return int An opaque marker which should be passed to
131     *             {@see IntStream::release()} when the marked range
132     *             is no longer required.
133     */
134    public function mark() : int;
135
136    /**
137     * This method releases a marked range created by a call to
138     * {@see IntStream::mark()}. Calls to `release` must appear in the
139     * reverse order of the corresponding calls to `mark`. If a mark is
140     * released twice, or if marks are not released in reverse order of the
141     * corresponding calls to `mark`, the behavior is unspecified.
142     *
143     * For more information and an example, see {@see IntStream::mark()}.
144     *
145     * @param int $marker A marker returned by a call to `mark`.
146     *
147     * @see IntStream::mark
148     */
149    public function release(int $marker) : void;
150
151    /**
152     * Return the index into the stream of the input symbol referred to by `LA(1)`.
153     *
154     * The behavior of this method is unspecified if no call to an
155     * {@see IntStream::initializing()} has occurred after this stream was
156     * constructed.
157     */
158    public function getIndex() : int;
159
160    /**
161     * Set the input cursor to the position indicated by `index`. If the
162     * specified index lies past the end of the stream, the operation behaves as
163     * though `index` was the index of the EOF symbol. After this method
164     * returns without throwing an exception, then at least one of the following
165     * will be true.
166     *
167     * - {@see IntStream::index index()} will return the index of the first symbol
168     *    appearing at or after the specified `index`. Specifically,
169     *    implementations which filter their sources should automatically
170     *    adjust `index` forward the minimum amount required for the
171     *    operation to target a non-ignored symbol.
172     * - `LA(1)` returns {@see IntStream::EOF}
173     *
174     * This operation is guaranteed to not throw an exception if `index` lies
175     * within a marked region. For more information on marked regions, see
176     * {@see IntStream::mark()}. The behavior of this method is unspecified if
177     * no call to an {@see IntStream::initializing()} has occurred after this stream
178     * was constructed.
179     *
180     * @param int $index The absolute index to seek to.
181     */
182    public function seek(int $index) : void;
183
184    /**
185     * Returns the total number of symbols in the stream, including a single EOF
186     * symbol.
187     */
188    public function getLength() : int;
189
190    /**
191     * Gets the name of the underlying symbol source. This method returns a
192     * non-null, non-empty string. If such a name is not known, this method
193     * returns {@see IntStream::UNKNOWN_SOURCE_NAME}.
194     */
195    public function getSourceName() : string;
196}
197