1324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver/* 2324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver [The "BSD licence"] 3324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver Copyright (c) 2005-2006 Terence Parr 4324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver All rights reserved. 5324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 6324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver Redistribution and use in source and binary forms, with or without 7324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver modification, are permitted provided that the following conditions 8324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver are met: 9324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 1. Redistributions of source code must retain the above copyright 10324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver notice, this list of conditions and the following disclaimer. 11324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 2. Redistributions in binary form must reproduce the above copyright 12324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver notice, this list of conditions and the following disclaimer in the 13324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver documentation and/or other materials provided with the distribution. 14324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 3. The name of the author may not be used to endorse or promote products 15324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver derived from this software without specific prior written permission. 16324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 17324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver*/ 28324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruverpackage org.antlr.runtime { 29324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver /** A simple stream of integers used when all I care about is the char 30324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * or token type sequence (such as interpretation). 31324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver */ 32324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver public interface IntStream { 33324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver function consume():void; 34324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 35324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver /** Get int at current input pointer + i ahead where i=1 is next int. 36324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * Negative indexes are allowed. LA(-1) is previous token (token 37324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * just matched). LA(-i) where i is before first token should 38324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * yield -1, invalid char / EOF. 39324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver */ 40324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver function LA(i:int):int; 41324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 42324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver /** Tell the stream to start buffering if it hasn't already. Return 43324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * current input position, index(), or some other marker so that 44324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * when passed to rewind() you get back to the same spot. 45324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * rewind(mark()) should not affect the input cursor. The Lexer 46324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * track line/col info as well as input index so its markers are 47324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * not pure input indexes. Same for tree node streams. 48324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver */ 49324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver function mark():int; 50324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 51324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver /** Return the current input symbol index 0..n where n indicates the 52324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * last symbol has been read. The index is the symbol about to be 53324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * read not the most recently read symbol. 54324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver */ 55324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver function get index():int; 56324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 57324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver /** Reset the stream so that next call to index would return marker. 58324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * The marker will usually be index() but it doesn't have to be. It's 59324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * just a marker to indicate what state the stream was in. This is 60324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * essentially calling release() and seek(). If there are markers 61324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * created after this marker argument, this routine must unroll them 62324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * like a stack. Assume the state the stream was in when this marker 63324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * was created. 64324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver */ 65324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver function rewindTo(marker:int):void; 66324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 67324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver /** Rewind to the input position of the last marker. 68324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * Used currently only after a cyclic DFA and just 69324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * before starting a sem/syn predicate to get the 70324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * input position back to the start of the decision. 71324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * Do not "pop" the marker off the state. mark(i) 72324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * and rewind(i) should balance still. It is 73324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * like invoking rewind(last marker) but it should not "pop" 74324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * the marker off. It's like seek(last marker's input position). 75324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver */ 76324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver function rewind():void; 77324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 78324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver /** You may want to commit to a backtrack but don't want to force the 79324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * stream to keep bookkeeping objects around for a marker that is 80324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * no longer necessary. This will have the same behavior as 81324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * rewind() except it releases resources without the backward seek. 82324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * This must throw away resources for all markers back to the marker 83324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * argument. So if you're nested 5 levels of mark(), and then release(2) 84324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * you have to release resources for depths 2..5. 85324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver */ 86324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver function release(marker:int):void; 87324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 88324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver /** Set the input cursor to the position indicated by index. This is 89324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * normally used to seek ahead in the input stream. No buffering is 90324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * required to do this unless you know your stream will use seek to 91324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * move backwards such as when backtracking. 92324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * 93324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * This is different from rewind in its multi-directional 94324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * requirement and in that its argument is strictly an input cursor (index). 95324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * 96324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * For char streams, seeking forward must update the stream state such 97324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * as line number. For seeking backwards, you will be presumably 98324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * backtracking using the mark/rewind mechanism that restores state and 99324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * so this method does not need to update state when seeking backwards. 100324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * 101324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * Currently, this method is only used for efficient backtracking using 102324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * memoization, but in the future it may be used for incremental parsing. 103324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * 104324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * The index is 0..n-1. A seek to position i means that LA(1) will 105324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * return the ith symbol. So, seeking to 0 means LA(1) will return the 106324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * first element in the stream. 107324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver */ 108324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver function seek(index:int):void; 109324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 110324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver /** Only makes sense for streams that buffer everything up probably, but 111324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * might be useful to display the entire stream or for testing. This 112324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * value includes a single EOF. 113324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver */ 114324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver function get size():int; 115324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 116324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver /** Where are you getting symbols from? Normally, implementations will 117324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * pass the buck all the way to the lexer who can ask its input stream 118324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * for the file name or whatever. 119324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver */ 120324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver function get sourceName():String; 121324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver } 122324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver}