You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by um...@apache.org on 2002/03/04 21:48:17 UTC
cvs commit: jakarta-ant/proposal/sandbox/filterreaders/src/etc/testcases/taskdefs loadfile.xml
umagesh 02/03/04 12:48:17
Modified: proposal/sandbox/filterreaders/docs/manual/CoreTypes
filterchain.html
proposal/sandbox/filterreaders/src/etc/testcases/taskdefs
loadfile.xml
Log:
Improved doc; loadfile.xml typo fix.
Revision Changes Path
1.2 +169 -25 jakarta-ant/proposal/sandbox/filterreaders/docs/manual/CoreTypes/filterchain.html
Index: filterchain.html
===================================================================
RCS file: /home/cvs/jakarta-ant/proposal/sandbox/filterreaders/docs/manual/CoreTypes/filterchain.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- filterchain.html 27 Feb 2002 21:51:34 -0000 1.1
+++ filterchain.html 4 Mar 2002 20:48:16 -0000 1.2
@@ -2,21 +2,97 @@
<HTML>
<HEAD>
- <TITLE>FilterChain Type</TITLE>
+ <TITLE>FilterChains and FilterReaders</TITLE>
</HEAD>
<BODY>
-<H2><A name="filterchain">FilterChain</A></H2>
-<P>FilterChains are groups of ordered FilterReaders. FilterChains can appear
-inside tasks that support this feature. <BR>FilterChains are used for
-filtering file contents read in by tasks like <a href="../CoreTasks/loadfile.html">
-LoadFile</a>, LoadProperties, etc.<BR>
+<H2>FilterChains and FilterReaders</H2>
+Look at Unix pipes - they offer you so much flexibility -
+say you wanted to copy just those lines that contained the
+string blee from the first 10 lines of a file 'foo'
+to a file 'bar' - you would do something like<P>
+<code>
+cat foo|head -n10|grep blee > bar
+</code><P>
+Ant was not flexible enough. There was no way for the
+<copy> task to do something similar. If you wanted
+the <copy> task to get the first 10 lines, you would have
+had to create special attributes:<P>
+<code>
+<copy file="foo" tofile="bar" head="10" contains="blee"/>
+</code><P>
+The obvious problem thus surfaced: Ant tasks would not be able
+to accomodate such data transformation attributes as they would
+be endless. The task would also not know in which order these
+attributes were to be interpreted. That is, must the task execute the
+contains attribute first and then the head attribute or vice-versa?
+What Ant tasks needed was a mechanism to allow pluggable filter (data
+tranformer) chains. Ant would provide a few filters for which there
+have been repeated requests. Users with special filtering needs
+would be able to easily write their own and plug them in.<P>
+
+The solution was to refactor data transformation oriented
+tasks to support FilterChains. A FilterChain is a group of
+ordered FilterReaders. Users can define their own FilterReaders
+by just extending the java.io.FilterReader class. Such custom
+FilterReaders can be easily plugged in as nested elements of
+<filterchain> by using <filterreader> elements.
+<P>
+Example:
+<BLOCKQUOTE><PRE>
+<copy file="${src.file}" tofile="${dest.file}">
+ <filterchain>
+ <filterreader classname="your.extension.of.java.io.FilterReader">
+ <param name="foo" value="bar"/>
+ </filterreader>
+ <filterreader classname="another.extension.of.java.io.FilterReader">
+ <classpath>
+ <pathelement path="${classpath}"/>
+ </classpath>
+ <param name="blah" value="blee"/>
+ <param type="abra" value="cadabra"/>
+ </filterreader>
+ </filterchain>
+</copy>
+</PRE></BLOCKQUOTE>
-Each FilterChain is composed of zero or more of the following nested elements.<BR>
+Ant provides some built-in filter readers. These filter readers
+can also be declared using a syntax similar to the above syntax.
+However, they can be declared using some simpler syntax also.<P>
+Example:
+<BLOCKQUOTE><PRE>
+<loadfile srcfile="${src.file}" property="${src.file.head}">
+ <filterchain>
+ <headfilter lines="15"/>
+ </filterchain>
+</loadfile>
+</PRE></BLOCKQUOTE>
+is equivalent to:
+<BLOCKQUOTE><PRE>
+<loadfile srcfile="${src.file}" property="${src.file.head}">
+ <filterchain>
+ <filterreader classname="org.apache.tools.ant.filters.HeadFilter">
+ <param name="lines" value="15"/>
+ </filterreader>
+ </filterchain>
+</loadfile>
+</PRE></BLOCKQUOTE>
+
+The following built-in tasks support nested <filterchain> elements.<BR>
+<a href="../CoreTasks/copy.html">Copy</a>,<BR>
+<a href="../CoreTasks/loadfile.html">LoadFile</a>,<BR>
+<a href="../CoreTasks/loadproperties.html">LoadProperties</a>,<BR>
+<a href="../CoreTasks/move.html">Move</a><BR><BR>
+
+A FilterChain is formed by defining zero or more of the following
+nested elements.<BR>
<a href="#filterreader">FilterReader</a><BR>
+<a href="#classconstants">ClassConstants</a><BR>
+<a href="#expandproperties">ExpandProperties</a><BR>
<a href="#headfilter">HeadFilter</a><BR>
<a href="#linecontains">LineContains</a><BR>
+<a href="#linecontainsregexp">LineContainsRegExp</a><BR>
<a href="#prefixlines">PrefixLines</a><BR>
<a href="#replacetokens">ReplaceTokens</a><BR>
<a href="#stripjavacomments">StripJavaComments</a><BR>
@@ -25,12 +101,13 @@
<a href="#tabstospaces">TabsToSpaces</a><BR>
<a href="#tailfilter">TailFilter</a><BR>
-<H2><a name="filterreader">FilterReader</a></H2>
+<H3><a name="filterreader">FilterReader</a></H3>
The filterreader element is the generic way to
-define a filter. User defined filters can be
-used using this. Built in filter readers can also
-be speficied using this.
+define a filter. User defined filter elements are
+defined in the build file using this. Please note that
+built in filter readers can also be defined using this
+syntax.
A FilterReader element must be supplied with a class name as
an attribute value. The class resolved by this name must
@@ -51,11 +128,78 @@
</TR>
</TABLE>
-<p>
+<P>
+<H4>Nested Elements:</H4>
+<filterreader> supports <classpath> and <param>
+as nested elements. Each <param> element may take in the following
+attributes - name, type and value.
+<P>
The following FilterReaders are supplied with the default
distribution.
-<H3>org.apache.tools.ant.filters.<a name="headfilter">HeadFilter</a></H3>
+<H3><a name="classconstants">ClassConstants</a></H3>
+<P>
+This filters basic constants defined in a Java Class,
+and outputs them in lines composed of the format name=value
+<P>
+<H4>Example:</H4>
+
+This loads the basic constants defined in a Java class as Ant properties.
+<BLOCKQUOTE><PRE>
+<loadproperties srcfile="foo.class">
+ <filterchain>
+ <filterreader classname="org.apache.tools.ant.filters.ClassConstants"/>
+ </filterchain>
+</loadproperties>
+</PRE></BLOCKQUOTE>
+
+Convenience method:
+<BLOCKQUOTE><PRE>
+<loadproperties srcfile="foo.class">
+ <filterchain>
+ <classconstants/>
+ </filterchain>
+</loadproperties>
+</PRE></BLOCKQUOTE>
+
+<H3><a name="expandproperties">ExpandProperties</a></H3>
+<P>
+If the data contains data that represents Ant
+properties (of the form ${...}), that is substituted
+with the property's actual value.
+<P>
+<H4>Example:</H4>
+
+This results in the property modifiedmessage holding the value
+"All these moments will be lost in time, like teardrops in the rain"
+<BLOCKQUOTE><PRE>
+<echo
+ message="All these moments will be lost in time, like teardrops in the ${weather}"
+ file="loadfile1.tmp"
+ />
+<property name="weather" value="rain" />
+<loadfile property="modifiedmessage" srcFile="loadfile1.tmp">
+ <filterchain>
+ <filterreader classname="org.apache.tools.ant.filters.ExpandProperties"/>
+ </filterchain>
+</loadfile>
+</PRE></BLOCKQUOTE>
+
+Convenience method:
+<BLOCKQUOTE><PRE>
+<echo
+ message="All these moments will be lost in time, like teardrops in the ${weather}"
+ file="loadfile1.tmp"
+ />
+<property name="weather" value="rain" />
+<loadfile property="modifiedmessage" srcFile="loadfile1.tmp">
+ <filterchain>
+ <expandproperties/>
+ </filterchain>
+</loadfile>
+</PRE></BLOCKQUOTE>
+
+<H3><a name="headfilter">HeadFilter</a></H3>
This filter reads the first few lines from the data supplied to it.
@@ -86,7 +230,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-Short form:
+Convenience method:
<BLOCKQUOTE><PRE>
<loadfile srcfile="${src.file}" property="${src.file.head}">
<filterchain>
@@ -95,7 +239,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-<H3>org.apache.tools.ant.filters.<a name="replacetokens">ReplaceTokens</a></H3>
+<H3><a name="replacetokens">ReplaceTokens</a></H3>
This filter reader replaces all strings that are
sandwiched between begintoken and endtoken with
@@ -146,7 +290,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-Short form:
+Convenience method:
<BLOCKQUOTE><PRE>
<tstamp/>
<loadfile srcfile="${src.file}" property="${src.file.replaced}">
@@ -158,7 +302,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-<H3>org.apache.tools.ant.filters.<a name="stripjavacomments">StripJavaComments</a></H3>
+<H3><a name="stripjavacomments">StripJavaComments</a></H3>
This filter reader strips away comments from the data,
using Java syntax guidelines. This filter does not
@@ -174,7 +318,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-Short form:
+Convenience method:
<BLOCKQUOTE><PRE>
<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">
<filterchain>
@@ -183,7 +327,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-<H3>org.apache.tools.ant.filters.<a name="striplinebreaks">StripLineBreaks</a></H3>
+<H3><a name="striplinebreaks">StripLineBreaks</a></H3>
This filter reader strips away specific characters
from the data supplied to it.
@@ -213,7 +357,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-Short form:
+Convenience method:
<BLOCKQUOTE><PRE>
<loadfile srcfile="${src.file}" property="${src.file.contents}">
<filterchain>
@@ -234,7 +378,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-<H3>org.apache.tools.ant.filters.<a name="tabstospaces">TabToSpaces</a></H3>
+<H3><a name="tabstospaces">TabsToSpaces</a></H3>
This filter replaces tabs with spaces
@@ -263,7 +407,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-Short form:
+Convenience method:
<BLOCKQUOTE><PRE>
<loadfile srcfile="${src.file}" property="${src.file.notab}">
<filterchain>
@@ -272,7 +416,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-<H3>org.apache.tools.ant.filters.<a name="tailfilter">TailFilter</a></H3>
+<H3><a name="tailfilter">TailFilter</a></H3>
This filter reads the last few lines from the data supplied to it.
@@ -303,7 +447,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-Short form:
+Convenience method:
<BLOCKQUOTE><PRE>
<loadfile srcfile="${src.file}" property="${src.file.tail}">
<filterchain>
@@ -328,7 +472,7 @@
</loadfile>
</PRE></BLOCKQUOTE>
-Short form:
+Convenience method:
<BLOCKQUOTE><PRE>
<loadfile srcfile="${src.file}" property="${src.file.mid}">
<filterchain>
1.2 +2 -2 jakarta-ant/proposal/sandbox/filterreaders/src/etc/testcases/taskdefs/loadfile.xml
Index: loadfile.xml
===================================================================
RCS file: /home/cvs/jakarta-ant/proposal/sandbox/filterreaders/src/etc/testcases/taskdefs/loadfile.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- loadfile.xml 4 Mar 2002 01:07:41 -0000 1.1
+++ loadfile.xml 4 Mar 2002 20:48:17 -0000 1.2
@@ -58,7 +58,7 @@
<expandproperties/>
</filterchain>
</loadfile>
- <echo>${testLoadAFile}</echo>
+ <echo>${testEvalProps}</echo>
</target>
@@ -74,7 +74,7 @@
<striplinebreaks/>
</filterchain>
</loadfile>
- <echo>${testLoadAFile}</echo>
+ <echo>${testOneLine}</echo>
</target>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>