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