| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <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="../Tasks/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 |
| Apache 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 these</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. |
| For the regexpmapper, <code>${file.separator}</code> will not work, |
| as on windows it is the '\' character, and this is an escape character |
| for regular expressions, one should use the <code>handledirsep</code> attribute |
| 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> |
| <p><b>Since Ant 1.7.0,</b> nested File Mappers can |
| be supplied via either <CODE><mapper></CODE> elements or |
| <a href="../Tasks/typedef.html"><code><typedef></code></a>'d |
| implementations of <CODE>org.apache.tools.ant.util.FileNameMapper</CODE>. |
| If nested File Mappers are specified by either means, the mapper will be |
| implicitly configured as a <a href="#composite-mapper">composite mapper</a>. |
| </p> |
| <hr> |
| <h3>The built-in mapper types are:</h3> |
| <p>All built-in mappers are case-sensitive.</p> |
| <p><b>As of Ant 1.7.0,</b> each of the built-in mapper implementation |
| types is directly accessible using a specific tagname. This makes it |
| possible for filename mappers to support attributes in addition to |
| the generally available <i>to</i> and <i>from</i>.<br> |
| The <code><mapper type|classname="..."></code> usage |
| form remains valid for reasons of backward compatibility.</p> |
| |
| <!-- --> |
| <!-- Identity Mapper --> |
| <!-- --> |
| |
| <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"/> |
| <identitymapper/> |
| </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> |
| |
| <!-- --> |
| <!-- Flatten Mapper --> |
| <!-- --> |
| |
| <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"/> |
| <flattenmapper/> |
| </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> |
| |
| <!-- --> |
| <!-- Merge Mapper --> |
| <!-- --> |
| |
| <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"/> |
| <mergemapper 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> |
| |
| <!-- --> |
| <!-- Glob Mapper --> |
| <!-- --> |
| |
| <h4><a name="glob-mapper">glob</a></h4> |
| <p>Both <code>to</code> and <code>from</code> are required and 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"/> |
| <globmapper 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"/> |
| <globmapper 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> |
| <p> |
| The globmapper mapper can take the following extra 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">casesensitive</td> |
| <td valign="top"> |
| If this is false, the mapper will ignore case when matching the glob pattern. |
| This attribute can be true or false, the default is true. |
| <em>Since Ant 1.6.3.</em> |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">handledirsep</td> |
| <td valign="top"> |
| If this is specified, the mapper will ignore the difference between the normal |
| directory separator characters - \ and /. |
| This attribute can be true or false, the default is false. |
| This attribute is useful for cross-platform build files. |
| <em>Since Ant 1.6.3.</em> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <p> |
| An example: |
| </p> |
| <pre> |
| <pathconvert property="x" targetos="unix"> |
| <path path="Aj.Java"/> |
| <mapper> |
| <chainedmapper> |
| <flattenmapper/> |
| <globmapper from="a*.java" to="*.java.bak" casesensitive="no"/> |
| </chainedmapper> |
| </mapper> |
| </pathconvert> |
| <echo>x is ${x}</echo> |
| </pre> |
| <p> |
| will output "x is j.java.bak". |
| </p> |
| <p> |
| and |
| </p> |
| <pre> |
| <pathconvert property="x" targetos="unix"> |
| <path path="d/e/f/j.java"/> |
| <mapper> |
| <globmapper from="${basedir}\d/e\*" to="*" handledirsep="yes"/> |
| </mapper> |
| </pathconvert> |
| <echo>x is ${x}</echo> |
| </pre> |
| <p> |
| will output "x is f/j.java". |
| </p> |
| |
| |
| <!-- --> |
| <!-- RegExp Mapper --> |
| <!-- --> |
| |
| <h4><a name="regexp-mapper">regexp</a></h4> |
| |
| <p>Both <code>to</code> and <code>from</code> are required and define |
| regular expressions. If the source file name (as a whole or in part) |
| 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. The <code>to</code> pattern |
| determines the <strong>whole</strong> file name, so if you wanted to |
| replace the extension of a file you should not use <code>from="\.old$" |
| to=".new"</code> but rather <code>from="(.*)\.old$" to="\1.new"</code> |
| (or rather use a glob mapper in this case).</p> |
| |
| <p>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. <em>Since Ant 1.8.0</em> Ant |
| requires Java 1.4 to run, so the implementation based on |
| the <code>java.util.regex</code> package will always be available. |
| You can still use the now retired Jakarta ORO or Jakarta Regex instead if your |
| provide the corresponding jar in your CLASSPATH.</p> |
| |
| <p>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>If you want to use one of the <a href="../install.html#librarydependencies">regular expression |
| libraries</a> other than <code>java.util.regex</code> you need to also use |
| the corresponding <code>ant-[apache-oro, apache-regexp].jar</code> |
| from the Ant release you are using. |
| 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>ant-[apache-oro, apache-regexp].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, uses the JDK 1.4 classes.</li> |
| </ul> |
| |
| <b>Examples:</b> |
| <blockquote><pre> |
| <mapper type="regexp" from="^(.*)\.java$$" to="\1.java.bak"/> |
| <regexpmapper 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"/> |
| <regexpmapper 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"/> |
| <regexpmapper 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> |
| <blockquote><pre> |
| <mapper type="regexp" from="^(.*?)(\$$[^/\\\.]*)?\.class$$" to="\1.java"/> |
| <regexpmapper from="^(.*?)(\$$[^/\\\.]*)?\.class$$" to="\1.java"/> |
| </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>ClassLoader.class</code></td> |
| <td valign="top"><code>ClassLoader.java</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>java/lang/ClassLoader.class</code></td> |
| <td valign="top"><code>java/lang/ClassLoader.java</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>java\lang\ClassLoader$1.class</code></td> |
| <td valign="top"><code>java\lang\ClassLoader.java</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>java/lang/ClassLoader$foo$1.class</code></td> |
| <td valign="top"><code>java/lang/ClassLoader.java</code></td> |
| </tr> |
| </table> |
| <p> |
| The regexpmapper mapper can take the following extra 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">casesensitive</td> |
| <td valign="top"> |
| If this is false, the mapper will ignore case when matching the pattern. |
| This attribute can be true or false, the default is true. |
| <em>Since Ant 1.6.3.</em> |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">handledirsep</td> |
| <td valign="top"> |
| If this is specified, the mapper will treat a \ character in a filename |
| as a / for the purposes of matching. |
| This attribute can be true or false, the default is false. |
| This attribute is useful for cross-platform build files. |
| <em>Since Ant 1.6.3.</em> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <p> |
| An example: |
| </p> |
| <pre> |
| <pathconvert property="x" targetos="unix"> |
| <path path="Aj.Java"/> |
| <chainedmapper> |
| <flattenmapper/> |
| <regexpmapper from="a(.*)\.java" to="\1.java.bak" casesensitive="no"/> |
| </chainedmapper> |
| </pathconvert> |
| <echo>x is ${x}</echo> |
| </pre> |
| <p> |
| will output "x is j.java.bak". |
| </p> |
| <p> |
| and |
| </p> |
| <pre> |
| <pathconvert property="hd.prop" targetos="windows"> |
| <path path="d\e/f\j.java"/> |
| <chainedmapper> |
| <regexpmapper from="${basedir}/d/e/(.*)" to="\1" handledirsep="yes"/> |
| </chainedmapper> |
| </pathconvert> |
| </pre> |
| <p> |
| will set <code>hd.prop</code> to "f\j.java". |
| </p> |
| |
| <!-- --> |
| <!-- Package Mapper --> |
| <!-- --> |
| |
| <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> |
| <p>The to and from attributes are both required.</p> |
| <b>Example:</b> |
| <blockquote><pre> |
| <mapper type="package" from="*Test.java" to="TEST-*Test.xml"/> |
| <packagemapper 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> |
| |
| <!-- --> |
| <!-- Unpackage Mapper --> |
| <!-- --> |
| |
| <h4><a name="unpackage-mapper">unpackage (since Ant 1.6.0)</a></h4> |
| <p>This mapper is the inverse of the <a href="#package-mapper">package</a> mapper. |
| It replaces the dots in a package name with directory separators. This |
| is useful for matching XML formatter results against their JUnit test |
| test cases. The mapper shares the sample syntax |
| as the <a href="#glob-mapper">glob mapper</a>. |
| </p> |
| <p>The to and from attributes are both required.</p> |
| <b>Example:</b> |
| <blockquote><pre> |
| <mapper type="unpackage" from="TEST-*Test.xml" to="${test.src.dir}/*Test.java"> |
| <unpackagemapper from="TEST-*Test.xml" to="${test.src.dir}/*Test.java"> |
| </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>TEST-org.acme.AcmeTest.xml</code></td> |
| <td valign="top"><code>${test.src.dir}/org/acme/AcmeTest.java</code></td> |
| </tr> |
| </table> |
| |
| <!-- --> |
| <!-- Composite Mapper --> |
| <!-- --> |
| |
| <h4><a name="composite-mapper">composite (since Ant 1.7.0)</a></h4> |
| <p>This mapper implementation can contain multiple nested mappers. |
| File mapping is performed by passing the source filename to each nested |
| <code><mapper></code> in turn, returning all results. |
| The <i>to</i> and <i>from</i> attributes are ignored.</p> |
| <p>Starting with Ant 1.8.0 the order of the mapped results is the |
| same as the order of the nested mappers; prior to Ant 1.8.0 the |
| order has been undefined.</p> |
| <b>Examples:</b> |
| <blockquote><pre> |
| <compositemapper> |
| <identitymapper/> |
| <packagemapper from="*.java" to="*"/> |
| </compositemapper> |
| </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 names</b></td> |
| </tr> |
| <tr> |
| <td valign="center" rowspan="2"><code>foo/bar/A.java</code></td> |
| <td valign="top"><code>foo/bar/A.java</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>foo.bar.A</code></td> |
| </tr> |
| </table> |
| <p>The composite mapper has no corresponding |
| <code><mapper <b>type</b>></code> attribute. |
| </p> |
| |
| <!-- --> |
| <!-- Chained Mapper --> |
| <!-- --> |
| |
| <h4><a name="chained-mapper">chained (since Ant 1.7.0)</a></h4> |
| <p>This mapper implementation can contain multiple nested mappers. |
| File mapping is performed by passing the source filename to the first |
| nested mapper, its results to the second, and so on. The target filenames |
| generated by the last nested mapper comprise the ultimate results of the |
| mapping operation. The <i>to</i> and <i>from</i> attributes are ignored.</p> |
| <b>Examples:</b> |
| <blockquote><pre> |
| <chainedmapper> |
| <flattenmapper/> |
| <globmapper from="*" to="new/path/*"/> |
| <mapper> |
| <globmapper from="*" to="*1"/> |
| <globmapper from="*" to="*2"/> |
| </mapper> |
| </chainedmapper> |
| </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 names</b></td> |
| </tr> |
| <tr> |
| <td valign="center" rowspan="2"><code>foo/bar/A.java</code></td> |
| <td valign="top"><code>new/path/A.java1</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>new/path/A.java2</code></td> |
| </tr> |
| <tr> |
| <td valign="center" rowspan="2"><code>boo/far/B.java</code></td> |
| <td valign="top"><code>new/path/B.java1</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>new/path/B.java2</code></td> |
| </tr> |
| </table> |
| <p>The chained mapper has no corresponding |
| <code><mapper <b>type</b>></code> attribute. |
| </p> |
| |
| <!-- --> |
| <!-- Filter Mapper --> |
| <!-- --> |
| |
| <h4><a name="filter-mapper">filtermapper (since Ant 1.6.3)</a></h4> |
| <p> |
| This mapper implementation applies a <a href="filterchain.html">filterchain</a> |
| to the source file name. |
| </p> |
| <b>Examples:</b> |
| <blockquote><pre> |
| <filtermapper> |
| <replacestring from="\" to="/"/> |
| </filtermapper> |
| </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 names</b></td> |
| </tr> |
| <tr> |
| <td valign="center"><code>foo\bar\A.java</code></td> |
| <td valign="top"><code>foo/bar/A.java</code></td> |
| </tr> |
| </table> |
| <blockquote><pre> |
| <filtermapper> |
| <scriptfilter language="beanshell"> |
| self.setToken(self.getToken().toUpperCase()); |
| </scriptfilter> |
| </filtermapper> |
| </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 names</b></td> |
| </tr> |
| <tr> |
| <td valign="center"><code>foo\bar\A.java</code></td> |
| <td valign="top"><code>FOO\BAR\A.JAVA</code></td> |
| </tr> |
| </table> |
| |
| <p>The filtermapper has no corresponding |
| <code><mapper <b>type</b>></code> attribute. |
| </p> |
| |
| <!-- --> |
| <!-- Script Mapper --> |
| <!-- --> |
| |
| <h4><a name="script-mapper">scriptmapper (since Ant 1.7)</a></h4> |
| <p> |
| This mapper executes a script written in <a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a> |
| or |
| <a href="https://scripting.dev.java.net">JSR 223</a> |
| supported language, once per file to map.</p> |
| The script can be declared inline or in a specified file. |
| </p> |
| <p> |
| See the <a href="../Tasks/script.html">Script</a> task for |
| an explanation of scripts and dependencies. |
| </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">language</td> |
| <td valign="top"> |
| Scripting language |
| </td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">manager</td> |
| <td valign="top"> |
| The script engine manager to use. |
| See the <a href="../Tasks/script.html">script</a> task |
| for using this attribute. |
| </td> |
| <td valign="top" align="center">No - default is "auto"</td> |
| </tr> |
| <tr> |
| <td valign="top">src</td> |
| <td valign="top"> |
| File containing the script |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">setbeans</td> |
| <td valign="top">whether to have all properties, references and targets as |
| global variables in the script. <em>since Ant 1.8.0</em></td> |
| <td valign="top" align="center">No, default is "true".</td> |
| </tr> |
| <tr> |
| <td valign="top">classpath</td> |
| <td valign="top"> |
| The classpath to pass into the script. |
| </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 |
| <a href="../using.html#references">reference</a> to a path defined elsewhere. |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <p> |
| This filename mapper can take a nested <classpath> element. |
| See the <a href="../Tasks/script.html">script</a> task |
| on how to use this element. |
| </p> |
| |
| <p> |
| <b>Example:</b> |
| </p> |
| <blockquote><pre> |
| <scriptmapper language="javascript"> |
| self.addMappedName(source.toUpperCase()); |
| self.addMappedName(source.toLowerCase()); |
| </scriptmapper> |
| </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 names</b></td> |
| </tr> |
| <tr> |
| <td valign="center" rowspan="2"><code>foo\bar\A.java</code></td> |
| <td valign="top"><code>FOO\BAR\A.JAVA</code></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>foo\bar\a.java</code></td> |
| </tr> |
| </table> |
| |
| <p> |
| To use this mapper, the scripts need access to the source file, |
| and the ability to return multiple mappings. Here are the relevant beans and |
| their methods. The script is called once for every source file, with the |
| list of mapped names reset after every invocation. |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Script bean</b></td> |
| <td valign="top"><b>Description</b></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>source: String</code></td> |
| <td valign="top"> |
| The file/path to map |
| </td> |
| </tr> |
| <tr> |
| <td valign="top"><code>self</code></td> |
| <td valign="top"> |
| the scriptmapper itself |
| </td> |
| </tr> |
| <tr> |
| <td valign="top"><code>self.addMappedName(String name)</code></td> |
| <td valign="top"> |
| Add a new mapping |
| </td> |
| </tr> |
| <tr> |
| <td valign="top"><code>self.clear()</code></td> |
| <td valign="top"> |
| Reset the list of files. |
| </td> |
| </tr> |
| </table> |
| |
| <p>The scriptmapper has no corresponding |
| <code><mapper <b>type</b>></code> attribute. |
| </p> |
| |
| <h4><a name="firstmatch-mapper">firstmatchmapper (since Ant 1.8.0)</a></h4> |
| <p> |
| This mapper supports an arbitrary number of nested mappers and |
| returns the results of the first mapper that matches. This is |
| different from <a href="#composite-mapper">composite mapper</a> |
| which collects the results of all matching children.</p> |
| <b>Examples:</b> |
| <blockquote><pre> |
| <firstmatchmapper> |
| <globmapper from="*.txt" to="*.bak"/> |
| <globmapper from="*A.*" to="*B.*"/> |
| </firstmatchmapper> |
| </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 names</b></td> |
| </tr> |
| <tr> |
| <td valign="center"><code>foo/bar/A.txt</code></td> |
| <td valign="top"><code>foo/bar/A.bak</code></td> |
| </tr> |
| <tr> |
| <td valign="center"><code>foo/bar/A.java</code></td> |
| <td valign="top"><code>foo/bar/B.java</code></td> |
| </tr> |
| </table> |
| |
| <p>The firstmatchmapper has no corresponding |
| <code><mapper <b>type</b>></code> attribute. |
| </p> |
| |
| <h4><a name="cutdirs-mapper">cutdirsmapper (since Ant 1.8.2)</a></h4> |
| |
| <p>This mapper strips a configured number of leading directories from |
| the source file name.</p> |
| |
| <b>Examples:</b> |
| <blockquote><pre> |
| <cutdirsmapper dirs="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 names</b></td> |
| </tr> |
| <tr> |
| <td valign="center"><code>foo/bar/A.txt</code></td> |
| <td valign="top"><code>bar/A.txt</code></td> |
| </tr> |
| </table> |
| |
| <p>The cutdirsmapper has no |
| corresponding <code><mapper <b>type</b>></code> attribute.</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">dirs</td> |
| <td valign="top"> |
| Number of directories to strip (must be a positive number). |
| </td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| </table> |
| |
| </body> |
| </html> |
