TokenId


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.api.lexer;
21  
22  /**
23   * Identifier of a token (could also be called a token-type).
24   * <br>
25   * It is not a token, because it does not contain
26   * the text (also called image) of the token.
27   *
28   * <p>
29   * Token ids are typically defined as enums by the following pattern:
30   * <pre>
31   * public enum JavaTokenId implements TokenId {
32   *
33   *     ERROR(null, "error"),
34   *     IDENTIFIER(null, "identifier"),
35   *     ABSTRACT("abstract", "keyword"),
36   *     ...
37   *     SEMICOLON(";", "separator"),
38   *     ...
39   *
40   *
41   *     private final String fixedText; // Used by lexer for production of flyweight tokens
42   *
43   *     private final String primaryCategory;
44   *
45   *     JavaTokenId(String fixedText, String primaryCategory) {
46   *         this.fixedText = fixedText;
47   *         this.primaryCategory = primaryCategory;
48   *     }
49   *
50   *     public String fixedText() {
51   *         return fixedText;
52   *     }
53   *
54   *     public String primaryCategory() {
55   *         return primaryCategory;
56   *     }
57   *
58   * }
59   * </pre>
60   *
61   * <p>
62   * Token ids can also be generated (e.g. by lexer generation tools)
63   * by using {@link org.netbeans.spi.lexer.LanguageHierarchy#newId(String,int,String)} method.
64   * <br>
65   * All token ids of a language must have both
66   * unique ordinal and name.
67   * <br/>
68   * Token name should be all uppercase while token categories should be named
69   * in lowercase.
70   *
71   * <p>
72   * Detailed information and rules for naming can be found
73   * in <A HREF="http://lexer.netbeans.org/doc/token-id-naming.html">TokenId Naming</A>.
74   *
75   * @author Miloslav Metelka
76   * @version 1.00
77   */
78  
79  public interface TokenId {
80      
81      /**
82       * Get name of this tokenId.
83       * <p>
84       * It can serve for several purposes such as finding
85       * a possible style information for the given token.
86       * </p>
87       *
88       * @return non-null unique name of the TokenId. The name must be unique
89       *  among other TokenId instances of the particular language
90       *  where it is defined. The name should consist of
91       *  uppercase alphanumeric letters and underscores only.
92       */
93      String   name();
94  
95      /**
96       * Get integer identification of this tokenId.
97       *
98       * @return numeric identification of this TokenId.
99       *  <BR>
100      *  Ordinal must be a non-negative
101      *  integer unique among all the tokenIDs inside the language
102      *  where it is declared.
103      *  <BR>
104      *  The ordinals are usually defined and adopted from lexer
105      *  generator tool that generates the lexer for the given language.
106      *  <BR>
107      *  They do not have to be consecutive.
108      *  <br>
109      *  On they other hand there should
110      *  not be big gaps (e.g. 100 or more) because
111      *  indexing arrays are constructed based on the ordinal values
112      *  so the length of the indexing array corresponds
113      *  to the highest ordinal of all the token ids declared
114      *  for the particular language.
115      *  <BR>
116      *  The intIds allow more efficient use
117      *  of the tokenIds in switch-case statements.
118      */
119     int ordinal();
120 
121     /**
122      * Get name of primary token category into which this token belongs.
123      * <br/>
124      * Other token categories for this id can be defined in the language hierarchy.
125      *
126      * @return name of the primary token category into which this token belongs
127      *  or null if there is no primary category for this token.
128      */
129     String   primaryCategory();
130     
131 }
132
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags