Section 10.3. Subtituting Text Using Regular Expressions

10.3. Subtituting Text Using Regular Expressions

The replaceregexp task can replace every occurrence of a given regular expression with a substitution pattern in a selected file or set of files.

The output file is written only if it differs from the existing file.

Example 10-2 uses replaceregexp, where text in the XML comment in the build file matching "Here's a comment." is converted to "Here's an XML comment."

Example 10-2. Using regular expression substitutions (ch10/regexp/build.xml)

<?xml version="1.0"?> <project default="main" basedir="."> <!--Here's a comment.-->     <target name="main">         <replaceregexp              match="a comment"             replace="an XML comment">             <fileset dir="." includes="**/*.xml" />         </replaceregexp>     </target> </project>

Here's what the build file looks like after you run it:

<?xml version="1.0"?> <project default="main" basedir="."> <!--Here's an XML comment.-->     <target name="main">         <replaceregexp              match="a comment"             replace="an XML comment">             <fileset dir="." includes="**/*.xml" />         </replaceregexp>     </target> </project>

Changing the contents of other files this way will be useful if you need to rewrite build files that you're about to call with the ant task. Here's an example of editing build files to convert from a local to an FTP install:

<?xml version="1.0"?> <project default="main" basedir=".">     <target name="main">         <replaceregexp              match="<copy file='Project.jar' todir='dist'/>"             replace="<ftp server='ftp.isp.com'><fileset dir='bin'/></ftp>"             <fileset dir="subproject" includes="**/*.xml" />         </replaceregexp>     </target>     <ant dir="subproject"/> </project>

Unless it's unavoidable, editing build files this way is not good programming practice. It's better to pass parameters along with the ant call.

Here's another example, this time of replacing all whitespace in documentation files with spaces:

<replaceregexp match="\s+" replace=" " flags="g">     <fileset dir="docs" includes="**/*.html" /> </replaceregexp>

The attributes of this task appear in Table 10-3.

Support exists for the regular expression library built into Java 1.4; you should have jakarta-oro.jar in the Ant lib directory.

Table 10-3. The replaceregexp attributes

Attribute	Description	Required	Default
byline	Specifies you want to process the file(s) one line at a time, executing the replacement on one line at a time.	No	false
encoding	Specifies the encoding of the file you're using. Available since Ant 1.6.	No	The default JVM encoding.
file	Specifies the file in which text matching the regular expression should be replaced.	Yes, if no nested fileset is used.
flags	Specifies flags to use when matching the regular expression. For example, "g" means global replacement, "i" means case insensitive, and so on.	No
match	Specifies the regular expression pattern you want to use to match text in the source file(s).	Yes, if no nested regexp is used.
replace	Specifies the text to replace matched text with.	Yes, if no nested substitution is used.

This task supports a nested fileset element. You can use a nested regexp element to specify the regular expression this way:

<regexp  pattern="\s+"/> <regexp ref/>

The replaceregexp task supports a nested substitution element to specify the substitution pattern; here are some examples:

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