FilterChains are groups of ordered FilterReaders. FilterChains can appear
-inside tasks that support this feature.
FilterChains are used for
-filtering file contents read in by tasks like
-LoadFile, LoadProperties, etc.
+
+
+cat foo|head -n10|grep blee > bar
+
+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:
+
+<copy file="foo" tofile="bar" head="10" contains="blee"/>
+
+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.
+ +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. +
+Example: +
+<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>
++Example: +
+<loadfile srcfile="${src.file}" property="${src.file.head}">
+ <filterchain>
+ <headfilter lines="15"/>
+ </filterchain>
+</loadfile>
+
+<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>
++
+
The following FilterReaders are supplied with the default distribution. -
+This filters basic constants defined in a Java Class, +and outputs them in lines composed of the format name=value +
+
+ +Convenience method: ++<loadproperties srcfile="foo.class"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.ClassConstants"/> + </filterchain> +</loadproperties> +
+ ++<loadproperties srcfile="foo.class"> + <filterchain> + <classconstants/> + </filterchain> +</loadproperties> +
+If the data contains data that represents Ant +properties (of the form ${...}), that is substituted +with the property's actual value. +
+
+<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>
+
+<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>
+
<loadfile srcfile="${src.file}" property="${src.file.head}">
<filterchain>
@@ -95,7 +239,7 @@ Short form:
</loadfile>
<tstamp/>
<loadfile srcfile="${src.file}" property="${src.file.replaced}">
@@ -158,7 +302,7 @@ Short form:
</loadfile>
<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">
<filterchain>
@@ -183,7 +327,7 @@ Short form:
</loadfile>
<loadfile srcfile="${src.file}" property="${src.file.contents}">
<filterchain>
@@ -234,7 +378,7 @@ strips them.
</loadfile>
<loadfile srcfile="${src.file}" property="${src.file.notab}">
<filterchain>
@@ -272,7 +416,7 @@ Short form:
</loadfile>
<loadfile srcfile="${src.file}" property="${src.file.tail}">
<filterchain>
@@ -328,7 +472,7 @@ data in the property ${src.file.mid}
</loadfile>
<loadfile srcfile="${src.file}" property="${src.file.mid}">
<filterchain>
diff --git a/proposal/sandbox/filterreaders/src/etc/testcases/taskdefs/loadfile.xml b/proposal/sandbox/filterreaders/src/etc/testcases/taskdefs/loadfile.xml
index 6d2874684..11ddfe98d 100644
--- a/proposal/sandbox/filterreaders/src/etc/testcases/taskdefs/loadfile.xml
+++ b/proposal/sandbox/filterreaders/src/etc/testcases/taskdefs/loadfile.xml
@@ -58,7 +58,7 @@
${testLoadAFile}
+ ${testEvalProps}
@@ -74,7 +74,7 @@
${testLoadAFile}
+ ${testOneLine}