Package org.fife.ui.rtextarea

Class SearchEngine

java.lang.Object

org.fife.ui.rtextarea.SearchEngine

public final class SearchEngine
extends java.lang.Object

A singleton class that can perform advanced find/replace operations in an RTextArea. Simply create a SearchContext and call one of the following methods:

• find(JTextArea, SearchContext)
• replace(RTextArea, SearchContext)
• replaceAll(RTextArea, SearchContext)
• markAll(RTextArea, SearchContext)

Version:

1.0

See Also:

SearchContext

Constructor Summary

Constructors

Modifier	Constructor	Description
private	SearchEngine()	Private constructor to prevent instantiation.

Method Summary

Modifier and Type	Method	Description
static SearchResult	find(javax.swing.JTextArea textArea, SearchContext context)	Finds the next instance of the string/regular expression specified from the caret position.
private static SearchResult	findImpl(java.lang.String findIn, SearchContext context)	Finds the next instance of the string/regular expression specified from the caret position.
private static java.lang.CharSequence	getFindInCharSequence(RTextArea textArea, int start, boolean forward)	Returns a CharSequence for a text area that doesn't make a copy of its contents for iteration.
private static java.lang.String	getFindInText(javax.swing.JTextArea textArea, int start, boolean forward)	Returns the text in which to search, as a string.
private static java.util.List	getMatches(java.util.regex.Matcher m, java.lang.String replaceStr)	This method is called internally by getNextMatchPosRegExImpl and is used to get the locations of all regular-expression matches, and possibly their replacement strings.
static int	getNextMatchPos(java.lang.String searchFor, java.lang.String searchIn, boolean forward, boolean matchCase, boolean wholeWord)	Searches searchIn for an occurrence of searchFor either forwards or backwards, matching case or not.
private static java.awt.Point	getNextMatchPosRegEx(java.lang.String regEx, java.lang.CharSequence searchIn, boolean goForward, boolean matchCase, boolean wholeWord)	Searches searchIn for an occurrence of regEx either forwards or backwards, matching case or not.
private static java.lang.Object	getNextMatchPosRegExImpl(java.lang.String regEx, java.lang.CharSequence searchIn, boolean goForward, boolean matchCase, boolean wholeWord, java.lang.String replaceStr)	Searches searchIn for an occurrence of regEx either forwards or backwards, matching case or not.
private static RegExReplaceInfo	getRegExReplaceInfo(java.lang.CharSequence searchIn, SearchContext context)	Returns information on how to implement a regular expression "replace" action in the specified text with the specified replacement string.
static java.lang.String	getReplacementText(java.util.regex.Matcher m, java.lang.CharSequence template)	Called internally by getMatches().
private static boolean	isWholeWord(java.lang.CharSequence searchIn, int offset, int len)	Returns whether the characters on either side of substr(searchIn, startPos, startPos+searchStringLength) are not letters or digits.
private static int	makeMarkAndDotEqual(javax.swing.JTextArea textArea, boolean forward)	Makes the caret's dot and mark the same location so that, for the next search in the specified direction, a match will be found even if it was within the original dot and mark's selection.
static SearchResult	markAll(RTextArea textArea, SearchContext context)	Marks all instances of the specified text in this text area.
private static SearchResult	markAllImpl(RTextArea textArea, SearchContext context)	Marks all instances of the specified text in this text area.
private static SearchResult	regexReplace(RTextArea textArea, SearchContext context)	Finds the next instance of the regular expression specified from the caret position.
static SearchResult	replace(RTextArea textArea, SearchContext context)	Finds the next instance of the text/regular expression specified from the caret position.
static SearchResult	replaceAll(RTextArea textArea, SearchContext context)	Replaces all instances of the text/regular expression specified in the specified document with the specified replacement.

Methods inherited from class java.lang.Object

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

Constructor Detail

SearchEngine

private SearchEngine()

Private constructor to prevent instantiation.

Method Detail

find

public static SearchResult find(javax.swing.JTextArea textArea,
                                SearchContext context)

Finds the next instance of the string/regular expression specified from the caret position. If a match is found, it is selected in this text area.

Parameters:

textArea - The text area in which to search.

context - What to search for and all search options.

Returns:

The result of the operation.

Throws:

java.util.regex.PatternSyntaxException - If this is a regular expression search but the search text is an invalid regular expression.

See Also:

replace(RTextArea, SearchContext), replaceAll(RTextArea, SearchContext)

findImpl

private static SearchResult findImpl(java.lang.String findIn,
                                     SearchContext context)

Finds the next instance of the string/regular expression specified from the caret position. If a match is found, it is selected in this text area.

Parameters:

findIn - The text to search in.

context - The search context.

Returns:

The result of the operation. "Mark all" will always be zero, since this method does not perform that operation.

Throws:

java.util.regex.PatternSyntaxException - If this is a regular expression search but the search text is an invalid regular expression.

