org.netbeans.spi.editor.bracesmatching.support
Class BracesMatcherSupport

java.lang.Object
  org.netbeans.spi.editor.bracesmatching.support.BracesMatcherSupport

public final class BracesMatcherSupport
extends Object

Some useful implementations of BracesMatcher.

Method Summary

static BracesMatcher	characterMatcher(MatcherContext context, int lowerBound, int upperBound, char... matchingPairs) Creates BracesMatcher for finding character pairs.
static BracesMatcher	defaultMatcher(MatcherContext context, int lowerBound, int upperBound) Creates the default BracesMatcher implementation.
static int[]	findChar(Document document, int offset, int limit, char... pairs) Finds a character in a document.
static int	matchChar(Document document, int offset, int limit, char origin, char matching) Searches for a matching character.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

defaultMatcher

public static BracesMatcher defaultMatcher(MatcherContext context,
                                           int lowerBound,
                                           int upperBound)

Creates the default BracesMatcher implementation. The default matcher is used when no other matcher is available. The default matcher is basically a character matcher, which looks for the following character pairs: '(', ')', '[', ']', '{', '}', '<', '>'.

Parameters:

context - The context for the matcher.

lowerBound - The start offset of the area where the created matcher should search. Can be -1 for no restriction.

upperBound - The end offset of the area where the crated matcher should search. Can be -1 for no restriction.

Returns:

The default matcher.

See Also:

characterMatcher(org.netbeans.spi.editor.bracesmatching.MatcherContext, int, int, char...)

characterMatcher

public static BracesMatcher characterMatcher(MatcherContext context,
                                             int lowerBound,
                                             int upperBound,
                                             char... matchingPairs)

Creates BracesMatcher for finding character pairs.

The character matcher looks for characters passed in as an array of paired characters that match each other. Any character from the array can be detected as the original character (area). The other character from the pair will then be used to search for the matching area.

The characters in each pair have to be listed in a specific order. The order determines where the matching character should lay in text relatively to the position of the original character. When the first character is detected as the original character the matcher will search for the matching character (ie. the second character from the pair) in the forward direction (ie. towards the end of a document). Similarily when the second character is detected as the original character the matcher will search for the matching character (ie. the first character in the pair) in the backward direction towards the beginning of a document.

In other words each pair should contain the 'opening' character first and the 'closing' character second. For example, when searching for curely braces they should be listed in the following order char [] braces = new char [] { '{', '}' }.

The created matcher can be further restricted to search in a certain area only. This might be useful for restricting the search to a particular lexical token in text (eg. a string literal, javadoc comment, etc.).

Parameters:

context - The context for the matcher.

lowerBound - The start offset of the area where the created matcher should search. Can be -1 for no restriction.

upperBound - The end offset of the area where the crated matcher should search. Can be -1 for no restriction.

matchingPairs - The array with pairs of matching characters. There should always be an even number of elements in the array.

Returns:

The character matcher.

findChar

public static int[] findChar(Document document,
                             int offset,
                             int limit,
                             char... pairs)
                      throws BadLocationException

Finds a character in a document. This methods will scan a document area between the offset and limit offsets to search for characters passed in the pairs parameter.

The offset parameter determines the position in the document where searching should start. The method will search from this position towards the position specified by the limit parameter. That means that if limit < offset the search will be done in the backward direction; while if limit > offset the method will search in the forward direction.

The pairs array should always contain an even number of chacters that match each other, eg. char [] { '(', ')' }. It is recommended to pass the 'opening' character first and the 'closing' character second.

If some of the pairs characters is found in the specified area of the document, the method will return an array of exactly three integers. The numbers returned have the following meaning.

• int[0] - offset in the document where the character was found.
• int[1] - index in the pairs array of the character that was found.
• int[2] - flag, indicating whether the search for the matching character should be done bacwkard or forward from the offset returned in int[0]. The value of this flag is either -1 for bacward search or +1 for forward search. The value can also be used for determining the index of the matching character in the pairs array simply by adding it to int[1].

The code below demonstrates how the original and the matching characters and the direction in which the matching character should lay can be determined from the return value.

 int offset = result[0];
 char original = pairs[result[1]];
 char matching = pairs[result[1] + result[2]];
 boolean backward = result[2] < 0;
 

Parameters:

document - The document to scan.

offset - The offset in the document to start searching at.

limit - The offset in the document to search towards.

pairs - The pairs of matching characters to search for.

Returns:

The search results as an array of three integers or null if none of the pairs characters was found in the specified area of the document.

Throws:

BadLocationException - If the offsets are incorrect.

matchChar

public static int matchChar(Document document,
                            int offset,
                            int limit,
                            char origin,
                            char matching)
                     throws BadLocationException

Searches for a matching character. This method will search document in the area between offset and limit for the matching character. The method will automatically skip any additional pairs of original - matching characters in the searched area.

The offset parameter determines the position in the document where searching should start. The method will search from this position towards the position specified by the limit parameter. That means that if limit < offset the search will be done in the backward direction; while if limit > offset the method will search in the forward direction.

This method in combination with findChar can be used for creating a character matcher as demonstrated below.

 int originOffset;
 char originalChar;
 char matchingChar;
 boolean backward;
 
 int [] findOrigin() {
   int result[] = findChar(doc, offset, limit, PAIRS);
   if (result != null) {
     originOffset = result[0];
     originalChar = PAIRS[result[1]];
     matchingChar = PAIRS[result[1] + result[2]];
     backward = result[2] < 0;
 
     return new int [] { originOffset, originOffset + 1 };
   } else {
     return null;
   }
 }
 
 int [] findMatches() {
   int offset = matchCharacter(
     doc, 
     backward ? originOffset : originOffset + 1, 
     backward ? 0 : doc.getLength(), 
     originalChar, 
     matchingChar);
 
   return offset != -1 ? new int [] { offset, offset + 1 } : null;
 }
 

Parameters:

document - The document to search in.

offset - The offset in the document to start seacrhing at.

limit - The offset in the document to search towards.

origin - The original character.

matching - The matching character. This is the character we are searching for.

Returns:

The offset of the matching character or -1 if the matching character can't be found in the specified area of the document.

Throws:

BadLocationException - If the offsets are invalid.