| <!DOCTYPE html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| https://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html lang="en"> |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>FilterSet Type</title> |
| </head> |
| |
| <body> |
| <h2 id="filterset">FilterSet</h2> |
| |
| <p>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 <code><target></code>—i.e., as children of <code><project></code>.</p> |
| |
| <p>FilterSets support the <var>id</var> and <var>refid</var> attributes. You can define a |
| FilterSet with an <var>id</var> attribute and then refer to that definition from another |
| FilterSet with a <var>refid</var> attribute. It is also possible to nest filtersets into |
| filtersets to get a set union of the contained filters.</p> |
| |
| <p>In addition, FilterSets can specify <var>begintoken</var> and/or <var>endtoken</var> |
| attributes to define what to match.</p> |
| |
| <p>Filtersets are used for doing replacements in tasks such as <code><copy></code>, |
| etc.</p> |
| |
| <p>Filters can also by specified by one or more nested propertysets, the contents of which are |
| applied when the filterset is created.</p> |
| |
| <p>If you specify multiple values for the same token, the last one defined within a filterset |
| will be used.</p> |
| |
| <p><strong>Note</strong>: 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.</p> |
| |
| <h3>Filterset</h3> |
| |
| <table class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Default</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>begintoken</td> |
| <td>The string marking the beginning of a token (eg., <samp>@DATE@</samp>).</td> |
| <td><q>@</q></td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>endtoken</td> |
| <td>The string marking the end of a token (eg., <samp>@DATE@</samp>).</td> |
| <td><q>@</q></td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>filtersfile</td> |
| <td>Specify a single filtersfile.</td> |
| <td><em>none</em></td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>recurse</td> |
| <td>Indicates whether the replacement text of tokens should be searched for more |
| tokens. <em>Since Ant 1.6.3</em></td> |
| <td><q>true</q></td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>onmissingfiltersfile</td> |
| <td>Indicate behavior when a nonexistent <var>filtersfile</var> is specified. One |
| of <q>fail</q>, <q>warn</q>, <q>ignore</q>. <em>Since Ant 1.7</em></td> |
| <td><q>fail</q></td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>refid</td> |
| <td>Makes this <code>filterset</code> |
| a <a href="../using.html#references">reference</a> to |
| a <code>filterset</code> defined elsewhere. If specified no |
| other attributes or nested elements are allowed.</td> |
| <td>No</td> |
| </tr> |
| </table> |
| |
| <h3>Filter</h3> |
| <table> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>token</td> |
| <td>The token to replace (eg., <samp>@DATE@</samp>)</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>value</td> |
| <td>The value to replace it with (eg., <q>Thursday, April 26, 2001</q>).</td> |
| <td>Yes</td> |
| </tr> |
| </table> |
| |
| <h3>Filtersfile</h3> |
| <table> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>file</td> |
| <td>A properties file of name-value pairs from which to load the tokens.</td> |
| <td>Yes</td> |
| </tr> |
| </table> |
| |
| <h4>Examples</h4> |
| |
| <p>You are copying the <samp>version.txt</samp> file to the <samp>dist</samp> directory from |
| the <samp>build</samp> directory but wish to replace the token <samp>@DATE@</samp> with today's |
| date.</p> |
| <pre> |
| <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt"> |
| <filterset> |
| <filter token="DATE" value="${TODAY}"/> |
| </filterset> |
| </copy> |
| </pre> |
| |
| <p>You are copying the <samp>version.txt</samp> file to the <samp>dist</samp> directory from the |
| build directory but wish to replace the token <samp>%DATE*</samp> with today's date.</p> |
| <pre> |
| <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt"> |
| <filterset begintoken="%" endtoken="*"> |
| <filter token="DATE" value="${TODAY}"/> |
| </filterset> |
| </copy> |
| </pre> |
| |
| <p>Copy all the docs but change all dates and appropriate notices as stored in a file.</p> |
| <pre> |
| <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> |
| </pre> |
| |
| <p>Define a FilterSet and reference it later.</p> |
| <pre> |
| <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> |
| </pre> |
| |
| <p>You are copying the <samp>version.txt</samp> file to the <samp>dist</samp> directory from |
| the <samp>build</samp> directory but wish to replace the token <samp>@project.date@</samp> with |
| the property of the same name.</p> |
| <pre> |
| <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt"> |
| <filterset> |
| <propertyset> |
| <propertyref name="project.date"/> |
| </propertyset> |
| </filterset> |
| </copy> |
| </pre> |
| </body> |
| </html> |