findText command

The findText command can be used to locate and optionally replace text in a document.  The parameters for the findText command are divided into two groups.  The first group of optional parameters includes up, checkStart, replace, all, quiet, and noBeep.  If only these options are specified, the findText command will use the values indicated by the current.findText parameters to perform the search.  If you specify any of the parameters from the second group you must specify the text parameter.  In this case, the current.findText parameters will be ignored and only the options specified will be taken into account.

Syntax

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

Parameters

up Use the optional parameter up to indicate that the search should proceed backward from the current position.
checkStart Use the optional parameter checkStart to indicate that the current cursor position should be checked before proceeding with the search.
replace Use the optional parameter replace 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 parameter columns to restrict the scope of the search to the specified start and end columns.  col1 and col2 must be positive integers.
block Use the optional parameter block to restrict the scope of the search to the current block selection.
noWrap Use the optional parameter noWrap 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 parameter asis to indicate that the search should be a case sensitive search.
noEmphasis Use the optional parameter noEmphasis to indicate that the found text is not to be emphasized with the document view's emphasis style.
regularExpression Use the optional parameter regularExpression to indicate that the search string should be treated as a regular expression pattern.
replaceWith replaceText Use the optional parameter replaceWith to indicate that the found text should be replaced with replaceText.  If replaceText contains spaces it must be quoted with quotes (").  If replaceText contains quotes, you must quote the quotes with a backslash (\").  If replaceText contains backslashes, you must quote the backslashes with a backslash (\\).
text Use the parameter text 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.

Status

The status parameter will be set to one of the following:  

null Indicates that the findText command successfully located the specified text without any special conditions.
findText.onlyOccurrence Indicates that the findText command searched the entire document, wrapped and located the specified text at the original cursor location.
findText.wrapped Indicates that the findText command successfully located the specified text but had to wrap around to the beginning of the file during the search.  Or, if searching backward it had to wrap around to the end of the file during the search.
findText.notFound Indicates that the specified text could not be found.
findText.invalidPattern Indicates that the specified text is not a valid regular expression pattern.  You will only receive this status if you have indicated that the specified text is a regular expression pattern.

Description

The findText command uses the following parameters:

The findText command only affects visible elements.

A regular expression pattern is made up of one or more of the following: 

c If c is a non special character, then match a single instance of that character.
\c Match a single instance of the character c.  If c is a special character, then it loses its special meaning.
yz Match expression y followed by expression z.
. Match any single character.
^ Match the beginning of a line.  ^ must be the first character in a regular expression pattern.
$ Match the end of a line.  $ must be the last character in a regular expression pattern.
* Match zero or more successive occurrences of the preceding expression.
+ Match one or more successive occurrences of the preceding expression.
? Match zero or one occurrence of the preceding expression.
{n} Match exactly n successive occurrences of the preceding expression.  Note that n must be an integer greater than or equal to zero.
{n,} Match at least n successive occurrences of the preceding expression.  Note that n must be an integer greater than or equal to zero.
{n1,n2} Match at least n1 but no more than n2 successive occurrences of the preceding expression.  Note that n1 and n2 must be integers greater than or equal to zero.
| Match either of the alternate expressions separated by |.  Note that if more than one alternate expression matches, the expression which allows the longest match will be chosen.
[characters] Match any single character included in characters.  characters may consist of zero or more individual characters and zero or more character ranges.  A character range is specified as c1-c2.  If you include a character range then characters will match any character with a collating value greater than or equal to the collating value of c1 and less than or equal to the collating value of c2.  If you wish to include the hyphen (-) character then it must appear immediately after "[" or immediately before "]".  If you wish to include the close bracket (]) character then it must appear immediately after "[".  If you wish to include the caret (^) character then it cannot be the first character after "[".
[^characters] Match any single character not not included in characters. characters may consist of zero or more individual characters and zero or more character ranges.  A character range is specified as c1-c2.  If you include a character range then characters will match any character with a collating value greater than or equal to the collating value of c1 and less than or equal to the collating value of c2.  If you wish to include the hyphen (-) character then it must appear immediately after "^" or immediately before "]".  If you wish to include the close bracket (]) character then it must appear immediately after "^".
(subexpression) Match any single instance of subexpression where subexpression is a valid regular expression pattern.

Examples

findText "text"
findText replaceWith "new text" "text"
findText up
findText regularExpression "(this)|(that)"

Editor commands and parameters


emphasisLength parameter
expandHide parameter
expanded parameter
findText.asis parameter
findText.block parameter
findText.columns parameter
findText.emphasis parameter
findText.endColumn parameter
findText.findText parameter
findText.mark parameter
findText.regularExpression parameter
findText.replaceText parameter
findText.startColumn parameter
findText.wrap parameter
topExpanded parameter
visible parameter
filterSelection action
find action
findAndReplace action
findAndReplaceNext action
findAndReplaceUp action
findNext action
findSelection action
findUp action
Default editor commands