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