1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
/* Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
* Use of this file is governed by the BSD 3-clause license that
* can be found in the LICENSE.txt file in the project root.
*/
using Antlr4.Runtime;
using Antlr4.Runtime.Misc;
using Antlr4.Runtime.Sharpen;
namespace Antlr4.Runtime
{
/// <summary>
/// An
/// <see cref="IIntStream"/>
/// whose symbols are
/// <see cref="IToken"/>
/// instances.
/// </summary>
public interface ITokenStream : IIntStream
{
/// <summary>
/// Get the
/// <see cref="IToken"/>
/// instance associated with the value returned by
/// <see cref="IIntStream.LA(int)">LA(k)</see>
/// . This method has the same pre- and post-conditions as
/// <see cref="IIntStream.LA(int)"/>
/// . In addition, when the preconditions of this method
/// are met, the return value is non-null and the value of
/// <c>LT(k).getType()==LA(k)</c>
/// .
/// </summary>
/// <seealso cref="IIntStream.LA(int)"/>
[return: NotNull]
IToken LT(int k);
/// <summary>
/// Gets the
/// <see cref="IToken"/>
/// at the specified
/// <c>index</c>
/// in the stream. When
/// the preconditions of this method are met, the return value is non-null.
/// <p>The preconditions for this method are the same as the preconditions of
/// <see cref="IIntStream.Seek(int)"/>
/// . If the behavior of
/// <c>seek(index)</c>
/// is
/// unspecified for the current state and given
/// <c>index</c>
/// , then the
/// behavior of this method is also unspecified.</p>
/// <p>The symbol referred to by
/// <c>index</c>
/// differs from
/// <c>seek()</c>
/// only
/// in the case of filtering streams where
/// <c>index</c>
/// lies before the end
/// of the stream. Unlike
/// <c>seek()</c>
/// , this method does not adjust
/// <c>index</c>
/// to point to a non-ignored symbol.</p>
/// </summary>
/// <exception cref="System.ArgumentException">if {code index} is less than 0</exception>
/// <exception cref="System.NotSupportedException">
/// if the stream does not support
/// retrieving the token at the specified index
/// </exception>
[return: NotNull]
IToken Get(int i);
/// <summary>
/// Gets the underlying
/// <see cref="ITokenSource"/>
/// which provides tokens for this
/// stream.
/// </summary>
ITokenSource TokenSource
{
get;
}
/// <summary>
/// Return the text of all tokens within the specified
/// <paramref name="interval"/>
/// . This
/// method behaves like the following code (including potential exceptions
/// for violating preconditions of
/// <see cref="Get(int)"/>
/// , but may be optimized by the
/// specific implementation.
/// <pre>
/// TokenStream stream = ...;
/// String text = "";
/// for (int i = interval.a; i <= interval.b; i++) {
/// text += stream.get(i).getText();
/// }
/// </pre>
/// </summary>
/// <param name="interval">
/// The interval of tokens within this stream to get text
/// for.
/// </param>
/// <returns>
/// The text of all tokens within the specified interval in this
/// stream.
/// </returns>
/// <exception cref="System.ArgumentNullException">
/// if
/// <paramref name="interval"/>
/// is
/// <see langword="null"/>
/// </exception>
[return: NotNull]
string GetText(Interval interval);
/// <summary>Return the text of all tokens in the stream.</summary>
/// <remarks>
/// Return the text of all tokens in the stream. This method behaves like the
/// following code, including potential exceptions from the calls to
/// <see cref="IIntStream.Size()"/>
/// and
/// <see cref="GetText(Antlr4.Runtime.Misc.Interval)"/>
/// , but may be
/// optimized by the specific implementation.
/// <pre>
/// TokenStream stream = ...;
/// String text = stream.getText(new Interval(0, stream.size()));
/// </pre>
/// </remarks>
/// <returns>The text of all tokens in the stream.</returns>
[return: NotNull]
string GetText();
/// <summary>
/// Return the text of all tokens in the source interval of the specified
/// context.
/// </summary>
/// <remarks>
/// Return the text of all tokens in the source interval of the specified
/// context. This method behaves like the following code, including potential
/// exceptions from the call to
/// <see cref="GetText(Antlr4.Runtime.Misc.Interval)"/>
/// , but may be
/// optimized by the specific implementation.
/// <p>If
/// <c>ctx.getSourceInterval()</c>
/// does not return a valid interval of
/// tokens provided by this stream, the behavior is unspecified.</p>
/// <pre>
/// TokenStream stream = ...;
/// String text = stream.getText(ctx.getSourceInterval());
/// </pre>
/// </remarks>
/// <param name="ctx">
/// The context providing the source interval of tokens to get
/// text for.
/// </param>
/// <returns>
/// The text of all tokens within the source interval of
/// <paramref name="ctx"/>
/// .
/// </returns>
[return: NotNull]
string GetText(RuleContext ctx);
/// <summary>
/// Return the text of all tokens in this stream between
/// <paramref name="start"/>
/// and
/// <paramref name="stop"/>
/// (inclusive).
/// <p>If the specified
/// <paramref name="start"/>
/// or
/// <paramref name="stop"/>
/// token was not provided by
/// this stream, or if the
/// <paramref name="stop"/>
/// occurred before the
/// <paramref name="start"/>
/// token, the behavior is unspecified.</p>
/// <p>For streams which ensure that the
/// <see cref="IToken.TokenIndex()"/>
/// method is
/// accurate for all of its provided tokens, this method behaves like the
/// following code. Other streams may implement this method in other ways
/// provided the behavior is consistent with this at a high level.</p>
/// <pre>
/// TokenStream stream = ...;
/// String text = "";
/// for (int i = start.getTokenIndex(); i <= stop.getTokenIndex(); i++) {
/// text += stream.get(i).getText();
/// }
/// </pre>
/// </summary>
/// <param name="start">The first token in the interval to get text for.</param>
/// <param name="stop">The last token in the interval to get text for (inclusive).</param>
/// <returns>
/// The text of all tokens lying between the specified
/// <paramref name="start"/>
/// and
/// <paramref name="stop"/>
/// tokens.
/// </returns>
/// <exception cref="System.NotSupportedException">
/// if this stream does not support
/// this method for the specified tokens
/// </exception>
[return: NotNull]
string GetText(IToken start, IToken stop);
}
}