2 * Defines the the class interface for an antlr3 INTSTREAM.
\r
4 * Certain functionality (such as DFAs for instance) abstract the stream of tokens
\r
5 * or characters in to a steam of integers. Hence this structure should be included
\r
6 * in any stream that is able to provide the output as a stream of integers (which is anything
\r
9 * There are no specific implementations of the methods in this interface in general. Though
\r
10 * for purposes of casting and so on, it may be necesssary to implement a function with
\r
11 * the signature in this interface which abstracts the base immplementation. In essence though
\r
12 * the base stream provides a pointer to this interface, within which it installs its
\r
13 * normal match() functions and so on. Interaces such as DFA are then passed the pANTLR3_INT_STREAM
\r
14 * and can treat any input as an int stream.
\r
16 * For instance, a lexer implements a pANTLR3_BASE_RECOGNIZER, within which there is a pANTLR3_INT_STREAM.
\r
17 * However, a pANTLR3_INPUT_STREAM also provides a pANTLR3_INT_STREAM, which it has constructed from
\r
18 * it's normal interface when it was created. This is then pointed at by the pANTLR_BASE_RECOGNIZER
\r
19 * when it is intialized with a pANTLR3_INPUT_STREAM.
\r
21 * Similarly if a pANTLR3_BASE_RECOGNIZER is initialized with a pANTLR3_TOKEN_STREAM, then the
\r
22 * pANTLR3_INT_STREAM is taken from the pANTLR3_TOKEN_STREAM.
\r
24 * If a pANTLR3_BASE_RECOGNIZER is initialized with a pANTLR3_TREENODE_STREAM, then guess where
\r
25 * the pANTLR3_INT_STREAM comes from?
\r
27 * Note that because the context pointer points to the actual interface structure that is providing
\r
28 * the ANTLR3_INT_STREAM it is defined as a (void *) in this interface. There is no direct implementation
\r
29 * of an ANTLR3_INT_STREAM (unless someone did not understand what I was doing here =;?P
\r
31 #ifndef _ANTLR3_INTSTREAM_H
\r
32 #define _ANTLR3_INTSTREAM_H
\r
34 // [The "BSD licence"]
\r
35 // Copyright (c) 2005-2009 Jim Idle, Temporal Wave LLC
\r
36 // http://www.temporal-wave.com
\r
37 // http://www.linkedin.com/in/jimidle
\r
39 // All rights reserved.
\r
41 // Redistribution and use in source and binary forms, with or without
\r
42 // modification, are permitted provided that the following conditions
\r
44 // 1. Redistributions of source code must retain the above copyright
\r
45 // notice, this list of conditions and the following disclaimer.
\r
46 // 2. Redistributions in binary form must reproduce the above copyright
\r
47 // notice, this list of conditions and the following disclaimer in the
\r
48 // documentation and/or other materials provided with the distribution.
\r
49 // 3. The name of the author may not be used to endorse or promote products
\r
50 // derived from this software without specific prior written permission.
\r
52 // THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
\r
53 // IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
\r
54 // OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
\r
55 // IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
\r
56 // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
\r
57 // NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
\r
58 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
\r
59 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
\r
60 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
\r
61 // THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\r
63 #include <antlr3defs.h>
\r
64 #include <antlr3commontoken.h>
\r
66 /** Type indicator for a character stream
\r
67 * \remark if a custom stream is created but it can be treated as
\r
68 * a char stream, then you may OR in this value to your type indicator
\r
70 #define ANTLR3_CHARSTREAM 0x0001
\r
72 /** Type indicator for a Token stream
\r
73 * \remark if a custom stream is created but it can be treated as
\r
74 * a token stream, then you may OR in this value to your type indicator
\r
76 #define ANTLR3_TOKENSTREAM 0x0002
\r
78 /** Type indicator for a common tree node stream
\r
79 * \remark if a custom stream is created but it can be treated as
\r
80 * a common tree node stream, then you may OR in this value to your type indicator
\r
82 #define ANTLR3_COMMONTREENODE 0x0004
\r
84 /** Type mask for input stream so we can switch in the above types
\r
85 * \remark DO NOT USE 0x0000 as a stream type!
\r
87 #define ANTLR3_INPUT_MASK 0x0007
\r
93 typedef struct ANTLR3_INT_STREAM_struct
\r
95 /** Input stream type indicator. Sometimes useful for error reporting etc.
\r
99 /** Potentially useful in error reporting and so on, this string is
\r
100 * an identification of the input source. It may be NULL, so anything
\r
101 * attempting to access it needs to check this and substitute a sensible
\r
104 pANTLR3_STRING streamName;
\r
106 /** Pointer to the super structure that contains this interface. This
\r
107 * will usually be a token stream or a tree stream.
\r
111 /** Last marker position allocated
\r
113 ANTLR3_MARKER lastMarker;
\r
115 // Return a string that identifies the input source
\r
117 pANTLR3_STRING (*getSourceName) (struct ANTLR3_INT_STREAM_struct * intStream);
\r
119 /** Consume the next 'ANTR3_UINT32' in the stream
\r
121 void (*consume) (struct ANTLR3_INT_STREAM_struct * intStream);
\r
123 /** Get ANTLR3_UINT32 at current input pointer + i ahead where i=1 is next ANTLR3_UINT32
\r
125 ANTLR3_UINT32 (*_LA) (struct ANTLR3_INT_STREAM_struct * intStream, ANTLR3_INT32 i);
\r
127 /** Tell the stream to start buffering if it hasn't already. Return
\r
128 * current input position, index(), or some other marker so that
\r
129 * when passed to rewind() you get back to the same spot.
\r
130 * rewind(mark()) should not affect the input cursor.
\r
132 ANTLR3_MARKER (*mark) (struct ANTLR3_INT_STREAM_struct * intStream);
\r
134 /** Return the current input symbol index 0..n where n indicates the
\r
135 * last symbol has been read.
\r
137 ANTLR3_MARKER (*index) (struct ANTLR3_INT_STREAM_struct * intStream);
\r
139 /** Reset the stream so that next call to index would return marker.
\r
140 * The marker will usually be index() but it doesn't have to be. It's
\r
141 * just a marker to indicate what state the stream was in. This is
\r
142 * essentially calling release() and seek(). If there are markers
\r
143 * created after this marker argument, this routine must unroll them
\r
144 * like a stack. Assume the state the stream was in when this marker
\r
147 void (*rewind) (struct ANTLR3_INT_STREAM_struct * intStream, ANTLR3_MARKER marker);
\r
149 /** Reset the stream to the last marker position, witouh destryoing the
\r
150 * last marker position.
\r
152 void (*rewindLast) (struct ANTLR3_INT_STREAM_struct * intStream);
\r
154 /** You may want to commit to a backtrack but don't want to force the
\r
155 * stream to keep bookkeeping objects around for a marker that is
\r
156 * no longer necessary. This will have the same behavior as
\r
157 * rewind() except it releases resources without the backward seek.
\r
159 void (*release) (struct ANTLR3_INT_STREAM_struct * intStream, ANTLR3_MARKER mark);
\r
161 /** Set the input cursor to the position indicated by index. This is
\r
162 * normally used to seek ahead in the input stream. No buffering is
\r
163 * required to do this unless you know your stream will use seek to
\r
164 * move backwards such as when backtracking.
\r
166 * This is different from rewind in its multi-directional
\r
167 * requirement and in that its argument is strictly an input cursor (index).
\r
169 * For char streams, seeking forward must update the stream state such
\r
170 * as line number. For seeking backwards, you will be presumably
\r
171 * backtracking using the mark/rewind mechanism that restores state and
\r
172 * so this method does not need to update state when seeking backwards.
\r
174 * Currently, this method is only used for efficient backtracking, but
\r
175 * in the future it may be used for incremental parsing.
\r
177 void (*seek) (struct ANTLR3_INT_STREAM_struct * intStream, ANTLR3_MARKER index);
\r
179 /** Only makes sense for streams that buffer everything up probably, but
\r
180 * might be useful to display the entire stream or for testing.
\r
182 ANTLR3_UINT32 (*size) (struct ANTLR3_INT_STREAM_struct * intStream);
\r
184 /** Because the indirect call, though small in individual cases can
\r
185 * mount up if there are thousands of tokens (very large input streams), callers
\r
186 * of size can optionally use this cached size field.
\r
188 ANTLR3_UINT32 cachedSize;
\r
190 /** Frees any resources that were allocated for the implementation of this
\r
191 * interface. Usually this is just releasing the memory allocated
\r
192 * for the structure itself, but it may of course do anything it need to
\r
193 * so long as it does not stamp on anything else.
\r
195 void (*free) (struct ANTLR3_INT_STREAM_struct * stream);
\r