## FilterSet

FilterSets are groups of filters. Filters can be defined as token-value pairs or be read in from a file. FilterSets can appear inside tasks that support this feature or at the same level as `<target>`—i.e., as children of `<project>`.

FilterSets support the id and refid attributes. You can define a FilterSet with an id attribute and then refer to that definition from another FilterSet with a refid attribute. It is also possible to nest filtersets into filtersets to get a set union of the contained filters.

In addition, FilterSets can specify begintoken and/or endtoken attributes to define what to match.

Filtersets are used for doing replacements in tasks such as `<copy>`, etc.

Filters can also by specified by one or more nested propertysets, the contents of which are applied when the filterset is created.

If you specify multiple values for the same token, the last one defined within a filterset will be used.

Note: When a filterset is used in an operation, the files are processed in text mode and the filters applied line by line. This means that the copy operations will typically corrupt binary files. When applying filters you should ensure that the set of files being filtered are all text files.

### Filterset

Attribute | Description | Default | Required
--- | --- | --- | ---
begintoken | The string marking the beginning of a token (eg., `@DATE@`). | @ | No
endtoken | The string marking the end of a token (eg., `@DATE@`). | @ | No
filtersfile | Specify a single filtersfile. | none | No
recurse | Indicates whether the replacement text of tokens should be searched for more tokens. Since Ant 1.6.3 | true | No
onmissingfiltersfile | Indicate behavior when a nonexistent filtersfile is specified. One of fail, warn, ignore. Since Ant 1.7 | fail | No
refid | Makes this `filterset` a reference to a `filterset` defined elsewhere. If specified no other attributes or nested elements are allowed. | No

### Filter

Attribute | Description | Required
--- | --- | ---
token | The token to replace (eg., `@DATE@`) | Yes
value | The value to replace it with (eg., Thursday, April 26, 2001). | Yes

### Filtersfile

Attribute | Description | Required
--- | --- | ---
file | A properties file of name-value pairs from which to load the tokens. | Yes

#### Examples

You are copying the `version.txt` file to the `dist` directory from the `build` directory but wish to replace the token `@DATE@` with today's date.

    <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
      <filterset>
        <filter token="DATE" value="${TODAY}"/>
      </filterset>
    </copy>

You are copying the `version.txt` file to the `dist` directory from the build directory but wish to replace the token `%DATE*` with today's date.

    <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
      <filterset begintoken="%" endtoken="*">
        <filter token="DATE" value="${TODAY}"/>
      </filterset>
    </copy>

Copy all the docs but change all dates and appropriate notices as stored in a file.

    <copy toDir="${dist.dir}/docs">
      <fileset dir="${build.dir}/docs">
        <include name="**/*.html">
      </fileset>
      <filterset begintoken="%" endtoken="*">
        <filtersfile file="${user.dir}/dist.properties"/>
      </filterset>
    </copy>

Define a FilterSet and reference it later.

    <filterset id="myFilterSet" begintoken="%" endtoken="*">
      <filter token="DATE" value="${TODAY}"/>
    </filterset>

    <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
      <filterset refid="myFilterSet"/>
    </copy>

You are copying the `version.txt` file to the `dist` directory from the `build` directory but wish to replace the token `@project.date@` with the property of the same name.

    <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
      <filterset>
        <propertyset>
          <propertyref name="project.date"/>
        </propertyset>
      </filterset>
    </copy>