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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags