Document <dirset> and new <dirset>/<filelist> support for

<path> and <pathconvert> (and clean that puppy up!).
PathConvert.java is comment changes only, no code.
PR:
Obtained from:
Submitted by:
Reviewed by:


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@272113 13f79535-47bb-0310-9956-ffa450edef68

WHATSNEW

@@ -251,8 +251,14 @@ Other changes:
 
 * Perforce tasks now support a "failonerror" attribute (defaults to "true").
 
-* Open Source application server JOnAS support :
-  EJB hot deploy and deploy with <serverdeploy> and <ejbjar>
+* Open Source application server JOnAS support:
+    EJB hot deploy and deploy with <serverdeploy> and <ejbjar>
+
+* Added new DirSet (<dirset>) datatype.
+
+* <path> now supports nested <dirset> and <filelist> elements.
+
+* <pathconvert> now supports nested <dirset> and <filelist> elements.
 
 Changes from Ant 1.4 to Ant 1.4.1
 ===========================================

docs/manual/CoreTasks/pathconvert.html

@@ -9,16 +9,16 @@
 
 <h2><a name="foreach">Pathconvert</a></h2>
 <h3>Description</h3>
-<p>Converts a nested path, path reference, or fileset reference to the form usable on a
-   specified platform
-   and stores the result in a given property.  This operation is useful when script files
-   (batch files or shell scripts) must be generated my the build system and they contain
-   path information that must be properly formatted for the target architecture, not the
-   architecture on which the build is running, or when you need to create a list of files
-   separated by a given character, like a comma or a space.
+<p>Converts a nested <code>&lt;path&gt;</code> or reference to a Path,
+FileSet, DirSet, or FileList into a path
+form for a particular platform, and stores the result in a given property.
+It can also be used when you need
+to convert a Path, FileSet, or DirSet into a list, separated by a given
+character, such as a comma or space, or, conversely, to convert a list
+of files in a FileList into a path.
 </p>
-<p>Prefix maps can be specified to map Windows drive letters to Unix paths and vice
-   versa.</p>
+<p>Nested <code>&lt;map&gt;</code> elements can be specified to map Windows
+drive letters to Unix paths, and vice-versa.</p>
 
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
@@ -30,12 +30,14 @@
   <tr>
     <td valign="top">targetos</td>
     <td valign="top">
-        The target architecture.  Must be one of 'unix' or 'windows'.  <BR>This is a
-        shorthand mechanism for specifying both <tt>pathsep</tt> and <tt>dirsep</tt>
+        The target architecture.  Must be one of 'unix' or 'windows'.
+        This is a shorthand mechanism for specifying both
+        <code>pathsep</code> and <code>dirsep</code>
         according to the specified target architecture.
     </td>
     <td valign="top" align="center">
-       Must specify one of <tt>targetos</tt>, <tt>pathsep</tt>,or <tt>dirsep</tt>.
+       Yes, unless <code>pathsep</code> and/or
+       <code>dirsep</code> are specified.
     </td>
   </tr>
   <tr>
@@ -54,15 +56,18 @@
   </tr>
   <tr>
     <td valign="top">property</td>
-    <td valign="top">The name of the property in which to place the converted path</td>
+    <td valign="top">The name of the property in which to place the converted path.</td>
     <td valign="top" align="center">Yes</td>
   </tr>
   <tr>
     <td valign="top">refid</td>
     <td valign="top">What to convert, given as a
-        <a href="../using.html#references">reference</a> to a PATH or FILESET
+        <a href="../using.html#references">reference</a> to a
+        <code>&lt;path&gt;</code>, <code>&lt;fileset&gt;</code>,
+        <code>&lt;dirset&gt;</code>, or <code>&lt;fileset&gt;</code>
         defined elsewhere</td>
-    <td valign="top" align="center">No, if omitted a nested &lt;path> element must be supplied.</td>
+    <td valign="top" align="center">No; if omitted, a nested
+        <code>&lt;path&gt;</code> element must be supplied.</td>
   </tr>
 </table>
 <h3>Parameters specified as nested elements</h3>
@@ -76,14 +81,14 @@
   </tr>
   <tr>
     <td valign="top">from</td>
