| 1 | <!--
|
|---|
| 2 | Licensed to the Apache Software Foundation (ASF) under one or more
|
|---|
| 3 | contributor license agreements. See the NOTICE file distributed with
|
|---|
| 4 | this work for additional information regarding copyright ownership.
|
|---|
| 5 | The ASF licenses this file to You under the Apache License, Version 2.0
|
|---|
| 6 | (the "License"); you may not use this file except in compliance with
|
|---|
| 7 | the License. You may obtain a copy of the License at
|
|---|
| 8 |
|
|---|
| 9 | http://www.apache.org/licenses/LICENSE-2.0
|
|---|
| 10 |
|
|---|
| 11 | Unless required by applicable law or agreed to in writing, software
|
|---|
| 12 | distributed under the License is distributed on an "AS IS" BASIS,
|
|---|
| 13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|---|
| 14 | See the License for the specific language governing permissions and
|
|---|
| 15 | limitations under the License.
|
|---|
| 16 | -->
|
|---|
| 17 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|---|
| 18 |
|
|---|
| 19 | <html>
|
|---|
| 20 | <head>
|
|---|
| 21 | <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
|---|
| 22 | <title>FilterSet Type</title>
|
|---|
| 23 | </head>
|
|---|
| 24 |
|
|---|
| 25 | <body>
|
|---|
| 26 | <h2><a name="filterset">FilterSet</a></h2>
|
|---|
| 27 |
|
|---|
| 28 | <p>FilterSets are groups of filters. Filters can be defined as token-value
|
|---|
| 29 | pairs
|
|---|
| 30 | or be read in from a file. FilterSets can appear inside tasks that support this
|
|---|
| 31 | feature or at the same level as <code><target></code> - i.e., as
|
|---|
| 32 | children of
|
|---|
| 33 | <code><project></code>.</p>
|
|---|
| 34 |
|
|---|
| 35 | <p>FilterSets support the <code>id</code> and <code>refid</code>
|
|---|
| 36 | attributes. You can define a FilterSet with an <code>id</code>
|
|---|
| 37 | attribute and then refer to that definition from another FilterSet
|
|---|
| 38 | with a <code>refid</code> attribute. It is also possible to nest
|
|---|
| 39 | filtersets into filtersets to get a set union of the contained
|
|---|
| 40 | filters.</p>
|
|---|
| 41 |
|
|---|
| 42 | <p>In addition, FilterSets can specify
|
|---|
| 43 | <code>begintoken</code> and/or
|
|---|
| 44 | <code>endtoken</code> attributes to define what to match.</p>
|
|---|
| 45 | <p>Filtersets are used for doing
|
|---|
| 46 | replacements in tasks such as <code><copy></code>, etc.</p>
|
|---|
| 47 |
|
|---|
| 48 | <p>
|
|---|
| 49 | <strong>Note: </strong>When a filterset is used in an operation, the files are
|
|---|
| 50 | processed in text mode and the filters applied line by line. This means that
|
|---|
| 51 | the copy operations will typically corrupt binary files. When applying filters
|
|---|
| 52 | you should ensure that the set of files being filtered are all text files.
|
|---|
| 53 | </p>
|
|---|
| 54 |
|
|---|
| 55 | <h2>Filterset</h2>
|
|---|
| 56 |
|
|---|
| 57 | <table cellSpacing=0 cellPadding=2 border=1>
|
|---|
| 58 | <tr>
|
|---|
| 59 | <td vAlign=top><b>Attribute</b></td>
|
|---|
| 60 | <td vAlign=top><b>Description</b></td>
|
|---|
| 61 | <td vAlign=top><b>Default</b></td>
|
|---|
| 62 | <td vAlign=top align="center"><b>Required</b></td>
|
|---|
| 63 | </tr>
|
|---|
| 64 | <tr>
|
|---|
| 65 | <td vAlign=top>begintoken</td>
|
|---|
| 66 | <td vAlign=top>The string marking the beginning of a token (eg.,
|
|---|
| 67 | <code>@DATE@</code>).</td>
|
|---|
| 68 | <td vAlign=top>@</td>
|
|---|
| 69 | <td vAlign=top align="center">No</td>
|
|---|
| 70 | </tr>
|
|---|
| 71 | <tr>
|
|---|
| 72 | <td vAlign=top>endtoken</td>
|
|---|
| 73 | <td vAlign=top>The string marking the end of a token (eg.,
|
|---|
| 74 | <code>@DATE@</code>).</td>
|
|---|
| 75 | <td vAlign=top>@</td>
|
|---|
| 76 | <td vAlign=top align="center">No</td>
|
|---|
| 77 | </tr>
|
|---|
| 78 | <tr>
|
|---|
| 79 | <td vAlign=top>filtersfile</td>
|
|---|
| 80 | <td vAlign=top>Specify a single filtersfile.</td>
|
|---|
| 81 | <td vAlign=top><i>none</i></td>
|
|---|
| 82 | <td vAlign=top align="center">No</td>
|
|---|
| 83 | </tr>
|
|---|
| 84 | <tr>
|
|---|
| 85 | <td vAlign=top>recurse</td>
|
|---|
| 86 | <td vAlign=top>Indicates whether the replacement text of tokens
|
|---|
| 87 | should be searched for more tokens. <b>Since Ant 1.6.3</b></td>
|
|---|
| 88 | <td vAlign=top><i>true</i></td>
|
|---|
| 89 | <td vAlign=top align="center">No</td>
|
|---|
| 90 | </tr>
|
|---|
| 91 | <tr>
|
|---|
| 92 | <td vAlign=top>onmissingfiltersfile</td>
|
|---|
| 93 | <td vAlign=top>Indicate behavior when a nonexistent <i>filtersfile</i>
|
|---|
| 94 | is specified. One of "fail", "warn", "ignore". <b>Since Ant 1.7</b></td>
|
|---|
| 95 | <td vAlign=top>"fail"</td>
|
|---|
| 96 | <td vAlign=top align="center">No</td>
|
|---|
| 97 | </tr>
|
|---|
| 98 | </table>
|
|---|
| 99 |
|
|---|
| 100 | <h2>Filter</h2>
|
|---|
| 101 | <table cellSpacing=0 cellPadding=2 border=1>
|
|---|
| 102 | <tr>
|
|---|
| 103 | <td vAlign=top><b>Attribute</b></td>
|
|---|
| 104 | <td vAlign=top><b>Description</b></td>
|
|---|
| 105 | <td vAlign=top align="center"><b>Required</b></td>
|
|---|
| 106 | </tr>
|
|---|
| 107 | <tr>
|
|---|
| 108 | <td vAlign=top>token</td>
|
|---|
| 109 | <td vAlign=top>The token to replace (eg., <code>@DATE@</code>)</td>
|
|---|
| 110 | <td vAlign=top align="center">Yes</td>
|
|---|
| 111 | </tr>
|
|---|
| 112 | <tr>
|
|---|
| 113 | <td vAlign=top>value</td>
|
|---|
| 114 | <td vAlign=top>The value to replace it with
|
|---|
| 115 | (eg., <code>Thursday, April 26, 2001</code>).</td>
|
|---|
| 116 | <td vAlign=top align="center">Yes</td>
|
|---|
| 117 | </tr>
|
|---|
| 118 | </table>
|
|---|
| 119 |
|
|---|
| 120 | <h2>Filtersfile</h2>
|
|---|
| 121 | <table cellSpacing=0 cellPadding=2 border=1>
|
|---|
| 122 | <tr>
|
|---|
| 123 | <td vAlign=top><b>Attribute</b></td>
|
|---|
| 124 | <td vAlign=top><b>Description</b></td>
|
|---|
| 125 | <td vAlign=top align="center"><b>Required</b></td>
|
|---|
| 126 | </tr>
|
|---|
| 127 | <tr>
|
|---|
| 128 | <td vAlign=top>file</td>
|
|---|
| 129 | <td vAlign=top>A properties file of
|
|---|
| 130 | name-value pairs from which to load the tokens.</td>
|
|---|
| 131 | <td vAlign=top align="center">Yes</td>
|
|---|
| 132 | </tr>
|
|---|
| 133 | </table>
|
|---|
| 134 |
|
|---|
| 135 | <h3>Examples</h3>
|
|---|
| 136 |
|
|---|
| 137 | <p>You are copying the <code>version.txt</code> file to the <code>dist</code>
|
|---|
| 138 | directory from the <code>build</code> directory
|
|---|
| 139 | but wish to replace the token <code>@DATE@</code> with today's date.</p>
|
|---|
| 140 | <blockquote><pre>
|
|---|
| 141 | <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
|
|---|
| 142 | <filterset>
|
|---|
| 143 | <filter token="DATE" value="${TODAY}"/>
|
|---|
| 144 | </filterset>
|
|---|
| 145 | </copy>
|
|---|
| 146 | </pre></blockquote>
|
|---|
| 147 |
|
|---|
| 148 | <p>You are copying the <code>version.txt</code> file to the <code>dist</code>
|
|---|
| 149 | directory from the build directory
|
|---|
| 150 | but wish to replace the token <code>%DATE*</code> with today's date.</p>
|
|---|
| 151 | <blockquote><pre>
|
|---|
| 152 | <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
|
|---|
| 153 | <filterset begintoken="%" endtoken="*">
|
|---|
| 154 | <filter token="DATE" value="${TODAY}"/>
|
|---|
| 155 | </filterset>
|
|---|
| 156 | </copy>
|
|---|
| 157 | </pre></blockquote>
|
|---|
| 158 |
|
|---|
| 159 | <p>Copy all the docs but change all dates and appropriate notices as stored in a file.</p>
|
|---|
| 160 | <blockquote><pre>
|
|---|
| 161 | <copy toDir="${dist.dir}/docs">
|
|---|
| 162 | <fileset dir="${build.dir}/docs">
|
|---|
| 163 | <include name="**/*.html">
|
|---|
| 164 | </fileset>
|
|---|
| 165 | <filterset begintoken="%" endtoken="*">
|
|---|
| 166 | <filtersfile file="${user.dir}/dist.properties"/>
|
|---|
| 167 | </filterset>
|
|---|
| 168 | </copy>
|
|---|
| 169 | </pre></blockquote>
|
|---|
| 170 |
|
|---|
| 171 | <p>Define a FilterSet and reference it later.</p>
|
|---|
| 172 | <blockquote><pre>
|
|---|
| 173 | <filterset id="myFilterSet" begintoken="%" endtoken="*">
|
|---|
| 174 | <filter token="DATE" value="${TODAY}"/>
|
|---|
| 175 | </filterset>
|
|---|
| 176 |
|
|---|
| 177 | <copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
|
|---|
| 178 | <filterset refid="myFilterSet"/>
|
|---|
| 179 | </copy>
|
|---|
| 180 | </pre></blockquote>
|
|---|
| 181 | </body></html>
|
|---|
