Text Find & Replace Action

The Text Find / Replace action allows you search for or replace a string. You can search in a file, or in variable contents. The search string can be plaintext or a regular expression. Wildcards are also available.

Find String

Source

The text to search can be sourced from either a file, the contents of a variable, or from each of the files in a FileSet.

When processing a FileSet, each file will be processed in turn (see below for more details, under the Behaviour tab.)

Search in file

Search in files from Fileset

Search in variables contents

Search String

The string to search for can be plain text, plain text with wildcards, or a regular expression. It can optionally span multiple lines. A range of search options are available:

Whole words Only

If this option is checked, the search will only match whole words.

Whole lines Only

If this option is checked, the search will only match results which make up an entire line.

Use wildcards * and ?

If this box is checked, the search string can contain the wildcard characters "*" and "?". * will match any number of characters (including none), whereas ? will match any single character.

Case Sensitive

If checked, the search will be case sensitive.

Match as Regular Expression

If checked, the search string will be treated as a regular expression. See the Regular Expression reference for details. If this option is set, the other search options listed above do not apply and will be grayed out.

Match instances

Replace

Replace Options

Do not replace text

If this option is set, then the action behaves as a "Text Find" action only. All other options on this property page will be disabled.

Replace text and write back to source file

If this option is set, then the action will make relevant replacements and write the new text over the existing source file or variable.

Replace text and write to (other) file

If this option is set, the output text will be written to another file (as specified.)

Replace text and write back to variable

Replacement String

Enter the string you wish to use as a replacement.

Expand variable names in replacement string

Enable this option to expand any variable reference (ie %VarName%) in the replacement string to their variable values, before making any replacements.

Substitute wildcard matches (syntax is $1, $2, etc.)

Enable this option to replace $1, $2, etc. with the text of the corresponding wildcard (*) match from the search string. "Wildcard * matches any substring" must be selected for this option to take effect. In the example above, $1 would be replaced with the value which matched the leading * from "*.dll" (based on the search string in the above screenshot.)

If "Match as Regular Expression" is enabled, then this option is renamed to become "Substitute regular expression matches (syntax is $&, $0, $1, $2, etc.)". In this case, matching and replacement is performed as per the standard Regular Expression rules for sub-expression substitution.

If the replacement text contains numbers adjacent to the substitution marker, escape it like this: ${1}

For example, if you want to replace every "ver <n>" with "ver <n>5" in strings like "Release ver 3 is now out", you could use "ver (\d+)" as the regular expression to match, and replace it with "ver ${1}5".

Behaviour

You can choose to have the action fail if there are less than or more than a specified number of matches found. If replacement is enabled and the action fails because of too few or too many matches, then the replacement string is not written to the target file/variable. The only exception is when using FileSets and "Count total matches..." is enabled (see below.)

Alternatively, you can choose to write the total number of matches to a variable.

Don't fail based on number of matches

Fail if there are LESS than X matches.

Fail if there are MORE than X matches.

Put match count into variable

Matches

This option is only enabled if you are searching all files in a FileSet. It allows you to specify whether or not you wish to count the grand total of matches across all files, or count matches on a file by file basis.

When replacement is enabled and the action is set to "Count total matches for all files", the replacement text will be written to every file regardless of whether or not the action fails. When "Count matches for each file" is selected, the replacement text will only be written if the action succeeds for that file. If the action fails while processing a file, no other files in the FileSet will be processed (the action stops.)

Count total matches for all files

Count match for each file

Script Events

In the Script Editor tab, you can see the OnFindText scripting event which allows you to respond to individual matches.

The OnFindText event has the following parameters:

Action

An object representing the Text Find Action.

Count

How many matches have been found so far as this action runs (starts from one and increments with each match.)

FoundText

The exact string that was matched. For plain text searches, this will be the search string. For regular expressions, it will be the specific instance which was matched.

Offset

The offset in the source at which the text was found. Offset is zero-indexed.

ReplaceText

The string which will be used for replacements (if replace is enabled.) This is a pass-by-reference parameter, so changes made here will reflect the replacement string which is used by the action.