Nisus Macro Reference

This section details general purpose find and replace commands.

If you are working with Text objects you should see the section Text Object - Find & Replace.

Find findText, [options], [where]

Finds and selects the given text, returning the number of matches that were found (zero or one, unless the “a” option is specified). The options and where arguments are strings as documented below in the Find and Replace command.

As of v2.0.5 the findText argument can also be a Style object instead of some text. If a style is given, then will match any text with that style applied.

Find and Replace findText, replacementText, [options], [where]

Finds the text findText and replaces it with replacementText. Unless the "S" option is specified, the newly inserted text is always selected after this command is finished. This command returns the number of replacements that were made.

The options argument is a string that contains one or more of the following characters:

*	Use options currently set in Find & Replace dialog. You can still add additional options as you like.
!	Copy text/options into the Find & Replace dialog instead of doing an actual find/replace.
$	For each capture in the find expression, the captured text is stored in the macro variables $1, $2 ... $N, where N is the number of captures that occur. The whole match is stored in $0. This option does not work for “replace” or “find all” operations. If a capture was not present then the variable is set to the @undefined value. This option will also make available named captures, which are a feature of PowerFind Pro expressions (regular expressions). Assuming the assigned names are legal in the Nisus Macro language. For example, the regular expression (?<word>\w+) would assign the variable $word the text matched by \w+. This option was added in v1.0.2.
¢	Works exactly like the $ option as described above, but instead of capturing fully formatted text, only captures plain text strings. This is more efficient. Added in v2.1.1.
+	Add the resulting matches to the existing selection, instead of clearing the current selection. Added in v3.0.
a	Find or replace all matches, instead of just the very next match.
A	Find all (or replace all) in all open document windows, instead of just the frontmost document. Added in v3.0. Warning: be very careful when using this option with replace all, as each document has its own undo history. If you replace in 7 open documents, you will need to switch between each affected window and undo separately 7 times.
b	Search backwards (reverse).
c	The results should be selected using the color chosen by the user in the preferences. Added in v1.1.
e	PowerFind expressions. In this mode it is possible for the find/replace expressions to contain PowerFind bubbles, eg: as generated by the macroize command in the Find and Replace dialog.
E	PowerFind Pro expressions, aka: regular expressions, regex, grep.
i	Case insensitive search.
m	Match case of found text before replacing. Added in v1.3.
n	Do not follow/enter note references (eg: footnote markers). Normally note references cannot be matched and their presence breaks the flow of text, having the effect that text before and after the reference are treated as logically disjoint. Using this option means that note references are treated as normal content that can be matched by the search. Added in v1.3.
r	Search backwards (reverse).
s	Limit to current selection.
S	Instead of selecting the found/replaced text, preserve the selection. In other words, the same logical content remains selected after the operation is complete. For a Find command with no replace action this option means the results will not be selected. Added in v1.1.
u	Find text is attribute sensitive.
U	Replacement text is attribute sensitive.
v	Verbose mode: show an alert dialog describing the number of matches.
V	Verbose mode: show all matches as a list in a new Find Results floating window. Add in v3.0.
w	Only match whole words.
W	Wrap search around if the end of the document is reached.
-x	Ignore text controlled by cross-references. That is, do not match any text displayed by a cross-reference. This option can only be used in its negated form with the minus sign prefix. Added in v3.0.

Each option character can be preceded by a minus/dash to turn off the given option. For example, “-i” makes the search case sensitive. By default the case insensitive option and wrap around are turned on, eg: default options are “iW”.

The where argument is a string that specifies in what kinds of content matching occurs. This option was added in v1.3. The string can contain one or more of the following characters:

a	Allow matches in any kind of content.
c	Allow matches in comments.
h	Allow matches in headers and footers.
m	Allow matches in the main document body.
n	Allow matches in notes, eg: footnotes, endnotes, section notes.

Each option character can be preceded by a minus/dash to disallow matching in that kind of content. By default matching occurs everywhere, eg: the "a" option is implied. As an example, the string "-ac" would only search comment text. As another example, either "-n" or "a-n" would exclude note text from the search.

As of v2.0.5 the findText argument can also be a Style object instead of some text. If a style is given, then will match any text with that style applied.

Find All v1.0.1

A synonym for Find with the “a” option implied.

Find All in Selection v1.2

A synonym for Find with the “as” options implied.

Find Next v1.2

A synonym for the Find command.

Find Previous v1.2

A synonym for Find with the “r” option implied.

Replace All v1.0.1

A synonym for Find and Replace with the “a” option implied.

Replace All in Selection v1.2

A synonym for Find and Replace with the “as” options implied.