Ant: The Definitive Guide

Name

filter

Synopsis

Defines token filters. These are used to perform text substitution, known as token filtering, when copying files. In Ant 1.2 and 1.3, tokens are always of the form @ token @. Ant 1.4 adds the ability to use a character other than @ with the <filterset> element. Filters should not be used with binary files.

The <filter> element can appear inside of targets, or as a nested element in various tasks that copy files.

Attributes

filtersfile (all, File, *)

A file containing token/value pairs, formatted as a Java properties file.

token (all, String, *)

The text to replace in the source file, not including the @ characters.

value (all, String, *)

The text to substitute in place of @ token @. The @ characters are not preserved.

You must specify either the filtersfile attribute, or both token and value.

Content

None.

Example Usage

Let’s start with the following source file:

                  // %COPYRIGHT!
/**
 * @version @VERSION@
 */
public class Hello {
  ...
}

We want to replace %COPYRIGHT! with a copyright notice, and @VERSION@ with the correct version number. Here is a target within a buildfile that does this:

<target name="tokenFilterDemo" depends="prepare">
  <filter token="VERSION" value="1.0"/>
  <copy todir="build" filtering="true">
    <!-- select files to copy -->
    <fileset dir="src">
      <include name="**/*.java"/>
    </fileset>
    <filterset begintoken="%" endtoken="!">
                        <filter token="COPYRIGHT" 
                                value="Copyright (C) 2002 O'Reilly"/>
                      </filterset>
  </copy>
</target>

The first <filter> element takes care of replacing ...