KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > core > compiler > IScanner


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11
12 package org.eclipse.jdt.core.compiler;
13
14 import org.eclipse.jdt.core.compiler.InvalidInputException;
15  
16  /**
17   * Definition of a Java scanner, as returned by the <code>ToolFactory</code>.
18   * The scanner is responsible for tokenizing a given source, providing information about
19   * the nature of the token read, its positions and source equivalent.
20   * <p>
21   * When the scanner has finished tokenizing, it answers an EOF token (<code>
22   * ITerminalSymbols#TokenNameEOF</code>.
23   * </p><p>
24   * When encountering lexical errors, an <code>InvalidInputException</code> is thrown.
25  * </p><p>
26  * This interface is not intended to be implemented by clients.
27  * </p>
28   *
29   * @see org.eclipse.jdt.core.ToolFactory
30   * @see ITerminalSymbols
31   * @since 2.0
32   */

33 public interface IScanner {
34
35     /**
36      * Answers the current identifier source, after unicode escape sequences have
37      * been translated into unicode characters.
38      * For example, if original source was <code>\\u0061bc</code> then it will answer <code>abc</code>.
39      *
40      * @return the current identifier source, after unicode escape sequences have
41      * been translated into unicode characters
42      */

43     char[] getCurrentTokenSource();
44     
45     /**
46      * Answers the current identifier source, before unicode escape sequences have
47      * been translated into unicode characters.
48      * For example, if original source was <code>\\u0061bc</code> then it will answer <code>\\u0061bc</code>.
49      *
50      * @return the current identifier source, before unicode escape sequences have
51      * been translated into unicode characters
52      * @since 2.1
53      */

54     char[] getRawTokenSource();
55
56     /**
57      * Answers the starting position of the current token inside the original source.
58      * This position is zero-based and inclusive. It corresponds to the position of the first character
59      * which is part of this token. If this character was a unicode escape sequence, it points at the first
60      * character of this sequence.
61      *
62      * @return the starting position of the current token inside the original source
63      */

64     int getCurrentTokenStartPosition();
65
66     /**
67      * Answers the ending position of the current token inside the original source.
68      * This position is zero-based and inclusive. It corresponds to the position of the last character
69      * which is part of this token. If this character was a unicode escape sequence, it points at the last
70      * character of this sequence.
71      *
72      * @return the ending position of the current token inside the original source
73      */

74     int getCurrentTokenEndPosition();
75
76     /**
77      * Answers the starting position of a given line number. This line has to have been encountered
78      * already in the tokenization process (in other words, it cannot be used to compute positions of lines beyond
79      * current token). Once the entire source has been processed, it can be used without any limit.
80      * Line starting positions are zero-based, and start immediately after the previous line separator (if any).
81      *
82      * @param lineNumber the given line number
83      * @return the starting position of a given line number
84      */

85     int getLineStart(int lineNumber);
86
87     /**
88      * Answers the ending position of a given line number. This line has to have been encountered
89      * already in the tokenization process (in other words, it cannot be used to compute positions of lines beyond
90      * current token). Once the entire source has been processed, it can be used without any limit.
91      * Line ending positions are zero-based, and correspond to the last character of the line separator
92      * (in case multi-character line separators).
93      *
94      * @param lineNumber the given line number
95      * @return the ending position of a given line number
96      **/

97     int getLineEnd(int lineNumber);
98
99     /**
100      * Answers an array of the ending positions of the lines encountered so far. Line ending positions
101      * are zero-based, and correspond to the last character of the line separator (in case multi-character
102      * line separators).
103      *
104      * @return an array of the ending positions of the lines encountered so far
105      */

106     int[] getLineEnds();
107
108     /**
109      * Answers a 1-based line number using the lines which have been encountered so far. If the position
110      * is located beyond the current scanned line, then the last line number will be answered.
111      *
112      * @param charPosition the given character position
113      * @return a 1-based line number using the lines which have been encountered so far
114      */

115     int getLineNumber(int charPosition);
116
117     /**
118      * Read the next token in the source, and answers its ID as specified by <code>ITerminalSymbols</code>.
119      * Note that the actual token ID values are subject to change if new keywords were added to the language
120      * (for instance, 'assert' is a keyword in 1.4).
121      *
122      * @throws InvalidInputException in case a lexical error was detected while reading the current token
123      * @return the next token
124      */

125     int getNextToken() throws InvalidInputException;
126
127     /**
128      * Answers the original source being processed (not a copy of it).
129      *
130      * @return the original source being processed
131      */

132     char[] getSource();
133
134     /**
135      * Reposition the scanner on some portion of the original source. The given endPosition is the last valid position.
136      * Beyond this position, the scanner will answer EOF tokens (<code>ITerminalSymbols.TokenNameEOF</code>).
137      *
138      * @param startPosition the given start position
139      * @param endPosition the given end position
140      */

141     void resetTo(int startPosition, int endPosition);
142
143     /**
144      * Set the scanner source to process. By default, the scanner will consider starting at the beginning of the
145      * source until it reaches its end.
146      * If the given source is <code>null</code>, this clears the source.
147      *
148      * @param source the given source
149      */

150     void setSource(char[] source);
151 }
152
Popular Tags