001: /*
002: [The "BSD licence"]
003: Copyright (c) 2005-2006 Terence Parr
004: All rights reserved.
005:
006: Redistribution and use in source and binary forms, with or without
007: modification, are permitted provided that the following conditions
008: are met:
009: 1. Redistributions of source code must retain the above copyright
010: notice, this list of conditions and the following disclaimer.
011: 2. Redistributions in binary form must reproduce the above copyright
012: notice, this list of conditions and the following disclaimer in the
013: documentation and/or other materials provided with the distribution.
014: 3. The name of the author may not be used to endorse or promote products
015: derived from this software without specific prior written permission.
016:
017: THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
018: IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
019: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
020: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
021: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
022: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
023: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
024: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
025: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
026: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
027: */
028: package org.antlr.runtime;
029:
030: /** A simple stream of integers used when all I care about is the char
031: * or token type sequence (such as interpretation).
032: */
033: public interface IntStream {
034: void consume();
035:
036: /** Get int at current input pointer + i ahead where i=1 is next int.
037: * Negative indexes are allowed. LA(-1) is previous token (token
038: * just matched). LA(-i) where i is before first token should
039: * yield -1, invalid char / EOF.
040: */
041: int LA(int i);
042:
043: /** Tell the stream to start buffering if it hasn't already. Return
044: * current input position, index(), or some other marker so that
045: * when passed to rewind() you get back to the same spot.
046: * rewind(mark()) should not affect the input cursor. The Lexer
047: * track line/col info as well as input index so its markers are
048: * not pure input indexes. Same for tree node streams.
049: */
050: int mark();
051:
052: /** Return the current input symbol index 0..n where n indicates the
053: * last symbol has been read. The index is the symbol about to be
054: * read not the most recently read symbol.
055: */
056: int index();
057:
058: /** Reset the stream so that next call to index would return marker.
059: * The marker will usually be index() but it doesn't have to be. It's
060: * just a marker to indicate what state the stream was in. This is
061: * essentially calling release() and seek(). If there are markers
062: * created after this marker argument, this routine must unroll them
063: * like a stack. Assume the state the stream was in when this marker
064: * was created.
065: */
066: void rewind(int marker);
067:
068: /** Rewind to the input position of the last marker.
069: * Used currently only after a cyclic DFA and just
070: * before starting a sem/syn predicate to get the
071: * input position back to the start of the decision.
072: * Do not "pop" the marker off the state. mark(i)
073: * and rewind(i) should balance still. It is
074: * like invoking rewind(last marker) but it should not "pop"
075: * the marker off. It's like seek(last marker's input position).
076: */
077: void rewind();
078:
079: /** You may want to commit to a backtrack but don't want to force the
080: * stream to keep bookkeeping objects around for a marker that is
081: * no longer necessary. This will have the same behavior as
082: * rewind() except it releases resources without the backward seek.
083: * This must throw away resources for all markers back to the marker
084: * argument. So if you're nested 5 levels of mark(), and then release(2)
085: * you have to release resources for depths 2..5.
086: */
087: void release(int marker);
088:
089: /** Set the input cursor to the position indicated by index. This is
090: * normally used to seek ahead in the input stream. No buffering is
091: * required to do this unless you know your stream will use seek to
092: * move backwards such as when backtracking.
093: *
094: * This is different from rewind in its multi-directional
095: * requirement and in that its argument is strictly an input cursor (index).
096: *
097: * For char streams, seeking forward must update the stream state such
098: * as line number. For seeking backwards, you will be presumably
099: * backtracking using the mark/rewind mechanism that restores state and
100: * so this method does not need to update state when seeking backwards.
101: *
102: * Currently, this method is only used for efficient backtracking using
103: * memoization, but in the future it may be used for incremental parsing.
104: *
105: * The index is 0..n-1. A seek to position i means that LA(1) will
106: * return the ith symbol. So, seeking to 0 means LA(1) will return the
107: * first element in the stream.
108: */
109: void seek(int index);
110:
111: /** Only makes sense for streams that buffer everything up probably, but
112: * might be useful to display the entire stream or for testing. This
113: * value includes a single EOF.
114: */
115: int size();
116: }
|