From 0beb8afac01a9c02f4cb3e24307e588e29acd7d1 Mon Sep 17 00:00:00 2001 From: Magesh Umasankar Date: Thu, 7 Mar 2002 03:09:59 +0000 Subject: [PATCH] Missed adding Filter Chain earlier. git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271784 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/CoreTypes/filterchain.html | 488 +++++++++++++++++++++++++ 1 file changed, 488 insertions(+) create mode 100644 docs/manual/CoreTypes/filterchain.html diff --git a/docs/manual/CoreTypes/filterchain.html b/docs/manual/CoreTypes/filterchain.html new file mode 100644 index 000000000..6bf995fcc --- /dev/null +++ b/docs/manual/CoreTypes/filterchain.html @@ -0,0 +1,488 @@ + + + + + FilterChains and FilterReaders + + + + +

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>
+
+ +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
+StripLineBreaks
+StripLineComments
+TabsToSpaces
+TailFilter
+ +

FilterReader

+ +The filterreader element is the generic way to +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 +extend java.io.FilterReader. If the custom filter reader +needs to be parameterized, it must implement +org.apache.tools.type.Parameterizable. + + + + + + + + + + + + +
AttributeDescriptionRequired
classnameThe class name of the filter reader.Yes
+ +

+

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

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. + + + + + + + + + + + + +
Parameter NameParameter ValueRequired
linesNumber of lines to be read. + Defaults to "10"No
+

+

Example:

+ +This stores the first 15 lines of the supplied data in the property ${src.file.head} +
+<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>
+
+ +Convenience method: +
+<loadfile srcfile="${src.file}" property="${src.file.head}">
+  <filterchain>
+    <headfilter lines="15"/>
+  </filterchain>
+</loadfile>
+
+ +

ReplaceTokens

+ +This filter reader replaces all strings that are +sandwiched between begintoken and endtoken with +user defined values. + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter TypeParameter NameParameter ValueRequired
tokencharbegintokenCharacter marking the + beginning of a token. Defaults to @No
tokencharendtokenCharacter marking the + end of a token. Defaults to @No
tokenUser defined String.User defined search StringYes
+

+ +

Example:

+ +This replaces occurences of the string @DATE@ in the data +with today's date and stores it in the property ${src.file.replaced} +
+<tstamp/>
+<loadfile srcfile="${src.file}" property="${src.file.replaced}">
+  <filterchain>
+    <filterreader classname="org.apache.tools.ant.filters.ReplaceTokens">
+      <param type="token" name="DATE" value="${TODAY}"/>
+    </filterreader>
+  </filterchain>
+</loadfile>
+
+ +Convenience method: +
+<tstamp/>
+<loadfile srcfile="${src.file}" property="${src.file.replaced}">
+  <filterchain>
+    <replacetokens>
+      <token key="DATE" value="${TODAY}"/>
+    </replacetokens>
+  </filterchain>
+</loadfile>
+
+ +

StripJavaComments

+ +This filter reader strips away comments from the data, +using Java syntax guidelines. This filter does not +take in any parameters. +

+

Example:

+ +
+<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">
+  <filterchain>
+    <filterreader classname="org.apache.tools.ant.filters.StripJavaComments"/>
+  </filterchain>
+</loadfile>
+
+ +Convenience method: +
+<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">
+  <filterchain>
+    <stripjavacomments/>
+  </filterchain>
+</loadfile>
+
+ +

StripLineBreaks

+ +This filter reader strips away specific characters +from the data supplied to it. + + + + + + + + + + + + +
Parameter NameParameter ValueRequired
linebreaksCharacters that are to + be stripped out. Defaults to "\r\n"No
+

+

Examples:

+ +This strips the '\r' and '\n' characters. +
+<loadfile srcfile="${src.file}" property="${src.file.contents}">
+  <filterchain>
+    <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"/>
+  </filterchain>
+</loadfile>
+
+ +Convenience method: +
+<loadfile srcfile="${src.file}" property="${src.file.contents}">
+  <filterchain>
+    <striplinebreaks/>
+  </filterchain>
+</loadfile>
+
+ +This treats the '(' and ')' characters as line break characters and +strips them. +
+<loadfile srcfile="${src.file}" property="${src.file.contents}">
+  <filterchain>
+    <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks">
+      <param name="linebreaks" value="()"/>
+    </filterreader>
+  </filterchain>
+</loadfile>
+
+ +

TabsToSpaces

+ +This filter replaces tabs with spaces + + + + + + + + + + + + +
Parameter NameParameter ValueRequired
linestablength + Defaults to "8"No
+

+

Examples:

+ +This replaces tabs in ${src.file} with spaces. +
+<loadfile srcfile="${src.file}" property="${src.file.notab}">
+  <filterchain>
+    <filterreader classname="org.apache.tools.ant.filters.TabsToSpaces"/>
+  </filterchain>
+</loadfile>
+
+ +Convenience method: +
+<loadfile srcfile="${src.file}" property="${src.file.notab}">
+  <filterchain>
+    <tabstospaces/>
+  </filterchain>
+</loadfile>
+
+ +

TailFilter

+ +This filter reads the last few lines from the data supplied to it. + + + + + + + + + + + + +
Parameter NameParameter ValueRequired
linesNumber of lines to be read. + Defaults to "10"No
+

+

Examples:

+ +This stores the last 15 lines of the supplied data in the property ${src.file.tail} +
+<loadfile srcfile="${src.file}" property="${src.file.tail}">
+  <filterchain>
+    <filterreader classname="org.apache.tools.ant.filters.TailFilter">
+      <param name="lines" value="15"/>
+    </filterreader>
+  </filterchain>
+</loadfile>
+
+ +Convenience method: +
+<loadfile srcfile="${src.file}" property="${src.file.tail}">
+  <filterchain>
+    <tailfilter lines="15"/>
+  </filterchain>
+</loadfile>
+
+ + +This stores the last 5 lines of the first 15 lines of the supplied +data in the property ${src.file.mid} +
+<loadfile srcfile="${src.file}" property="${src.file.mid}">
+  <filterchain>
+    <filterreader classname="org.apache.tools.ant.filters.HeadFilter">
+      <param name="lines" value="15"/>
+    </filterreader>
+    <filterreader classname="org.apache.tools.ant.filters.TailFilter">
+      <param name="lines" value="5"/>
+    </filterreader>
+  </filterchain>
+</loadfile>
+
+ +Convenience method: +
+<loadfile srcfile="${src.file}" property="${src.file.mid}">
+  <filterchain>
+    <HeadFilter lines="15"/>
+    <TailFilter lines="5"/>
+  </filterchain>
+</loadfile>
+
+ +
+ +

Copyright © 2002 Apache Software Foundation. All rights +Reserved.