antlr.v4.runtime.TokenStream source code

1 /*
2  * Copyright (c) 2012-2019 The ANTLR Project. All rights reserved.
3  * Use of this file is governed by the BSD 3-clause license that
4  * can be found in the LICENSE.txt file in the project root.
5  */
6 
7 module antlr.v4.runtime.TokenStream;
8 
9 import antlr.v4.runtime.IntStream;
10 import antlr.v4.runtime.Token;
11 import antlr.v4.runtime.TokenSource;
12 import antlr.v4.runtime.RuleContext;
13 import antlr.v4.runtime.misc.Interval;
14 import std.variant;
15 
16 /**
17  * TODO add interface description
18  */
19 interface TokenStream : IntStream
20 {
21 
22     /**
23      * Get the {@link Token} instance associated with the value returned by
24      * {@link #LA LA(k)}. This method has the same pre- and post-conditions as
25      * {@link IntStream#LA}. In addition, when the preconditions of this method
26      * are met, the return value is non-null and the value of
27      * {@code LT(k).getType()==LA(k)}.
28      *
29      *  @see IntStream#LA
30      */
31     public Token LT(int k);
32 
33     /**
34      * Gets the {@link Token} at the specified {@code index} in the stream. When
35      * the preconditions of this method are met, the return value is non-null.
36      *
37      * <p>The preconditions for this method are the same as the preconditions of
38      * {@link IntStream#seek}. If the behavior of {@code seek(index)} is
39      * unspecified for the current state and given {@code index}, then the
40      * behavior of this method is also unspecified.</p>
41      *
42      * <p>The symbol referred to by {@code index} differs from {@code seek()} only
43      * in the case of filtering streams where {@code index} lies before the end
44      * of the stream. Unlike {@code seek()}, this method does not adjust
45      * {@code index} to point to a non-ignored symbol.</p>
46      *
47      * Throws:
48      * - IllegalArgumentException if {code index} is less than 0<br>
49      * - UnsupportedOperationException if the stream does not support
50      *  retrieving the token at the specified index
51      */
52     public Token get(int index);
53 
54     /**
55      * Gets the underlying {@link TokenSource} which provides tokens for this
56      * stream.
57      */
58     public TokenSource getTokenSource();
59 
60     /**
61      * Return the text of all tokens within the specified {@code interval}. This
62      * method behaves like the following code (including potential exceptions)
63      * for violating preconditions of {@link #get}, but may be optimized by the
64      * specific implementation.
65      *
66      * <pre>
67      * TokenStream stream = ...;
68      * String text = "";
69      * for (int i = interval.a; i &lt;= interval.b; i++) {
70      *   text += stream.get(i).getText();
71      * }
72      * </pre>
73      *
74      *  @param interval The interval of tokens within this stream to get text
75      * for.
76      *  @return The text of all tokens within the specified interval in this
77      * stream.
78      *
79      *  Throws:
80      *  NullPointerException if {@code interval} is {@code null}
81      */
82     public Variant getText(Interval interval);
83 
84     /**
85      * Return the text of all tokens in the stream. This method behaves like the
86      * following code, including potential exceptions from the calls to
87      * {@link IntStream#size} and {@link #getText(Interval)}, but may be
88      * optimized by the specific implementation.
89      *
90      * <pre>
91      * TokenStream stream = ...;
92      * String text = stream.getText(new Interval(0, stream.size()));
93      * </pre>
94      *
95      *  @return The text of all tokens in the stream.
96      */
97     public Variant getText();
98 
99     /**
100      * Return the text of all tokens in the source interval of the specified
101      * context. This method behaves like the following code, including potential
102      * exceptions from the call to {@link #getText(Interval)}, but may be
103      * optimized by the specific implementation.
104      *
105      * <p>If {@code ctx.getSourceInterval()} does not return a valid interval of
106      * tokens provided by this stream, the behavior is unspecified.</p>
107      *
108      * <pre>
109      * TokenStream stream = ...;
110      * String text = stream.getText(ctx.getSourceInterval());
111      * </pre>
112      *
113      *  @param ctx The context providing the source interval of tokens to get
114      *  text for.
115      *  @return The text of all tokens within the source interval of {@code ctx}.
116      */
117     public Variant getText(RuleContext ctx);
118 
119     /**
120      * Return the text of all tokens in this stream between {@code start} and
121      * {@code stop} (inclusive).
122      *
123      * <p>If the specified {@code start} or {@code stop} token was not provided by
124      * this stream, or if the {@code stop} occurred before the {@code start}
125      * token, the behavior is unspecified.</p>
126      *
127      * <p>For streams which ensure that the {@link Token#getTokenIndex} method is
128      * accurate for all of its provided tokens, this method behaves like the
129      * following code. Other streams may implement this method in other ways
130      * provided the behavior is consistent with this at a high level.</p>
131      *
132      * <pre>
133      * TokenStream stream = ...;
134      * String text = "";
135      * for (int i = start.getTokenIndex(); i &lt;= stop.getTokenIndex(); i++) {
136      *   text += stream.get(i).getText();
137      * }
138      * </pre>
139      *
140      *  @param start The first token in the interval to get text for.
141      *  @param stop The last token in the interval to get text for (inclusive).
142      *  @return The text of all tokens lying between the specified {@code start}
143      *  and {@code stop} tokens.
144      *
145      *  @throws UnsupportedOperationException if this stream does not support
146      *  this method for the specified tokens
147      */
148     public Variant getText(Token start, Token stop);
149 
150 }