Ant: The Definitive Guide

FilterSet DataType

The filterset DataType was introduced in Ant 1.4, and allows for the definition of groups of filters. These filters (implemented by the filter task) perform text substitution in files as they are moved or copied. This is known as token filtering. The text substitution occurs when certain tokens are found in the input files. As the files are moved or copied, the tokens are replaced by text defined in the matching filter. Prior to Ant 1.4, the filter task always used @ characters as token delimiters. filterset allows you to customize the beginning and ending token delimiters.

The filterset DataType is represented by the <filterset> element. <filterset> elements may appear as nested content within the copy and move tasks, or as target-level buildfile elements (i.e., children of <project>). Following are the allowable filterset attributes:

begintoken (1.4, String, N)

The string marking the beginning of a token that nested filters search for. Defaults to @.

endtoken (1.4, String, N)

The string marking the end of a token that nested filters search for. Defaults to @.

id (1.4, String, N)

A unique identifier for this filter. This is required when the filter is defined as a target-level buildfile element and must be referenced later.

refid (1.4, Reference, N)

A reference to a filter defined elsewhere in the buildfile.

A filterset may also contain the following:

0..n nested <filter> elements (1.4)

Each nested <filter> element defines a token and the replacement text. <filter> requires the following attributes:

token (1.4, String, Y)

Specifies the token to replace, not including the delimiter characters. If this filter is intended to replace @VERSION@, use VERSION as this attribute value.

value (1.4, String, Y)

Specifies the replacement text whenever the token is encountered.

0..n nested <filtersfile> elements. (1.4)

Each specifies a Java properties file from which to load additional filters. Each line of the file contains a token, followed by a colon (:), followed by a value. <filtersfile> requires the following attribute:

file (1.4, File, Y)

The name of the properties file containing filters.

Example

This example target shows how to replace the %COPYRIGHT! and %BUILD_DATE! tokens as files are copied:

  <target name="tokenFilterDemo" depends="prepare">
    <!-- set up the timestamp -->
    <tstamp>
      <format property="now" pattern="MMMM d yyyy hh:mm aa"/>
    </tstamp>

    <copy todir="build" filtering="true">
      <fileset dir="src">
        <include name="**/*.java"/>
      </fileset>

      <!-- search for %COPYRIGHT! and %BUILD_DATE! -->
               
      <filterset begintoken="%" endtoken="!">
               
         <filter token="BUILD_DATE" value="${now}"/>
               
         <filter token="COPYRIGHT" value="Copyright (C) 2002 O'Reilly"/>
               
      </filterset>
    </copy>
  </target>

Notice that filtering="true" must be set on the copy task in order for token filtering to occur. Our filterset consists of two different filters, and we explicitly specify the begintoken and endtoken because we do not want to use the default @ characters.

Here is a source file before it is copied:

// %COPYRIGHT!
// Built on %BUILD_DATE!

public class Whatever {
    ...
}

And here is what the target file looks like after the copy operation:

// Copyright (C) 2002 O'Reilly
// Built on March 12 2002 03:10 PM

public class Whatever {
    ...
}

Tokens may appear numerous times in each source file; all are replaced. For another example, see the filter task in Chapter 7.