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