KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > spi > lexer > CharPreprocessor


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.netbeans.spi.lexer;
21
22 import org.netbeans.lib.lexer.CharPreprocessorOperation;
23 import org.netbeans.lib.lexer.UnicodeEscapesPreprocessor;
24
25
26 /**
27  * Character preprocessor allows to translate a sequence
28  * of characters to a single character so it may be used
29  * for example for Unicode sequences translation.
30  * <br/>
31  * If there are any preprocessed characters for a particular token
32  * then a special token instance get created that provides
33  * the preprocessed chars.
34  *
35  * @author Miloslav Metelka
36  * @version 1.00
37  */
38
39 public abstract class CharPreprocessor {
40     
41     /**
42      * Create instance of character preprocessor for Unicode escape sequences.
43      */
44     public static CharPreprocessor createUnicodeEscapesPreprocessor() {
45         return new UnicodeEscapesPreprocessor();
46     }
47
48     private CharPreprocessorOperation operation;
49     
50
51     /**
52      * Preprocess at least one character of the input.
53      * <br/>
54      * Preprocessor must always preprocess at least one input character
55      * per invocation but only a minimum necessary number of characters
56      * should be preprocessed by each invocation of this method.
57      *
58      * <p>
59      * Example:
60      * <pre>
61      * public void preprocessChar() {
62      * switch (ch = inputRead()) {
63      * case '\\': // possible start of sequence
64      * switch (ch = inputRead()) {
65      * case 'u': // start of escape sequence
66      * ... // read the whole sequence
67      * outputPreprocessed(prepCh, extraInputLength);
68      * break;
69      * default:
70      * outputOriginal('\\');
71      * outputOriginal(ch);
72      * break;
73      * }
74      * break;
75      * default:
76      * outputOriginal(ch);
77      * }
78      * }
79      * </pre>
80      * </p>
81      *
82      * <p>
83      * The processor is only designed to do several-chars-to-one translation.
84      * <br/>
85      * It is not designed to return more than one character for a single input char.
86      * <br/>
87      * Also if the character is really preprocessed it must be composed
88      * from at least two input characters (see extraInputLength parameter
89      * of {@link #outputPreprocessed(char, int)}.
90      * </p>
91      *
92      * <p>
93      * The preprocessor must be able to process all the characters
94      * given to it on input.
95      * However it should not preprocess EOF in any way
96      * - the EOF is just information that there is an end of the input
97      * and any possibly unfinished escape sequence needs to be translated
98      * in a reasonable way.
99      * <br/>
100      * Once all the characters prior EOF were preprocessed the EOF
101      * should be returned by {@link #outputOriginal(int)}.
102      * </p>
103      *
104      */
105     protected abstract void preprocessChar();
106     
107     /**
108      * Check whether the given character may be part of the sequences preprocessed
109      * by this preprocessor.
110      * <br/>
111      * The infrastructure may use this method to test whether it can start
112      * relexing starting at a particular position.
113      */
114     protected abstract boolean isSensitiveChar(char ch);
115     
116     /**
117      * Return maximum number of extra characters (not being part of the recognized
118      * sequence) that this preprocessor
119      * may look ahead in order to recognize the preprocessed character sequence.
120      * <br/>
121      * For example for unicode escape sequences the returned number is 1
122      * (see UnicodeEscapesPreprocessor implementation for details).
123      */
124     protected abstract int maxLookahead();
125     
126     /**
127      * Read a single character for preprocessing from the underlying input.
128      *
129      * @return valid character or {@link LexerInput#EOF} if there are no more
130      * characters available on the input.
131      */
132     protected final int inputRead() {
133         return operation.inputRead();
134     }
135     
136     /**
137      * Backup a given number of input characters.
138      *
139      * @param count >=0 number of chars to backup.
140      */
141     protected final void inputBackup(int count) {
142         operation.inputBackup(count);
143     }
144     
145     /**
146      * Output the character as it was read from the input.
147      * <br/>
148      * By using this method the infrastructure knows that the character
149      * is the same like the original character read by {@link #inputRead()}.
150      */
151     protected final void outputOriginal(int ch) {
152         operation.outputOriginal(ch);
153     }
154
155     /**
156      * Output preprocessed character. There is usually more than one input character
157      * forming a single preprocessed character.
158      *
159      * @param ch preprocessed character.
160      * @param extraInputLength >0 number of extra input characters
161      * (besides a single character) that form the preprocessed character.
162      * <br/>
163      * For example for unicode escape sequence " " it's 6-1=5.
164      * <br/>
165      * The number is expected to be greater than zero
166      * (otherwise the present implementation would not work correctly).
167      * which should be fine for the known implementations
168      * (if not please request an API change).
169      */
170     protected final void outputPreprocessed(char ch, int extraInputLength) {
171         assert (extraInputLength > 0) : "extraInputLength > 0 expected.";
172         operation.outputPreprocessed(ch, extraInputLength);
173     }
174     
175     /**
176      * Notify the error that occurred during preprocessing of the current character.
177      *
178      * @param errorMessage non-null error description.
179      */
180     protected final void notifyError(String JavaDoc errorMessage) {
181         operation.notifyError(errorMessage);
182     }
183
184     void init(CharPreprocessorOperation operation) {
185         this.operation = operation;
186     }
187
188 }
189
Popular Tags