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