ReplaceRegExp

Description

ReplaceRegExp is a directory based task for replacing the occurrence of a given regular expression with a substitution pattern in a selected file or set of files.

The output file is only written if it differs from the existing file. This prevents spurious rebuilds based on unchanged files which have been regenerated by this task. In order to assess whether a file has changed, this task will create a pre-processed version of the source file inside of the temporary directory.

Similar to regexp type mappers this task needs a supporting regular expression library and an implementation of org.apache.tools.ant.util.regexp.Regexp. See details in the documentation of the Regexp Type.

Parameters

Attribute Description Required
file file for which the regular expression should be replaced. Yes, unless nested <fileset> is used
match The regular expression pattern to match in the file(s) Yes, unless nested <regexp> is used
replace The substitution pattern to place in the file(s) in place of the regular expression. Yes, unless nested <substitution> is used
flags The flags to use when matching the regular expression. For more information, consult the Perl 5 syntax
g : Global replacement. Replace all occurrences found
i : Case Insensitive. Do not consider case in the match
m : Multiline. Treat the string as multiple lines of input, using ^ and $ as the start or end of any line, respectively, rather than start or end of string.
s : Singleline. Treat the string as a single line of input, using . to match any character, including a newline, which normally, it would not match. 		No
byline Process the file(s) one line at a time, executing the replacement on one line at a time (true|false). This is useful if you want to only replace the first occurrence of a regular expression on each line, which is not easy to do when processing the file as a whole. No; defaults to false
encoding The encoding of the file. since Apache Ant 1.6 No; defaults to default JVM character encoding
preserveLastModified Keep the file timestamp(s) even if the file(s) is(are) modified. since Ant 1.8.0. No; defaults to false
failonerror Stop the build process if certain file operations fail.
For historical reasons the task swallows and logs certain failure cases, enabling this option makes sure the exception make the build fail instead. since Ant 1.10.15		 No; defaults to false

Examples

<replaceregexp file="${src}/build.properties"
               match="OldProperty=(.*)"
               replace="NewProperty=\1"
               byline="true"/>

replaces occurrences of the property name OldProperty with NewProperty in a properties file, preserving the existing value, in the file ${src}/build.properties

Parameters specified as nested elements

This task supports a nested FileSet element.

Since Ant 1.8.0, this task supports any filesystem based resource collections as nested elements.

This task supports a nested Regexp element to specify the regular expression. You can use this element to refer to a previously defined regular expression datatype instance.

<regexp id="id" pattern="alpha(.+)beta"/>
<regexp refid="id"/>

This task supports a nested substitution element to specify the substitution pattern. You can use this element to refer to a previously defined substitution pattern datatype instance.

<substitution id="id" expression="beta\1alpha"/>

<substitution refid="id"/>

Examples

Replace occurrences of the property name OldProperty with NewProperty in a properties file, preserving the existing value, in all files ending in .properties in the current directory:

<replaceregexp byline="true">
    <regexp pattern="OldProperty=(.*)"/>
    <substitution expression="NewProperty=\1"/>
    <fileset dir=".">
        <include name="*.properties"/>
    </fileset>
</replaceregexp>

Replace all whitespaces (blanks, tabs, etc) by one blank remaining the line separator:

<replaceregexp match="\s+" replace=" " flags="g" byline="true">
    <fileset dir="${html.dir}" includes="**/*.html"/>
</replaceregexp>

Then, input

<html>    <body>
<<TAB>><h1>    T E S T   </h1>  <<TAB>>
<<TAB>> </body></html>

is converted to

<html> <body>
 <h1> T E S T </h1> </body></html>

The task

<replaceregexp match="\\n" replace="${line.separator}" flags="g" byline="true">
    <fileset dir="${dir}"/>
</replaceregexp>

replaces all \n markers (beware the quoting of the backslash) by a line break. Then, input

one\ntwo\nthree

is converted to

one
two
three

Beware that inserting line breaks could break file syntax. For example in XML:

<root>
    <text>line breaks \n should work in text</text>
    <attribute value="but breaks \n attributes"/>
</root>