org.netbeans.api.lexer

Class Language<T extends TokenId>

java.lang.Object

org.netbeans.api.lexer.Language<T>

public final class Language<T extends TokenId>
extends Object

Language describes a set of token ids that comprise the given language.
Each language corresponds to a certain mime-type.
An input source may be lexed by using an existing language - see TokenHierarchy which is an entry point into the Lexer API.
Language hierarchy is represented by an unmodifiable set of TokenIds that can be retrieved by Language.tokenIds() and token categories Language.tokenCategories().

The language cannot be instantiated directly.
Instead it should be obtained from LanguageHierarchy.language() on an existing language hierarchy.

See Also:

LanguageHierarchy, TokenId

Method Summary

Modifier and Type	Method and Description
String	dumpInfo() Dump list of token ids for this language into string.
boolean	equals(Object obj) The languages are equal only if they are the same objects.
static Language<? extends TokenId>	find(String mimeType) Finds a language by its mime type.
int	hashCode() The hashCode of the language is the identity hashCode.
int	maxOrdinal() Get maximum ordinal of all the token ids that this language contains.
Set<T>	merge(Collection<T> tokenIds1, Collection<T> tokenIds2) Merge two collections of token ids from this language into an efficient indexed set (the implementation similar to EnumSet).
String	mimeType() Gets the mime type of this language.
List<String>	nonPrimaryTokenCategories(T tokenId) Get list of non-primary token categories (not containing the primary category) for the particular token id.
Set<String>	tokenCategories() Get names of all token categories of this language.
List<String>	tokenCategories(T tokenId) Get list of all token categories for the particular token id.
Set<T>	tokenCategoryMembers(String tokenCategory) Get members of the category with given name.
T	tokenId(int ordinal) Get tokenId for the given ordinal.
T	tokenId(String name) Find the tokenId from its name.
Set<T>	tokenIds() Get unmodifiable set of ids contained in this language.
String	toString()
T	validTokenId(int ordinal) Similar to Language.tokenId(int) however it guarantees that it will always return non-null tokenId.
T	validTokenId(String name) Similar to Language.tokenId(String) but guarantees a valid tokenId to be returned.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

find

public static Language<? extends TokenId> find(String mimeType)

Finds a language by its mime type.

This method uses information from LanguageProviders registered in the default lookup to find Language for a given mime type.

Netbeans provide an implementation of LanguageProvider that reads data from the Editors folder on the system filesystem. Therefore Netbeans modules can register their Languages in MimeLookup as any other mime-type related service.

Parameters:

mimeType - The mime type of a language that you want to find.

Returns:

The Language registered for the given mimeType. Null is returned for null mimeType.

tokenIds

public Set<T> tokenIds()

Get unmodifiable set of ids contained in this language.
An iterator over the set returns the ids sorted by their ordinals.

Returns:

unmodifiable set of ids contained in this language.

tokenId

public T tokenId(int ordinal)

Get tokenId for the given ordinal. This method can be used by lexers to quickly translate ordinal to tokenId.

Parameters:

ordinal - ordinal to be translated to corresponding tokenId.

Returns:

valid tokenId or null if there's no corresponding tokenId for the given int-id. It's possible because intIds of the language's token ids do not need to be continuous. If the ordinal is <0 or higher than the highest ordinal of all the token ids of this language the method throws IndexOutOfBoundsException.

Throws:

IndexOutOfBoundsException - if the ordinal is <0 or higher than Language.maxOrdinal().

validTokenId

public T validTokenId(int ordinal)

Similar to Language.tokenId(int) however it guarantees that it will always return non-null tokenId. Typically for a lexer just being developed it's possible that there are some integer token ids defined in the generated lexer for which there is no correspondence in the language. The lexer wrapper should always call this method if it expects to find a valid counterpart for given integer id.

Parameters:

ordinal - ordinal to translate to token id.

Returns:

always non-null tokenId that corresponds to the given integer id.

Throws:

IndexOutOfBoundsException - if the ordinal is <0 or higher than Language.maxOrdinal() or when there is no corresponding token id for it.

tokenId

public T tokenId(String name)

Find the tokenId from its name.

Parameters:

name - name of the tokenId to find.

Returns:

tokenId with the requested name or null if it does not exist.

validTokenId

public T validTokenId(String name)

Similar to Language.tokenId(String) but guarantees a valid tokenId to be returned.

Throws:

IllegalArgumentException - if no token in this language has the given name.

maxOrdinal

public int maxOrdinal()

Get maximum ordinal of all the token ids that this language contains.

Returns:

maximum integer ordinal of all the token ids that this language contains or -1 if the language contains no token ids.

tokenCategories

public Set<String> tokenCategories()

Get names of all token categories of this language.

Returns:

unmodifiable set containing names of all token categories contained in this language.

tokenCategoryMembers

public Set<T> tokenCategoryMembers(String tokenCategory)

Get members of the category with given name.

Parameters:

tokenCategory - non-null name of the category.

Returns:

set of token ids belonging to the given category.

tokenCategories

public List<String> tokenCategories(T tokenId)

Get list of all token categories for the particular token id.

Returns:

non-null unmodifiable list of all token categories for the particular token id.
Primary token's category (if defined for the token id) will be contained as first one in the list.

Throws:

IllegalArgumentException - if the given token id does not belong to this language.

nonPrimaryTokenCategories

public List<String> nonPrimaryTokenCategories(T tokenId)

Get list of non-primary token categories (not containing the primary category) for the particular token id.
If the token id has no primary category defined then the result of this method is equal to Language.tokenCategories(TokenId).

Returns:

non-null unmodifiable list of secondary token categories for the particular token id. Primary token's category (if defined for the token id) will not be contained in the list.

Throws:

IllegalArgumentException - if the given token id does not belong to this language.

merge

public Set<T> merge(Collection<T> tokenIds1,
                    Collection<T> tokenIds2)

Merge two collections of token ids from this language into an efficient indexed set (the implementation similar to EnumSet).

Parameters:

tokenIds1 - non-null collection of token ids to be contained in the returned set.

tokenIds2 - collection of token ids to be contained in the returned set.

Returns:

set of token ids indexed by their ordinal number.

mimeType

public String mimeType()

Gets the mime type of this language.

Returns:

non-null language's mime type.

equals

public boolean equals(Object obj)

The languages are equal only if they are the same objects.

Overrides:

equals in class Object

hashCode

public int hashCode()

The hashCode of the language is the identity hashCode.

Overrides:

hashCode in class Object

dumpInfo

public String dumpInfo()

Dump list of token ids for this language into string.

Returns:

dump of contents of this language.

toString

public String toString()

Overrides:

toString in class Object