001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.api.lexer;
043:
044: /**
045: * Identifier of a token (could also be called a token-type).
046: * <br>
047: * It is not a token, because it does not contain
048: * the text (also called image) of the token.
049: *
050: * <p>
051: * Token ids are typically defined as enums by the following pattern:
052: * <pre>
053: * public enum JavaTokenId implements TokenId {
054: *
055: * ERROR(null, "error"),
056: * IDENTIFIER(null, "identifier"),
057: * ABSTRACT("abstract", "keyword"),
058: * ...
059: * SEMICOLON(";", "separator"),
060: * ...
061: *
062: *
063: * private final String fixedText; // Used by lexer for production of flyweight tokens
064: *
065: * private final String primaryCategory;
066: *
067: * JavaTokenId(String fixedText, String primaryCategory) {
068: * this.fixedText = fixedText;
069: * this.primaryCategory = primaryCategory;
070: * }
071: *
072: * public String fixedText() {
073: * return fixedText;
074: * }
075: *
076: * public String primaryCategory() {
077: * return primaryCategory;
078: * }
079: *
080: * }
081: * </pre>
082: *
083: * <p>
084: * Token ids can also be generated (e.g. by lexer generation tools)
085: * by using {@link org.netbeans.spi.lexer.LanguageHierarchy#newId(String,int,String)} method.
086: * <br>
087: * All token ids of a language must have both
088: * unique ordinal and name.
089: * <br/>
090: * Token name should be all uppercase while token categories should be named
091: * in lowercase.
092: *
093: * <p>
094: * Detailed information and rules for naming can be found
095: * in <A href="http://lexer.netbeans.org/doc/token-id-naming.html">TokenId Naming</A>.
096: *
097: * @author Miloslav Metelka
098: * @version 1.00
099: */
100:
101: public interface TokenId {
102:
103: /**
104: * Get name of this tokenId.
105: * <p>
106: * It can serve for several purposes such as finding
107: * a possible style information for the given token.
108: * </p>
109: *
110: * @return non-null unique name of the TokenId. The name must be unique
111: * among other TokenId instances of the particular language
112: * where it is defined. The name should consist of
113: * uppercase alphanumeric letters and underscores only.
114: */
115: String name();
116:
117: /**
118: * Get integer identification of this tokenId.
119: *
120: * @return numeric identification of this TokenId.
121: * <BR>
122: * Ordinal must be a non-negative
123: * integer unique among all the tokenIDs inside the language
124: * where it is declared.
125: * <BR>
126: * The ordinals are usually defined and adopted from lexer
127: * generator tool that generates the lexer for the given language.
128: * <BR>
129: * They do not have to be consecutive.
130: * <br>
131: * On they other hand there should
132: * not be big gaps (e.g. 100 or more) because
133: * indexing arrays are constructed based on the ordinal values
134: * so the length of the indexing array corresponds
135: * to the highest ordinal of all the token ids declared
136: * for the particular language.
137: * <BR>
138: * The intIds allow more efficient use
139: * of the tokenIds in switch-case statements.
140: */
141: int ordinal();
142:
143: /**
144: * Get name of primary token category into which this token belongs.
145: * <br/>
146: * Other token categories for this id can be defined in the language hierarchy.
147: *
148: * @return name of the primary token category into which this token belongs
149: * or null if there is no primary category for this token.
150: */
151: String primaryCategory();
152:
153: }
|