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>
|
---|