+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:
+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 accommodate such data transformation attributes as they would be endless. The task would also not know in which order these @@ -31,7 +31,7 @@ contains attribute first and then the head attribute or vice-versa? What Ant tasks needed was a mechanism to allow pluggable filter (data transformer) 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.
+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
@@ -39,9 +39,9 @@ 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: -
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.++<copy file="${src.file}" tofile="${dest.file}"> <filterchain> <filterreader classname="your.extension.of.java.io.FilterReader"> @@ -56,21 +56,21 @@ Example: </filterreader> </filterchain> </copy> -
+However, they can be declared using some simpler syntax also.
Example: -
is equivalent to: -++<loadfile srcfile="${src.file}" property="${src.file.head}"> <filterchain> <headfilter lines="15"/> </filterchain> </loadfile> -
-The following built-in tasks support nested++<loadfile srcfile="${src.file}" property="${src.file.head}"> <filterchain> <filterreader classname="org.apache.tools.ant.filters.HeadFilter"> @@ -78,36 +78,36 @@ is equivalent to: </filterreader> </filterchain> </loadfile> -
<filterchain> elements.<filterchain> elements.| Attribute | -Description | -Required | -
| classname | -The class name of the filter reader. | -Yes | -
-
| Attribute | +Description | +Required | +
| classname | +The class name of the filter reader. | +Yes | +
+
<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. -
+
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> -
+
This filter converts its input by changing all non US-ASCII characters into their equivalent unicode escape backslash u plus 4 digits.
-since Ant 1.6
+since Ant 1.6
-Convenience method: -++<loadproperties srcfile="non_ascii_property.properties"> <filterchain> <filterreader classname="org.apache.tools.ant.filters.EscapeUnicode"/> </filterchain> </loadproperties> -
-++<loadproperties srcfile="non_ascii_property.properties"> <filterchain> <escapeunicode/> </filterchain> </loadproperties> -
+
If the data contains data that represents Ant properties (of the form ${...}), that is substituted with the property's actual value. -
-
+
Convenience method: -++<echo message="All these moments will be lost in time, like teardrops in the ${weather}" file="loadfile1.tmp" @@ -216,10 +216,10 @@ This results in the property modifiedmessage holding the value <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" @@ -230,37 +230,37 @@ Convenience method: <expandproperties/> </filterchain> </loadfile> -
| Parameter Name | -Parameter Value | -Required | -
| lines | -Number of lines to be read.
- Defaults to "10" A negative value means that all lines are - passed (useful with skip) |
- No | -
| skip | -Number of lines to be skipped (from the beginning). - Defaults to "0" | -No | -
-
| Parameter Name | +Parameter Value | +Required | +
| lines | +Number of lines to be read.
+ Defaults to "10" A negative value means that all lines are + passed (useful with skip) |
+ No | +
| skip | +Number of lines to be skipped (from the beginning). + Defaults to "0" | +No | +
+
Convenience method: -++<loadfile srcfile="${src.file}" property="${src.file.head}"> <filterchain> <filterreader classname="org.apache.tools.ant.filters.HeadFilter"> @@ -268,162 +268,162 @@ This stores the first 15 lines of the supplied data in the property ${src.file.h </filterreader> </filterchain> </loadfile> -
This stores the first 15 lines, skipping the first 2 lines, of the supplied data in the property ${src.file.head}. (Means: lines 3-17) -++<loadfile srcfile="${src.file}" property="${src.file.head}"> <filterchain> <headfilter lines="15"/> </filterchain> </loadfile> -
-See the testcases for more examples (src\etc\testcases\filters\head-tail.xml in the +See the testcases for more examples (src\etc\testcases\filters\head-tail.xml in the source distribution). -++<loadfile srcfile="${src.file}" property="${src.file.head}"> <filterchain> <headfilter lines="15" skip="2"/> </filterchain> </loadfile> -
| Parameter Type | -Parameter Value | -Required | -
| contains | -Substring to be searched for. | -Yes | -
-
| Parameter Type | +Parameter Value | +Required | +
| contains | +Substring to be searched for. | +Yes | +
+
foo and
bar.
-Convenience method: -++<filterreader classname="org.apache.tools.ant.filters.LineContains"> <param type="contains" value="foo"/> <param type="contains" value="bar"/> </filterreader> -
-++<linecontains> <contains value="foo"/> <contains value="bar"/> </linecontains> -
foo
-Convenience method: -++<filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp"> <param type="regexp" value="foo*"/> </filterreader> -
-++<linecontainsregexp> <regexp pattern="foo*"/> </linecontainsregexp> -
| Parameter Name | -Parameter Value | -Required | -
| prefix | -Prefix to be attached to lines. | -Yes | -
-
| Parameter Name | +Parameter Value | +Required | +
| prefix | +Prefix to be attached to lines. | +Yes | +
+
Foo to all lines.
-Convenience method: -++<filterreader classname="org.apache.tools.ant.filters.PrefixLines"> <param name="prefix" value="Foo"/> </filterreader> -
-++<prefixlines prefix="Foo"/> -
| Parameter Type | -Parameter Name | -Parameter Value | -Required | -
| tokenchar | -begintoken | -Character marking the - beginning of a token. Defaults to @ | -No | -
| tokenchar | -endtoken | -Character marking the - end of a token. Defaults to @ | -No | -
| token | -User defined String. | -User defined search String | -Yes | -
- -
| Parameter Type | +Parameter Name | +Parameter Value | +Required | +
| tokenchar | +begintoken | +Character marking the + beginning of a token. Defaults to @ | +No | +
| tokenchar | +endtoken | +Character marking the + end of a token. Defaults to @ | +No | +
| token | +User defined String. | +User defined search String | +Yes | +
+ +
Convenience method: -++<tstamp/> <loadfile srcfile="${src.file}" property="${src.file.replaced}"> <filterchain> @@ -432,10 +432,10 @@ with today's date and stores it in the property ${src.file.replaced} </filterreader> </filterchain> </loadfile> -
-++<tstamp/> <loadfile srcfile="${src.file}" property="${src.file.replaced}"> <filterchain> @@ -444,75 +444,75 @@ Convenience method: </replacetokens> </filterchain> </loadfile> -
-
+
Convenience method: -++<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}"> <filterchain> <filterreader classname="org.apache.tools.ant.filters.StripJavaComments"/> </filterchain> </loadfile> -
-++<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}"> <filterchain> <stripjavacomments/> </filterchain> </loadfile> -
| Parameter Name | -Parameter Value | -Required | -
| linebreaks | -Characters that are to - be stripped out. Defaults to "\r\n" | -No | -
-
| Parameter Name | +Parameter Value | +Required | +
| linebreaks | +Characters that are to + be stripped out. Defaults to "\r\n" | +No | +
+
Convenience method: -++<loadfile srcfile="${src.file}" property="${src.file.contents}"> <filterchain> <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"/> </filterchain> </loadfile> -
This treats the '(' and ')' characters as line break characters and strips them. -++<loadfile srcfile="${src.file}" property="${src.file.contents}"> <filterchain> <striplinebreaks/> </filterchain> </loadfile> -
-++<loadfile srcfile="${src.file}" property="${src.file.contents}"> <filterchain> <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"> @@ -520,31 +520,31 @@ strips them. </filterreader> </filterchain> </loadfile> -
| Parameter Type | -Parameter Value | -Required | -
| comment | -Strings that identify a line as a comment - when they appear at the start of the line. | -Yes | -
-
| Parameter Type | +Parameter Value | +Required | +
| comment | +Strings that identify a line as a comment + when they appear at the start of the line. | +Yes | +
+
Convenience method: -++<filterreader classname="org.apache.tools.ant.filters.StripLineComments"> <param type="comment" value="#"/> <param type="comment" value="--"/> @@ -552,10 +552,10 @@ This removes all lines that begin with #, --, REM, rem and // <param type="comment" value="rem "/> <param type="comment" value="//"/> </filterreader> -
-++<striplinecomments> <comment value="#"/> <comment value="--"/> @@ -563,166 +563,166 @@ Convenience method: <comment value="rem "/> <comment value="//"/> </striplinecomments> -
| Parameter Name | -Parameter Value | -Required | -
| tablength | -Defaults to "8" | -No | -
-
| Parameter Name | +Parameter Value | +Required | +
| tablength | +Defaults to "8" | +No | +
+
Convenience method: -++<loadfile srcfile="${src.file}" property="${src.file.notab}"> <filterchain> <filterreader classname="org.apache.tools.ant.filters.TabsToSpaces"/> </filterchain> </loadfile> -
-++<loadfile srcfile="${src.file}" property="${src.file.notab}"> <filterchain> <tabstospaces/> </filterchain> </loadfile> -
| Parameter Name | -Parameter Value | -Required | -
| lines | -Number of lines to be read.
- Defaults to "10" A negative value means that all lines are - passed (useful with skip) |
- No | -
| skip | -Number of lines to be skipped (from the end). - Defaults to "0" | -No | -
- -
| Parameter Name | +Parameter Value | +Required | +
| lines | +Number of lines to be read.
+ Defaults to "10" A negative value means that all lines are + passed (useful with skip) |
+ No | +
| skip | +Number of lines to be skipped (from the end). + Defaults to "0" | +No | +
+ +
| Content | -- | - | - | Filter | -||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Line 1 | -- | - | - |
-
|
+||||||||||||||||||||||||||||||||||||||||||||
| Line 2 | +||||||||||||||||||||||||||||||||||||||||||||||||
| Line 3 | ++ | |||||||||||||||||||||||||||||||||||||||||||||||
| Line 4 | +||||||||||||||||||||||||||||||||||||||||||||||||
| Line 5 | ++ | |||||||||||||||||||||||||||||||||||||||||||||||
| Lines ... | +||||||||||||||||||||||||||||||||||||||||||||||||
| Line 95 | +||||||||||||||||||||||||||||||||||||||||||||||||
| Line 96 | ++ | |||||||||||||||||||||||||||||||||||||||||||||||
| Line 97 | +||||||||||||||||||||||||||||||||||||||||||||||||
| Line 98 | ++ | |||||||||||||||||||||||||||||||||||||||||||||||
| Line 99 | +
Convenience method: -++<loadfile srcfile="${src.file}" property="${src.file.tail}"> <filterchain> <filterreader classname="org.apache.tools.ant.filters.TailFilter"> @@ -730,21 +730,21 @@ This stores the last 15 lines of the supplied data in the property ${src.file.ta </filterreader> </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.tail}"> <filterchain> <tailfilter lines="15"/> </filterchain> </loadfile> -
Convenience method: -++<loadfile srcfile="${src.file}" property="${src.file.mid}"> <filterchain> <filterreader classname="org.apache.tools.ant.filters.HeadFilter"> @@ -755,114 +755,114 @@ data in the property ${src.file.mid} </filterreader> </filterchain> </loadfile> -
This stores the last 10 lines, skipping the last 2 lines, of the supplied data in the property ${src.file.head}. (Means: if supplied data contains 60 lines, lines 49-58 are extracted) -++<loadfile srcfile="${src.file}" property="${src.file.mid}"> <filterchain> <headfilter lines="15"/> <tailfilter lines="5"/> </filterchain> </loadfile> -
-++<loadfile srcfile="${src.file}" property="${src.file.head}"> <filterchain> <tailfilter lines="10" skip="2"/> </filterchain> </loadfile> -
This filter deletes specified characters.
since Ant 1.6
This filter is only available in the convenience form.
-| Parameter Name | -Parameter Value | -Required | -||||||
| chars | -
+
- Examples:+ |
+ Yes | +
+
-++<deletecharacters chars="\t\r"/> -
This filter prepends or appends the content file to the filtered files.
since Ant 1.6
-| Parameter Name | -Parameter Value | -Required | -||||||||||||
| prepend | -
+
+ |
+ No | +
-
Adds a license text before each java source: -++<filterchain> <concatfilter/> </filterchain> -
-++<filterchain> <concatfilter prepend="apache-license-java.txt"/> </filterchain> -
since Ant 1.6
-+
since Ant 1.6
+Only one tokenizer element may be used, the LineTokenizer is the default if none are specified. A tokenizer splits the input into token strings and trailing delimiter strings. -
+
There may be zero or more string filters. A string filter processes a token and either returns a string or a null. It the string is not null it is passed to the next filter. This @@ -872,30 +872,30 @@ outputs with its associated token delimitier (if one is present). The trailing delimiter may be overridden by the delimOutput attribute. -
+
blackslash interpretation A number of attributes (including delimOutput) interpret backslash escapes. The following are understood: \n, \r, \f, \t and \\. -
| Attribute | -Description | -Required | -||||||
| delimOutput | -
+
+ |
+ No | +
The following tokenizers are provided by the default distribution.
@@ -925,58 +925,58 @@ case a tokenfilter is created implicitly. An extra attribute "byline" is added to the filter to specify whether to use a linetokenizer (byline="true") or a filetokenizer (byline="false"). The default is "true". -
+
This tokenizer splits the input into lines. The tokenizer delimits lines by "\r", "\n" or "\r\n". This is the default tokenizer. -
| Attribute | -Description | -Required | -||||||
| includeDelims | -
+
Examples:+ |
+ No | +
Remove blank lines. -++<tokenfilter delimoutput="\n"/> -
This tokenizer treats all the input as a token. So be careful not to use this on very large input. -++<tokenfilter> <ignoreblank/> </tokenfilter> -
This tokenizer is based on java.util.StringTokenizer. @@ -986,20 +986,20 @@ If the stream starts with delimiter characters, the first token will be the empty string (unless the delimsaretokens attribute is used). -++<tokenfilter> <filetokenizer/> <replaceregex pattern="([\n\r]+[ \t]*|^[ \t]*)package" flags="s" replace="\1//package"/> </tokenfilter> -
| Attribute | -Description | -Required | -|||||||||
| delims | -The delimiter characters. White space
+
|
This is a simple filter to replace strings. This filter may be used directly within a filterchain. -++<tokenfilter> <stringtokenizer/> <replaceregex pattern="(.+)" replace="[\1]"/> </tokenfilter> -
| Attribute | -Description | -Required | -
| from | -The string that must be replaced. | -Yes | -
| Attribute | +Description | +Required | +
| from | +The string that must be replaced. | +Yes | +
| to | The new value for the replaced string. When omitted @@ -1060,45 +1060,45 @@ This filter may be used directly within a filterchain. | No |
This is a simple filter to filter tokens that contains a specified string. -++<tokenfilter> <replacestring from="sun" to="moon"/> </tokenfilter> -
| Attribute | -Description | -Required | -
| contains | -The string that the token must contain. | -Yes | -
| Attribute | +Description | +Required | +
| contains | +The string that the token must contain. | +Yes | +
This string filter replaces regular expressions. @@ -1108,42 +1108,42 @@ This filter may be used directly within a filterchain. concerning the choice of the implementation. -++<tokenfilter> <containsstring contains="foo"/> </tokenfilter> -
| Attribute | -Description | -Required | -||||||||||||
| pattern | -The regular expression pattern to match in - the token. | -Yes | -||||||||||||
| replace | -The substitution pattern to replace the matched - regular expression. When omitted an empty string is used. | -No | -||||||||||||
| flags | -See
+
Examples:+for an explanation of regex flags. |
+ No | +
This filters strings that match regular expressions. @@ -1154,55 +1154,55 @@ See Regexp Type concerning the choice of regular expression implementation. -++<tokenfilter> <replaceregex pattern="hello" replace="world" flags="gi"/> </tokenfilter> -
| Attribute | -Description | -Required | -|||||||||||||||
| pattern | -The regular expression pattern to match in - the token. | -Yes | -|||||||||||||||
| replace | -The substitution pattern to replace the matched
+
|
+ No | +
This example replaces lines like "SUITE(TestSuite, bits);" with "void register_bits();" and removes other lines. -++<tokenfilter> <containsregex pattern="(hello|world)" flags="i"/> </tokenfilter> -
This filter trims whitespace from the start and end of @@ -1214,32 +1214,32 @@ This filter may be used directly within a filterchain. This filter deletes specified characters from tokens. -++<tokenfilter> <containsregex pattern="^ *SUITE\(.*,\s*(.*)\s*\).*" replace="void register_\1();"/> </tokenfilter> -
| Attribute | -Description | -Required | -
| chars | -The characters to delete. This attribute - is backslash enabled. | -Yes | -
| Attribute | +Description | +Required | +
| chars | +The characters to delete. This attribute + is backslash enabled. | +Yes | +
This is an optional filter that executes a script in a @@ -1256,37 +1256,37 @@ method replaces the current token. This filter may be used directly within a filterchain.++<tokenfilter> <deletecharacters chars="\t"/> <trim/> <ignoreblank/> </tokenfilter> -
-
| Attribute | -Description | -Required | -
| language | -The programming language the script is written in. -Must be a supported Apache BSF language | -Yes | -
| src | -The location of the script as a file, if not inline - | -No | -
| Attribute | +Description | +Required | +
| language | +The programming language the script is written in. +Must be a supported Apache BSF language | +Yes | +
| src | +The location of the script as a file, if not inline + | +No | +
Remove lines containing the string "bad" while copying text files: @@ -1303,7 +1303,7 @@ copying text files: -++<tokenfilter> <scriptfilter language="javascript"> self.setToken(self.getToken().toUpperCase()); </scriptfilter> </tokenfilter> -
Copyright © 2002-2005 The Apache Software Foundation. All rights -Reserved.
+Copyright © 2002-2005 The Apache Software Foundation. All rights +Reserved.