getFindInCharSequence

private static java.lang.CharSequence getFindInCharSequence(RTextArea textArea,
                                                            int start,
                                                            boolean forward)

Returns a CharSequence for a text area that doesn't make a copy of its contents for iteration. This conserves memory but is likely just a tad slower.

Parameters:

textArea - The text area whose document is the basis for the CharSequence.

start - The starting offset of the sequence (or ending offset if forward is false).

forward - Whether we're searching forward or backward.

Returns:

The character sequence.

getFindInText

private static java.lang.String getFindInText(javax.swing.JTextArea textArea,
                                              int start,
                                              boolean forward)

Returns the text in which to search, as a string. This is used internally to grab the smallest buffer possible in which to search.

getMatches

private static java.util.List getMatches(java.util.regex.Matcher m,
                                         java.lang.String replaceStr)

This method is called internally by getNextMatchPosRegExImpl and is used to get the locations of all regular-expression matches, and possibly their replacement strings.

Returns either:

• A list of points representing the starting and ending positions of all matches returned by the specified matcher, or
• A list of RegExReplaceInfos describing the matches found by the matcher and the replacement strings for each.

If replacement is null, this method call is assumed to be part of a "find" operation and points are returned. If it is non-null, it is assumed to be part of a "replace" operation and the RegExReplaceInfos are returned.

Parameters:

m - The matcher.

replaceStr - The string to replace matches with. This is a "template" string and can contain captured group references in the form "${digit}".

Returns:

A list of result objects.

Throws:

java.lang.IndexOutOfBoundsException - If replaceStr references an invalid group (less than zero or greater than the number of groups matched).

getNextMatchPos

public static int getNextMatchPos(java.lang.String searchFor,
                                  java.lang.String searchIn,
                                  boolean forward,
                                  boolean matchCase,
                                  boolean wholeWord)

Searches searchIn for an occurrence of searchFor either forwards or backwards, matching case or not.

Most clients will have no need to call this method directly.

Parameters:

searchFor - The string to look for.

searchIn - The string to search in.

forward - Whether to search forward or backward in searchIn.

matchCase - If true, do a case-sensitive search for searchFor.

wholeWord - If true, searchFor occurrences embedded in longer words in searchIn don't count as matches.

Returns:

The starting position of a match, or -1 if no match was found.

getNextMatchPosRegEx

private static java.awt.Point getNextMatchPosRegEx(java.lang.String regEx,
                                                   java.lang.CharSequence searchIn,
                                                   boolean goForward,
                                                   boolean matchCase,
                                                   boolean wholeWord)

Searches searchIn for an occurrence of regEx either forwards or backwards, matching case or not.

Parameters:

regEx - The regular expression to look for.

searchIn - The string to search in.

goForward - Whether to search forward. If false, search backward.

matchCase - Whether to do a case-sensitive search for regEx.

wholeWord - If true, regEx occurrences embedded in longer words in searchIn don't count as matches.

Returns:

A Point representing the starting and ending position of the match, or null if no match was found.

Throws:

java.util.regex.PatternSyntaxException - If regEx is an invalid regular expression.

See Also:

getNextMatchPos(java.lang.String, java.lang.String, boolean, boolean, boolean)

getNextMatchPosRegExImpl

private static java.lang.Object getNextMatchPosRegExImpl(java.lang.String regEx,
                                                         java.lang.CharSequence searchIn,
                                                         boolean goForward,
                                                         boolean matchCase,
                                                         boolean wholeWord,
                                                         java.lang.String replaceStr)

Searches searchIn for an occurrence of regEx either forwards or backwards, matching case or not.

Parameters:

regEx - The regular expression to look for.

searchIn - The string to search in.

goForward - Whether to search forward. If false, search backward.

matchCase - Whether to do a case-sensitive search for regEx.

wholeWord - If true, regEx occurrences embedded in longer words in searchIn don't count as matches.

replaceStr - The string that will replace the match found (if a match is found). The object returned will contain the replacement string with matched groups substituted. If this value is null, it is assumed this call is part of a "find" instead of a "replace" operation.

Returns:

If replaceStr is null, a Point representing the starting and ending points of the match. If it is non-null, an object with information about the match and the morphed string to replace it with. If no match is found, null is returned.

Throws:

java.util.regex.PatternSyntaxException - If regEx is an invalid regular expression.

java.lang.IndexOutOfBoundsException - If replaceStr references an invalid group (less than zero or greater than the number of groups matched).

See Also:

getNextMatchPos(java.lang.String, java.lang.String, boolean, boolean, boolean)

getRegExReplaceInfo

private static RegExReplaceInfo getRegExReplaceInfo(java.lang.CharSequence searchIn,
                                                    SearchContext context)

Returns information on how to implement a regular expression "replace" action in the specified text with the specified replacement string.

Parameters:

searchIn - The string to search in.

context - The search options.

Returns:

