TokenizerProperty


1   /*
2    * TokenizerProperty.java: Various characteristics of Tokenizer.
3    *
4    * Copyright (C) 2002 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  // Imports
35  //
36  
37  
38  //-----------------------------------------------------------------------------
39  // Class TokenizerProperty
40  //
41  
42  /**<p>
43   * This class is mainly used by {@link TokenizerProperties} implementations to 
44   * return {@link java.util.Iterator} objects of their various properties (keywords, 
45   * special sequences etc.). Moreover, it can be used whereever information about
46   * a lexical element description is needed, for instance when firing a 
47   * {@link TokenizerPropertyEvent}.
48   *</p><p>
49   * This class replaces the older {@link de.susebox.java.util.TokenizerProperty}
50   * class which is deprecated.
51   *</p>
52   *
53   * @see     TokenizerProperties
54   * @author  Heiko Blau
55   */
56  public class TokenizerProperty {
57    
58    //---------------------------------------------------------------------------
59    // special property types
60    //
61    
62    /**
63     * The property describes a parse flag mask. This type is nessecary for the
64     * "parse flag changed" event fired by {@link TokenizerProperties} 
65     * implementations.
66     */
67    public static final byte PARSE_FLAG_MASK = 127;
68    
69    
70    //---------------------------------------------------------------------------
71    // getter- and setter methods
72    //
73    
74    /**
75     * Setting the type of the <code>TokenizerProperty</code>. Usually, one of the 
76     * constants defined in {@link Token} is passed to this method, for instance 
77     * {@link Token#NORMAL}, {@link Token#KEYWORD} or {@link Token#WHITESPACE}.
78     *<br>
79     * However, implementations and subclasses of the interfaces and classes in the 
80     * package {@link de.susebox.jtopas} may define, set and return their own type 
81     * constants.
82     *
83     * @param type type of the tokenizer property (one of the {@link Token} constants)
84     * @see Token
85     * @see #getType
86     */  
87    public void setType(int type) {
88      _type = type;
89    }
90      
91    /**
92     * Retrieving the type of this property. Usually, one of the constants defined 
93     * in {@link Token} is returned, for instance {@link Token#NORMAL}, {@link Token#KEYWORD} 
94     * or {@link Token#WHITESPACE}. However, implementations and subclasses of the
95     * interfaces and classes in the package {@link de.susebox.jtopas} may define,
96     * set and return their own type constants.
97     *
98     * @return type of the property
99     * @see #setType
100    */  
101   public int getType() {
102     return _type;
103   }
104 
105   /**
106    * Setting flags. These flags are not specified here. Usually, a combination
107    * of {@link TokenizerProperties} <code>F_...</code> constants is used here.
108    *<br>
109    * The method is equivalent to <code>{@link #setFlags(int, int)}(flags, flags)</code>.
110    *
111    * @param flags   a bitmask
112    * @see   #getFlags
113    */  
114   public void setFlags(int flags) {
115     setFlags(flags, flags);
116   }
117     
118   /**
119    * Setting the values for the flags contained in the flag mask. The flags 
120    * are not specified here. Usually, a combination of {@link TokenizerProperties} 
121    * <code>F_...</code> constants is used here.
122    *<br>
123    * The flag mask contains the set flags that are valid for this 
124    * <code>TokenizerProperty</code>. Flags that are not contained in the flag mask, 
125    * have an "unknown" value in this instance.
126    *<br>
127    * A flag mask value of -1 means that all flags should are valid. <code>flag = 0</code>
128    * and <code>flagMask = TokenizerProperties.F_CASE</code> means that the property
129    * is case-insensitive, but there are no other characteristics explicitely set
130    * for this property.
131    *<br>
132    *
133    * @param flags     a bitmask of flags to be set or clear
134    * @param flagMask  a bitmask containing the flags that are valid in <code>flags</code>
135    * @see   #getFlags
136    */  
137   public void setFlags(int flags, int flagMask) {
138     _flags    = (flags & flagMask);
139     _flagMask = flagMask;
140   }
141     
142   /**
143    * Retrieving the flags of this property. 
144    *
145    * @return flags of the property
146    * @see #setFlags
147    * @see #getFlags(int)
148    */  
149   public int getFlags() {
150     return _flags;
151   }
152 
153   /**
154    * Retrieving the current flag mask containing the bits that are valid in the
155    * return value of {@link #getFlags}. The return value -1 means that all bits
156    * in <code>getFlags</code> are explicitely set for this property.
157    *
158    * @return a bitmask containing the flags that are explicitely set for this property
159    * @see #getFlags()
160    * @see #setFlags(int, int)
161    */  
162   public int getFlagMask() {
163     return _flagMask;
164   }
165   
166   /**
167    * Checks wether a given flag is set or cleared for this property. The default
168    * value is returned if the current flag mask (see {@link #getFlagMask}) does
169    * not contain the given flag. This is the case if {@link #containsFlag} would
170    * return <code>false</code> for the given flag.
171    *<br>
172    * If <code>containsFlag</code> returns <code>true</code> for the given flag,
173    * <code>isFlagSet</code> returns <code>true</code> only if the all bits in the 
174    * given flag are in the current flags.
175    *
176    * @param   flag      the flag to check
177    * @param   defVal    the default value if the flag is not contained in the 
178    *                    current flag mask
179    * @return  <code>true</code> if the given flag is explicitely set or the default
180    *          value is <code>true</code>, <code>false</code> if the given flag is
181    *          explicitely cleared or the default value is <code>false</code>.
182    */
183   public boolean isFlagSet(int flag, boolean defVal) {
184     if (containsFlag(flag)) {
185       return (getFlags() & flag) == flag;
186     } else {
187       return defVal;
188     }
189   }
190 
191   /**
192    * Checks wether a given flag is in the current flag mask. That means that the
193    * property contains its own explicit value for the flag.
194    *<br>
195    * The method can be used in combination with {@link #isFlagSet} to determine
196    * wether the return value of <code>isFlagSet</code> is actually the default 
197    * value given to that method, or the flag value of the property itself.
198    *<br>
199    * The method returns <code>true</code> only if the all bits in the given flag
200    * are in the current flag mask.
201    *
202    * @param   flag      the flag to check
203    * @param   defVal    the default value if the flag is not contained in the 
204    *                    current flag mask
205    * @return  <code>true</code> if the given flag is explicitely set or the default
206    *          value is <code>true</code>, <code>false</code> if the given flag is
207    *          explicitely cleared or the default value is <code>false</code>.
208    */
209   public boolean containsFlag(int flag) {
210     return (getFlagMask() & flag) == flag;
211   }
212 
213   /**
214    * Images of lexical elements are quite different. Starting sequences of line 
215    * comments, keywords  and special sequences are strings representing only 
216    * themselfes. Whitespaces and separators are represented as string consisting 
217    * of the single whitespace and separator characters and / or character ranges.
218    *<br>
219    * A block comment is represented an array of two strings. The first is the 
220    * starting sequence, the second the finishing sequence. The same is true for
221    * string elements. However, string elements usually have an escape sequence.
222    *
223    * @param   images  the characterising images of a lexical element
224    */
225   public void setImages(String  [] images) throws IllegalArgumentException   {
226     _images = images;
227   }
228     
229   /**
230    * Retrieving the one or more images a lexical element description has.
231    *
232    * @return the array with images like string start and end sequences etc.
233    * @see #setImages
234    */
235   public String  [] getImages() {
236     return _images;
237   }
238     
239   /**
240    * Some token may have associated informations for the user of the <code>Token</code>.
241    * A popular thing would be the association of an integer constant to a special
242    * sequence or keyword to be used in fast <code>switch</code> statetents.
243    *
244    * @param companion   the associated information for the lexical element
245    */  
246   public void setCompanion(Object   companion) {
247     _companion = companion;
248   }
249     
250   /**
251    * Obtaining the associated information of the token. Can be <code>null</code>. See
252    * {@link #setCompanion} for details.
253    *
254    * @return the associated information of this token
255    */  
256   public Object   getCompanion() {
257     return _companion;
258   }
259 
260   
261   //---------------------------------------------------------------------------
262   // construction
263   //
264   
265   /**
266    * Default constructor. Initializes a property with type {@link Token#UNKNOWN}
267    * and no images or flags.
268    */  
269   public TokenizerProperty() {
270     this(Token.UNKNOWN);
271   }
272   
273   /**
274    * Constructs a <code>TokenizerProperty</code> where only the type is known so
275    * far. For the type, one of the constants defined in {@link Token} must be 
276    * used.
277    *
278    * @param type the property type
279    */  
280   public TokenizerProperty(int type) {
281     this(type, null);
282   }
283   
284   /**
285    * Constructs a <code>TokenizerProperty</code> with type and image(s). For the 
286    * type, one of the constants defined in {@link Token} must be used.
287    *
288    * @param type    the property type
289    * @param images  the characterising images of a lexical element
290    */  
291   public TokenizerProperty(int type, String  [] images) {
292     this(type, images, null);
293   }
294   
295   /**
296    * Constructs a <code>TokenProperty</code> object with a set of type, image(s)
297    * and companion.
298    *
299    * @param type        the property type
300    * @param images      the characterising images of a lexical element
301    * @param companion   the associated information for the lexical element
302    */  
303   public TokenizerProperty(int type, String  [] images, Object   companion) {
304     this(type, images, companion, 0);
305   }
306   
307   /**
308    * Constructs a <code>TokenProperty</code> object with a set of type, image(s), 
309    * companion object and flags.
310    *
311    * @param type        the property type
312    * @param images      the characterising images of a lexical element
313    * @param companion   the associated information for the lexical element
314    * @param flags       the specific parse flags for this lexical element
315    */  
316   public TokenizerProperty(int type, String  [] images, Object   companion, int flags) {
317     this(type, images, companion, flags, flags);
318   }
319   
320   /**
321    * Constructs a <code>TokenProperty</code> object with a set of type, image(s), 
322    * companion object and flags with an associated flag mask ({@see #setFlags(int, int)} 
323    * for details). 
324    *
325    * @param type        the property type
326    * @param images      the characterising images of a lexical element
327    * @param companion   the associated information for the lexical element
328    * @param flags       the specific parse flags for this lexical element
329    * @param flagMask    which bits of the parse flags are actually valid
330    */  
331   public TokenizerProperty(int type, String  [] images, Object   companion, int flags, int flagMask) {
332     setType(type);
333     setImages(images);
334     setCompanion(companion);
335     setFlags(flags, flagMask);
336   }
337   
338   
339   //---------------------------------------------------------------------------
340   // overloaded methods
341   //
342   
343   /**
344    * Redefinition of the well-known {@link java.lang.Object#equals} method.
345    *
346    * @param   that  compare this instance with that object
347    * @return  <code>true</code> if the two object describe the same property,
348    *          <code>false</code> otherwise
349    */
350   public boolean equals(Object   that) {
351     // primitive tests
352     if (that == null) {
353       return false;
354     } else if (that == this) {
355       return true;
356     } else if ( ! (that.getClass() == getClass())) {
357       return false;
358     }
359     
360     // compare contents
361     TokenizerProperty thatProp = (TokenizerProperty)that;
362 
363     if (   getType()      == thatProp.getType()
364         && getCompanion() == thatProp.getCompanion()
365         && getFlags()     == thatProp.getFlags()) {
366       // compare images
367       String  [] thisImg = getImages();
368       String  [] thatImg = thatProp.getImages();
369       
370       if (thisImg != thatImg) {
371         if (thisImg == null || thatImg == null || thisImg.length != thatImg.length) {
372           return false;
373         }
374         for (int index = 0; index < thisImg.length; ++index) {
375           if ( ! thisImg[index].equals(thatImg[index])) {
376             return false;
377           }
378         }
379       }
380       return true;
381     } else {
382       return false;
383     }
384   }
385   
386   /**
387    * Redefinition of the well-known {@link java.lang.Object#toString} method.
388    *
389    * @return a string representation of this <code>TokenizerProperty</code>
390    */
391   public String   toString() {
392     StringBuffer    buffer = new StringBuffer  ();
393     
394     buffer.append(getClass().getName());
395     buffer.append(':');
396 
397     switch (getType()) {
398       case Token.NORMAL:
399         buffer.append(" NORMAL, ");
400         break;
401       case Token.BLOCK_COMMENT:
402         buffer.append(" BLOCK_COMMENT, ");
403         break;
404       case Token.LINE_COMMENT:
405         buffer.append(" LINE_COMMENT, ");
406         break;
407       case Token.STRING:
408         buffer.append(" STRING, ");
409         break;
410       case Token.PATTERN:
411         buffer.append(" PATTERN, ");
412         break;
413       case Token.KEYWORD:
414         buffer.append(" KEYWORD, ");
415         break;
416       case Token.WHITESPACE:
417         buffer.append(" WHITESPACE, ");
418         break;
419       case Token.SEPARATOR:
420         buffer.append(" SEPARATOR, ");
421         break;
422       case Token.SPECIAL_SEQUENCE:
423         buffer.append(" SPECIAL_SEQUENCE, ");
424         break;
425       case Token.EOF:
426         buffer.append(" EOF, ");
427         break;
428       case TokenizerProperty.PARSE_FLAG_MASK:
429         buffer.append(" PARSE FLAG MASK, ");
430         break;
431       default:
432         buffer.append(" UNKNOWN, ");
433     }
434     
435     // add the flags
436     buffer.append("flags/mask 0x");
437     buffer.append(Integer.toHexString(_flags));
438     buffer.append("/0x");
439     buffer.append(Integer.toHexString(_flagMask));
440     
441     // add images
442     if (_images != null) {
443       buffer.append(':');
444       for (int index = 0; index < _images.length; ++index) {
445         if (_images[index] != null) {
446           buffer.append(' ');
447           buffer.append(_images[index]);
448         } else {
449           break;
450         }
451       }
452     }
453     
454     // ready
455     return buffer.toString();
456   }
457   
458   //---------------------------------------------------------------------------
459   // implementation
460   //
461   
462   //---------------------------------------------------------------------------
463   // members
464   //
465   protected int       _type;
466   protected int       _flags;
467   protected int       _flagMask;
468   protected String  []  _images;
469   protected Object      _companion;
470 }
471
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags