01: /*
02: * WhitespaceHandler.java: whitespace handling in tokenizers.
03: *
04: * Copyright (C) 2002 Heiko Blau
05: *
06: * This file belongs to the JTopas Library.
07: * JTopas is free software; you can redistribute it and/or modify it
08: * under the terms of the GNU Lesser General Public License as published by the
09: * Free Software Foundation; either version 2.1 of the License, or (at your
10: * option) any later version.
11: *
12: * This software is distributed in the hope that it will be useful, but WITHOUT
13: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14: * FITNESS FOR A PARTICULAR PURPOSE.
15: * See the GNU Lesser General Public License for more details.
16: *
17: * You should have received a copy of the GNU Lesser General Public License along
18: * with JTopas. If not, write to the
19: *
20: * Free Software Foundation, Inc.
21: * 59 Temple Place, Suite 330,
22: * Boston, MA 02111-1307
23: * USA
24: *
25: * or check the Internet: http://www.fsf.org
26: *
27: * Contact:
28: * email: heiko@susebox.de
29: */
30:
31: package de.susebox.jtopas.spi;
32:
33: //-----------------------------------------------------------------------------
34: // Imports
35: //
36: import de.susebox.jtopas.TokenizerException;
37:
38: //-----------------------------------------------------------------------------
39: // Interface WhitespaceHandler
40: //
41:
42: /**<p>
43: * This interface declares the methods a {@link de.susebox.jtopas.Tokenizer} needs
44: * to deal with whitespaces.
45: *</p><p>
46: * Whitespaces are single characters that separate other tokens. In programming
47: * languages, the item whitespace also refers to comments. This does not apply
48: * to a <code>WhitespaceHandler</code> that only recognizes single characters.
49: * Comments are handled by the {@link SequenceHandler} interface.
50: *</p>
51: *
52: * @see de.susebox.jtopas.Tokenizer
53: * @see de.susebox.jtopas.TokenizerProperties
54: * @see de.susebox.jtopas.spi.DataMapper
55: * @see SequenceHandler
56: * @author Heiko Blau
57: */
58: public interface WhitespaceHandler {
59:
60: /**
61: * This method checks if the given character is a whitespace.
62: *
63: * @param testChar check this character
64: * @return <code>true</code> if the given character is a whitespace,
65: * <code>false</code> otherwise
66: * @see de.susebox.jtopas.TokenizerProperties#setWhitespaces
67: */
68: public boolean isWhitespace(char testChar);
69:
70: /**
71: * This method detects the number of whitespace characters the data range given
72: * through the {@link DataProvider} parameter starts with. An implementation
73: * should use a {@link de.susebox.jtopas.TokenizerException} to report problems.
74: *
75: * @param dataProvider the source to get the data range from
76: * @return number of whitespace characters starting from the given offset
77: * @throws TokenizerException generic exception
78: * @throws NullPointerException if no {@link DataProvider} is given
79: * @see DataProvider
80: */
81: public int countLeadingWhitespaces(DataProvider dataProvider)
82: throws TokenizerException, NullPointerException;
83:
84: /**
85: * If a {@link de.susebox.jtopas.Tokenizer} performs line counting, it is often
86: * nessecary to know if newline characters (Carriage return and line feed) are
87: * (currently) considered to be whitespaces, which is most often the case.
88: * This method informs interested callers about the current condition.
89: *<br>
90: * Note that this method should return <code>true</code> only if both newline
91: * characters are part of the current whitespace set.
92: *
93: * @return <code>true</code> if newline characters are in the current whitespace set,
94: * <code>false</code> otherwise
95: */
96: public boolean newlineIsWhitespace();
97: }
|