source: other-projects/trunk/gs3-release-maker/apache-ant-1.6.5/docs/manual/CoreTypes/filterset.html@ 14627

Last change on this file since 14627 was 14627, checked in by oranfry, 17 years ago

initial import of the gs3-release-maker
File size: 5.3 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2
3<html>
4<head>
5 <title>FilterSet Type</title>
6 <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
7</head>
8
9<body>
10<h2><a name="filterset">FilterSet</a></h2>
11
12<p>FilterSets are groups of filters. Filters can be defined as token-value
13pairs
14or be read in from a file. FilterSets can appear inside tasks that support this
15feature or at the same level as <code>&lt;target&gt;</code> - i.e., as
16children of
17<code>&lt;project&gt;</code>.</p>
18
19<p>FilterSets support the <code>id</code> and <code>refid</code>
20attributes. You can define a FilterSet with an <code>id</code>
21attribute and then refer to that definition from another FilterSet
22with a <code>refid</code> attribute. It is also possible to nest
23filtersets into filtersets to get a set union of the contained
24filters.</p>
25
26<p>In addition, FilterSets can specify
27<code>begintoken</code> and/or
28<code>endtoken</code> attributes to define what to match.</p>
29<p>Filtersets are used for doing
30replacements in tasks such as <code>&lt;copy&gt;</code>, etc.</p>
31
32<p>
33<strong>Note: </strong>When a filterset is used in an operation, the files are
34processed in text mode and the filters applied line by line. This means that
35the copy operations will typically corrupt binary files. When applying filters
36you should ensure that the set of files being filtered are all text files.
37</p>
38
39<h2>Filterset</h2>
40
41<table cellSpacing=0 cellPadding=2 border=1>
42 <tr>
43 <td vAlign=top><b>Attribute</b></td>
44 <td vAlign=top><b>Description</b></td>
45 <td vAlign=top><b>Default</b></td>
46 <td vAlign=top align="center"><b>Required</b></td>
47 </tr>
48 <tr>
49 <td vAlign=top>begintoken</td>
50 <td vAlign=top>The string marking the beginning of a token (eg.,
51 <code>&#64;DATE&#64;</code>).</td>
52 <td vAlign=top>@</td>
53 <td vAlign=top align="center">No</td>
54 </tr>
55 <tr>
56 <td vAlign=top>endtoken</td>
57 <td vAlign=top>The string marking the end of a token (eg.,
58 <code>&#64;DATE&#64;</code>).</td>
59 <td vAlign=top>@</td>
60 <td vAlign=top align="center">No</td>
61 </tr>
62 <tr>
63 <td vAlign=top>recurse</td>
64 <td vAlign=top>Indicates whether the replacement text of tokens
65 should be searched for more tokens. <b>Since Ant 1.6.3</b></td>
66 <td vAlign=top><i>true</i></td>
67 <td vAlign=top align="center">No</td>
68 </tr>
69</table>
70
71<h2>Filter</h2>
72<table cellSpacing=0 cellPadding=2 border=1>
73 <tr>
74 <td vAlign=top><b>Attribute</b></td>
75 <td vAlign=top><b>Description</b></td>
76 <td vAlign=top align="center"><b>Required</b></td>
77 </tr>
78 <tr>
79 <td vAlign=top>token</td>
80 <td vAlign=top>The token to replace (eg., <code>&#64;DATE&#64;</code>)</td>
81 <td vAlign=top align="center">Yes</td>
82 </tr>
83 <tr>
84 <td vAlign=top>value</td>
85 <td vAlign=top>The value to replace it with
86 (eg., <code>Thursday, April 26, 2001</code>).</td>
87 <td vAlign=top align="center">Yes</td>
88 </tr>
89</table>
90
91<h2>Filtersfile</h2>
92<table cellSpacing=0 cellPadding=2 border=1>
93 <tr>
94 <td vAlign=top><b>Attribute</b></td>
95 <td vAlign=top><b>Description</b></td>
96 <td vAlign=top align="center"><b>Required</b></td>
97 </tr>
98 <tr>
99 <td vAlign=top>file</td>
100 <td vAlign=top>A properties file of
101 name-value pairs from which to load the tokens.</td>
102 <td vAlign=top align="center">Yes</td>
103 </tr>
104</table>
105
106<h4>Examples</h4>
107
108<p>You are copying the <code>version.txt</code> file to the <code>dist</code>
109directory from the <code>build</code> directory
110but wish to replace the token <code>&#64;DATE&#64;</code> with today's date.</p>
111<blockquote><pre>
112&lt;copy file=&quot;${build.dir}/version.txt&quot; toFile=&quot;${dist.dir}/version.txt&quot;&gt;
113 &lt;filterset&gt;
114 &lt;filter token=&quot;DATE&quot; value=&quot;${TODAY}&quot;/&gt;
115 &lt;/filterset&gt;
116&lt;/copy&gt;
117</pre></blockquote>
118
119<p>You are copying the <code>version.txt</code> file to the <code>dist</code>
120directory from the build directory
121but wish to replace the token <code>%DATE*</code> with today's date.</p>
122<blockquote><pre>
123&lt;copy file=&quot;${build.dir}/version.txt&quot; toFile=&quot;${dist.dir}/version.txt&quot;&gt;
124 &lt;filterset begintoken=&quot;%&quot; endtoken=&quot;*&quot;&gt;
125 &lt;filter token=&quot;DATE&quot; value=&quot;${TODAY}&quot;/&gt;
126 &lt;/filterset&gt;
127&lt;/copy&gt;
128</pre></blockquote>
129
130<p>Copy all the docs but change all dates and appropriate notices as stored in a file.</p>
131<blockquote><pre>
132&lt;copy toDir=&quot;${dist.dir}/docs&quot;&gt;
133 &lt;fileset dir=&quot;${build.dir}/docs&quot;&gt;
134 &lt;include name=&quot;**/*.html&quot;&gt;
135 &lt;/fileset&gt;
136 &lt;filterset begintoken=&quot;%&quot; endtoken=&quot;*&quot;&gt;
137 &lt;filtersfile file=&quot;${user.dir}/dist.properties&quot;/&gt;
138 &lt;/filterset&gt;
139&lt;/copy&gt;
140</pre></blockquote>
141
142<p>Define a FilterSet and reference it later.</p>
143<blockquote><pre>
144&lt;filterset id=&quot;myFilterSet&quot; begintoken=&quot;%&quot; endtoken=&quot;*&quot;&gt;
145 &lt;filter token=&quot;DATE&quot; value=&quot;${TODAY}&quot;/&gt;
146&lt;/filterset&gt;
147
148&lt;copy file=&quot;${build.dir}/version.txt&quot; toFile=&quot;${dist.dir}/version.txt&quot;&gt;
149 &lt;filterset refid=&quot;myFilterSet&quot;/&gt;
150&lt;/copy&gt;
151</pre></blockquote>
152<hr>
153
154<p align=center>Copyright &copy; 2001-2005 The Apache Software Foundation.
155All rights Reserved.</p></body></html>
Note: See TracBrowser for help on using the repository browser.