findText command

Use the findText command to locate and optionally replace text in a document.

The parameters for the findText command are divided into two groups:

Syntax

findText [ up
         | checkStart
         | replace
         | all
         | quiet
         | noBeep
         ] [...]
         [ [ mark
           | columns col1 col2
           | { block | selection }
           | uiMode
           | wholeWord
           | noWrap
           | asis
           | noEmphasis
           | regularExpression
           | replaceWith replaceText
           ] [...]
           text
         ] 

Parameters

up Use the optional up parameter to indicate that the search should proceed backward from the current position.
checkStart Use the optional checkStart parameter to indicate that the current cursor position should be checked before proceeding with the search.
replace Use the optional replace parameter to indicate that the found text should be replaced by the text indicated by the findText.replaceText parameter.
all Use the optional all parameter to indicate that all of the occurrences of the sought text should be located.  The search ignores the current cursor position but it honors the block and columns restrictions.
quiet Use the optional quiet parameter to indicate that no messages or audio feedback should be issued.
noBeep Use the optional noBeep parameter to indicate that no audio feedback should be issued.
mark Use the optional mark parameter to indicate that the found text should be selected.
columns col1 col2 Use the optional columns parameter to restrict the scope of the search to the specified start and end columns.  col1 and col2 must be positive integers.
block | selection Use the optional block or selection parameter to restrict the scope of the search to the current block selection.
uiMode When used in conjunction with block or selection, changes the selection type to character, and highlights the first match in the selection. Subsequent calls to findText with the same parameters iterate through the matches without losing the selection.
wholeWord Use the optional wholeWord parameter to restrict the search to whole words.  Words consist of letters, digits, and underscores.
noWrap Use the optional noWrap parameter to indicate that the search is to stop when it hits the bottom of the document.  Or, in the case where the search is proceeding backward through the document, the noWrap parameter indicates that the search is to stop when the top of the document is reached.
asis Use the optional asis parameter to indicate that the search should be a case sensitive search.
noEmphasis Use the optional noEmphasis parameter to indicate that the found text is not to be emphasized with the document view's emphasis style.
regularExpression Use the optional regularExpression parameter to indicate that the search and replace strings should be treated as regular expression patterns.
replaceWith replaceText Use the optional replaceWith parameter to indicate that the found text should be replaced with replaceText.  If replaceText contains spaces it must be enclosed in quotes (");  if it contains quotes, you must prefix the quotes with a backslash (\");  if it contains backslashes, you must prefix the backslashes with a backslash (\\).
text Use the text parameter to indicate the text for which you wish to search.  You may need to quote the string if you are searching for one of the findText keywords, or if it contains spaces.

Status

The status parameter will be set to one of the following:
null The specified text was successfully located (and optionally replaced) without any special conditions.
findText.onlyOccurrence The findText command searched the entire document, wrapped and located the specified text at the original cursor location.
findText.wrapped The findText command successfully located the specified text but had to wrap around to the beginning of the document during the search.  Or, if searching backward it had to wrap around to the end of the document during the search.
findText.notFound The specified text could not be found.
findText.invalidPattern The specified text is not a correct regular expression pattern.  This status may only be set when you have indicated that the search and replace strings are regular expression patterns.
fields.truncate Replace text truncated because of editing fields in effect.
textLimit.overflow Replaced text exceeds the text limit.  Truncation will occur when the file is saved.

Description

The findText command uses the following parameters:

Unless the all parameter was specified, the findText command only affects visible elements.

Regular expressions allow you to find text that matches a pattern you specify.  The regular expression support in the editor is that provided by the Java language.
Note:

Below are a few common regular expression patterns:

c If c is not a special character, then match a single instance of that character.
\c Match a single instance of the character c that otherwise would be interpreted as a special character.  For example, the expression \\ matches a single backslash, and the expression \[ matches a left square bracket.
\t The tab character (U+0009).
\xhh The character with hexadecimal value 0xhh.  Each h represents a hexadecimal digit.
\uhhhh The character with hexadecimal value 0xhhhh.  Each h represents a hexadecimal digit.
. Match any single character.
[abc] Match any single character included in abc.
[^abc] Match any single character except those included in abc.
[a-z] Match any single character in the range a through z.
[^a-z] Match any single character except those included in the range a through z.
[a-zA-Z] Match any single character in the range a through z or A through Z.
\d A digit.  This is equivalent to [0-9].
\D A non digit.  This is equivalent to [^0-9].
\s A white space character.  This is equivalent to [ \t\x0A\x0B\x0C\x0D].
\S A non white space character.  This is equivalent to [^\s].
\w A word character (an alphanumeric).  This is equivalent to [a-zA-Z0-9_].
\W A non word character.  This is equivalent to [^\w].
^ Match at the beginning of a line.  ^ must be the first character in the expression.
$ Match at the end of a line.  $ must be the last character in the expression.
$n Specify a capture group where n represents the number for the capture group. For example, $1 for the first capture group, $2 for the second, and so on.
() Create a capture group. A matched pattern within () is assigned to a capture group. $n assignments for capture groups are enumerated in sequence. For example, for the pattern (\dabc)(\dxyz), matches within the first () would be assigned to capture group $1, and matches within the second () would be assigned to capture group $2.
\b Match a word boundary.
\B Match a non-word boundary.
X? Match zero or one occurrence of expression X.  The longest match possible is found (greedy match).
X* Match zero or more successive occurrences of expression X.  The longest match possible is found (greedy match).
X+ Match one or more successive occurrences of expression X.  The longest match possible is found (greedy match).
X{n} Match exactly n successive occurrences of expression X.  The longest match possible is found (greedy match).
X{n,} Match at least n successive occurrences of expression X.  The longest match possible is found (greedy match).
X{n,m} Match at least n but no more than m successive occurrences of expression X.  The longest match possible is found (greedy match).
X?? Match zero or one occurrence of expression X.  The shortest match is found (non greedy match).
X*? Match zero or more successive occurrences of expression X.  The shortest match is found (non greedy match).
X+? Match one or more successive occurrences of expression X.  The shortest match is found (non greedy match).
X{n}? Match exactly n successive occurrences of expression X.  The shortest match is found (non greedy match).
X{n,}? Match at least n successive occurrences of expression X.  The shortest match is found (non greedy match).
X{n,m}? Match at least n but no more than m successive occurrences of expression X.  The shortest match is found (non greedy match).
XY Match expression X followed by expression Y.
X|Y Match either expression X or Y.

Examples



Related concepts
Editor commands, actions, and parameters

Related reference
emphasisLength parameter
expandHide parameter
expanded parameter
fields parameter
findText.asis parameter
findText.block parameter
findText.columns parameter
findText.emphasis parameter
findText.endColumn parameter
findText.findText parameter
findText.incremental parameter
findText.mark parameter
findText.regularExpression parameter
findText.replaceText parameter
findText.startColumn parameter
findText.wholeWord parameter
findText.wrap parameter
save.textLimit parameter
status parameter
topExpanded parameter
visible parameter

excludeSelection action
filterSelection action
find action
findAndReplace action
findAndReplaceNext action
findAndReplaceUp action
findNext action
findSelection action
findUp action
Java regular expression patterns