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 IllegalArgumentException if {code index} is less than 0
48      *  @throws UnsupportedOperationException if the stream does not support
49      *  retrieving the token at the specified index
50      */
51     public Token get(int index);
52 
53     /**
54      * Gets the underlying {@link TokenSource} which provides tokens for this
55      * stream.
56      */
57     public TokenSource getTokenSource();
58 
59     /**
60      * Return the text of all tokens within the specified {@code interval}. This
61      * method behaves like the following code (including potential exceptions
62      * for violating preconditions of {@link #get}, but may be optimized by the
63      * specific implementation.
64      *
65      * <pre>
66      * TokenStream stream = ...;
67      * String text = "";
68      * for (int i = interval.a; i &lt;= interval.b; i++) {
69      *   text += stream.get(i).getText();
70      * }
71      * </pre>
72      *
73      *  @param interval The interval of tokens within this stream to get text
74      * for.
75      *  @return The text of all tokens within the specified interval in this
76      * stream.
77      *
78      *  @throws NullPointerException if {@code interval} is {@code null}
79      */
80     public Variant getText(Interval interval);
81 
82     /**
83      * Return the text of all tokens in the stream. This method behaves like the
84      * following code, including potential exceptions from the calls to
85      * {@link IntStream#size} and {@link #getText(Interval)}, but may be
86      * optimized by the specific implementation.
87      *
88      * <pre>
89      * TokenStream stream = ...;
90      * String text = stream.getText(new Interval(0, stream.size()));
91      * </pre>
92      *
93      *  @return The text of all tokens in the stream.
94      */
95     public Variant getText();
96 
97     /**
98      * Return the text of all tokens in the source interval of the specified
99      * context. This method behaves like the following code, including potential
100      * exceptions from the call to {@link #getText(Interval)}, but may be
101      * optimized by the specific implementation.
102      *
103      * <p>If {@code ctx.getSourceInterval()} does not return a valid interval of
104      * tokens provided by this stream, the behavior is unspecified.</p>
105      *
106      * <pre>
107      * TokenStream stream = ...;
108      * String text = stream.getText(ctx.getSourceInterval());
109      * </pre>
110      *
111      *  @param ctx The context providing the source interval of tokens to get
112      *  text for.
113      *  @return The text of all tokens within the source interval of {@code ctx}.
114      */
115     public Variant getText(RuleContext ctx);
116 
117     /**
118      * Return the text of all tokens in this stream between {@code start} and
119      * {@code stop} (inclusive).
120      *
121      * <p>If the specified {@code start} or {@code stop} token was not provided by
122      * this stream, or if the {@code stop} occurred before the {@code start}
123      * token, the behavior is unspecified.</p>
124      *
125      * <p>For streams which ensure that the {@link Token#getTokenIndex} method is
126      * accurate for all of its provided tokens, this method behaves like the
127      * following code. Other streams may implement this method in other ways
128      * provided the behavior is consistent with this at a high level.</p>
129      *
130      * <pre>
131      * TokenStream stream = ...;
132      * String text = "";
133      * for (int i = start.getTokenIndex(); i &lt;= stop.getTokenIndex(); i++) {
134      *   text += stream.get(i).getText();
135      * }
136      * </pre>
137      *
138      *  @param start The first token in the interval to get text for.
139      *  @param stop The last token in the interval to get text for (inclusive).
140      *  @return The text of all tokens lying between the specified {@code start}
141      *  and {@code stop} tokens.
142      *
143      *  @throws UnsupportedOperationException if this stream does not support
144      *  this method for the specified tokens
145      */
146     public Variant getText(Token start, Token stop);
147 
148 }