| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Mapper Type</title> |
| </head> |
| |
| <body> |
| |
| <h2><a name="mapper">Mapping File Names</a></h2> |
| <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="../CoreTasks/javac.html">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.html">fileset</a>s, you don't specify target files directly - |
| instead, you 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">specifies one of the built-in implementations.</td> |
| <td rowspan="2" align="center" valign="middle">Exactly one of both</td> |
| </tr> |
| <tr> |
| <td valign="top">classname</td> |
| <td valign="top">specifies 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="../using.html#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 <code>from</code> 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 <code>to</code> attribute for the given |
| implementation.</td> |
| <td align="center" valign="top">Depends on implementation.</td> |
| </tr> |
| </table> |
| <p>Note that Ant will not automatically convert / or \ characters in |
| the <code>to</code> and <code>from</code> attributes to the correct |
| directory separator of your current platform. If you need to specify |
| this separator, use <code>${file.separator}</code> instead.</p> |
| <h3>Parameters specified as nested elements</h3> |
| <p>The classpath can be specified via a nested |
| <code><classpath></code>, as well - that is, |
| a <a href="../using.html#path">path</a>-like structure.</p> |
| <h3>The built-in mapper types are:</h3> |
| <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> |
| <b>Examples:</b> |
| <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 off. Both <code>to</code> and |
| <code>from</code> will be ignored.</p> |
| <b>Examples:</b> |
| <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 with 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> |
| <b>Examples:</b> |
| <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</code></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 be constructed from the |
| <code>to</code> pattern, using <code>\0</code> to <code>\9</code> as |
| back-references for the full |
| match (<code>\0</code>) or the matches of the subexpressions in |
| parentheses. |
| Source |
| files not matching the <code>from</code> pattern will be ignored.</p> |
| <p>Note that you need to escape a dollar-sign (<code>$</code>) with |
| another dollar-sign in Ant.</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://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>, |
| <a href="http://jakarta.apache.org/regexp/" target="_top">jakarta-regexp</a> and <a |
| href="http://jakarta.apache.org/oro/" target="_top">jakarta-ORO</a>. If you compile |
| from sources and plan to use one of them, make sure the libraries are |
| in your <code>CLASSPATH</code>. For information about using <a |
| href="http://www.cacas.org/~wes/java/" target="_top">gnu.regexp</a> or <a |
| href="http://www.crocodile.org/~sts/Rex/" target="_top">gnu.rex</a> with Ant, see <a |
| href="http://marc.theaimsgroup.com/?l=ant-dev&m=97550753813481&w=2" target="_top">this</a> |
| article.</p> |
| <p>This means, you need <code>optional.jar</code> from the Ant release |
| you are using <strong>and</strong> one of the supported regular |
| expression libraries. Make sure, both will be loaded from the same |
| classpath, that is either put them into your <code>CLASSPATH</code>, |
| <code>ANT_HOME/lib</code> directory or a nested |
| <code><classpath></code> element of the mapper - you cannot have |
| <code>optional.jar</code> in <code>ANT_HOME/lib</code> and the library |
| in a nested <code><classpath></code>.</p> |
| <p>Ant will choose the regular-expression library based on the |
| following algorithm:</p> |
| <ul> |
| <li>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.</li> |
| <li>If it has not been set, first try the JDK 1.4 classes, then |
| jakarta-ORO and finally try jakarta-regexp.</li> |
| </ul> |
| |
| <b>Examples:</b> |
| <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> |
| |
| <h4><a name="package-mapper">package</a></h4> |
| <p>Sharing the same syntax as the <a href="#glob-mapper">glob mapper</a>, |
| the package mapper replaces |
| directory separators found in the matched source pattern with dots in the target |
| pattern placeholder. This mapper is particularly useful in combination |
| with <code><uptodate></code> and <code><junit></code> output.</p> |
| <b>Example:</b> |
| <blockquote><pre> |
| <mapper type="package" |
| from="*Test.java" to="TEST-*Test.xml"/> |
| </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>org/apache/tools/ant/util/PackageMapperTest.java</code></td> |
| <td valign="top"><code>TEST-org.apache.tools.ant.util.PackageMapperTest.xml</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>org/apache/tools/ant/util/Helper.java</code></td> |
| <td valign="top">ignored</td> |
| </tr> |
| </table> |
| |
| <hr> |
| <p align="center">Copyright © 2001 Apache Software Foundation. All rights |
| Reserved.</p> |
| |
| </body> |
| </html> |
| |