A RegExReplaceInfo object describing how to implement the replace.

Throws:

java.util.regex.PatternSyntaxException - If the search text is an invalid regular expression.

java.lang.IndexOutOfBoundsException - If the replacement text references an invalid group (less than zero or greater than the number of groups matched).

See Also:

getNextMatchPos(java.lang.String, java.lang.String, boolean, boolean, boolean)

getReplacementText

public static java.lang.String getReplacementText(java.util.regex.Matcher m,
                                                  java.lang.CharSequence template)

Called internally by getMatches(). This method assumes that the specified matcher has just found a match, and that you want to get the string with which to replace that match.

Escapes simply insert the escaped character, except for \n and \t, which insert a newline and tab respectively. Substrings of the form $\d+ are considered to be matched groups. To include a literal dollar sign in your template, escape it (i.e. \$).

Most clients will have no need to call this method directly.

Parameters:

m - The matcher.

template - The template for the replacement string. For example, "foo" would yield the replacement string "foo", while "$1 is the greatest" would yield different values depending on the value of the first captured group in the match.

Returns:

The string to replace the match with.

Throws:

java.lang.IndexOutOfBoundsException - If template references an invalid group (less than zero or greater than the number of groups matched).

isWholeWord

private static boolean isWholeWord(java.lang.CharSequence searchIn,
                                   int offset,
                                   int len)

Returns whether the characters on either side of substr(searchIn, startPos, startPos+searchStringLength) are not letters or digits.

makeMarkAndDotEqual

private static int makeMarkAndDotEqual(javax.swing.JTextArea textArea,
                                       boolean forward)

Makes the caret's dot and mark the same location so that, for the next search in the specified direction, a match will be found even if it was within the original dot and mark's selection.

Parameters:

textArea - The text area.

forward - Whether the search will be forward through the document (false means backward).

Returns:

The new dot and mark position.

markAll

public static SearchResult markAll(RTextArea textArea,
                                   SearchContext context)

Marks all instances of the specified text in this text area. This method is typically only called directly in response to search events of type SearchEvent.Type.MARK_ALL. "Mark all" behavior is automatically performed when find(JTextArea, SearchContext) or replace(RTextArea, SearchContext) is called.

Parameters:

textArea - The text area in which to mark occurrences.

context - The search context specifying the text to search for. It is assumed that context.getMarkAll() has already been checked and returns true.

Returns:

The results of the operation.

markAllImpl

private static SearchResult markAllImpl(RTextArea textArea,
                                        SearchContext context)

Marks all instances of the specified text in this text area. This method is typically only called directly in response to search events of type SearchEvent.Type.MARK_ALL. "Mark all" behavior is automatically performed when find(JTextArea, SearchContext) or #replace(RTextArea, SearchContext) is called.

Parameters:

textArea - The text area in which to mark occurrences.

context - The search context specifying the text to search for. It is assumed that context.getMarkAll() has already been checked and returns true.

Returns:

The results of the operation.

regexReplace

private static SearchResult regexReplace(RTextArea textArea,
                                         SearchContext context)

Finds the next instance of the regular expression specified from the caret position. If a match is found, it is replaced with the specified replacement string.

Parameters:

textArea - The text area in which to search.

context - What to search for and all search options.

Returns:

The result of the operation.

Throws:

java.util.regex.PatternSyntaxException - If this is a regular expression search but the search text is an invalid regular expression.

java.lang.IndexOutOfBoundsException - If this is a regular expression search but the replacement text references an invalid group (less than zero or greater than the number of groups matched).

See Also:

replace(RTextArea, SearchContext), find(JTextArea, SearchContext)

replace

public static SearchResult replace(RTextArea textArea,
                                   SearchContext context)

Finds the next instance of the text/regular expression specified from the caret position. If a match is found, it is replaced with the specified replacement string.

Parameters:

textArea - The text area in which to search.

context - What to search for and all search options.

Returns:

The result of the operation.

Throws:

java.util.regex.PatternSyntaxException - If this is a regular expression search but the search text is an invalid regular expression.

java.lang.IndexOutOfBoundsException - If this is a regular expression search but the replacement text references an invalid group (less than zero or greater than the number of groups matched).

See Also:

replaceAll(RTextArea, SearchContext), find(JTextArea, SearchContext)

replaceAll

public static SearchResult replaceAll(RTextArea textArea,
                                      SearchContext context)

Replaces all instances of the text/regular expression specified in the specified document with the specified replacement.

Parameters:

textArea - The text area in which to search.

context - What to search for and all search options.

Returns:

The result of the operation.

Throws:

java.util.regex.PatternSyntaxException - If this is a regular expression search but the replacement text is an invalid regular expression.

java.lang.IndexOutOfBoundsException - If this is a regular expression search but the replacement text references an invalid group (less than zero or greater than the number of groups matched).

See Also:

replace(RTextArea, SearchContext), find(JTextArea, SearchContext)