source: other-projects/trunk/realistic-books/packages/AntInstaller/web/manual/manual/CoreTypes/mapper.html@ 19253

Last change on this file since 19253 was 19253, checked in by davidb, 15 years ago

Establishing a source code repository for Veronica's Realistic Book's software
File size: 29.3 KB
Line 
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<html>
18
19<head>
20<meta http-equiv="Content-Language" content="en-us">
21<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
22<title>Mapper Type</title>
23</head>
24
25<body>
26
27<h2><a name="mapper">Mapping File Names</a></h2>
28<p>Some tasks take source files and create target files. Depending on
29the task, it may be quite obvious which name a target file will have
30(using <a href="../CoreTasks/javac.html">javac</a>, you know there will be
31<code>.class</code> files for your <code>.java</code> files) - in
32other cases you may want to specify the target files, either to help
33Ant or to get an extra bit of functionality.</p>
34<p>While source files are usually specified as <a
35href="fileset.html">fileset</a>s, you don't specify target files directly -
36instead, you tell Ant how to find the target file(s) for one source file. An
37instance of <code>org.apache.tools.ant.util.FileNameMapper</code> is
38responsible for this. It constructs target file names based on rules
39that can be parameterized with <code>from</code> and <code>to</code>
40attributes - the exact meaning of which is implementation-dependent.</p>
41<p>These instances are defined in <code>&lt;mapper&gt;</code> elements
42with the following attributes:</p>
43<table border="1" cellpadding="2" cellspacing="0">
44 <tr>
45 <td valign="top"><b>Attribute</b></td>
46 <td valign="top"><b>Description</b></td>
47 <td align="center" valign="top"><b>Required</b></td>
48 </tr>
49 <tr>
50 <td valign="top">type</td>
51 <td valign="top">specifies one of the built-in implementations.</td>
52 <td rowspan="2" align="center" valign="middle">Exactly one of these</td>
53 </tr>
54 <tr>
55 <td valign="top">classname</td>
56 <td valign="top">specifies the implementation by class name.</td>
57 </tr>
58 <tr>
59 <td valign="top">classpath</td>
60 <td valign="top">the classpath to use when looking up
61 <code>classname</code>.</td>
62 <td align="center" valign="top">No</td>
63 </tr>
64 <tr>
65 <td valign="top">classpathref</td>
66 <td valign="top">the classpath to use, given as <a
67 href="../using.html#references">reference</a> to a path defined elsewhere.</td>
68 <td align="center" valign="top">No</td>
69 </tr>
70 <tr>
71 <td valign="top">from</td>
72 <td valign="top">the <code>from</code> attribute for the given
73 implementation.</td>
74 <td align="center" valign="top">Depends on implementation.</td>
75 </tr>
76 <tr>
77 <td valign="top">to</td>
78 <td valign="top">the <code>to</code> attribute for the given
79 implementation.</td>
80 <td align="center" valign="top">Depends on implementation.</td>
81 </tr>
82</table>
83<p>Note that Ant will not automatically convert / or \ characters in
84the <code>to</code> and <code>from</code> attributes to the correct
85directory separator of your current platform. If you need to specify
86this separator, use <code>${file.separator}</code> instead.
87 For the regexpmapper, <code>${file.separator}</code> will not work,
88as on windows it is the '\' character, and this is an escape character
89for regular expressions, one should use the <code>handledirsep</code> attribute
90instead.
91</p>
92<h3>Parameters specified as nested elements</h3>
93<p>The classpath can be specified via a nested
94<code>&lt;classpath&gt;</code>, as well - that is,
95a <a href="../using.html#path">path</a>-like structure.</p>
96<p><b>Since Ant 1.6.2,</b> nested File Mappers can
97be supplied via either <CODE>&lt;mapper&gt;</CODE> elements or
98<a href="../CoreTasks/typedef.html"><code>&lt;typedef&gt;</code></a>'d
99implementations of <CODE>org.apache.tools.ant.util.FileNameMapper</CODE>.
100If nested File Mappers are specified by either means, the mapper will be
101implicitly configured as a <a href="#composite-mapper">composite mapper</a>.
102</p>
103<hr>
104<h3>The built-in mapper types are:</h3>
105<p>All built-in mappers are case-sensitive.</p>
106<p><b>As of Ant 1.6.2,</b> each of the built-in mapper implementation
107 types is directly accessible using a specific tagname. This makes it
108 possible for filename mappers to support attributes in addition to
109 the generally available <i>to</i> and <i>from</i>.<br>
110 The <code>&lt;mapper type|classname=&quot;...&quot;&gt;</code> usage
111 form remains valid for reasons of backward compatibility.</p>
112<h4><a name="identity-mapper">identity</a></h4>
113<p>The target file name is identical to the source file name. Both
114<code>to</code> and <code>from</code> will be ignored.</p>
115<b>Examples:</b>
116<blockquote><pre>
117&lt;mapper type=&quot;identity&quot;/&gt;
118&lt;identitymapper/&gt;
119</pre></blockquote>
120<table border="1" cellpadding="2" cellspacing="0">
121 <tr>
122 <td valign="top"><b>Source file name</b></td>
123 <td valign="top"><b>Target file name</b></td>
124 </tr>
125 <tr>
126 <td valign="top"><code>A.java</code></td>
127 <td valign="top"><code>A.java</code></td>
128 </tr>
129 <tr>
130 <td valign="top"><code>foo/bar/B.java</code></td>
131 <td valign="top"><code>foo/bar/B.java</code></td>
132 </tr>
133 <tr>
134 <td valign="top"><code>C.properties</code></td>
135 <td valign="top"><code>C.properties</code></td>
136 </tr>
137 <tr>
138 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
139 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
140 </tr>
141</table>
142<h4><a name="flatten-mapper">flatten</a></h4>
143<p>The target file name is identical to the source file name, with all
144leading directory information stripped off. Both <code>to</code> and
145<code>from</code> will be ignored.</p>
146<b>Examples:</b>
147<blockquote><pre>
148&lt;mapper type=&quot;flatten&quot;/&gt;
149&lt;flattenmapper/&gt;
150</pre></blockquote>
151<table border="1" cellpadding="2" cellspacing="0">
152 <tr>
153 <td valign="top"><b>Source file name</b></td>
154 <td valign="top"><b>Target file name</b></td>
155 </tr>
156 <tr>
157 <td valign="top"><code>A.java</code></td>
158 <td valign="top"><code>A.java</code></td>
159 </tr>
160 <tr>
161 <td valign="top"><code>foo/bar/B.java</code></td>
162 <td valign="top"><code>B.java</code></td>
163 </tr>
164 <tr>
165 <td valign="top"><code>C.properties</code></td>
166 <td valign="top"><code>C.properties</code></td>
167 </tr>
168 <tr>
169 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
170 <td valign="top"><code>A.properties</code></td>
171 </tr>
172</table>
173<h4><a name="merge-mapper">merge</a></h4>
174<p>The target file name will always be the same, as defined by
175<code>to</code> - <code>from</code> will be ignored.</p>
176<h5>Examples:</h5>
177<blockquote><pre>
178&lt;mapper type=&quot;merge&quot; to=&quot;archive.tar&quot;/&gt;
179&lt;mergemapper to=&quot;archive.tar&quot;/&gt;
180</pre></blockquote>
181<table border="1" cellpadding="2" cellspacing="0">
182 <tr>
183 <td valign="top"><b>Source file name</b></td>
184 <td valign="top"><b>Target file name</b></td>
185 </tr>
186 <tr>
187 <td valign="top"><code>A.java</code></td>
188 <td valign="top"><code>archive.tar</code></td>
189 </tr>
190 <tr>
191 <td valign="top"><code>foo/bar/B.java</code></td>
192 <td valign="top"><code>archive.tar</code></td>
193 </tr>
194 <tr>
195 <td valign="top"><code>C.properties</code></td>
196 <td valign="top"><code>archive.tar</code></td>
197 </tr>
198 <tr>
199 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
200 <td valign="top"><code>archive.tar</code></td>
201 </tr>
202</table>
203<h4><a name="glob-mapper">glob</a></h4>
204<p>Both <code>to</code> and <code>from</code> define patterns that may
205contain at most one <code>*</code>. For each source file that matches
206the <code>from</code> pattern, a target file name will be constructed
207from the <code>to</code> pattern by substituting the <code>*</code> in
208the <code>to</code> pattern with the text that matches the
209<code>*</code> in the <code>from</code> pattern. Source file names
210that don't match the <code>from</code> pattern will be ignored.</p>
211<b>Examples:</b>
212<blockquote><pre>
213&lt;mapper type=&quot;glob&quot; from=&quot;*.java&quot; to=&quot;*.java.bak&quot;/&gt;
214&lt;globmapper from=&quot;*.java&quot; to=&quot;*.java.bak&quot;/&gt;
215</pre></blockquote>
216<table border="1" cellpadding="2" cellspacing="0">
217 <tr>
218 <td valign="top"><b>Source file name</b></td>
219 <td valign="top"><b>Target file name</b></td>
220 </tr>
221 <tr>
222 <td valign="top"><code>A.java</code></td>
223 <td valign="top"><code>A.java.bak</code></td>
224 </tr>
225 <tr>
226 <td valign="top"><code>foo/bar/B.java</code></td>
227 <td valign="top"><code>foo/bar/B.java.bak</code></td>
228 </tr>
229 <tr>
230 <td valign="top"><code>C.properties</code></td>
231 <td valign="top">ignored</td>
232 </tr>
233 <tr>
234 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
235 <td valign="top">ignored</td>
236 </tr>
237</table>
238<blockquote><pre>
239&lt;mapper type=&quot;glob&quot; from=&quot;C*ies&quot; to=&quot;Q*y&quot;/&gt;
240&lt;globmapper from=&quot;C*ies&quot; to=&quot;Q*y&quot;/&gt;
241</pre></blockquote>
242<table border="1" cellpadding="2" cellspacing="0">
243 <tr>
244 <td valign="top"><b>Source file name</b></td>
245 <td valign="top"><b>Target file name</b></td>
246 </tr>
247 <tr>
248 <td valign="top"><code>A.java</code></td>
249 <td valign="top">ignored</td>
250 </tr>
251 <tr>
252 <td valign="top"><code>foo/bar/B.java</code></td>
253 <td valign="top">ignored</td>
254 </tr>
255 <tr>
256 <td valign="top"><code>C.properties</code></td>
257 <td valign="top"><code>Q.property</code></td>
258 </tr>
259 <tr>
260 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
261 <td valign="top"><code>Qlasses/dir/dir2/A.property</code></td>
262 </tr>
263</table>
264 <p>
265 The globmapper mapper can take the following extra attributes.
266 </p>
267 <table border="1" cellpadding="2" cellspacing="0">
268 <tr>
269 <td valign="top"><b>Attribute</b></td>
270 <td valign="top"><b>Description</b></td>
271 <td align="center" valign="top"><b>Required</b></td>
272 </tr>
273 <tr>
274 <td valign="top">casesensitive</td>
275 <td valign="top">
276 If this is false, the mapper will ignore case when matching the glob pattern.
277 This attribute can be true or false, the default is true.
278 <em>Since Ant 1.6.3.</em>
279 </td>
280 <td align="center" valign="top">No</td>
281 </tr>
282 <tr>
283 <td valign="top">handledirsep</td>
284 <td valign="top">
285 If this is specified, the mapper will ignore the difference between the normal
286 directory separator characters - \ and /.
287 This attribute can be true or false, the default is false.
288 This attribute is useful for cross-platform build files.
289 <em>Since Ant 1.6.3.</em>
290 <td align="center" valign="top">No</td>
291 </tr>
292 </table>
293 <p>
294 An example:
295 </p>
296 <pre>
297 &lt;pathconvert property="x" targetos="unix"&gt;
298 &lt;path path="Aj.Java"/&gt;
299 &lt;mapper&gt;
300 &lt;chainedmapper&gt;
301 &lt;flattenmapper/&gt;
302 &lt;globmapper from="a*.java" to="*.java.bak" casesensitive="no"/&gt;
303 &lt;/chainedmapper&gt;
304 &lt;/mapper&gt;
305 &lt;/pathconvert&gt;
306 &lt;echo&gt;x is ${x}&lt;/echo&gt;
307 </pre>
308 <p>
309 will output "x is j.java.bak".
310 </p>
311 <p>
312 and
313 </p>
314 <pre>
315 &lt;pathconvert property="x" targetos="unix"&gt;
316 &lt;path path="d/e/f/j.java"/&gt;
317 &lt;mapper&gt;
318 &lt;globmapper from="${basedir}\d/e\*" to="*" ignoredirchar="yes"/&gt;
319 &lt;/mapper&gt;
320 &lt;/pathconvert&gt;
321 &lt;echo&gt;x is ${x}&lt;/echo&gt;
322 </pre>
323 <p>
324 will output "x is f/j.java".
325 </p>
326
327<h4><a name="regexp-mapper">regexp</a></h4>
328<p>Both <code>to</code> and <code>from</code> define regular
329expressions. If the source file name matches the <code>from</code>
330pattern, the target file name will be constructed from the
331<code>to</code> pattern, using <code>\0</code> to <code>\9</code> as
332back-references for the full
333match (<code>\0</code>) or the matches of the subexpressions in
334parentheses.
335Source
336files not matching the <code>from</code> pattern will be ignored.</p>
337<p>Note that you need to escape a dollar-sign (<code>$</code>) with
338another dollar-sign in Ant.</p>
339<p>The regexp mapper needs a supporting library and an implementation
340of <code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that
341hides the specifics of the library. Ant comes with implementations for
342<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 or higher</a>,
343<a href="http://jakarta.apache.org/regexp/" target="_top">jakarta-regexp</a> and <a
344href="http://jakarta.apache.org/oro/" target="_top">jakarta-ORO</a>. If you compile
345from sources and plan to use one of them, make sure the libraries are
346in your <code>CLASSPATH</code>. For information about using <a
347href="http://www.cacas.org/~wes/java/" target="_top">gnu.regexp</a> or <a
348href="http://www.crocodile.org/~sts/Rex/" target="_top">gnu.rex</a> with Ant, see <a
349href="http://marc.theaimsgroup.com/?l=ant-dev&m=97550753813481&w=2" target="_top">this</a>
350article.</p>
351<p>This means, you need one of the supported regular expression
352 libraries <strong>and</strong>
353 the corresponding <code>ant-[jakarta-oro, jakarta-regexp, apache-oro, apache-regexp}.jar</code>
354from the Ant release you are using.
355Make sure, both will be loaded from the same
356classpath, that is either put them into your <code>CLASSPATH</code>,
357<code>ANT_HOME/lib</code> directory or a nested
358<code>&lt;classpath&gt;</code> element of the mapper - you cannot have
359<code>ant-[jakarta-oro, jakarta-regexp, apache-oro, apache-regexp].jar</code> in <code>ANT_HOME/lib</code>
360 and the library
361in a nested <code>&lt;classpath&gt;</code>.</p>
362<p>Ant will choose the regular-expression library based on the
363following algorithm:</p>
364<ul>
365<li>If the system property
366<code>ant.regexp.matcherimpl</code> has been set, it is taken as the
367name of the class implementing
368<code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that
369should be used.</li>
370<li>If it has not been set, first try the JDK 1.4 classes, then
371jakarta-ORO and finally try jakarta-regexp.</li>
372</ul>
373
374<b>Examples:</b>
375<blockquote><pre>
376&lt;mapper type=&quot;regexp&quot; from=&quot;^(.*)\.java$$&quot; to=&quot;\1.java.bak&quot;/&gt;
377&lt;regexpmapper from=&quot;^(.*)\.java$$&quot; to=&quot;\1.java.bak&quot;/&gt;
378</pre></blockquote>
379<table border="1" cellpadding="2" cellspacing="0">
380 <tr>
381 <td valign="top"><b>Source file name</b></td>
382 <td valign="top"><b>Target file name</b></td>
383 </tr>
384 <tr>
385 <td valign="top"><code>A.java</code></td>
386 <td valign="top"><code>A.java.bak</code></td>
387 </tr>
388 <tr>
389 <td valign="top"><code>foo/bar/B.java</code></td>
390 <td valign="top"><code>foo/bar/B.java.bak</code></td>
391 </tr>
392 <tr>
393 <td valign="top"><code>C.properties</code></td>
394 <td valign="top">ignored</td>
395 </tr>
396 <tr>
397 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
398 <td valign="top">ignored</td>
399 </tr>
400</table>
401<blockquote><pre>
402&lt;mapper type=&quot;regexp&quot; from=&quot;^(.*)/([^/]+)/([^/]*)$$&quot; to=&quot;\1/\2/\2-\3&quot;/&gt;
403&lt;regexpmapper from=&quot;^(.*)/([^/]+)/([^/]*)$$&quot; to=&quot;\1/\2/\2-\3&quot;/&gt;
404</pre></blockquote>
405<table border="1" cellpadding="2" cellspacing="0">
406 <tr>
407 <td valign="top"><b>Source file name</b></td>
408 <td valign="top"><b>Target file name</b></td>
409 </tr>
410 <tr>
411 <td valign="top"><code>A.java</code></td>
412 <td valign="top">ignored</td>
413 </tr>
414 <tr>
415 <td valign="top"><code>foo/bar/B.java</code></td>
416 <td valign="top"><code>foo/bar/bar-B.java</code></td>
417 </tr>
418 <tr>
419 <td valign="top"><code>C.properties</code></td>
420 <td valign="top">ignored</td>
421 </tr>
422 <tr>
423 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
424 <td valign="top"><code>Classes/dir/dir2/dir2-A.properties</code></td>
425 </tr>
426</table>
427<blockquote><pre>
428&lt;mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1"/&gt;
429&lt;regexpmapper from="^(.*)\.(.*)$$&" to="\2.\1"/&gt;
430</pre></blockquote>
431<table border="1" cellpadding="2" cellspacing="0">
432 <tr>
433 <td valign="top"><b>Source file name</b></td>
434 <td valign="top"><b>Target file name</b></td>
435 </tr>
436 <tr>
437 <td valign="top"><code>A.java</code></td>
438 <td valign="top"><code>java.A</code></td>
439 </tr>
440 <tr>
441 <td valign="top"><code>foo/bar/B.java</code></td>
442 <td valign="top"><code>java.foo/bar/B</code></td>
443 </tr>
444 <tr>
445 <td valign="top"><code>C.properties</code></td>
446 <td valign="top"><code>properties.C</code></td>
447 </tr>
448 <tr>
449 <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
450 <td valign="top"><code>properties.Classes/dir/dir2/A</code></td>
451 </tr>
452</table>
453<blockquote><pre>
454&lt;mapper type="regexp" from="^(.*?)(\$$[^/\\\.]*)?\.class$$" to="\1.java"/&gt;
455&lt;regexpmapper from="^(.*?)(\$$[^/\\\.]*)?\.class$$" to="\1.java"/&gt;
456</pre></blockquote>
457<table border="1" cellpadding="2" cellspacing="0">
458 <tr>
459 <td valign="top"><b>Source file name</b></td>
460 <td valign="top"><b>Target file name</b></td>
461 </tr>
462 <tr>
463 <td valign="top"><code>ClassLoader.class</code></td>
464 <td valign="top"><code>ClassLoader.java</code></td>
465 </tr>
466 <tr>
467 <td valign="top"><code>java/lang/ClassLoader.class</code></td>
468 <td valign="top"><code>java/lang/ClassLoader.java</code></td>
469 </tr>
470 <tr>
471 <td valign="top"><code>java\lang\ClassLoader$1.class</code></td>
472 <td valign="top"><code>java\lang\ClassLoader.java</code></td>
473 </tr>
474 <tr>
475 <td valign="top"><code>java/lang/ClassLoader$foo$1.class</code></td>
476 <td valign="top"><code>java/lang/ClassLoader.java</code></td>
477 </tr>
478</table>
479 <p>
480 The regexpmapper mapper can take the following extra attributes.
481 </p>
482 <table border="1" cellpadding="2" cellspacing="0">
483 <tr>
484 <td valign="top"><b>Attribute</b></td>
485 <td valign="top"><b>Description</b></td>
486 <td align="center" valign="top"><b>Required</b></td>
487 </tr>
488 <tr>
489 <td valign="top">casesensitive</td>
490 <td valign="top">
491 If this is false, the mapper will ignore case when matching the pattern.
492 This attribute can be true or false, the default is true.
493 <em>Since Ant 1.6.3.</em>
494 </td>
495 <td align="center" valign="top">No</td>
496 </tr>
497 <tr>
498 <td valign="top">handledirsep</td>
499 <td valign="top">
500 If this is specified, the mapper will treat a \ character in a filename
501 as a / for the purposes of matching.
502 This attribute can be true or false, the default is false.
503 This attribute is useful for cross-platform build files.
504 <em>Since Ant 1.6.3.</em>
505 <td align="center" valign="top">No</td>
506 </tr>
507 </table>
508 <p>
509 An example:
510 </p>
511 <pre>
512 &lt;pathconvert property="x" targetos="unix"&gt;
513 &lt;path path="Aj.Java"/&gt;
514 &lt;chainedmapper&gt;
515 &lt;flattenmapper/&gt;
516 &lt;regexpmapper from="a(.*)\.java" to="\1.java.bak" casesensitive="no"/&gt;
517 &lt;/chainedmapper&gt;
518 &lt;/pathconvert&gt;
519 &lt;echo&gt;x is ${x}&lt;/echo&gt;
520 </pre>
521 <p>
522 will output "x is j.java.bak".
523 </p>
524 <p>
525 and
526 </p>
527 <pre>
528 &lt;pathconvert property="hd.prop" targetos="windows"&gt;
529 &lt;path path="d\e/f\j.java"/&gt;
530 &lt;chainedmapper&gt;
531 &lt;regexpmapper from="${basedir}/d/e/(.*)" to="\1" handledirsep="yes"/&gt;
532 &lt;/chainedmapper&gt;
533 &lt;/pathconvert&gt;
534 </pre>
535 <p>
536 will set <code>hd.prop</code> to "f\j.java".
537 </p>
538<h4><a name="package-mapper">package</a></h4>
539<p>Sharing the same syntax as the <a href="#glob-mapper">glob mapper</a>,
540the package mapper replaces
541directory separators found in the matched source pattern with dots in the target
542pattern placeholder. This mapper is particularly useful in combination
543with <code>&lt;uptodate&gt;</code> and <code>&lt;junit&gt;</code> output.</p>
544<b>Example:</b>
545<blockquote><pre>
546&lt;mapper type="package" from="*Test.java" to="TEST-*Test.xml"/&gt;
547&lt;packagemapper from="*Test.java" to="TEST-*Test.xml"/&gt;
548</pre></blockquote>
549<table border="1" cellpadding="2" cellspacing="0">
550 <tr>
551 <td valign="top"><b>Source file name</b></td>
552 <td valign="top"><b>Target file name</b></td>
553 </tr>
554 <tr>
555 <td valign="top"><code>org/apache/tools/ant/util/PackageMapperTest.java</code></td>
556 <td valign="top"><code>TEST-org.apache.tools.ant.util.PackageMapperTest.xml</code></td>
557 </tr>
558 <tr>
559 <td valign="top"><code>org/apache/tools/ant/util/Helper.java</code></td>
560 <td valign="top">ignored</td>
561 </tr>
562</table>
563<h4><a name="unpackage-mapper">unpackage (since Ant 1.6.0)</a></h4>
564 <p>This mapper is the inverse of the <a href="#package-mapper">package</a> mapper.
565 It replaces the dots in a package name with directory separators. This
566 is useful for matching XML formatter results against their JUnit test
567 test cases. The mapper shares the sample syntax
568 as the <a href="#glob-mapper">glob mapper</a>.
569 </p>
570<b>Example:</b>
571<blockquote><pre>
572&lt;mapper type="unpackage" from="TEST-*Test.xml" to="${test.src.dir}/*Test.java"&gt;
573&lt;unpackagemapper from="TEST-*Test.xml" to="${test.src.dir}/*Test.java"&gt;
574</pre></blockquote>
575<table border="1" cellpadding="2" cellspacing="0">
576 <tr>
577 <td valign="top"><b>Source file name</b></td>
578 <td valign="top"><b>Target file name</b></td>
579 </tr>
580 <tr>
581 <td valign="top"><code>TEST-org.acme.AcmeTest.xml</code></td>
582 <td valign="top"><code>${test.src.dir}/org/acme/AcmeTest.java</code></td>
583 </tr>
584</table>
585<h4><a name="composite-mapper">composite (since Ant 1.6.2)</a></h4>
586 <p>This mapper implementation can contain multiple nested mappers.
587 File mapping is performed by passing the source filename to each nested
588 <code>&lt;mapper&gt;</code> in turn, returning all results.
589 The <i>to</i> and <i>from</i> attributes are ignored.</p>
590<b>Examples:</b>
591<blockquote><pre>
592&lt;compositemapper&gt;
593 &lt;identitymapper/&gt;
594 &lt;packagemapper from="*.java" to="*"/&gt;
595&lt;/compositemapper&gt;
596</pre></blockquote>
597<table border="1" cellpadding="2" cellspacing="0">
598 <tr>
599 <td valign="top"><b>Source file name</b></td>
600 <td valign="top"><b>Target file names</b></td>
601 </tr>
602 <tr>
603 <td valign="center" rowspan="2"><code>foo/bar/A.java</code></td>
604 <td valign="top"><code>foo/bar/A.java</code></td>
605 </tr>
606 <tr>
607 <td valign="top"><code>foo.bar.A</code></td>
608 </tr>
609</table>
610 <p>The composite mapper has no corresponding
611 <code>&lt;mapper <b>type</b>&gt;</code> attribute.
612 </p>
613<h4><a name="chained-mapper">chained (since Ant 1.6.2)</a></h4>
614 <p>This mapper implementation can contain multiple nested mappers.
615 File mapping is performed by passing the source filename to the first
616 nested mapper, its results to the second, and so on. The target filenames
617 generated by the last nested mapper comprise the ultimate results of the
618 mapping operation. The <i>to</i> and <i>from</i> attributes are ignored.</p>
619<b>Examples:</b>
620<blockquote><pre>
621&lt;chainedmapper&gt;
622 &lt;flattenmapper/&gt;
623 &lt;globmapper from="*" to="new/path/*"/&gt;
624 &lt;mapper&gt;
625 &lt;globmapper from="*" to="*1"/&gt;
626 &lt;globmapper from="*" to="*2"/&gt;
627 &lt;/mapper&gt;
628&lt;/chainedmapper&gt;
629</pre></blockquote>
630<table border="1" cellpadding="2" cellspacing="0">
631 <tr>
632 <td valign="top"><b>Source file name</b></td>
633 <td valign="top"><b>Target file names</b></td>
634 </tr>
635 <tr>
636 <td valign="center" rowspan="2"><code>foo/bar/A.java</code></td>
637 <td valign="top"><code>new/path/A.java1</code></td>
638 </tr>
639 <tr>
640 <td valign="top"><code>new/path/A.java2</code></td>
641 </tr>
642 <tr>
643 <td valign="center" rowspan="2"><code>boo/far/B.java</code></td>
644 <td valign="top"><code>new/path/B.java1</code></td>
645 </tr>
646 <tr>
647 <td valign="top"><code>new/path/B.java2</code></td>
648 </tr>
649</table>
650 <p>The chained mapper has no corresponding
651 <code>&lt;mapper <b>type</b>&gt;</code> attribute.
652 </p>
653
654 <!-- -->
655 <!-- Filter Mapper -->
656 <!-- -->
657
658<h4><a name="filter-mapper">filtermapper (since Ant 1.6.3)</a></h4>
659 <p>
660 This mapper implementation applies a <a href="filterchain.html">filterchain</a>
661 to the source file name.
662 </p>
663<b>Examples:</b>
664<blockquote><pre>
665&lt;filtermapper&gt;
666 &lt;replacestring from="\" to="/"/&gt;
667&lt;/filtermapper&gt;
668</pre></blockquote>
669
670<table border="1" cellpadding="2" cellspacing="0">
671 <tr>
672 <td valign="top"><b>Source file name</b></td>
673 <td valign="top"><b>Target file names</b></td>
674 </tr>
675 <tr>
676 <td valign="center"><code>foo\bar\A.java</code></td>
677 <td valign="top"><code>foo/bar/A.java</code></td>
678 </tr>
679</table>
680<blockquote><pre>
681&lt;filtermapper&gt;
682 &lt;scriptfilter language="beanshell"&gt;
683 self.setToken(self.getToken().toUpperCase());
684 &lt;/scriptfilter&gt;
685&lt;/filtermapper&gt;
686</pre></blockquote>
687
688<table border="1" cellpadding="2" cellspacing="0">
689 <tr>
690 <td valign="top"><b>Source file name</b></td>
691 <td valign="top"><b>Target file names</b></td>
692 </tr>
693 <tr>
694 <td valign="center"><code>foo\bar\A.java</code></td>
695 <td valign="top"><code>FOO\BAR\A.JAVA</code></td>
696 </tr>
697</table>
698
699 <p>The filtermapper has no corresponding
700 <code>&lt;mapper <b>type</b>&gt;</code> attribute.
701 </p>
702
703 <!-- -->
704 <!-- Script Mapper -->
705 <!-- -->
706
707<h4><a name="script-mapper">scriptmapper (since Ant 1.7)</a></h4>
708<p>
709This mapper executes a script written in <a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a>
710or
711 <a href="https://scripting.dev.java.net">JSR 223</a>
712supported language, once per file to map.</p>
713The script can be declared inline or in a specified file.
714</p>
715<p>
716See the <a href="../OptionalTasks/script.html">Script</a> task for
717an explanation of scripts and dependencies.
718</p>
719
720 <table border="1" cellpadding="2" cellspacing="0">
721 <tr>
722 <td valign="top"><b>Attribute</b></td>
723 <td valign="top"><b>Description</b></td>
724 <td align="center" valign="top"><b>Required</b></td>
725 </tr>
726 <tr>
727 <td valign="top">language</td>
728 <td valign="top">
729 Scripting language
730 </td>
731 <td align="center" valign="top">Yes</td>
732 </tr>
733 <tr>
734 <td valign="top">manager</td>
735 <td valign="top">
736 The script engine manager to use.
737 See the <a href="../OptionalTasks/script.html">script</a> task
738 for using this attribute.
739 </td>
740 <td valign="top" align="center">No - default is "auto"</td>
741 </tr>
742 <tr>
743 <td valign="top">src</td>
744 <td valign="top">
745 File containing the script
746 </td>
747 <td align="center" valign="top">No</td>
748 </tr>
749 <tr>
750 <td valign="top">setbeans</td>
751 <td valign="top">whether to have all properties, references and targets as
752 global variables in the script.</td>
753 <td valign="top" align="center">No, default is "true".</td>
754 </tr>
755 <tr>
756 <td valign="top">classpath</td>
757 <td valign="top">
758 The classpath to pass into the script.
759 </td>
760 <td align="center" valign="top">No</td>
761 </tr>
762 <tr>
763 <td valign="top">classpathref</td>
764 <td valign="top">The classpath to use, given as a
765 <a href="../using.html#references">reference</a> to a path defined elsewhere.
766 <td align="center" valign="top">No</td>
767 </tr>
768 </table>
769 <p>
770 This filename mapper can take a nested &lt;classpath&gt; element.
771 See the <a href="../OptionalTasks/script.html">script</a> task
772 on how to use this element.
773 </p>
774
775<p>
776 <b>Example:</b>
777</p>
778<blockquote><pre>
779&lt;scriptmapper language="javascript"&gt;
780 self.addMappedName(source.toUpperCase());
781 self.addMappedName(source.toLowerCase());
782&lt;/scriptmapper&gt;
783</pre></blockquote>
784
785<table border="1" cellpadding="2" cellspacing="0">
786 <tr>
787 <td valign="top"><b>Source file name</b></td>
788 <td valign="top"><b>Target file names</b></td>
789 </tr>
790 <tr>
791 <td valign="center"><code>foo\bar\A.java</code></td>
792 <td valign="top"><code>FOO\BAR\A.JAVA foo\bar\a.java</code></td>
793 </tr>
794</table>
795
796<p>
797To use this mapper, the scripts need access to the source file,
798and the ability to return multiple mappings. Here are the relevant beans and
799their methods. The script is called once for every source file, with the
800list of mapped names reset after every invocation.
801
802 <table border="1" cellpadding="2" cellspacing="0">
803 <tr>
804 <td valign="top"><b>Script bean</b></td>
805 <td valign="top"><b>Description</b></td>
806 </tr>
807 <tr>
808 <td valign="top"><code>source: String</code></td>
809 <td valign="top">
810 The file/path to map
811 </td>
812 </tr>
813 <tr>
814 <td valign="top">self</td>
815 <td valign="top">
816 the scriptmapper itself
817 </td>
818 </tr>
819 <tr>
820 <td valign="top"><code>self.addMappedName(String name)</code></td>
821 <td valign="top">
822 Add a new mapping
823 </td>
824 </tr>
825 <tr>
826 <td valign="top"><code>self.clear()</code></td>
827 <td valign="top">
828 Reset the list of files.
829 </td>
830 </tr>
831 </table>
832
833 <p>The scriptmapper has no corresponding
834 <code>&lt;mapper <b>type</b>&gt;</code> attribute.
835 </p>
836
837
838
839</body>
840</html>
Note: See TracBrowser for help on using the repository browser.