From 098f15932fbfceb692885e3a45e02c58af524abe Mon Sep 17 00:00:00 2001 From: Diane Holt Date: Sat, 30 Mar 2002 21:37:41 +0000 Subject: [PATCH] Document and new / support for and (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 | 10 +- docs/manual/CoreTasks/pathconvert.html | 136 ++++++++---------- docs/manual/CoreTypes/dirset.html | 103 +++++++++++++ docs/manual/conceptstypeslist.html | 5 +- docs/manual/using.html | 23 ++- .../tools/ant/taskdefs/PathConvert.java | 13 +- 6 files changed, 196 insertions(+), 94 deletions(-) create mode 100644 docs/manual/CoreTypes/dirset.html diff --git a/WHATSNEW b/WHATSNEW index 22f3fc0c2..25da225da 100644 --- a/WHATSNEW +++ b/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 and +* Open Source application server JOnAS support: + EJB hot deploy and deploy with and + +* Added new DirSet () datatype. + +* now supports nested and elements. + +* now supports nested and elements. Changes from Ant 1.4 to Ant 1.4.1 =========================================== diff --git a/docs/manual/CoreTasks/pathconvert.html b/docs/manual/CoreTasks/pathconvert.html index 82a428d8c..4f8daa6e5 100644 --- a/docs/manual/CoreTasks/pathconvert.html +++ b/docs/manual/CoreTasks/pathconvert.html @@ -9,16 +9,16 @@

Pathconvert

Description

-

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. +

Converts a nested <path> 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.

-

Prefix maps can be specified to map Windows drive letters to Unix paths and vice - versa.

+

Nested <map> elements can be specified to map Windows +drive letters to Unix paths, and vice-versa.

Parameters

@@ -30,12 +30,14 @@ @@ -54,15 +56,18 @@ - + - +
targetos - The target architecture. Must be one of 'unix' or 'windows'.
This is a - shorthand mechanism for specifying both pathsep and dirsep + The target architecture. Must be one of 'unix' or 'windows'. + This is a shorthand mechanism for specifying both + pathsep and dirsep according to the specified target architecture. 		- Must specify one of targetos, pathsep,or dirsep. + Yes, unless pathsep and/or + dirsep are specified.
propertyThe name of the property in which to place the converted pathThe name of the property in which to place the converted path. Yes
refid What to convert, given as a - reference to a PATH or FILESET + reference to a + <path>, <fileset>, + <dirset>, or <fileset> defined elsewhereNo, if omitted a nested <path> element must be supplied.No; if omitted, a nested + <path> element must be supplied.

Parameters specified as nested elements

@@ -76,14 +81,14 @@ from - 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 + 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. Yes to - The replacement text to use when from is matched. + The replacement text to use when from is matched. Yes @@ -92,87 +97,61 @@ the path being processed. If no map entries are specified, then no path prefix mapping is performed.

-

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 from values are prefixes of other from values. +

Note: 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 from values are +prefixes of other from values.

path

-

If a path reference is not supplied using the refid attribute, then a - nested path element must be supplied. See +

If the refid attribute is not specified, then a + nested <path> element must be supplied. See Path-like Structures for details.

Examples

-

In the examples below, assume that the property wl.home has the value -d:\weblogic on Windows and /weblogic on Unix.

+

In the examples below, assume that the ${wl.home} property +has the value +d:\weblogic, and ${wl.home.unix} has the value +/weblogic.

Example 1

     <path id="wl.path">
-      <pathelement location="${wl.home}/lib/weblogicaux.jar" />
-      <pathelement location="${wl.home}/classes" />
-      <pathelement location="${wl.home}/mssqlserver4/classes" />
-      <pathelement location="c:\winnt\System32" />
+      <pathelement location="${wl.home}/lib/weblogicaux.jar"/>
+      <pathelement location="${wl.home}/classes"/>
+      <pathelement location="${wl.home}/mssqlserver4/classes"/>
+      <pathelement location="c:\winnt\System32"/>
     </path>
     
-    <pathconvert targetos="unix" property="newpath" refid="wl.path"/>
+    <pathconvert targetos="unix" property="wl.path.unix" refid="wl.path">
+      <map from="${wl.home}" to="${wl.home.unix}"/>
+      <map from="c:" to=""/>
+    </pathconvert>
-

Assuming wl.property has the value "d:\weblogic", will generate the path shown below - and store it in the property named newpath +

will generate the path shown below +and store it in the property named wl.path.unix. 

 /weblogic/lib/weblogicaux.jar:/weblogic/classes:/weblogic/mssqlserver4/classes:/WINNT/SYSTEM32
-Note that the drive letters have been removed. This is the default behavior when no map -elements have been specified.

Example 2

+Given a FileList defined as: 
-    
-    <pathconvert targetos="unix" property="newpath" >
-      <path id="wl.path">
-        <pathelement location="${wl.home}/lib/weblogicaux.jar" />
-        <pathelement location="${wl.home}/classes" />
-        <pathelement location="${wl.home}/mssqlserver4/classes" />
-        <pathelement location="c:\winnt\System32" />
-      </path>
-    </pathconvert>
-
-This generates the exact same path as the previous example. It demonstrates the use of -a nested path element. -

Example 3

-
-    <pathconvert targetos="unix" property="newpath" refid="wl.path">
-      <map from="d:" to="/foo"/>
-      <map from="c:" to="/bar"/>
-    </pathconvert>
-
-

This example specifies two map entries that will convert path elements that start with -c: to /dos and d: to /. The resulting path is shown -below.

-
-/weblogic/lib/weblogicaux.jar:/weblogic/classes:/weblogic/mssqlserver4/classes:/dos/WINNT/SYSTEM32
+  <filelist id="custom_tasks.jars"
+        dir="${env.HOME}/ant/lib"
+        files="njavac.jar,xproperty.jar"/>
-

Example 4

+then: 
-    <pathconvert targetos="windows" property="newpath" >
-      <path id="wl.path">
-        <pathelement location="${wl.home}/lib/weblogicaux.jar" />
-        <pathelement location="${wl.home}/classes" />
-        <pathelement location="${wl.home}/mssqlserver4/classes" />
-        <pathelement location="/dos/winnt/System32" />
-      </path>
-      <map from="/dos" to="c:\"/>
-      <map from="/" to="d:\"/>
+    <pathconvert targetos="unix" property="custom_tasks.jars" refid="custom_tasks.jars">
+      <map from="${env.HOME}" to="/usr/local"/>
     </pathconvert>
-

This example, similar to the one above but targetting windows, specifies two map -entries that will convert path elements that start with -/dos to c:\ and / to d:\. Note that the order of the -map elements was important here since / is a prefix of /dos. -The resulting path is shown below.

+will convert the list of files to the following Unix path: 
-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
-

Example 5

+ +

Example 3

     <fileset dir="${src.dir}" id="src.files">
       <include name="**/*.java"/>
@@ -187,12 +166,11 @@ it defaults to the appropriate character for the current platform.  Such a list
 then be used in another task, like javadoc, that requires a comma separated
 list of files.
 

-

 
 

-
Copyright © 2001 Apache Software Foundation. All rights
-Reserved.

+
Copyright © 2001,2002 Apache Software Foundation.
+All rights Reserved.

 
 
 
- 
\ No newline at end of file
+ 
diff --git a/docs/manual/CoreTypes/dirset.html b/docs/manual/CoreTypes/dirset.html
new file mode 100644
index 000000000..2a6a86094
--- /dev/null
+++ b/docs/manual/CoreTypes/dirset.html
@@ -0,0 +1,103 @@
+
+
+
+
+DirSet Type
+
+
+
+
+
DirSet

+
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 PatternSets. DirSets can appear inside tasks
+that support this feature or at the same level as target
+(i.e., as children of <project>).

+
PatternSets can be specified as nested
+<patternset> elements. In addition, DirSet holds
+an implicit PatternSet and supports the nested
+<include>, <includesfile>,
+<exclude> and <excludesfile>
+elements of <patternset> directly, as well as
+<patternset>'s attributes.

+
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
AttributeDescriptionRequired
dirThe root of the directory tree of this DirSet.Yes
includesA comma-separated list of patterns of directories that
+     must be included; all directories are included when omitted.No
includesfileThe name of a file; each line of this file is
+      taken to be an include pattern.No
excludesA comma-separated list of patterns of directories that
+     must be excluded; no directories are excluded when omitted.No
excludesfileThe name of a file; each line of this file is
+      taken to be an exclude pattern.No
casesensitiveSpecifies whether case-sensitivty should be applied
+     (true|yes|on or
+     false|no|off).No; defaults to true.

+
+
Examples

+
+<dirset dir="${build.dir}">
+  <include name="apps/**/classes"/>
+  <exclude name="apps/**/*Test*"/>
+</dirset>
+

+
Groups all directories named classes found under the
+apps subdirectory of ${build.dir}, except those
+that have the text Test in their name.

+
+<dirset dir="${build.dir}">
+  <patternset id="non.test.sources">
+    <include name="apps/**/classes"/>
+    <exclude name="apps/**/*Test*"/>
+  </patternset>
+</dirset>
+

+
Groups the same directories as the above example, but also establishes
+a PatternSet that can be referenced in other
+<dirset> elements, rooted at a different directory.

+
+<dirset dir="${debug_build.src}" >
+  <patternset refid="non.test.sources"/>
+</dirset>
+

+
Groups all files in directory ${debug_build.src}, using the
+same patterns as the above example.

+
+

+
Copyright © 2001,2002 Apache Software Foundation.
+All rights Reserved.

+
+
+
+
diff --git a/docs/manual/conceptstypeslist.html b/docs/manual/conceptstypeslist.html
index 915c590d3..9c30f22d9 100644
--- a/docs/manual/conceptstypeslist.html
+++ b/docs/manual/conceptstypeslist.html
@@ -15,12 +15,13 @@
 Common Attributes

 Description Type

 Directory-based Tasks

+DirSet

 FileList

 FileSet

 File Mappers

 FilterChains and FilterReaders

-Filterset

-Patternset

+FilterSet

+PatternSet

 XMLCatalog

 
 
diff --git a/docs/manual/using.html b/docs/manual/using.html
index 62661ebf0..1d69ba610 100644
--- a/docs/manual/using.html
+++ b/docs/manual/using.html
@@ -354,9 +354,13 @@ supports path and
 
     <classpath path="${classpath}"/>
 

-
In addition, FileSets can be specified via
-nested <fileset> elements. The order in which the files
-building up a fileset are added to the path-like structure is not
+
In addition, DirSets,
+FileSets, and 
+FileLists
+can be specified via nested <dirset>,
+<fileset>, and <filelist>
+elements, respectively. Note: The order in which the files
+building up a FileSet are added to the path-like structure is not
 defined.

 
     <classpath>
@@ -365,11 +369,20 @@ defined.

         <include name="**/*.jar"/>
       </fileset>
       <pathelement location="classes"/>
+      <dirset dir="${build.dir}">
+        <include name="apps/**/classes"/>
+        <exclude name="apps/**/*Test*"/>
+      </dirset>
+      <filelist refid="third-party_jars">
     </classpath>
 

 
This builds a path that holds the value of ${classpath},
-followed by all jar files in the lib directory, followed
-by the classes directory.

+followed by all jar files in the lib directory, 
+the classes directory, all directories named
+classes under the apps subdirectory of
+${build.dir}, except those
+that have the text Test in their name, and
+the files specified in the referenced FileList.

 
If you want to use the same path-like structure for several tasks,
 you can define them with a <path> element at the
 same level as targets, and reference them via their
diff --git a/src/main/org/apache/tools/ant/taskdefs/PathConvert.java b/src/main/org/apache/tools/ant/taskdefs/PathConvert.java
index af47aa616..271df93f0 100644
--- 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  elements when using the refid attribute.");
     }