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
23 years ago · 098f15932f
--- a/+ 8
+++ b/+ 8
@@ -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
 ===========================================
--- a/docs/manual/CoreTasks/pathconvert.html
+++ b/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>

 
 
--- a/docs/manual/CoreTypes/dirset.html
+++ b/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>

--- a/docs/manual/conceptstypeslist.html
+++ b/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>
--- a/docs/manual/using.html
+++ b/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
--- a/src/main/org/apache/tools/ant/taskdefs/PathConvert.java
+++ b/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.");
    }