ReplaceRegExp Task

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

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

### Parameters

Attribute | Description | Required
file | file for which the regular expression should be replaced. | Yes if no nested <fileset> is used
match | The regular expression pattern to match in the file(s) | Yes, if no nested <regexp> is used
replace | The substitution pattern to place in the file(s) in place of the regular expression. | Yes, if no nested <substitution> is used
flags | The flags to use when matching the regular expression. For more information, consult the Perl5 syntax g : Global replacement. Replace all occurences 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 occurence of a regular expression on each line, which is not easy to do when processing the file as a whole. Defaults to false. | No
encoding | The encoding of the file. since Ant 1.6 | No - defaults to default JVM encoding

### 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`

### Choice of regular expression implementation

Ant comes with wrappers for the java.util.regex package of JDK 1.4, jakarta-regexp and jakarta-ORO, See installation dependencies concerning the supporting libraries.

The system property `ant.regexp.regexpimpl` governs which regular expression implementation will be chosen. Possible values for this property are :

- org.apache.tools.ant.util.regexp.Jdk14RegexpRegexp
- org.apache.tools.ant.util.regexp.JakartaOroRegexp
- org.apache.tools.ant.util.regexp.JakartaRegexpRegexp

It can also be another implementation of the interface `org.apache.tools.ant.util.regexp.Regexp`. If `ant.regexp.regexpimpl` is not defined, ant checks in the order Jdk14Regexp, JakartaOroRegexp, JakartaRegexp for the availability of the corresponding library. The first of these 3 which is found will be used.

There are cross-platform issues for matches related to line terminator. For example if you use $ to anchor your regular expression on the end of a line the results might be very different depending on both your platform and the regular expression library you use. It is 'highly recommended' that you test your pattern on both Unix and Windows platforms before you rely on it.

- Jakarta Oro defines a line terminator as '\n' and is consistent with Perl.
- Jakarta RegExp uses a system-dependant line terminator.
- JDK 1.4 uses '\n', '\r\n', '\u0085', '\u2028', '\u2029' as a default but is configured in the wrapper to use only '\n' (UNIX_LINE)

We strongly recommend that you use Jakarta Oro.

### Parameters specified as nested elements

This task supports a nested FileSet element.

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

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

replaces 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 match="\s+" replace=" " flags="g" byline="true">
>         <fileset dir="${html.dir}" includes="**/*.html" />
>     </replaceregexp>

replaces all whitespaces (blanks, tabs, etc) by one blank remaining the line separator. So with input

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

would converted to

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

Copyright © 2001-2004 The Apache Software Foundation. All rights Reserved.