From fdcfd1dd9bb5c9182b88de734838338ad9b39bbf Mon Sep 17 00:00:00 2001 From: Magesh Umasankar Date: Mon, 4 Mar 2002 20:48:17 +0000 Subject: [PATCH] Improved doc; loadfile.xml typo fix. git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271724 13f79535-47bb-0310-9956-ffa450edef68 --- .../docs/manual/CoreTypes/filterchain.html | 194 +++++++++++++++--- .../src/etc/testcases/taskdefs/loadfile.xml | 4 +- 2 files changed, 171 insertions(+), 27 deletions(-) diff --git a/proposal/sandbox/filterreaders/docs/manual/CoreTypes/filterchain.html b/proposal/sandbox/filterreaders/docs/manual/CoreTypes/filterchain.html index c1104df2c..6bf995fcc 100644 --- a/proposal/sandbox/filterreaders/docs/manual/CoreTypes/filterchain.html +++ b/proposal/sandbox/filterreaders/docs/manual/CoreTypes/filterchain.html @@ -2,21 +2,97 @@ - FilterChain Type + FilterChains and FilterReaders -

FilterChain

-

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

FilterChains and FilterReaders

+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

+ +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>
+
-Each FilterChain is composed of zero or more of the following nested elements.
+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.

+Example: +

+<loadfile srcfile="${src.file}" property="${src.file.head}">
+  <filterchain>
+    <headfilter lines="15"/>
+  </filterchain>
+</loadfile>
+
+is equivalent to: +
+<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 built-in tasks support nested <filterchain> elements.
+Copy,
+LoadFile,
+LoadProperties,
+Move

+ +A FilterChain is formed by defining zero or more of the following +nested elements.
FilterReader
+ClassConstants
+ExpandProperties
HeadFilter
LineContains
+LineContainsRegExp
PrefixLines
ReplaceTokens
StripJavaComments
@@ -25,12 +101,13 @@ Each FilterChain is composed of zero or more of the following nested elements.TabsToSpaces
TailFilter
-

FilterReader

+

FilterReader

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 @@ org.apache.tools.type.Parameterizable. -

+

+

Nested Elements:

+<filterreader> supports <classpath> and <param> +as nested elements. Each <param> element may take in the following +attributes - name, type and value. +

The following FilterReaders are supplied with the default distribution. -

org.apache.tools.ant.filters.HeadFilter

+

ClassConstants

+

+This filters basic constants defined in a Java Class, +and outputs them in lines composed of the format name=value +

+

Example:

+ +This loads the basic constants defined in a Java class as Ant properties. +
+<loadproperties srcfile="foo.class">
+  <filterchain>
+    <filterreader classname="org.apache.tools.ant.filters.ClassConstants"/>
+  </filterchain>
+</loadproperties>
+
+ +Convenience method: +
+<loadproperties srcfile="foo.class">
+  <filterchain>
+    <classconstants/>
+  </filterchain>
+</loadproperties>
+
+ +

ExpandProperties

+

+If the data contains data that represents Ant +properties (of the form ${...}), that is substituted +with the property's actual value. +

+

Example:

+ +This results in the property modifiedmessage holding the value +"All these moments will be lost in time, like teardrops in the rain" +
+<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>
+
+ +Convenience method: +
+<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>
+
+ +

HeadFilter

This filter reads the first few lines from the data supplied to it. @@ -86,7 +230,7 @@ This stores the first 15 lines of the supplied data in the property ${src.file.h </loadfile> -Short form: +Convenience method: 
 <loadfile srcfile="${src.file}" property="${src.file.head}">
   <filterchain>
@@ -95,7 +239,7 @@ Short form:
 </loadfile>
-

org.apache.tools.ant.filters.ReplaceTokens

+

ReplaceTokens

This filter reader replaces all strings that are sandwiched between begintoken and endtoken with @@ -146,7 +290,7 @@ with today's date and stores it in the property ${src.file.replaced} </loadfile> -Short form: +Convenience method: 
 <tstamp/>
 <loadfile srcfile="${src.file}" property="${src.file.replaced}">
@@ -158,7 +302,7 @@ Short form:
 </loadfile>
-

org.apache.tools.ant.filters.StripJavaComments

+

StripJavaComments

This filter reader strips away comments from the data, using Java syntax guidelines. This filter does not @@ -174,7 +318,7 @@ take in any parameters. </loadfile> -Short form: +Convenience method: 
 <loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">
   <filterchain>
@@ -183,7 +327,7 @@ Short form:
 </loadfile>
-

org.apache.tools.ant.filters.StripLineBreaks

+

StripLineBreaks

This filter reader strips away specific characters from the data supplied to it. @@ -213,7 +357,7 @@ This strips the '\r' and '\n' characters. </loadfile> -Short form: +Convenience method: 
 <loadfile srcfile="${src.file}" property="${src.file.contents}">
   <filterchain>
@@ -234,7 +378,7 @@ strips them.
 </loadfile>
-

org.apache.tools.ant.filters.TabToSpaces

+

TabsToSpaces

This filter replaces tabs with spaces @@ -263,7 +407,7 @@ This replaces tabs in ${src.file} with spaces. </loadfile> -Short form: +Convenience method: 
 <loadfile srcfile="${src.file}" property="${src.file.notab}">
   <filterchain>
@@ -272,7 +416,7 @@ Short form:
 </loadfile>
-

org.apache.tools.ant.filters.TailFilter

+

TailFilter

This filter reads the last few lines from the data supplied to it. @@ -303,7 +447,7 @@ This stores the last 15 lines of the supplied data in the property ${src.file.ta </loadfile> -Short form: +Convenience method: 
 <loadfile srcfile="${src.file}" property="${src.file.tail}">
   <filterchain>
@@ -328,7 +472,7 @@ data in the property ${src.file.mid}
 </loadfile>
-Short form: +Convenience method: 
 <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}