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