KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > de > susebox > jtopas > Flags


1 /*
2  * Flags.java: commonly used constants.
3  *
4  * Copyright (C) 2004 Heiko Blau
5  *
6  * This file belongs to the JTopas Library.
7  * JTopas is free software; you can redistribute it and/or modify it
8  * under the terms of the GNU Lesser General Public License as published by the
9  * 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;
32
33
34 //-----------------------------------------------------------------------------
35 // Interface Flags
36 //
37
38 /**
39  * The interface defines flags that are used by various classes during tokenizing.
40  * A flag can be set in three ways:
41  *<ul><li>
42  * Globally for a {@link TokenizerProperties} object: The setting affects all
43  * {@link Tokenizer} instances that share this <code>TokenizerProperties</code>
44  * object as well as the {@link TokenizerProperty} objects registered in this
45  * <code>TokenizerProperties</code> that do haven't set the flag locally.
46  *</li><li>
47  * Separately for a {@link Tokenizer} (see {@link Tokenizer#changeParseFlags}:
48  * A single <code>Tokenizer</code> will behave differently to the setting in
49  * the used {@link TokenizerProperties} object, but still follow the setting
50  * for a single {@link TokenizerProperty} object. Only a limited number of
51  * flags can be set for a <code>Tokenizer</code>, especially the flags that
52  * are "dynamic", applicable more for the tokenizing process than describing
53  * an attribute of a {@link TokenizerProperty}, e. g. {@link #F_COUNT_LINES}
54  * and {@link #F_KEEP_DATA}.
55  *</li><li>
56  * Specifically for a single {@link TokenizerProperty}: This setting affects
57  * only the handling of the property and overrules both settings for the
58  * {@link TokenizerProperties} that contains the property, and settings for a
59  * {@link Tokenizer} using the <code>TokenizerProperties</code> object. Only
60  * a limited number of flags can be set for a singel property including the
61  * descriptive flags like {@link #F_NO_CASE}, {@link #F_ALLOW_NESTED_COMMENTS}
62  * and {@link #F_SINGLE_LINE_STRING}.
63  *</li></ul>
64  *
65  * @see TokenizerProperties
66  * @author Heiko Blau
67  */
68 public interface Flags {
69   
70   /**
71    * When this flag is set globally for a {@link TokenizerProperties} instance
72    * (see {@link #setParseFlags}, input data is generally treated case-insensitive.
73    * Specific properties may still be treated case-sensitive. Set this flag set
74    * in the flag mask and cleared in the corresponding flags).
75    *<br>
76    * Implementation note: The flag should be applicable for both {@link TokenizerProperties}
77    * and {@link TokenizerProperty} instances. It should not to be used
78    * dynamically ({@link Tokenizer#changeParseFlags}).
79    */
80   public static final short F_NO_CASE = 0x0001;
81
82   /**
83    * General compare operations are case-sensitive, that means 'A' equals 'A'
84    * but not 'a'. It is not nessecary to set this flag, since case-sensitive
85    * comparison is the default.
86    *<br>
87    * The flag was mainly used in conjunction with {@link #F_NO_CASE}. If
88    * <code>F_NO_CASE</code> is set via {@link TokenizerProperties#setParseFlags},
89    * <code>F_CASE</code> can be used for single properties where case-sensitivity
90    * is nessecary inspite of the global case-insensitivity.
91    *<br>
92    * If neither <code>F_CASE</code> nor <code>F_NO_CASE</code> is set, <code>F_CASE</code>
93    * is assumed. If both flags are set, <code>F_CASE</code> takes preceedence.
94    *<br>
95    * Implementation note: The flag should be applicable for both {@link TokenizerProperties}
96    * and {@link TokenizerProperty} instances. It should not to be used
97    * dynamically ({@link Tokenizer#changeParseFlags}).
98    *
99    * @deprecated for properties with a case handling different to the global
100    * settings of a {@link TokenizerProperties} instance use
101    * the constructor {@link TokenizerProperty(int, java.lang.String[], java.lang.Object, int, int)}
102    */
103   public static final short F_CASE = 0x0002;
104
105   /**
106    * For performance and memory reasons, this flag is used to avoid copy operations
107    * for every token. The token image itself is not returned in a {@link Token}
108    * instance, only its position and length in the input stream.
109    *<br>
110    * Implementation note: The flag should be applicable for {@link TokenizerProperties},
111    * and {@link TokenizerProperty} instances. It should also be a dynamic flag
112    * that can be switched on and off during runtime using {@link Tokenizer#changeParseFlags}.
113    */
114   public static final short F_TOKEN_POS_ONLY = 0x0010;
115
116   /**
117    * Set this flag to let a {@link Tokenizer} buffer all data. Usually, a tokenizer
118    * will apply a strategie to allocate only a reasonable amount of memory.
119    *<br>
120    * Implementation note: The flag should be applicable for {@link TokenizerProperties}
121    * and {@link Tokenizer} objects, but not for single {@link TokenizerProperty}
122    * instances. It could also be a dynamic flag that can be switched on and off
123    * during runtime of a tokenizer ({@link Tokenizer#changeParseFlags}), although
124    * it is generally set before parsing starts.
125    */
126   public static final short F_KEEP_DATA = 0x0020;
127
128   /**
129    * Tells a {@link Tokenizer} to count lines and columns. The tokenizer may use
130    * {@link java.lang.System.getProperty}<code>("line.separator")</code> to
131    * obtain the end-of-line sequence or accept different line separator sequences
132    * for a better portability: single carriage return (Mac OS), single line feed
133    * (Unix), combination of carriage return and line feed (Windows OS).
134    *<br>
135    * Usually, the end-of-line characters '\r' and '\n' are whitespaces. If they
136    * are also part of one or more special sequences or pattern, it is
137    * <strong>NOT</strong> guaranteed that the line counting mechanism of a
138    * {@link Tokenizer} implementation finds these occurences. This is in order to
139    * maintain a good performance, since otherwise there would be a potential huge
140    * amount of unsuccessfull newline scans in these tokens. Consider defining
141    * special sequences for '\r', '\n' and '\r\n' alone and remove them from the
142    * whitespace set, if You cannot live with the described limitation.
143    *<br>
144    * Implementation note: The flag should be applicable for {@link TokenizerProperties}
145    * and {@link Tokenizer} objects, but not for single {@link TokenizerProperty}
146    * instances. It could also be a dynamic flag that can be switched on and off
147    * during runtime of a tokenizer, although it is generally set before parsing
148    * starts.
149    */
150   public static final short F_COUNT_LINES = 0x0040;
151
152   /**
153    * Nested block comments are normally not allowed. This flag changes the
154    * default behaviour.
155    *<br>
156    * Implementation note: The flag should be applicable for both {@link TokenizerProperties}
157    * and {@link TokenizerProperty} instances. It should not to be used
158    * dynamically (as in versions of JTopas prior to 0.8).
159    */
160   public static final short F_ALLOW_NESTED_COMMENTS = 0x0080;
161   
162   /**
163    * Treat pattern the same way as whitespaces, separators or special sequences.
164    * Pattern of this type are recognized anywhere outside comments and strings.
165    * They terminate normal token. In fact, strings and comments could be
166    * described as free pattern.
167    *<br>
168    * Without this flag, pattern are treated in the same way as normal token.
169    * They are preceeded and followed by whitespaces, separators or special sequences.
170    *<br>
171    * Implementation note: The flag should be applicable for both {@link TokenizerProperties}
172    * and {@link TokenizerProperty} instances. It should not to be used
173    * dynamically.
174    */
175   public static final short F_FREE_PATTERN = 0x0100;
176   
177   /**
178    * Return simple whitespaces. These whitespaces are the ones set by
179    * {@link #setWhitespaces}. The flag is part of the composite mask
180    * {@link #F_RETURN_WHITESPACES}.
181    *<br>
182    * Implementation note: The flag should be applicable for {@link TokenizerProperties}
183    * and {@link Tokenizer}, but not for single {@link TokenizerProperty}
184    * instances. It is also a dynamic flag that can be switched on and off
185    * during runtime of a tokenizer (<strong>Note:</strong>: Flags for a single
186    * {@link TokenizerProperty} take precedence over other settings).
187    */
188   public static final short F_RETURN_SIMPLE_WHITESPACES = 0x0200;
189   
190   /**
191    * Return block comments. The flag is part of the composite mask
192    * {@link #F_RETURN_WHITESPACES}.
193    *<br>
194    * Implementation note: The flag should be applicable for <code>TokenizerProperties</code>,
195    * {@link Tokenizer} and for single {@link TokenizerProperty} instances. It is
196    * also a dynamic flag that can be switched on and off during runtime of a
197    * tokenizer (<strong>Note:</strong>: Flags for a single {@link TokenizerProperty}
198    * take precedence over other settings).
199    */
200   public static final short F_RETURN_BLOCK_COMMENTS = 0x0400;
201   
202   /**
203    * Return line comments. The flag is part of the composite mask
204    * {@link #F_RETURN_WHITESPACES}.
205    *<br>
206    * Implementation note: The flag should be applicable for <code>TokenizerProperties</code>,
207    * {@link Tokenizer} and for single {@link TokenizerProperty} instances. It is
208    * also a dynamic flag that can be switched on and off during runtime of a
209    * tokenizer (<strong>Note:</strong>: Flags for a single {@link TokenizerProperty}
210    * take precedence over other settings).
211    */
212   public static final short F_RETURN_LINE_COMMENTS = 0x0800;
213   
214   /**
215    * In many cases, parsers are not interested in whitespaces. If You are, use
216    * this value to force the tokenizer to return whitespace sequences and comments
217    * as a token. Per default, the flag is not set.
218    *<br>
219    * You can control the whitespace policy with finer granularity by using the
220    * flags {@link #F_RETURN_SIMPLE_WHITESPACES}, {@link #F_RETURN_BLOCK_COMMENTS}
221    * and {@link #F_RETURN_LINE_COMMENTS} either by setting it generally for
222    * a {@link TokenizerProperties} or a single {@link Tokenizer} object or even
223    * more specific for a single {@link TokenizerProperties}.
224    */
225   public static final short F_RETURN_WHITESPACES = F_RETURN_SIMPLE_WHITESPACES
226                                                   + F_RETURN_BLOCK_COMMENTS
227                                                   + F_RETURN_LINE_COMMENTS;
228   
229   /**
230    * Per default, strings are all characters between and including a pair of
231    * string start and end sequences, regardless if there are line separators in
232    * between. This flag changes that behaviour for the <code>TokenizerProperties</code>
233    * instance in general or for a single string property.
234    *<br>
235    * Implementation note: The flag should be applicable for both <code>TokenizerProperties</code>
236    * and {@link TokenizerProperty} instances. It should not to be used
237    * dynamically.
238    */
239   public static final short F_SINGLE_LINE_STRING = 0x1000;
240   
241   /**
242    * By setting this flag for a {@link TokenizerProperties} instance, a
243    * {@link Tokenizer} or for a single property, a tokenizer returns not only
244    * the token images but also image parts (see {@link Token#getImageParts}).
245    *<br>
246    * Implementation note: The flag should be applicable for {@link TokenizerProperties},
247    * {@link Tokenizer} and for single {@link TokenizerProperty} instances.
248    */
249   public static final short F_RETURN_IMAGE_PARTS = 0x4000;
250 }
251
Popular Tags