-    <td valign="top">The prefix to match.  Note that this value is case insensitive when
-    the build is running on a windows platform and case sensitive when running on a
+    <td valign="top">The prefix to match.  Note that this value is case-insensitive when
+    the build is running on a Windows platform and case-sensitive when running on a
     Unix platform.</td>
     <td valign="top" align="center">Yes</td>
   </tr>
   <tr>
     <td valign="top">to</td>
-    <td valign="top">The replacement text to use when <i>from</i> is matched.</td>
+    <td valign="top">The replacement text to use when <code>from</code> is matched.</td>
     <td valign="top" align="center">Yes</td>
   </tr>
 </table>
@@ -92,87 +97,61 @@
    the path being processed.  If no map entries are specified, then no path prefix mapping
    is performed.
 </p>
-<p><i>Note that the map elements are applied in the order specified and the only the first
-   matching map element is applied.  So, the ordering of your map elements can be important
-   if any <TT>from</tt> values are prefixes of other <tt>from</tt> values.</i>
+<p><strong>Note</strong>: The map elements are applied in the order specified,
+and only the first matching map element is applied.  So, the ordering of
+your map elements can be important, if any <code>from</code> values are
+prefixes of other <code>from</code> values.</i>
 </p>   
 <h4>path</h4>
-<p>If a path reference is not supplied using the <i>refid</i> attribute, then a
-   nested path element must be supplied.  See
+<p>If the <code>refid</code> attribute is not specified, then a
+   nested <code>&lt;path&gt;</code> element must be supplied.  See
    <a href="../using.html#path">Path-like Structures</a> for details.</p>
 
 <h3>Examples</h3>
-<p>In the examples below, assume that the property <b>wl.home</b> has the value
-<tt>d:\weblogic</tt> on Windows and <tt>/weblogic</tt> on Unix.</p>
+<p>In the examples below, assume that the <code>${wl.home}</code> property
+has the value
+<code>d:\weblogic</code>, and <code>${wl.home.unix}</code> has the value
+<code>/weblogic</code>.</p>
 <h4>Example 1</h4>
 <pre>
     &lt;path id="wl.path"&gt;
-      &lt;pathelement location=&quot;${wl.home}/lib/weblogicaux.jar&quot; /&gt;
-      &lt;pathelement location=&quot;${wl.home}/classes&quot; /&gt;
-      &lt;pathelement location=&quot;${wl.home}/mssqlserver4/classes&quot; /&gt;
-      &lt;pathelement location=&quot;c:\winnt\System32&quot; /&gt;
+      &lt;pathelement location=&quot;${wl.home}/lib/weblogicaux.jar&quot;/&gt;
+      &lt;pathelement location=&quot;${wl.home}/classes&quot;/&gt;
+      &lt;pathelement location=&quot;${wl.home}/mssqlserver4/classes&quot;/&gt;
+      &lt;pathelement location=&quot;c:\winnt\System32&quot;/&gt;
     &lt;/path&gt;
     
-    &lt;pathconvert targetos=&quot;unix&quot; property=&quot;newpath&quot; refid=&quot;wl.path&quot;/&gt;
+    &lt;pathconvert targetos=&quot;unix&quot; property=&quot;wl.path.unix&quot; refid=&quot;wl.path&quot;&gt;
+      &lt;map from=&quot;${wl.home}&quot; to=&quot;${wl.home.unix}&quot;/&gt;
+      &lt;map from=&quot;c:&quot; to=&quot;&quot;/&gt;
+    &lt;/pathconvert&gt;
 </pre>
-<p>Assuming wl.property has the value "d:\weblogic", will generate the path shown below
-   and store it in the property named <tt>newpath</tt>
+<p> will generate the path shown below
+and store it in the property named <code>wl.path.unix</code>.
 </p>   
 <pre>
 /weblogic/lib/weblogicaux.jar:/weblogic/classes:/weblogic/mssqlserver4/classes:/WINNT/SYSTEM32
 </pre>
-Note that the drive letters have been removed.  This is the default behavior when no map
-elements have been specified.
 
 <h4>Example 2</h4>
+Given a FileList defined as:
 <pre>
