The RegexReplace command allows you to replace specific text in a specified text file with alternative text, and optionally output the modified text to a new file.
IMPORTANT: The function of this command is to use Regular Expressions to replace specific text in a file with alternative text. The command uses the Microsoft .Net Regular expression engine, which is beyond the scope of this document. As a result if you need support on the syntax required you should read the Microsoft documentation. We are unable to offer support for any third party applications of which we have limited knowledge and over which we have no control.
Command Syntax
RegexReplace:[Pattern],[Replacement],[SourceFileName],[TargetFileName],[RegexOptions]
The colon after the command and the space between parameters are compulsory. Any additional spaces or characters will cause an error to be thrown. The command itself is not case sensitive, but parameters may be depending on the operating system and locale.
Parameters:
Pattern: A valid Regex pattern to detect the text to replace
Replacement: The text to replace the detected text
SourceFileName: The fully qualified path and file name identifying the file to update.
TargetFileName: The fully qualified path and file name to which the updated file should be saved
RegexOptions: Zero or more pieces or text representing members of the RegexOptions enumeration separated by Pipe characters.
The Pattern, Replacement, and SourceFileName parameters are compulsory, as are the commas between the parameters. The TargetFileName and RegexOptions parameters are optional. If the TargetFileName parameter is not provided, the source file will be overwritten once modified. The SourceFileName and TargetFileName parameters may be surrounded by quotation marks if one or more spaces are included in the path and file name. It is good practice to include the quotation marks in any case, so that it reduces the risk of error when writing scripts.
Note: It is permissible for the Source and Target file names to be the same. In that situation the file modification will be written to a temporary file in case an error occurs during processing. If the processing succeeds, the original file will be deleted and the temporary file renamed to the original file name.
Regex Options
The RegexOptions parameter allows you to change the way that the Regex behaves. You enter any combination of compatible options separated by Pipe characters. This will be turned into a special type of enumeration that allows a bitwise combination of its member values. The currently available options are:
Compiled |
Specifies that the regular expression is compiled to an assembly. This yields faster execution but increases startup time.
|
CultureInvariant |
Specifies that cultural differences in language is ignored
|
ECMAScript |
Enables ECMAScript-compliant behavior for the expression. This value can be used only in conjunction with the IgnoreCase, Multiline, and Compiled values. The use of this value with any other values results in an exception.
|
ExplicitCapture |
Specifies that the only valid captures are explicitly named or numbered groups of the form (?<name>...). This allows unnamed parentheses to act as non-capturing groups without the syntactic clumsiness of the expression (?:...).
|
IgnoreCase |
Specifies case-insensitive matching
|
IgnorePatternWhitespace |
Eliminates unescaped white space from the pattern and enables comments marked with #. However, this value does not affect or eliminate white space in character classes, numeric quantifiers, or tokens that mark the beginning of individual regular expression language elements
|
Multiline |
Multiline mode. Changes the meaning of ^ and $ so they match at the beginning and end, respectively, of any line, and not just the beginning and end of the entire string
|
None |
Specifies that no options are set and default behavior of the regular expression engine should be used
|
RightToLeft |
Specifies that the search will be from right to left instead of from left to right.
|
Singleline |
Specifies single-line mode. Changes the meaning of the dot (.) so it matches every character (instead of every character except \n). |
Note: If you do not specify any RegexOptions, the behaviour will be the same as if you specified the None option.
Examples:
These examples assume a file containing the words "Test play play Player" and that you wish to replace the word play with 123.
Single file replacement to a different file with default Regex options:
RegexReplace:\bplay\b,123,"C:\Test Text.txt","C:\Test Text (updated).txt",
Single file replacement overwriting the existing file with default Regex options:
RegexReplace:\bplay\b,123,"C:\Test Text.txt",,
Single File replacement to a different file ignoring case and reading from right to left:
RegexReplace:\bplay\b,123,"C:\Test Text.txt","C:\Test Text (updated).txt",IgnoreCase|RightToLeft
IMPORTANT: This command has to load the entire source file into memory in order to be able to process it. It is therefore unsuitable for use with extremely large files which could result in an out of memory exception. We suggest an upper limit of approximately 20k lines of text on a modern computer purely as an arbitrary guide. The actual limit will depend on your system and the amount of memory installed amongst other things.
See Also: AssignSubs ClearSubs Subs Substitute