1/*
2 * [The "BSD licence"]
3 * Copyright (c) 2005-2008 Terence Parr
4 * All rights reserved.
5 *
6 * Conversion to C#:
7 * Copyright (c) 2008-2009 Sam Harwell, Pixel Mine, Inc.
8 * All rights reserved.
9 *
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions
12 * are met:
13 * 1. Redistributions of source code must retain the above copyright
14 *    notice, this list of conditions and the following disclaimer.
15 * 2. Redistributions in binary form must reproduce the above copyright
16 *    notice, this list of conditions and the following disclaimer in the
17 *    documentation and/or other materials provided with the distribution.
18 * 3. The name of the author may not be used to endorse or promote products
19 *    derived from this software without specific prior written permission.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
23 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32
33namespace Antlr.Runtime
34{
35
36    /** <summary>
37     *  A simple stream of integers used when all I care about is the char
38     *  or token type sequence (such as interpretation).
39     *  </summary>
40     */
41    public interface IIntStream
42    {
43        void Consume();
44
45        /** <summary>
46         *  Get int at current input pointer + i ahead where i=1 is next int.
47         *  Negative indexes are allowed.  LA(-1) is previous token (token
48         *  just matched).  LA(-i) where i is before first token should
49         *  yield -1, invalid char / EOF.
50         *  </summary>
51         */
52        int LA( int i );
53
54        /** <summary>
55         *  Tell the stream to start buffering if it hasn't already.  Return
56         *  current input position, Index, or some other marker so that
57         *  when passed to rewind() you get back to the same spot.
58         *  rewind(mark()) should not affect the input cursor.  The Lexer
59         *  track line/col info as well as input index so its markers are
60         *  not pure input indexes.  Same for tree node streams.
61         *  </summary>
62         */
63        int Mark();
64
65        /** <summary>
66         *  Return the current input symbol index 0..n where n indicates the
67         *  last symbol has been read.  The index is the symbol about to be
68         *  read not the most recently read symbol.
69         *  </summary>
70         */
71        int Index
72        {
73            get;
74        }
75
76        /** <summary>
77         *  Reset the stream so that next call to index would return marker.
78         *  The marker will usually be Index but it doesn't have to be.  It's
79         *  just a marker to indicate what state the stream was in.  This is
80         *  essentially calling release() and seek().  If there are markers
81         *  created after this marker argument, this routine must unroll them
82         *  like a stack.  Assume the state the stream was in when this marker
83         *  was created.
84         *  </summary>
85         */
86        void Rewind( int marker );
87
88        /** <summary>
89         *  Rewind to the input position of the last marker.
90         *  Used currently only after a cyclic DFA and just
91         *  before starting a sem/syn predicate to get the
92         *  input position back to the start of the decision.
93         *  Do not "pop" the marker off the state.  mark(i)
94         *  and rewind(i) should balance still. It is
95         *  like invoking rewind(last marker) but it should not "pop"
96         *  the marker off.  It's like seek(last marker's input position).
97         *  </summary>
98         */
99        void Rewind();
100
101        /** <summary>
102         *  You may want to commit to a backtrack but don't want to force the
103         *  stream to keep bookkeeping objects around for a marker that is
104         *  no longer necessary.  This will have the same behavior as
105         *  rewind() except it releases resources without the backward seek.
106         *  This must throw away resources for all markers back to the marker
107         *  argument.  So if you're nested 5 levels of mark(), and then release(2)
108         *  you have to release resources for depths 2..5.
109         *  </summary>
110         */
111        void Release( int marker );
112
113        /** <summary>
114         *  Set the input cursor to the position indicated by index.  This is
115         *  normally used to seek ahead in the input stream.  No buffering is
116         *  required to do this unless you know your stream will use seek to
117         *  move backwards such as when backtracking.
118         *  </summary>
119         *
120         *  <remarks>
121         *  This is different from rewind in its multi-directional
122         *  requirement and in that its argument is strictly an input cursor (index).
123         *
124         *  For char streams, seeking forward must update the stream state such
125         *  as line number.  For seeking backwards, you will be presumably
126         *  backtracking using the mark/rewind mechanism that restores state and
127         *  so this method does not need to update state when seeking backwards.
128         *
129         *  Currently, this method is only used for efficient backtracking using
130         *  memoization, but in the future it may be used for incremental parsing.
131         *
132         *  The index is 0..n-1.  A seek to position i means that LA(1) will
133         *  return the ith symbol.  So, seeking to 0 means LA(1) will return the
134         *  first element in the stream.
135         *  </remarks>
136         */
137        void Seek( int index );
138
139        /** <summary>
140         *  Only makes sense for streams that buffer everything up probably, but
141         *  might be useful to display the entire stream or for testing.  This
142         *  value includes a single EOF.
143         *  </summary>
144         */
145        int Count
146        {
147            get;
148        }
149
150        /** <summary>
151         *  Where are you getting symbols from?  Normally, implementations will
152         *  pass the buck all the way to the lexer who can ask its input stream
153         *  for the file name or whatever.
154         *  </summary>
155         */
156        string SourceName
157        {
158            get;
159        }
160    }
161}
162