001: /*
002:
003: Derby - Class org.apache.derby.impl.sql.compile.CharStream
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.impl.sql.compile;
023:
024: /**
025: * This interface describes a character stream that maintains line and
026: * column number positions of the characters. It also has the capability
027: * to backup the stream to some extent. An implementation of this
028: * interface is used in the TokenManager implementation generated by
029: * JavaCCParser.
030: *
031: * All the methods except backup can be implemented in any fashion. backup
032: * needs to be implemented correctly for the correct operation of the lexer.
033: * Rest of the methods are all used to get information like line number,
034: * column number and the String that constitutes a token and are not used
035: * by the lexer. Hence their implementation won't affect the generated lexer's
036: * operation.
037: */
038:
039: public interface CharStream {
040:
041: /**
042: * Returns the next character from the selected input. The method
043: * of selecting the input is the responsibility of the class
044: * implementing this interface. Can throw any java.io.IOException.
045: */
046: char readChar() throws java.io.IOException;
047:
048: /**
049: * Returns the column position of the character last read.
050: * @deprecated
051: * @see #getEndColumn
052: */
053: int getColumn();
054:
055: /**
056: * Returns the line number of the character last read.
057: * @deprecated
058: * @see #getEndLine
059: */
060: int getLine();
061:
062: /**
063: * Returns the column number of the last character for current token (being
064: * matched after the last call to BeginTOken).
065: */
066: int getEndColumn();
067:
068: /**
069: * Returns the line number of the last character for current token (being
070: * matched after the last call to BeginTOken).
071: */
072: int getEndLine();
073:
074: /**
075: * Returns the column number of the first character for current token (being
076: * matched after the last call to BeginTOken).
077: */
078: int getBeginColumn();
079:
080: /**
081: * Returns the line number of the first character for current token (being
082: * matched after the last call to BeginTOken).
083: */
084: int getBeginLine();
085:
086: /**
087: * Backs up the input stream by amount steps. Lexer calls this method if it
088: * had already read some characters, but could not use them to match a
089: * (longer) token. So, they will be used again as the prefix of the next
090: * token and it is the implemetation's responsibility to do this right.
091: */
092: void backup(int amount);
093:
094: /**
095: * Returns the next character that marks the beginning of the next token.
096: * All characters must remain in the buffer between two successive calls
097: * to this method to implement backup correctly.
098: */
099: char BeginToken() throws java.io.IOException;
100:
101: /**
102: * Returns a string made up of characters from the marked token beginning
103: * to the current buffer position. Implementations have the choice of returning
104: * anything that they want to. For example, for efficiency, one might decide
105: * to just return null, which is a valid implementation.
106: */
107: String GetImage();
108:
109: /**
110: * Returns an array of characters that make up the suffix of length 'len' for
111: * the currently matched token. This is used to build up the matched string
112: * for use in actions in the case of MORE. A simple and inefficient
113: * implementation of this is as follows :
114: *
115: * {
116: * String t = GetImage();
117: * return t.substring(t.length() - len, t.length()).toCharArray();
118: * }
119: */
120: char[] GetSuffix(int len);
121:
122: /**
123: * The lexer calls this function to indicate that it is done with the stream
124: * and hence implementations can free any resources held by this class.
125: * Again, the body of this function can be just empty and it will not
126: * affect the lexer's operation.
127: */
128: void Done();
129:
130: // This method was added to support ability to get the input
131: // between two tokens.
132: abstract int getBeginOffset();
133:
134: // This method was added to support ability to get the input
135: // between two tokens.
136: abstract int getEndOffset();
137:
138: // These methods were added to support re-initialization of CharStreams
139: abstract void ReInit(java.io.Reader dstream, int startline,
140: int startcolumn, int buffersize);
141:
142: abstract void ReInit(java.io.Reader dstream, int startline,
143: int startcolumn);
144:
145: abstract void ReInit(java.io.InputStream dstream, int startline,
146: int startcolumn, int buffersize);
147:
148: abstract void ReInit(java.io.InputStream dstream, int startline,
149: int startcolumn);
150:
151: }
|