Author: bodewig
Date: Fri Feb 5 14:39:50 2010
New Revision: 906952
URL: http://svn.apache.org/viewvc?rev=906952&view=rev
Log:
document sortfilter
Modified:
ant/core/trunk/docs/manual/CoreTypes/filterchain.html
ant/core/trunk/src/main/org/apache/tools/ant/filters/SortFilter.java
Modified: ant/core/trunk/docs/manual/CoreTypes/filterchain.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/CoreTypes/filterchain.html?rev=906952&r1=906951&r2=906952&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/CoreTypes/filterchain.html (original)
+++ ant/core/trunk/docs/manual/CoreTypes/filterchain.html Fri Feb 5 14:39:50
2010
@@ -1547,8 +1547,116 @@
<h3><a name="sortfilter">SortFilter</a></h3>
- <p><strong>(documentation pending)</strong></p>
<p><em>since Ant 1.8.0</em></p>
+<p>The sort filter reads all lines and sorts them. The sort order can
+ be reversed and it is possible to specify a custom implementation of
+ the <code>java.util.Comparator</code> interface to get even more
+ control.</p>
+
+<table cellSpacing=0 cellPadding=2 border=1>
+ <tr>
+ <td vAlign=top><b>Parameter Name</b></td>
+ <td vAlign=top><b>Parameter Value</b></td>
+ <td vAlign=top align="center"><b>Required</b></td>
+ </tr>
+ <tr>
+ <td vAlign=top>reverse</td>
+ <td vAlign=top align="center">whether to reverse the sort order,
+ defaults to false. <b>Note:</b> this parameter is ignored if
+ the comparator parameter is present as well.</td>
+ <td vAlign=top align="center">No</td>
+ </tr>
+ <tr>
+ <td vAlign=top>comparator</td>
+ <td vAlign=top align="center">Class name of a class that
+ implements <code>java.util.Comparator</code> for Strings. This
+ class will be used to determine the sort order of lines.</td>
+ <td vAlign=top align="center">No</td>
+ </tr>
+</table>
+
+<p>This filter is also available using the
+ name <code>sortfilter</code>. The <code>reverse</code> parameter
+ becomes an attribute, <code>comparator</code> can be specified by
+ using a nested element.</p>
+
+<h4>Examples:</h4>
+
+<blockquote><pre>
+ <copy todir="build">
+ <fileset dir="input" includes="*.txt"/>
+ <filterchain>
+ <sortfilter/>
+ </filterchain>
+ </copy>
+</pre></blockquote>
+
+<p>
+Sort all files <code>*.txt</code> from <i>src</i> location
+into <i>build</i> location. The lines of each file are sorted in
+ascendant order comparing the lines via the
+<code>String.compareTo(Object o)</code> method.
+</p>
+
+<blockquote><pre>
+ <copy todir="build">
+ <fileset dir="input" includes="*.txt"/>
+ <filterchain>
+ <sortfilter reverse="true"/>
+ </filterchain>
+ </copy>
+</pre></blockquote>
+
+<p>
+Sort all files <code>*.txt</code> from <i>src</i> location into reverse
+order and copy them into <i>build</i> location.
+</p>
+
+<blockquote><pre>
+ <copy todir="build">
+ <fileset dir="input" includes="*.txt"/>
+ <filterchain>
+ <filterreader
classname="org.apache.tools.ant.filters.SortFilter">
+ <param name="comparator"
value="org.apache.tools.ant.filters.EvenFirstCmp"/>
+ </filterreader/>
+ </filterchain>
+ </copy>
+</pre></blockquote>
+
+<p>
+Sort all files <code>*.txt</code> from <i>src</i> location using as
+sorting criterium <code>EvenFirstCmp</code> class, that sorts the file
+lines putting even lines first then odd lines for example. The modified files
+are copied into <i>build</i> location. The <code>EventFirstCmp</code>,
+has to an instanciable class via <code>Class.newInstance()</code>,
+therefore in case of inner class has to be <em>static</em>. It also has to
+implement <code>java.util.Comparator</code> interface, for example:
+</p>
+
+<pre>
+ package org.apache.tools.ant.filters;
+ ...(omitted)
+ public final class EvenFirstCmp implements
<b>Comparator</b> {
+ public int compare(Object o1, Object o2) {
+ ...(omitted)
+ }
+ }
+</pre>
+
+<p>The example above is equivalent to:</p>
+
+<blockquote><pre>
+ <componentdef name="evenfirst"
+ classname="org.apache.tools.ant.filters.EvenFirstCmp"/>
+ <copy todir="build">
+ <fileset dir="input" includes="*.txt"/>
+ <filterchain>
+ <sortfilter>
+ <evenfirst/>
+ </sortfilter/>
+ </filterchain>
+ </copy>
+</pre></blockquote>
</body></html>
Modified: ant/core/trunk/src/main/org/apache/tools/ant/filters/SortFilter.java
URL:
http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/filters/SortFilter.java?rev=906952&r1=906951&r2=906952&view=diff
==============================================================================
--- ant/core/trunk/src/main/org/apache/tools/ant/filters/SortFilter.java
(original)
+++ ant/core/trunk/src/main/org/apache/tools/ant/filters/SortFilter.java Fri
Feb 5 14:39:50 2010
@@ -47,9 +47,9 @@
* </pre>
*
* <p>
- * Sort all files <code>*.txt</code> from <i>src</i> location in descendant
- * order and copy them into <i>build</i> location. The lines of each file are
- * sorted in ascendant order comparing the lines via the
+ * Sort all files <code>*.txt</code> from <i>src</i> location and copy
+ * them into <i>build</i> location. The lines of each file are sorted
+ * in ascendant order comparing the lines via the
* <code>String.compareTo(Object o)</code> method.
* </p>
*
@@ -57,9 +57,7 @@
* <copy todir="build">
* <fileset dir="input" includes="*.txt"/>
* <filterchain>
- * <sortfilter/>
- * <param name="reverse" value="true"/>
- * </sortfilter/>
+ * <sortfilter reverse="true"/>
* </filterchain>
* </copy>
* </pre>
@@ -75,9 +73,9 @@
* <copy todir="build">
* <fileset dir="input" includes="*.txt"/>
* <filterchain>
- * <sortfilter/>
+ * <filterreader
classname="org.apache.tools.ant.filters.SortFilter">
* <param name="comparator"
value="org.apache.tools.ant.filters.EvenFirstCmp"/>
- * </sortfilter/>
+ * </filterreader/>
* </filterchain>
* </copy>
* </pre>
@@ -102,8 +100,23 @@
* }
* </pre>
*
+ * <p>The example above is equivalent to:</p>
+ *
+ * <blockquote><pre>
+ * <componentdef name="evenfirst"
+ *
classname="org.apache.tools.ant.filters.EvenFirstCmp"/>
+ * <copy todir="build">
+ * <fileset dir="input" includes="*.txt"/>
+ * <filterchain>
+ * <sortfilter>
+ * <evenfirst/>
+ * </sortfilter/>
+ * </filterchain>
+ * </copy>
+ * </pre></blockquote>
+ *
* <p> If parameter <code>comparator</code> is present, then
- * <code>reverse</code> parameter will not taken into account. </p>
+ * <code>reverse</code> parameter will not be taken into account. </p>
*
* @since Ant 1.8.0
*/
