oracle.javatools.editor.language
Interface BraceProvider

All Known Subinterfaces:

ExtendedBraceProvider

All Known Implementing Classes:

AbstractBraceProvider, GenericBraceProvider

public interface BraceProvider

The BraceProvider interface provides the necessary routines to support matching-brace highlighting support in a language independent mechanism. The term brace is loosely defined as a character or set of characters which delimits the start or end of a language block.

Consider Java as an example, a language block may consist of an expression delimited by '(' and ')', or a block of statements delimited by '{' and '}', or the index operator of an array delimited by '[' and ']'. This interface allows languages to support braces which may consist of multiple characters.

Note that it is possible to find a matching brace, yet still have unbalanced braces between. For example, the following sequence is matched and balanced, "( [ ] )" for all braces. The following sequence is matched for the outer braces, but contains imbalanced braces inside, "( [ )". The last sequence is completely mismatched, "( ]".

See Also:

LanguageModule, LanguageSupport

Field Summary

static int	BALANCED_MATCH Constant indicating that the findMatchingBrace() operation found a matching brace, and that all braces contained within are balanced.
static int	MISMATCH Constant indicating that the findMatchingBrace() operation could not find a matching brace.
static int	UNBALANCED_MATCH Constant indicating that the findMatchingBrace() operation found a matching brace, but that at least one of the braces contained within is unbalanced.

Method Summary

int	findMatchingBrace(int tokenType, NumberRange braceLocation, NumberRange matchingLocation) Finds the brace matching the given brace identified by isPartOfBrace().
int	isPartOfBrace(int offset, NumberRange braceLocation) Determines whether the character at the given offset is considered a brace (such as '(', '[', or '{' in Java) or part of a brace in this language.

Field Detail

BALANCED_MATCH

static final int BALANCED_MATCH

Constant indicating that the findMatchingBrace() operation found a matching brace, and that all braces contained within are balanced. The outer braces for the following sequence are matched, and the contains braces within balanced, "( [ ] )".

See Also:

Constant Field Values

UNBALANCED_MATCH

static final int UNBALANCED_MATCH

Constant indicating that the findMatchingBrace() operation found a matching brace, but that at least one of the braces contained within is unbalanced. The outer braces for the following sequence are matched, but contains an unbalanced brace within, "( [ )".

See Also:

Constant Field Values

MISMATCH

static final int MISMATCH

Constant indicating that the findMatchingBrace() operation could not find a matching brace. Both braces in the following sequence are mismatched, "( ]".

See Also:

Constant Field Values

Method Detail

isPartOfBrace

int isPartOfBrace(int offset,
                  NumberRange braceLocation)

Determines whether the character at the given offset is considered a brace (such as '(', '[', or '{' in Java) or part of a brace in this language. It is conceivable that the brace may consist of multiple characters in certain languages. The NumberRange object passed in by the caller is filled in by this routine to indicate the start and end of the brace at the given offset provided. This routine returns a language-specific token type corresponding to the given brace at the offset, or -1 (Lexer.NOT_FOUND) if the offset is not part of a brace.

Parameters:

offset - the offset in the document associated with the specific LanguageSupport to check if it is a brace

braceLocation - an out parameter to pass start and end offset information to the caller if the provided brace offset is indeed part of a brace

Returns:

a language-specific token type (which should not be interpreted by callers) that should be passed to findMatchingBrace() to find the matching brace.

findMatchingBrace

int findMatchingBrace(int tokenType,
                      NumberRange braceLocation,
                      NumberRange matchingLocation)

Finds the brace matching the given brace identified by isPartOfBrace(). If a matching brace is found, the matchingLocation is filled in with the start and end offsets of the matching brace, and either BALANCED_MATCH or UNBALANCED_MATCH returned depending on whether the braces in between are balanced. If a matching brace is not found, then MISMATCH will be returned, and the contents of matchingLocation are undefined.

Parameters:

tokenType - the language-specific token type returned by isPartOfBrace().

braceLocation - the brace location filled in by isPartOfBrace()

matchingLocation - an out parameter to pass start and end offset information to the caller if a matching brace was found

Returns:

BALANCED_MATCH, UNBALANCED_MATCH, or MISMATCH to indicate the result of the match operation