KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > api > lexer > 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 JavaDoc 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 JavaDoc primaryCategory();
130     
131 }
132
Popular Tags