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.








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


"Wildcard * matches any substring"


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.


If using wildcards, the characters * and ? can be escaped as ** and ??, respectively.


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





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/variable"


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



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







You can choose to have the action fail if there are less than or more than a specified number of matches found. Note that 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.





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



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:



An object representing the Text Find Action.



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



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.



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



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.