ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@locus.apache.org
Subject cvs commit: jakarta-ant/docs index.html
Date Fri, 01 Dec 2000 14:07:00 GMT
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:dwalend@cs.tufts.edu">dwalend@cs.tufts.edu</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>&lt;mapper&gt;</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 &quot;from&quot; 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 &quot;to&quot; 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>&lt;classpath&gt;</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>
  +&lt;mapper type=&quot;identity&quot; /&gt;
  +</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>
  +&lt;mapper type=&quot;flatten&quot; /&gt;
  +</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>
  +&lt;mapper type=&quot;merge&quot; to=&quot;archive.tar&quot; /&gt;
  +</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>
  +&lt;mapper type=&quot;glob&quot; from=&quot;*.java&quot; to=&quot;*.java.bak&quot;
/&gt;
  +</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>
  +&lt;mapper type=&quot;glob&quot; from=&quot;C*ies&quot; to=&quot;Q*y&quot;
/&gt;
  +</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>
  +&lt;mapper type=&quot;regexp&quot; from=&quot;^(.*)\.java$$&quot; to=&quot;\1.java.bak&quot;
/&gt;
  +</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>
  +&lt;mapper type=&quot;regexp&quot; from=&quot;^(.*)/([^/]+)/([^/]*)$$&quot;
to=&quot;\1/\2/\2-\3&quot; /&gt;
  +</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>
  +&lt;mapper type=&quot;regexp&quot; from=&quot;^(.*)\.(.*)$$&quot; to=&quot;\2.\1&quot;
/&gt;
  +</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>
  
  
  

Mime
View raw message