-    
-    &lt;pathconvert targetos=&quot;unix&quot; property=&quot;newpath&quot; &gt;
-      &lt;path id="wl.path"&gt;
-        &lt;pathelement location=&quot;${wl.home}/lib/weblogicaux.jar&quot; /&gt;
-        &lt;pathelement location=&quot;${wl.home}/classes&quot; /&gt;
-        &lt;pathelement location=&quot;${wl.home}/mssqlserver4/classes&quot; /&gt;
-        &lt;pathelement location=&quot;c:\winnt\System32&quot; /&gt;
-      &lt;/path&gt;
-    &lt;/pathconvert&gt;
-</pre>
-This generates the exact same path as the previous example.  It demonstrates the use of
-a nested path element.
-<h4>Example 3</h4>
-<pre>
-    &lt;pathconvert targetos=&quot;unix&quot; property=&quot;newpath&quot; refid=&quot;wl.path&quot;&gt;
-      &lt;map from=&quot;d:&quot; to=&quot;/foo&quot;/&gt;
-      &lt;map from=&quot;c:&quot; to=&quot;/bar&quot;/&gt;
-    &lt;/pathconvert&gt;
-</pre>
-<p>This example specifies two map entries that will convert path elements that start with
-<tt>c:</tt> to <TT>/dos</tt> and <tt>d:</tt> to <TT>/</tt>.  The resulting path is shown
-below.</p>
-<pre>
-/weblogic/lib/weblogicaux.jar:/weblogic/classes:/weblogic/mssqlserver4/classes:/dos/WINNT/SYSTEM32
+  &lt;filelist id=&quot;custom_tasks.jars&quot;
+        dir=&quot;${env.HOME}/ant/lib&quot;
+        files=&quot;njavac.jar,xproperty.jar&quot;/&gt;
 </pre>
-<h4>Example 4</h4>
+then:
 <pre>
-    &lt;pathconvert targetos=&quot;windows&quot; property=&quot;newpath&quot; &gt;
-      &lt;path id="wl.path"&gt;
-        &lt;pathelement location=&quot;${wl.home}/lib/weblogicaux.jar&quot; /&gt;
-        &lt;pathelement location=&quot;${wl.home}/classes&quot; /&gt;
-        &lt;pathelement location=&quot;${wl.home}/mssqlserver4/classes&quot; /&gt;
-        &lt;pathelement location=&quot;/dos/winnt/System32&quot; /&gt;
-      &lt;/path&gt;
-      &lt;map from=&quot;/dos&quot; to=&quot;c:\&quot;/&gt;
-      &lt;map from=&quot;/&quot; to=&quot;d:\&quot;/&gt;
+    &lt;pathconvert targetos=&quot;unix&quot; property=&quot;custom_tasks.jars&quot; refid=&quot;custom_tasks.jars&quot;&gt;
+      &lt;map from=&quot;${env.HOME}&quot; to=&quot;/usr/local&quot;/&gt;
     &lt;/pathconvert&gt;
 </pre>
-<p>This example, similar to the one above but targetting windows, specifies two map
-entries that will convert path elements that start with
-<tt>/dos</tt> to <TT>c:\</tt> and <tt>/</tt> to <TT>d:\</tt>.  Note that the order of the
-map elements was important here since <tt>/</tt> is a prefix of <tt>/dos</tt>.
-The resulting path is shown below.</p>
+will convert the list of files to the following Unix path:
 <pre>
-d:\weblogic\lib\weblogicaux.jar;d:\weblogic\classes;d:\weblogic\mssqlserver4\classes;c:\WINNT\SYSTEM32
+/usr/local/ant/lib/njavac.jar:/usr/local/ant/lib/xproperty.jar
 </pre>
