1 /* 2 * [The "BSD license"] 3 * Copyright (c) 2012 Terence Parr 4 * Copyright (c) 2012 Sam Harwell 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 11 * 1. Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * 2. Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in the 15 * documentation and/or other materials provided with the distribution. 16 * 3. The name of the author may not be used to endorse or promote products 17 * derived from this software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 20 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 21 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 22 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 23 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 24 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 28 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 */ 30 31 module antlr.v4.runtime.TokenStream; 32 33 import antlr.v4.runtime.IntStream; 34 import antlr.v4.runtime.Token; 35 import antlr.v4.runtime.TokenSource; 36 import antlr.v4.runtime.RuleContext; 37 import antlr.v4.runtime.misc.Interval; 38 39 // Interface TokenStream 40 /** 41 * TODO add interface description 42 */ 43 interface TokenStream : IntStream 44 { 45 46 /** 47 * Get the {@link Token} instance associated with the value returned by 48 * {@link #LA LA(k)}. This method has the same pre- and post-conditions as 49 * {@link IntStream#LA}. In addition, when the preconditions of this method 50 * are met, the return value is non-null and the value of 51 * {@code LT(k).getType()==LA(k)}. 52 * 53 * @see IntStream#LA 54 */ 55 public Token LT(int k); 56 57 /** 58 * Gets the {@link Token} at the specified {@code index} in the stream. When 59 * the preconditions of this method are met, the return value is non-null. 60 * 61 * <p>The preconditions for this method are the same as the preconditions of 62 * {@link IntStream#seek}. If the behavior of {@code seek(index)} is 63 * unspecified for the current state and given {@code index}, then the 64 * behavior of this method is also unspecified.</p> 65 * 66 * <p>The symbol referred to by {@code index} differs from {@code seek()} only 67 * in the case of filtering streams where {@code index} lies before the end 68 * of the stream. Unlike {@code seek()}, this method does not adjust 69 * {@code index} to point to a non-ignored symbol.</p> 70 * 71 * @throws IllegalArgumentException if {code index} is less than 0 72 * @throws UnsupportedOperationException if the stream does not support 73 * retrieving the token at the specified index 74 */ 75 public Token get(int index); 76 77 /** 78 * Gets the underlying {@link TokenSource} which provides tokens for this 79 * stream. 80 */ 81 public TokenSource getTokenSource(); 82 83 /** 84 * Return the text of all tokens within the specified {@code interval}. This 85 * method behaves like the following code (including potential exceptions 86 * for violating preconditions of {@link #get}, but may be optimized by the 87 * specific implementation. 88 * 89 * <pre> 90 * TokenStream stream = ...; 91 * String text = ""; 92 * for (int i = interval.a; i <= interval.b; i++) { 93 * text += stream.get(i).getText(); 94 * } 95 * </pre> 96 * 97 * @param interval The interval of tokens within this stream to get text 98 * for. 99 * @return The text of all tokens within the specified interval in this 100 * stream. 101 * 102 * @throws NullPointerException if {@code interval} is {@code null} 103 */ 104 public string getText(Interval interval); 105 106 /** 107 * Return the text of all tokens in the stream. This method behaves like the 108 * following code, including potential exceptions from the calls to 109 * {@link IntStream#size} and {@link #getText(Interval)}, but may be 110 * optimized by the specific implementation. 111 * 112 * <pre> 113 * TokenStream stream = ...; 114 * String text = stream.getText(new Interval(0, stream.size())); 115 * </pre> 116 * 117 * @return The text of all tokens in the stream. 118 */ 119 public string getText(); 120 121 /** 122 * Return the text of all tokens in the source interval of the specified 123 * context. This method behaves like the following code, including potential 124 * exceptions from the call to {@link #getText(Interval)}, but may be 125 * optimized by the specific implementation. 126 * 127 * <p>If {@code ctx.getSourceInterval()} does not return a valid interval of 128 * tokens provided by this stream, the behavior is unspecified.</p> 129 * 130 * <pre> 131 * TokenStream stream = ...; 132 * String text = stream.getText(ctx.getSourceInterval()); 133 * </pre> 134 * 135 * @param ctx The context providing the source interval of tokens to get 136 * text for. 137 * @return The text of all tokens within the source interval of {@code ctx}. 138 */ 139 public string getText(RuleContext ctx); 140 141 /** 142 * Return the text of all tokens in this stream between {@code start} and 143 * {@code stop} (inclusive). 144 * 145 * <p>If the specified {@code start} or {@code stop} token was not provided by 146 * this stream, or if the {@code stop} occurred before the {@code start} 147 * token, the behavior is unspecified.</p> 148 * 149 * <p>For streams which ensure that the {@link Token#getTokenIndex} method is 150 * accurate for all of its provided tokens, this method behaves like the 151 * following code. Other streams may implement this method in other ways 152 * provided the behavior is consistent with this at a high level.</p> 153 * 154 * <pre> 155 * TokenStream stream = ...; 156 * String text = ""; 157 * for (int i = start.getTokenIndex(); i <= stop.getTokenIndex(); i++) { 158 * text += stream.get(i).getText(); 159 * } 160 * </pre> 161 * 162 * @param start The first token in the interval to get text for. 163 * @param stop The last token in the interval to get text for (inclusive). 164 * @return The text of all tokens lying between the specified {@code start} 165 * and {@code stop} tokens. 166 * 167 * @throws UnsupportedOperationException if this stream does not support 168 * this method for the specified tokens 169 */ 170 public string getText(Token start, Token stop); 171 172 }