You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by br...@apache.org on 2003/02/04 18:29:12 UTC
cvs commit: jakarta-ant/docs/manual/CoreTypes fileset.html
bruce 2003/02/04 09:29:11
Modified: docs/manual dirtasks.html
docs/manual/CoreTypes fileset.html
Log:
Added references to Selectors in fileset documentation, and cleaned up directory task documentation to be more accurate as well as point to selectors.
PR: 16682
Revision Changes Path
1.18 +127 -31 jakarta-ant/docs/manual/dirtasks.html
Index: dirtasks.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/manual/dirtasks.html,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- dirtasks.html 20 Jan 2003 08:09:01 -0000 1.17
+++ dirtasks.html 4 Feb 2003 17:29:10 -0000 1.18
@@ -8,29 +8,62 @@
<body>
<h2><a name="directorybasedtasks">Directory-based Tasks</a></h2>
-<p>Some tasks use directory trees for the task they perform.
-For example, the <a
-href="CoreTasks/javac.html">javac</a> task, which works upon a directory tree
-with <code>.java</code> files.
-Sometimes it can be very useful to work on a subset of that directory tree. This
-section describes how you can select a subset of such a directory tree.</p>
-<p>Ant gives you two ways to create a subset, both of which can be used at the same
-time:</p>
+<p>Some tasks use directory trees for the actions they perform.
+For example, the <a href="CoreTasks/javac.html">javac</a> task, which
+compiles a directory tree with <code>.java</code> files into
+<code>.class</code> files, is one of these directory-based tasks. Because
+some of these tasks do so much work with a directory tree, the task itself
+can act as an implicit <a href="CoreTypes/fileset.html">FileSet</a>.</p>
+<p>Whether the fileset is implicit or not, it can often be very useful to
+work on a subset of the directory tree. This section describes how you can
+select a subset of such a directory tree when using one of these
+directory-based tasks.</p>
+<p>Ant gives you two ways to create a subset of files in a fileset, both of
+which can be used at the same time:</p>
<ul>
- <li>Only include files/directories that match at least one pattern of a set of
- patterns.</li>
- <li>Exclude files/directories that match at least one pattern a set of
- patterns.</li>
+ <li>Only include files and directories that match any
+ <code>include</code> patterns and do not match any
+ <code>exclude</code> patterns in a given
+ <a href="CoreTypes/patternset.html">PatternSet</a>.</li>
+ <li>Select files based on selection criteria defined by a collection of
+ <a href="CoreTypes/selectors.html">selector</a> nested elements.</li>
</ul>
-<p>When both inclusion and exclusion are used, only files/directories that match
-the include patterns, and don't match the exclude patterns, are used.</p>
-<p>Patterns can be specified inside the buildfile via task attributes or
-nested elements and via external files. Each line of the external file
+<h3><a name="patternset">Patternset</a></h3>
+
+<p>We said that Directory-based tasks can sometimes act as an implicit
+<a href="CoreTypes/fileset.html"><code><fileset></code></a>,
+but in addtion to that, a FileSet acts as an implicit
+<a href="CoreTypes/patternset.html"><code><patternset></code></a>.</p>
+
+<p>The inclusion and exclusion elements of the implicit PatternSet can be
+specified inside the directory-based task (or explicit fileset) via
+either:</p>
+<ul>
+ <li>the attributes <code>includes</code> and
+ <code>excludes</code>.</li>
+ <li>nested elements <code><include></code> and
+ <code><exclude></code>.</li>
+ <li>external files specified with the attributes
+ <code>includesfile</code> and <code>excludesfile</code>.</li>
+ <li>external files specified with the nested elements
+ <code><includesfile></code> and <code><excludesfile></code>.
+ </li>
+</ul>
+When dealing with an external file, each line of the file
is taken as a pattern that is added to the list of include or exclude
patterns.</p>
-<h3><a name="patterns">Patterns</a></h3>
-<p>As described earlier, patterns are used for the inclusion and exclusion.
-These patterns look very much like the patterns used in DOS and UNIX:</p>
+
+<p>When both inclusion and exclusion are used, only files/directories that
+match at least one of the include patterns and don't match any of the
+exclude patterns are used. If no include pattern is given, all files
+are assumed to match the include pattern (with the possible exception of
+the default excludes).</p>
+
+<h4><a name="patterns">Patterns</a></h4>
+
+<p>As described earlier, patterns are used for the inclusion and exclusion
+of files. These patterns look very much like the patterns used in DOS and
+UNIX:</p>
<p>'*' matches zero or more characters, '?' matches one character.</p>
<p><b>Examples:</b></p>
<p>
@@ -45,7 +78,8 @@
Combinations of <code>*</code>'s and <code>?</code>'s are allowed.</p>
<p>Matching is done per-directory. This means that first the first directory in
the pattern is matched against the first directory in the path to match. Then
-the second directory is matched, and so on. For example, when we have the pattern <code>/?abc/*/*.java</code>
+the second directory is matched, and so on. For example, when we have the pattern
+<code>/?abc/*/*.java</code>
and the path <code>/xabc/foobar/test.java</code>,
the first <code>?abc</code> is matched with <code>xabc</code>,
then <code>*</code> is matched with <code>foobar</code>,
@@ -72,7 +106,8 @@
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><code>**/CVS/*</code></td>
- <td valign="top">Matches all files in <code>CVS</code> directories that can be located
+ <td valign="top">Matches all files in <code>CVS</code>
+ directories that can be located
anywhere in the directory tree.<br>
Matches:
<pre>
@@ -82,12 +117,14 @@
</pre>
But not:
<pre>
- org/apache/CVS/foo/bar/Entries (<code>foo/bar/</code> part does not match)</td>
+ org/apache/CVS/foo/bar/Entries (<code>foo/bar/</code>
+ part does not match)</td>
</pre>
</tr>
<tr>
<td valign="top"><code>org/apache/jakarta/**</code></td>
- <td valign="top">Matches all files in the <code>org/apache/jakarta</code> directory tree.<br>
+ <td valign="top">Matches all files in the <code>org/apache/jakarta</code>
+ directory tree.<br>
Matches:
<pre>
org/apache/jakarta/tools/ant/docs/index.html
@@ -124,7 +161,57 @@
<p>When these patterns are used in inclusion and exclusion, you have a powerful
way to select just the files you want.</p>
-<h3>Examples</h3>
+<h3><a name="selectors">Selectors</a></h3>
+<p>The <a href="CoreTypes/fileset.html"><code><fileset></code></a>,
+whether implicit or explicit in the
+directory-based task, also acts as an
+<a href="CoreTypes/selectors.html#andselect"><code><and></code></a>
+selector container. This can be used to create arbitrarily complicated
+selection criteria for the files the task should work with. See the
+<a href="CoreTypes/selectors.html">Selector</a> documentation for more
+information.</p>
+
+<h3><a name="tasklist">Standard Tasks/Filesets</a></h3>
+<p>Many of the standard tasks in ant take one or more filesets which follow
+the rules given here. This list, a subset of those, is a list of standard ant
+tasks that can act as an implicit fileset:</p>
+<ul>
+ <li><a href="CoreTasks/checksum.html"><checksum></a></li>
+ <li><a href="CoreTasks/copydir.html"><copydir></a> (deprecated)</li>
+ <li><a href="CoreTasks/delete.html"><delete></a></li>
+ <li><a href="CoreTasks/dependset.html"><dependset></a></li>
+ <li><a href="CoreTasks/fixcrlf.html"><fixcrlf></a></li>
+ <li><a href="CoreTasks/javac.html"><javac></a></li>
+ <li><a href="CoreTasks/replace.html"><replace></a></li>
+ <li><a href="CoreTasks/rmic.html"><rmic></a></li>
+ <li><a href="CoreTasks/style.html"><style> (aka <xslt>)</a></li>
+ <li><a href="CoreTasks/tar.html"><tar></a></li>
+ <li><a href="CoreTasks/zip.html"><zip></a></li>
+ <li><a href="OptionalTasks/ejb.html#ddcreator"><ddcreator></a></li>
+ <li><a href="OptionalTasks/ejb.html#ejbjar.html"><ejbjar></a></li>
+ <li><a href="OptionalTasks/ejb.html#ejbc"><ejbc></a></li>
+ <li><a href="OptionalTasks/cab.html"><cab></a></li>
+ <li><a href="OptionalTasks/icontract.html"><icontract></a></li>
+ <li><a href="OptionalTasks/native2ascii.html"><native2ascii></a></li>
+ <li><a href="OptionalTasks/netrexxc.html"><netrexxc></a></li>
+ <li>
+ <a href="OptionalTasks/renameextensions.html"><renameextensions></a>
+ </li>
+ <li><a href="OptionalTasks/depend.html"><depend></a></li>
+ <li><a href="OptionalTasks/dotnet.html"><ilasm></a></li>
+ <li><a href="OptionalTasks/dotnet.html"><csc></a></li>
+ <li><a href="OptionalTasks/dotnet.html"><vbc></a></li>
+ <li><a href="OptionalTasks/translate.html"><translate></a></li>
+ <li>
+ <a href="Integration/VAJAntTool.html#vajexport"><vajexport></a>
+ </li>
+ <li><image></li>
+ <li><a href="OptionalTasks/jlink.html"><jlink></a> (deprecated)</li>
+ <li><a href="OptionalTasks/jspc.html"><jspc></a></li>
+ <li><a href="OptionalTasks/wljspc.html"><wljspc></a></li>
+</ul>
+
+<h3><a name="examples">Examples</a></h3>
<pre>
<copy todir="${dist}">
<fileset dir="${src}"
@@ -136,7 +223,6 @@
located in the directory tree defined by <code>${src}</code> to the
destination directory defined by <code>${dist}</code>,
but excludes all <code>*.gif</code> files from the copy.</p>
-<p> This example can also be expressed using nested elements:</p>
<pre>
<copy todir="${dist}">
<fileset dir="${src}">
@@ -145,10 +231,20 @@
</fileset>
</copy>
</pre>
+<p> The same as the example above, but expressed using nested elements.</p>
+
+<pre>
+<delete dir="${dist}">
+ <include name="**/images/*"/>
+ <exclude name="**/*.gif"/>
+</delete>
+</pre>
+<p>Deleting the original set of files, the <code>delete</code> task can act
+as an implicit fileset.</p>
<h3><a name="defaultexcludes">Default Excludes</a></h3>
-<p>There are a set of definitions that are excluded by default from all directory-based tasks.
-They are:</p>
+<p>There are a set of definitions that are excluded by default from all
+directory-based tasks. They are:</p>
<pre>
**/*~
**/#*#
@@ -165,11 +261,11 @@
**/.svn/**
**/.DS_Store
</pre>
-<p>If you do not want these default excludes applied, you may disable them with the
-<code>defaultexcludes="no"</code> attribute.</p>
+<p>If you do not want these default excludes applied, you may disable them
+with the <code>defaultexcludes="no"</code> attribute.</p>
<hr>
-<p align="center">Copyright © 2000-2003 Apache Software Foundation. All rights
-Reserved.</p>
+<p align="center">Copyright © 2000-2003 Apache Software Foundation. All
+rights Reserved.</p>
</body>
</html>
1.17 +25 -1 jakarta-ant/docs/manual/CoreTypes/fileset.html
Index: fileset.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/manual/CoreTypes/fileset.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- fileset.html 12 Dec 2002 14:17:44 -0000 1.16
+++ fileset.html 4 Feb 2003 17:29:11 -0000 1.17
@@ -11,7 +11,8 @@
<p>FileSets are groups of files. These files 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>. FileSets can appear inside tasks
+href="patternset.html">PatternSets</a> and
+<a href="selectors.html">Selectors</a>. FileSets can appear inside tasks
that support this feature or at the same level as <code>target</code>
- i.e., as children of <code>project</code>.</p>
<p>PatternSets can be specified as nested
@@ -21,6 +22,10 @@
<code><exclude></code> and <code><excludesfile></code>
elements of PatternSet directly, as well as PatternSet's
attributes.</p>
+<p>Selectors are available as nested elements.within the FileSet.
+If any of the selectors within the FileSet do not select the file, the
+file is not considered part of the FileSet. This makes FileSets
+euqivalent to an <code><and></code> selector container.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
@@ -110,6 +115,25 @@
</pre></blockquote>
<p>Groups all files in directory <code>${client.src}</code>, using the
same patterns as the above example.</p>
+<blockquote><pre>
+<fileset dir="${server.src}" casesensitive="yes">
+ <filename name="**/*.java"/>
+ <filename name="**/*Test*" negate="true"/>
+</fileset>
+</pre></blockquote>
+<p>Groups the same files as the top example, but using the
+<code><filename></code> selector.</p>
+<blockquote><pre>
+<fileset dir="${server.src}" casesensitive="yes">
+ <filename name="**/*.java"/>
+ <not>
+ <filename name="**/*Test*"/>
+ </not>
+</fileset>
+</pre></blockquote>
+<p>Groups the same files as the previous example using a combination of the
+<code><filename></code> selector and the <code><not></code>
+selector container.</p>
<hr>
<p align="center">Copyright © 2000-2002 Apache Software Foundation.