-<h4>Example 5</h4>
+
+<h4>Example 3</h4>
 <pre>
     &lt;fileset dir=&quot;${src.dir}&quot; id=&quot;src.files&quot;&gt;
       &lt;include name=&quot;**/*.java&quot;/&gt;
@@ -187,12 +166,11 @@ it defaults to the appropriate character for the current platform.  Such a list
 then be used in another task, like <tt>javadoc</tt>, that requires a comma separated
 list of files.
 </p>
-<hr>
 
 <hr>
-<p align="center">Copyright &copy; 2001 Apache Software Foundation. All rights
-Reserved.</p>
+<p align="center">Copyright &copy; 2001,2002 Apache Software Foundation.
+All rights Reserved.</p>
 </body>
 </html>
 
- 
+ 

docs/manual/CoreTypes/dirset.html

@@ -0,0 +1,103 @@
+<html>
+
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<title>DirSet Type</title>
+</head>
+
+<body>
+
+<h2><a name="dirset">DirSet</a></h2>
+<p>DirSets are groups of directories. These directories can be found in a
+directory tree starting in a base directory and are matched by
+patterns taken from a number of <a
+href="patternset.html">PatternSets</a>. DirSets can appear inside tasks
+that support this feature or at the same level as <code>target</code>
+(i.e., as children of <code>&lt;project&gt;</code>).</p>
+<p>PatternSets can be specified as nested
+<code>&lt;patternset&gt;</code> elements. In addition, DirSet holds
+an implicit PatternSet and supports the nested
+<code>&lt;include&gt;</code>, <code>&lt;includesfile&gt;</code>,
+<code>&lt;exclude&gt;</code> and <code>&lt;excludesfile&gt;</code>
+elements of <code>&lt;patternset&gt;</code> directly, as well as
+<code>&lt;patternset&gt;</code>'s 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">dir</td>
+    <td valign="top">The root of the directory tree of this DirSet.</td>
+    <td valign="top" align="center">Yes</td>
+  </tr>
+  <tr>
+    <td valign="top">includes</td>
+    <td valign="top">A comma-separated list of patterns of directories that
+     must be included; all directories are included when omitted.</td>
+    <td valign="top" align="center">No</td>
+  </tr>
+  <tr>
+    <td valign="top">includesfile</td>
+    <td valign="top">The name of a file; each line of this file is
+      taken to be an include pattern.</td>
+    <td valign="top" align="center">No</td>
+  </tr>
+  <tr>
+    <td valign="top">excludes</td>
+    <td valign="top">A comma-separated list of patterns of directories that
+     must be excluded; no directories are excluded when omitted.</td>
+    <td valign="top" align="center">No</td>
+  </tr>
+  <tr>
+    <td valign="top">excludesfile</td>
+    <td valign="top">The name of a file; each line of this file is
+      taken to be an exclude pattern.</td>
+    <td valign="top" align="center">No</td>
+  </tr>
+  <tr>
+    <td valign="top">casesensitive</td>
+    <td valign="top">Specifies whether case-sensitivty should be applied
+     (<code>true</code>|<code>yes</code>|<code>on</code> or
+     <code>false</code>|<code>no</code>|<code>off</code>).</td>
+    <td valign="top" align="center">No; defaults to true.</td>
+  </tr>
+</table>
+
+<h4>Examples</h4>
+<blockquote><pre>
+&lt;dirset dir=&quot;${build.dir}&quot;&gt;
+  &lt;include name=&quot;apps/**/classes&quot;/&gt;
+  &lt;exclude name=&quot;apps/**/*Test*&quot;/&gt;
+&lt;/dirset&gt;
+</pre></blockquote>
+<p>Groups all directories named <code>classes</code> found under the
+<code>apps</code> subdirectory of <code>${build.dir}</code>, except those
+that have the text <code>Test</code> in their name.</p>
+<blockquote><pre>
+&lt;dirset dir=&quot;${build.dir}&quot;&gt;
+  &lt;patternset id=&quot;non.test.sources&quot;&gt;
+    &lt;include name=&quot;apps/**/classes&quot;/&gt;
+    &lt;exclude name=&quot;apps/**/*Test*&quot;/&gt;
+  &lt;/patternset&gt;
+&lt;/dirset&gt;
+</pre></blockquote>
+<p>Groups the same directories as the above example, but also establishes
+a PatternSet that can be referenced in other
+<code>&lt;dirset&gt;</code> elements, rooted at a different directory.</p>
+<blockquote><pre>
+&lt;dirset dir=&quot;${debug_build.src}&quot; &gt;
+  &lt;patternset refid=&quot;non.test.sources&quot;/&gt;
+&lt;/dirset&gt;
+</pre></blockquote>
+<p>Groups all files in directory <code>${debug_build.src}</code>, using the
+same patterns as the above example.</p>
+
+<hr>
+<p align="center">Copyright &copy; 2001,2002 Apache Software Foundation.
+All rights Reserved.</p>
+
+</body>
+</html>
+

docs/manual/conceptstypeslist.html

@@ -15,12 +15,13 @@
 <a href="CoreTasks/common.html">Common Attributes</a><br>
 <a href="CoreTypes/description.html">Description Type</a><br>
 <a href="dirtasks.html">Directory-based Tasks</a><br>
