bodewig 00/12/01 06:06:59
Modified: . WHATSNEW
docs index.html
Log:
Documentation of <mapper>.
Revision Changes Path
1.59 +4 -0 jakarta-ant/WHATSNEW
Index: WHATSNEW
===================================================================
RCS file: /home/cvs/jakarta-ant/WHATSNEW,v
retrieving revision 1.58
retrieving revision 1.59
diff -u -r1.58 -r1.59
--- WHATSNEW 2000/11/30 17:27:48 1.58
+++ WHATSNEW 2000/12/01 14:06:54 1.59
@@ -33,6 +33,10 @@
* <ftp> now supports passive mode.
+* New <mapper> data type that can be used to get influence on the
+ target files for some tasks like <copy> or enable new types of tasks
+ like <transform>.
+
Fixed bugs:
-----------
1.161 +313 -1 jakarta-ant/docs/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/index.html,v
retrieving revision 1.160
retrieving revision 1.161
diff -u -r1.160 -r1.161
--- index.html 2000/12/01 11:58:41 1.160
+++ index.html 2000/12/01 14:06:57 1.161
@@ -27,7 +27,7 @@
<li>Dave Walend (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
</ul>
-<p>Version 1.3 - 2000/11/30</p>
+<p>Version 1.3 - 2000/12/01</p>
<hr>
<h2>Table of Contents</h2>
@@ -864,6 +864,318 @@
</pre></blockquote>
<p>Groups all files in directory <code>${client.src}</code> using the
same patterns as the example before.</p>
+<h3><a name="mapper">Mapping file names</a></h3>
+<p>Some tasks take source files and create target files. Depending on
+the task it may be quite obvious which name a target file will have
+(using <a href="#javac">javac</a>, you know there will be
+<code>.class</code> files for your <code>.java</code> files) - in
+other cases you may want to specify the target files either to help
+Ant or to get an extra bit of functionality.</p>
+<p>While source files are usually specified as <a
+href="#fileset">fileset</a>s, you don't specify target files directly,
+but tell Ant how to find the target file(s) for one source file. An
+instance of <code>org.apache.tools.ant.util.FileNameMapper</code> is
+responsible for this. It constructs target file names based on rules
+that can be parameterized with <code>from</code> and <code>to</code>
+attributes - the exact meaning of which is implementation
+dependent.</p>
+<p>These instances are defined in <code><mapper></code> elements
+with the following attributes:</p>
+<table border="1" cellpadding="2" cellspacing="0">
+ <tr>
+ <td valign="top"><b>Attribute</b></td>
+ <td valign="top"><b>Description</b></td>
+ <td align="center" valign="top"><b>Required</b></td>
+ </tr>
+ <tr>
+ <td valign="top">type</td>
+ <td valign="top">Specify one of the built in implementations</td>
+ <td align="center" valign="center" rowspan="2">Exactly one of both</td>
+ </tr>
+ <tr>
+ <td valign="top">classname</td>
+ <td valign="top">Specify the implementation by class name</td>
+ </tr>
+ <tr>
+ <td valign="top">classpath</td>
+ <td valign="top">the classpath to use when looking up
+ <code>classname</code>.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">classpathref</td>
+ <td valign="top">the classpath to use, given as <a
+ href="#references">reference</a> to a PATH defined elsewhere.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">from</td>
+ <td valign="top">The "from" attribute for the given
+ implementation</td>
+ <td align="center" valign="top">Depends on implementation.</td>
+ </tr>
+ <tr>
+ <td valign="top">to</td>
+ <td valign="top">The "to" attribute for the given
+ implementation</td>
+ <td align="center" valign="top">Depends on implementation.</td>
+ </tr>
+</table>
+<p>The classpath can as well be specified via a nested
+<code><classpath></code>, that is a <a href="#path">PATH</a>
+like structure.</p>
+<p>The built in mapper types are:</p>
+<h4><a name="identity-mapper">identity</a></h4>
+<p>The target file name is identical to the source file name. Both
+<code>to</code> and <code>from</code> will be ignored.</p>
+<h5>Examples:</h5>
+<blockquote><pre>
+<mapper type="identity" />
+</pre></blockquote>
+<table border="1" cellpadding="2" cellspacing="0">
+ <tr>
+ <td valign="top"><b>Source file name</b></td>
+ <td valign="top"><b>Target file name</b></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>A.java</code></td>
+ <td valign="top"><code>A.java</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>foo/bar/B.java</code></td>
+ <td valign="top"><code>foo/bar/B.java</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>C.properties</code></td>
+ <td valign="top"><code>C.properties</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
+ <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
+ </tr>
+</table>
+<h4><a name="flatten-mapper">flatten</a></h4>
+<p>The target file name is identical to the source file name with all
+leading directory information stripped of. Both <code>to</code> and
+<code>from</code> will be ignored.</p>
+<h5>Examples:</h5>
+<blockquote><pre>
+<mapper type="flatten" />
+</pre></blockquote>
+<table border="1" cellpadding="2" cellspacing="0">
+ <tr>
+ <td valign="top"><b>Source file name</b></td>
+ <td valign="top"><b>Target file name</b></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>A.java</code></td>
+ <td valign="top"><code>A.java</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>foo/bar/B.java</code></td>
+ <td valign="top"><code>B.java</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>C.properties</code></td>
+ <td valign="top"><code>C.properties</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
+ <td valign="top"><code>A.properties</code></td>
+ </tr>
+</table>
+<h4><a name="merge-mapper">merge</a></h4>
+<p>The target file name will always be the same - as defined by
+<code>to</code>, <code>from</code> will be ignored.</p>
+<h5>Examples:</h5>
+<blockquote><pre>
+<mapper type="merge" to="archive.tar" />
+</pre></blockquote>
+<table border="1" cellpadding="2" cellspacing="0">
+ <tr>
+ <td valign="top"><b>Source file name</b></td>
+ <td valign="top"><b>Target file name</b></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>A.java</code></td>
+ <td valign="top"><code>archive.tar</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>foo/bar/B.java</code></td>
+ <td valign="top"><code>archive.tar</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>C.properties</code></td>
+ <td valign="top"><code>archive.tar</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
+ <td valign="top"><code>archive.tar</code></td>
+ </tr>
+</table>
+<h4><a name="glob-mapper">glob</a></h4>
+<p>Both <code>to</code> and <code>from</code> define patterns that may
+contain at most one <code>*</code>. For each source file that matches
+the <code>from</code> pattern a target file name will be constructed
+from the <code>to</code> pattern by substituting the <code>*</code> in
+the <code>to</code> pattern by the text that matches the
+<code>*</code> in the <code>from</code> pattern. Source file names
+that don't match the <code>from</code> pattern will be ignored.</p>
+<h5>Examples:</h5>
+<blockquote><pre>
+<mapper type="glob" from="*.java"
to="*.java.bak" />
+</pre></blockquote>
+<table border="1" cellpadding="2" cellspacing="0">
+ <tr>
+ <td valign="top"><b>Source file name</b></td>
+ <td valign="top"><b>Target file name</b></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>A.java</code></td>
+ <td valign="top"><code>A.java.bak</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>foo/bar/B.java</code></td>
+ <td valign="top"><code>foo/bar/B.java.bak</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>C.properties</code></td>
+ <td valign="top">ignored</td>
+ </tr>
+ <tr>
+ <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
+ <td valign="top">ignored</td>
+ </tr>
+</table>
+<blockquote><pre>
+<mapper type="glob" from="C*ies" to="Q*y"
/>
+</pre></blockquote>
+<table border="1" cellpadding="2" cellspacing="0">
+ <tr>
+ <td valign="top"><b>Source file name</b></td>
+ <td valign="top"><b>Target file name</b></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>A.java</code></td>
+ <td valign="top">ignored</td>
+ </tr>
+ <tr>
+ <td valign="top"><code>foo/bar/B.java</code></td>
+ <td valign="top">ignored</td>
+ </tr>
+ <tr>
+ <td valign="top"><code>C.properties</code></td>
+ <td valign="top"><code>Q.property</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
+ <td valign="top"><code>Qlasses/dir/dir2/A.property</td>
+ </tr>
+</table>
+<h4><a name="regexp-mapper">regexp</a></h4>
+<p>Both <code>to</code> and <code>from</code> define regular
+expressions. If the source file name matches the <code>from</code>
+pattern, the target file name will constructed from the
+<code>to</code> pattern using \0 to \9 as back references for the full
+match (\0) or the matches of the subexpressions in parens. Source
+files not matching the <code>from</code> pattern will be ignored.</p>
+<p><b>Note that you need to escape a $-sign with another $-sign in
+Ant.</b></p>
+<p>The regexp mapper needs a supporting library and an implementation
+of <code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that
+hides the specifics of the library. Ant comes with implementations for
+<a href="http://jakarta.apache.org/regexp/";>jakarta-regexp</a> and <a
+href="http://jakarta.apache.org/oro/";>jakarta-ORO</a> - if you compile
+from sources and plan to use one of them, make sure the libraries are
+in your CLASSPATH.</a> For information about using <a
+href="http://www.cacas.org/~wes/java/";>gnu.regexp</a> or <a
+href="http://www.crocodile.org/~sts/Rex/";>gnu.rex</a> with Ant, see <a
+href="http://marc.theaimsgroup.com/?l=ant-dev&m=97550753813481&w=2";>this</a>
+article.</p>
+<p>Ant will choose the regular expression library based on the
+following algorithm: if the system property
+<code>ant.regexp.matcherimpl</code> has been set, it is taken as the
+name of the class implementing
+<code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that
+should be used. If it has not been set, first try jakarta-ORO, if that
+cannot be found, try jakarta-regexp.</p>
+<h5>Examples:</h5>
+<blockquote><pre>
+<mapper type="regexp" from="^(.*)\.java$$"
to="\1.java.bak" />
+</pre></blockquote>
+<table border="1" cellpadding="2" cellspacing="0">
+ <tr>
+ <td valign="top"><b>Source file name</b></td>
+ <td valign="top"><b>Target file name</b></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>A.java</code></td>
+ <td valign="top"><code>A.java.bak</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>foo/bar/B.java</code></td>
+ <td valign="top"><code>foo/bar/B.java.bak</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>C.properties</code></td>
+ <td valign="top">ignored</td>
+ </tr>
+ <tr>
+ <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
+ <td valign="top">ignored</td>
+ </tr>
+</table>
+<blockquote><pre>
+<mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$"
to="\1/\2/\2-\3" />
+</pre></blockquote>
+<table border="1" cellpadding="2" cellspacing="0">
+ <tr>
+ <td valign="top"><b>Source file name</b></td>
+ <td valign="top"><b>Target file name</b></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>A.java</code></td>
+ <td valign="top">ignored</td>
+ </tr>
+ <tr>
+ <td valign="top"><code>foo/bar/B.java</code></td>
+ <td valign="top"><code>foo/bar/bar-B.java</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>C.properties</code></td>
+ <td valign="top">ignored</td>
+ </tr>
+ <tr>
+ <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
+ <td valign="top"><code>Classes/dir/dir2/dir2-A.properties</code></td>
+ </tr>
+</table>
+<blockquote><pre>
+<mapper type="regexp" from="^(.*)\.(.*)$$"
to="\2.\1" />
+</pre></blockquote>
+<table border="1" cellpadding="2" cellspacing="0">
+ <tr>
+ <td valign="top"><b>Source file name</b></td>
+ <td valign="top"><b>Target file name</b></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>A.java</code></td>
+ <td valign="top"><code>java.A</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>foo/bar/B.java</code></td>
+ <td valign="top"><code>java.foo/bar/B</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>C.properties</code></td>
+ <td valign="top"><code>properties.C</code></td>
+ </tr>
+ <tr>
+ <td valign="top"><code>Classes/dir/dir2/A.properties</code></td>
+ <td valign="top"><code>properties.Classes/dir/dir2/A</code></td>
+ </tr>
+</table>
+
<hr>
<h2><a name="tasks">Built in tasks</a></h2>
<ul>
