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
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.