source: release-kits/lirk3/bin/ant-installer/web/manual1.6.2/manual/CoreTypes/mapper.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

initial import of LiRK3
File size: 18.4 KB
Line 
1<html>
2
3<head>
4<meta http-equiv="Content-Language" content="en-us">
5<title>Mapper Type</title>
6<link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
7</head>
8
9<body>
10
11<h2><a name="mapper">Mapping File Names</a></h2>
12<p>Some tasks take source files and create target files. Depending on
13the task, it may be quite obvious which name a target file will have
14(using <a href="../CoreTasks/javac.html">javac</a>, you know there will be
15<code>.class</code> files for your <code>.java</code> files) - in
16other cases you may want to specify the target files, either to help
17Ant or to get an extra bit of functionality.</p>
18<p>While source files are usually specified as <a
19href="fileset.html">fileset</a>s, you don't specify target files directly -
20instead, you tell Ant how to find the target file(s) for one source file. An
21instance of <code>org.apache.tools.ant.util.FileNameMapper</code> is
22responsible for this. It constructs target file names based on rules
23that can be parameterized with <code>from</code> and <code>to</code>
24attributes - the exact meaning of which is implementation-dependent.</p>
25<p>These instances are defined in <code>&lt;mapper&gt;</code> elements
26with the following attributes:</p>
27<table border="1" cellpadding="2" cellspacing="0">
28 <tr>
29 <td valign="top"><b>Attribute</b></td>
30 <td valign="top"><b>Description</b></td>
31 <td align="center" valign="top"><b>Required</b></td>
32 </tr>
33 <tr>
34 <td valign="top">type</td>
35 <td valign="top">specifies one of the built-in implementations.</td>
36 <td rowspan="2" align="center" valign="middle">Exactly one of these</td>
37 </tr>
38 <tr>
39 <td valign="top">classname</td>
40 <td valign="top">specifies the implementation by class name.</td>
41 </tr>
42 <tr>
43 <td valign="top">classpath</td>
44 <td valign="top">the classpath to use when looking up
45 <code>classname</code>.</td>
46 <td align="center" valign="top">No</td>
47 </tr>
48 <tr>
49 <td valign="top">classpathref</td>
50 <td valign="top">the classpath to use, given as <a
51 href="../using.html#references">reference</a> to a path defined elsewhere.</td>
52 <td align="center" valign="top">No</td>
53 </tr>
54 <tr>
55 <td valign="top">from</td>
56 <td valign="top">the <code>from</code> attribute for the given
57 implementation.</td>
58 <td align="center" valign="top">Depends on implementation.</td>
59 </tr>
60 <tr>
61 <td valign="top">to</td>
62 <td valign="top">the <code>to</code> attribute for the given
63 implementation.</td>
64 <td align="center" valign="top">Depends on implementation.</td>
65 </tr>
66</table>
67<p>Note that Ant will not automatically convert / or \ characters in
68the <code>to</code> and <code>from</code> attributes to the correct
69directory separator of your current platform. If you need to specify
70this separator, use <code>${file.separator}</code> instead.</p>
71<h3>Parameters specified as nested elements</h3>
72<p>The classpath can be specified via a nested
73<code>&lt;classpath&gt;</code>, as well - that is,
74a <a href="../using.html#path">path</a>-like structure.</p>
75<p><b>Since Ant 1.6.2,</b> nested File Mappers can
76be supplied via either <CODE>&lt;mapper&gt;</CODE> elements or
77<a href="../CoreTasks/typedef.html"><code>&lt;typedef&gt;</code></a>'d
78implementations of <CODE>org.apache.tools.ant.util.FileNameMapper</CODE>.
79If nested File Mappers are specified by either means, the mapper will be
80implicitly configured as a <a href="#composite-mapper">composite mapper</a>.
81</p>
82<hr/>
83<h3>The built-in mapper types are:</h3>
84<p>All built-in mappers are case-sensitive.</p>
85<p><b>As of Ant 1.6.2,</b> each of the built-in mapper implementation
86 types is directly accessible using a specific tagname. This makes it
87 possible for filename mappers to support attributes in addition to
88 the generally available <i>to</i> and <i>from</i>.<br/>
89 The <code>&lt;mapper type|classname=&quot;...&quot;&gt;</code> usage
90 form remains valid for reasons of backward compatibility.</p>
91<h4><a name="identity-mapper">identity</a></h4>
92<p>The target file name is identical to the source file name. Both
93<code>to</code> and <code>from</code> will be ignored.</p>
94<b>Examples:</b>
95<blockquote><pre>
96&lt;mapper type=&quot;identity&quot;/&gt;
97&lt;identitymapper /&gt;
98</pre></blockquote>
99<table border="1" cellpadding="2" cellspacing="0">
100 <tr>
101 <td valign="top"><b>Source file name</b></td>
102 <td valign="top"><b>Target file name</b></td>
103 </tr>
104 <tr>
105 <td valign="top"><code>A.java</code></td>
106 <td valign="top"><code>A.java</code></td>
107 </tr>
108 <tr>
109 <td valign="top"><code>foo/bar/B.java</code></td>
110 <td valign="top"><code>foo/bar/B.java</code></td>
111 </tr>
112 <tr>
113 <td valign="top"><code>C.properties</code></td>
114 <td valign="top"><code>C.properties</code></td>
115 </tr>
116 <tr>
117 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
118 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
119 </tr>
120</table>
121<h4><a name="flatten-mapper">flatten</a></h4>
122<p>The target file name is identical to the source file name, with all
123leading directory information stripped off. Both <code>to</code> and
124<code>from</code> will be ignored.</p>
125<b>Examples:</b>
126<blockquote><pre>
127&lt;mapper type=&quot;flatten&quot;/&gt;
128&lt;flattenmapper /&gt;
129</pre></blockquote>
130<table border="1" cellpadding="2" cellspacing="0">
131 <tr>
132 <td valign="top"><b>Source file name</b></td>
133 <td valign="top"><b>Target file name</b></td>
134 </tr>
135 <tr>
136 <td valign="top"><code>A.java</code></td>
137 <td valign="top"><code>A.java</code></td>
138 </tr>
139 <tr>
140 <td valign="top"><code>foo/bar/B.java</code></td>
141 <td valign="top"><code>B.java</code></td>
142 </tr>
143 <tr>
144 <td valign="top"><code>C.properties</code></td>
145 <td valign="top"><code>C.properties</code></td>
146 </tr>
147 <tr>
148 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
149 <td valign="top"><code>A.properties</code></td>
150 </tr>
151</table>
152<h4><a name="merge-mapper">merge</a></h4>
153<p>The target file name will always be the same, as defined by
154<code>to</code> - <code>from</code> will be ignored.</p>
155<h5>Examples:</h5>
156<blockquote><pre>
157&lt;mapper type=&quot;merge&quot; to=&quot;archive.tar&quot;/&gt;
158&lt;mergemapper to=&quot;archive.tar&quot;/&gt;
159</pre></blockquote>
160<table border="1" cellpadding="2" cellspacing="0">
161 <tr>
162 <td valign="top"><b>Source file name</b></td>
163 <td valign="top"><b>Target file name</b></td>
164 </tr>
165 <tr>
166 <td valign="top"><code>A.java</code></td>
167 <td valign="top"><code>archive.tar</code></td>
168 </tr>
169 <tr>
170 <td valign="top"><code>foo/bar/B.java</code></td>
171 <td valign="top"><code>archive.tar</code></td>
172 </tr>
173 <tr>
174 <td valign="top"><code>C.properties</code></td>
175 <td valign="top"><code>archive.tar</code></td>
176 </tr>
177 <tr>
178 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
179 <td valign="top"><code>archive.tar</code></td>
180 </tr>
181</table>
182<h4><a name="glob-mapper">glob</a></h4>
183<p>Both <code>to</code> and <code>from</code> define patterns that may
184contain at most one <code>*</code>. For each source file that matches
185the <code>from</code> pattern, a target file name will be constructed
186from the <code>to</code> pattern by substituting the <code>*</code> in
187the <code>to</code> pattern with the text that matches the
188<code>*</code> in the <code>from</code> pattern. Source file names
189that don't match the <code>from</code> pattern will be ignored.</p>
190<b>Examples:</b>
191<blockquote><pre>
192&lt;mapper type=&quot;glob&quot; from=&quot;*.java&quot; to=&quot;*.java.bak&quot;/&gt;
193&lt;globmapper from=&quot;*.java&quot; to=&quot;*.java.bak&quot;/&gt;
194</pre></blockquote>
195<table border="1" cellpadding="2" cellspacing="0">
196 <tr>
197 <td valign="top"><b>Source file name</b></td>
198 <td valign="top"><b>Target file name</b></td>
199 </tr>
200 <tr>
201 <td valign="top"><code>A.java</code></td>
202 <td valign="top"><code>A.java.bak</code></td>
203 </tr>
204 <tr>
205 <td valign="top"><code>foo/bar/B.java</code></td>
206 <td valign="top"><code>foo/bar/B.java.bak</code></td>
207 </tr>
208 <tr>
209 <td valign="top"><code>C.properties</code></td>
210 <td valign="top">ignored</td>
211 </tr>
212 <tr>
213 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
214 <td valign="top">ignored</td>
215 </tr>
216</table>
217<blockquote><pre>
218&lt;mapper type=&quot;glob&quot; from=&quot;C*ies&quot; to=&quot;Q*y&quot;/&gt;
219&lt;globmapper from=&quot;C*ies&quot; to=&quot;Q*y&quot;/&gt;
220</pre></blockquote>
221<table border="1" cellpadding="2" cellspacing="0">
222 <tr>
223 <td valign="top"><b>Source file name</b></td>
224 <td valign="top"><b>Target file name</b></td>
225 </tr>
226 <tr>
227 <td valign="top"><code>A.java</code></td>
228 <td valign="top">ignored</td>
229 </tr>
230 <tr>
231 <td valign="top"><code>foo/bar/B.java</code></td>
232 <td valign="top">ignored</td>
233 </tr>
234 <tr>
235 <td valign="top"><code>C.properties</code></td>
236 <td valign="top"><code>Q.property</code></td>
237 </tr>
238 <tr>
239 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
240 <td valign="top"><code>Qlasses/dir/dir2/A.property</code></td>
241 </tr>
242</table>
243<h4><a name="regexp-mapper">regexp</a></h4>
244<p>Both <code>to</code> and <code>from</code> define regular
245expressions. If the source file name matches the <code>from</code>
246pattern, the target file name will be constructed from the
247<code>to</code> pattern, using <code>\0</code> to <code>\9</code> as
248back-references for the full
249match (<code>\0</code>) or the matches of the subexpressions in
250parentheses.
251Source
252files not matching the <code>from</code> pattern will be ignored.</p>
253<p>Note that you need to escape a dollar-sign (<code>$</code>) with
254another dollar-sign in Ant.</p>
255<p>The regexp mapper needs a supporting library and an implementation
256of <code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that
257hides the specifics of the library. Ant comes with implementations for
258<a href="http://java.sun.com/j2se/1.4/docs/api/java/util/regex/package-summary.html" target="_top">the java.util.regex package of JDK 1.4</a>,
259<a href="http://jakarta.apache.org/regexp/" target="_top">jakarta-regexp</a> and <a
260href="http://jakarta.apache.org/oro/" target="_top">jakarta-ORO</a>. If you compile
261from sources and plan to use one of them, make sure the libraries are
262in your <code>CLASSPATH</code>. For information about using <a
263href="http://www.cacas.org/~wes/java/" target="_top">gnu.regexp</a> or <a
264href="http://www.crocodile.org/~sts/Rex/" target="_top">gnu.rex</a> with Ant, see <a
265href="http://marc.theaimsgroup.com/?l=ant-dev&m=97550753813481&w=2" target="_top">this</a>
266article.</p>
267<p>This means, you need <code>optional.jar</code> from the Ant release
268you are using <strong>and</strong> one of the supported regular
269expression libraries. Make sure, both will be loaded from the same
270classpath, that is either put them into your <code>CLASSPATH</code>,
271<code>ANT_HOME/lib</code> directory or a nested
272<code>&lt;classpath&gt;</code> element of the mapper - you cannot have
273<code>optional.jar</code> in <code>ANT_HOME/lib</code> and the library
274in a nested <code>&lt;classpath&gt;</code>.</p>
275<p>Ant will choose the regular-expression library based on the
276following algorithm:</p>
277<ul>
278<li>If the system property
279<code>ant.regexp.matcherimpl</code> has been set, it is taken as the
280name of the class implementing
281<code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that
282should be used.</li>
283<li>If it has not been set, first try the JDK 1.4 classes, then
284jakarta-ORO and finally try jakarta-regexp.</li>
285</ul>
286
287<b>Examples:</b>
288<blockquote><pre>
289&lt;mapper type=&quot;regexp&quot; from=&quot;^(.*)\.java$$&quot; to=&quot;\1.java.bak&quot;/&gt;
290&lt;regexpmapper from=&quot;^(.*)\.java$$&quot; to=&quot;\1.java.bak&quot;/&gt;
291</pre></blockquote>
292<table border="1" cellpadding="2" cellspacing="0">
293 <tr>
294 <td valign="top"><b>Source file name</b></td>
295 <td valign="top"><b>Target file name</b></td>
296 </tr>
297 <tr>
298 <td valign="top"><code>A.java</code></td>
299 <td valign="top"><code>A.java.bak</code></td>
300 </tr>
301 <tr>
302 <td valign="top"><code>foo/bar/B.java</code></td>
303 <td valign="top"><code>foo/bar/B.java.bak</code></td>
304 </tr>
305 <tr>
306 <td valign="top"><code>C.properties</code></td>
307 <td valign="top">ignored</td>
308 </tr>
309 <tr>
310 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
311 <td valign="top">ignored</td>
312 </tr>
313</table>
314<blockquote><pre>
315&lt;mapper type=&quot;regexp&quot; from=&quot;^(.*)/([^/]+)/([^/]*)$$&quot; to=&quot;\1/\2/\2-\3&quot;/&gt;
316&lt;regexpmapper from=&quot;^(.*)/([^/]+)/([^/]*)$$&quot; to=&quot;\1/\2/\2-\3&quot;/&gt;
317</pre></blockquote>
318<table border="1" cellpadding="2" cellspacing="0">
319 <tr>
320 <td valign="top"><b>Source file name</b></td>
321 <td valign="top"><b>Target file name</b></td>
322 </tr>
323 <tr>
324 <td valign="top"><code>A.java</code></td>
325 <td valign="top">ignored</td>
326 </tr>
327 <tr>
328 <td valign="top"><code>foo/bar/B.java</code></td>
329 <td valign="top"><code>foo/bar/bar-B.java</code></td>
330 </tr>
331 <tr>
332 <td valign="top"><code>C.properties</code></td>
333 <td valign="top">ignored</td>
334 </tr>
335 <tr>
336 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
337 <td valign="top"><code>Classes/dir/dir2/dir2-A.properties</code></td>
338 </tr>
339</table>
340<blockquote><pre>
341&lt;mapper type=&quot;regexp&quot; from=&quot;^(.*)\.(.*)$$&quot; to=&quot;\2.\1&quot;/&gt;
342&lt;regexpmapper from=&quot;^(.*)\.(.*)$$&quot; to=&quot;\2.\1&quot;/&gt;
343</pre></blockquote>
344<table border="1" cellpadding="2" cellspacing="0">
345 <tr>
346 <td valign="top"><b>Source file name</b></td>
347 <td valign="top"><b>Target file name</b></td>
348 </tr>
349 <tr>
350 <td valign="top"><code>A.java</code></td>
351 <td valign="top"><code>java.A</code></td>
352 </tr>
353 <tr>
354 <td valign="top"><code>foo/bar/B.java</code></td>
355 <td valign="top"><code>java.foo/bar/B</code></td>
356 </tr>
357 <tr>
358 <td valign="top"><code>C.properties</code></td>
359 <td valign="top"><code>properties.C</code></td>
360 </tr>
361 <tr>
362 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
363 <td valign="top"><code>properties.Classes/dir/dir2/A</code></td>
364 </tr>
365</table>
366
367<h4><a name="package-mapper">package</a></h4>
368<p>Sharing the same syntax as the <a href="#glob-mapper">glob mapper</a>,
369the package mapper replaces
370directory separators found in the matched source pattern with dots in the target
371pattern placeholder. This mapper is particularly useful in combination
372with <code>&lt;uptodate&gt;</code> and <code>&lt;junit&gt;</code> output.</p>
373<b>Example:</b>
374<blockquote><pre>
375&lt;mapper type="package" from="*Test.java" to="TEST-*Test.xml"/&gt;
376&lt;packagemapper from="*Test.java" to="TEST-*Test.xml"/&gt;
377</pre></blockquote>
378<table border="1" cellpadding="2" cellspacing="0">
379 <tr>
380 <td valign="top"><b>Source file name</b></td>
381 <td valign="top"><b>Target file name</b></td>
382 </tr>
383 <tr>
384 <td valign="top"><code>org/apache/tools/ant/util/PackageMapperTest.java</code></td>
385 <td valign="top"><code>TEST-org.apache.tools.ant.util.PackageMapperTest.xml</code></td>
386 </tr>
387 <tr>
388 <td valign="top"><code>org/apache/tools/ant/util/Helper.java</code></td>
389 <td valign="top">ignored</td>
390 </tr>
391</table>
392<h4><a name="unpackage-mapper">unpackage (since ant 1.6.0)</a></h4>
393 <p>This mapper is the inverse of the <a href="#package-mapper">package</a> mapper.
394 It replaces the dots in a package name with directory separators. This
395 is useful for matching XML formatter results against their JUnit test
396 test cases. The mapper shares the sample syntax
397 as the <a href="#glob-mapper">glob mapper</a>.
398 </p>
399<b>Example:</b>
400<blockquote><pre>
401&lt;mapper type="unpackage" from="TEST-*Test.xml" to="${test.src.dir}/*Test.java"&gt;
402&lt;unpackagemapper from="TEST-*Test.xml" to="${test.src.dir}/*Test.java"&gt;
403</pre></blockquote>
404<table border="1" cellpadding="2" cellspacing="0">
405 <tr>
406 <td valign="top"><b>Source file name</b></td>
407 <td valign="top"><b>Target file name</b></td>
408 </tr>
409 <tr>
410 <td valign="top"><code>TEST-org.acme.AcmeTest.xml</code></td>
411 <td valign="top"><code>${test.src.dir}/org/acme/AcmeTest.java</code></td>
412 </tr>
413</table>
414<h4><a name="composite-mapper">composite (since ant 1.6.2)</a></h4>
415 <p>This mapper implementation can contain multiple nested mappers.
416 File mapping is performed by passing the source filename to each nested
417 <code>&lt;mapper&gt;</code> in turn, returning all results.
418 The <i>to</i> and <i>from</i> attributes are ignored.</p>
419<b>Examples:</b>
420<blockquote><pre>
421&lt;compositemapper&gt;
422 &lt;identitymapper /&gt;
423 &lt;packagemapper from="*.java" to="*"/&gt;
424&lt;/compositemapper&gt;
425</pre></blockquote>
426<table border="1" cellpadding="2" cellspacing="0">
427 <tr>
428 <td valign="top"><b>Source file name</b></td>
429 <td valign="top"><b>Target file names</b></td>
430 </tr>
431 <tr>
432 <td valign="center" rowspan="2"><code>foo/bar/A.java</code></td>
433 <td valign="top"><code>foo/bar/A.java</code></td>
434 </tr>
435 <tr>
436 <td valign="top"><code>foo.bar.A</code></td>
437 </tr>
438</table>
439 <p>The composite mapper has no corresponding
440 <code>&lt;mapper <b>type</b>&gt;</code> attribute.
441 </p>
442<h4><a name="chained-mapper">chained (since ant 1.6.2)</a></h4>
443 <p>This mapper implementation can contain multiple nested mappers.
444 File mapping is performed by passing the source filename to the first
445 nested mapper, its results to the second, and so on. The target filenames
446 generated by the last nested mapper comprise the ultimate results of the
447 mapping operation. The <i>to</i> and <i>from</i> attributes are ignored.</p>
448<b>Examples:</b>
449<blockquote><pre>
450&lt;chainedmapper&gt;
451 &lt;flattenmapper /&gt;
452 &lt;globmapper from="*" to="new/path/*"/&gt;
453 &lt;mapper&gt;
454 &lt;globmapper from="*" to="*1"/&gt;
455 &lt;globmapper from="*" to="*2"/&gt;
456 &lt;/mapper&gt;
457&lt;/chainedmapper&gt;
458</pre></blockquote>
459<table border="1" cellpadding="2" cellspacing="0">
460 <tr>
461 <td valign="top"><b>Source file name</b></td>
462 <td valign="top"><b>Target file names</b></td>
463 </tr>
464 <tr>
465 <td valign="center" rowspan="2"><code>foo/bar/A.java</code></td>
466 <td valign="top"><code>new/path/A.java1</code></td>
467 </tr>
468 <tr>
469 <td valign="top"><code>new/path/A.java2</code></td>
470 </tr>
471 <tr>
472 <td valign="center" rowspan="2"><code>boo/far/B.java</code></td>
473 <td valign="top"><code>new/path/B.java1</code></td>
474 </tr>
475 <tr>
476 <td valign="top"><code>new/path/B.java2</code></td>
477 </tr>
478</table>
479 <p>The chained mapper has no corresponding
480 <code>&lt;mapper <b>type</b>&gt;</code> attribute.
481 </p>
482<hr>
483<p align="center">Copyright &copy; 2000-2004 The Apache Software Foundation. All rights
484Reserved.</p>
485
486</body>
487</html>
488
Note: See TracBrowser for help on using the repository browser.