+<a href="CoreTypes/dirset.html">DirSet</a><br>
 <a href="CoreTypes/filelist.html">FileList</a><br>
 <a href="CoreTypes/fileset.html">FileSet</a><br>
 <a href="CoreTypes/mapper.html">File Mappers</a><br>
 <a href="CoreTypes/filterchain.html">FilterChains and FilterReaders</a><br>
-<a href="CoreTypes/filterset.html">Filterset</a><br>
-<a href="CoreTypes/patternset.html">Patternset</a><br>
+<a href="CoreTypes/filterset.html">FilterSet</a><br>
+<a href="CoreTypes/patternset.html">PatternSet</a><br>
 <a href="CoreTypes/xmlcatalog.html">XMLCatalog</a><br>
 </body>
 </html>

docs/manual/using.html

@@ -354,9 +354,13 @@ supports <code>path</code> and
 <pre>
     &lt;classpath path=&quot;${classpath}&quot;/&gt;
 </pre>
-<p>In addition, <a href="CoreTypes/fileset.html">FileSet</a>s can be specified via
-nested <code>&lt;fileset&gt;</code> elements. The order in which the files
-building up a fileset are added to the path-like structure is not
+<p>In addition, <a href="CoreTypes/dirset.html">DirSet</a>s,
+<a href="CoreTypes/fileset.html">FileSet</a>s, and 
+<a href="CoreTypes/filelist.html">FileList</a>s
+can be specified via nested <code>&lt;dirset&gt;</code>,
+<code>&lt;fileset&gt;</code>, and <code>&lt;filelist&gt;</code>
+elements, respectively. <em>Note</em>: The order in which the files
+building up a FileSet are added to the path-like structure is not
 defined.</p>
 <pre>
     &lt;classpath&gt;
@@ -365,11 +369,20 @@ defined.</p>
         &lt;include name=&quot;**/*.jar&quot;/&gt;
       &lt;/fileset&gt;
       &lt;pathelement location=&quot;classes&quot;/&gt;
+      &lt;dirset dir=&quot;${build.dir}&quot;&gt;
+        &lt;include name=&quot;apps/**/classes&quot;/&gt;
+        &lt;exclude name=&quot;apps/**/*Test*&quot;/&gt;
+      &lt;/dirset&gt;
+      &lt;filelist refid=&quot;third-party_jars&quot;&gt;
     &lt;/classpath&gt;
 </pre>
 <p>This builds a path that holds the value of <code>${classpath}</code>,
-followed by all jar files in the <code>lib</code> directory, followed
-by the <code>classes</code> directory.</p>
+followed by all jar files in the <code>lib</code> directory, 
+the <code>classes</code> directory, all directories named
+<code>classes</code> under the <code>apps</code> subdirectory of
+<code>${build.dir}</code>, except those
+that have the text <code>Test</code> in their name, and
+the files specified in the referenced FileList.</p>
 <p>If you want to use the same path-like structure for several tasks,
 you can define them with a <code>&lt;path&gt;</code> element at the
 same level as <i>target</i>s, and reference them via their

src/main/org/apache/tools/ant/taskdefs/PathConvert.java

@@ -184,15 +184,16 @@ public class PathConvert extends Task {
     }
 
     /**
-     * Set the value of the proprty attribute - this is the property into which our
-     * converted path will be placed.
+     * Set the value of the property attribute - this is the property
+     * into which our converted path will be placed.
      */
     public void setProperty( String p ) {
         property = p;
     }
 
     /**
-     * Adds a reference to a PATH or FILESET defined elsewhere.
+     * Adds a reference to a Path, FileSet, DirSet, or FileList defined
+     * elsewhere.
      */
     public void setRefid(Reference r) {
         if( path != null ) {
@@ -312,8 +313,8 @@ public class PathConvert extends Task {
 
         if( size != 0 ) {
 
-            // Iterate over the map entries and apply each one.  Stop when one of the
-            // entries actually changes the element
+            // Iterate over the map entries and apply each one.
+            // Stop when one of the entries actually changes the element.
 
             for( int i=0; i < size; i++ ) {
                 MapEntry entry = (MapEntry)prefixMap.elementAt(i);
@@ -379,7 +380,7 @@ public class PathConvert extends Task {
      * not have child elements if the refid attribute is set.  
      */
     private BuildException noChildrenAllowed() {
-        return new BuildException("You must not specify nested PATH elements when using refid");
+        return new BuildException("You must not specify nested <path> elements when using the refid attribute.");
     }