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.
Concat,
Copy,
LoadFile,
LoadProperties,
Move

A FilterChain is formed by defining zero or more of the following nested elements.
FilterReader
ClassConstants
EscapeUnicode
ExpandProperties
HeadFilter
LineContains
LineContainsRegExp
PrefixLines
ReplaceTokens
StripJavaComments
StripLineBreaks
StripLineComments
TabsToSpaces
TailFilter
DeleteCharacters
ConcatFilter
TokenFilter

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.
Attribute Description Required
classname The 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>

EscapeUnicode

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

Example:

This loads the basic constants defined in a Java class as Ant properties. 
<loadproperties srcfile="non_ascii_property.properties">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.EscapeUnicode"/>
  </filterchain>
</loadproperties>
Convenience method: 
<loadproperties srcfile="non_ascii_property.properties">
  <filterchain>
    <escapeunicode/>
  </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 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

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>
This stores the first 15 lines, skipping the first 2 lines, of the supplied data in the porperty ${src.file.head}. (Means: lines 3-17) 
<loadfile srcfile="${src.file}" property="${src.file.head}">
  <filterchain>
    <headfilter lines="15" skip="2"/>
  </filterchain>
</loadfile>
See the testcases for more examples (src\etc\testcases\filters\head-tail.xml in the source distribution).

LineContains

This filter includes only those lines that contain all the user-specified strings.
Parameter Type Parameter Value Required
contains Substring to be searched for. Yes

Example:

This will include only those lines that contain foo and bar. 
<filterreader classname="org.apache.tools.ant.filters.LineContains">
  <param type="contains" value="foo"/>
  <param type="contains" value="bar"/>
</filterreader>
Convenience method: 
<linecontains>
  <contains value="foo">
  <contains value="bar">
</linecontains>

LineContainsRegExp

Filter which includes only those lines that contain the user-specified regular expression matching strings.
Parameter Type Parameter Value Required
regexp Pattern of the substring to be searched for. Yes

Example:

This will fetch all those lines that contain the pattern foo 
<filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp">
  <param type="regexp" value="foo*"/>
</filterreader>
Convenience method: 
<linecontainsregexp>
  <regexp pattern="foo*">
</linecontainsregexp>

PrefixLines

Attaches a prefix to every line.
Parameter Name Parameter Value Required
prefix Prefix to be attached to lines. Yes

Example:

This will attach the prefix Foo to all lines. 
<filterreader classname="org.apache.tools.ant.filters.PrefixLines">
  <param name="prefix" value="Foo"/>
</filterreader>
Convenience method: 
<prefixlines prefix="Foo"/>

ReplaceTokens

This filter reader replaces all strings that are sandwiched between begintoken and endtoken with user defined values.
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

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 Name Parameter Value Required
linebreaks Characters 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>

StripLineComments

This filter removes all those lines that begin with strings that represent comments as specified by the user.
Parameter Type Parameter Value Required
comment Strings that identify a line as a comment when they appear at the start of the line. Yes

Examples:

This removes all lines that begin with #, --, REM, rem and // 
<filterreader classname="org.apache.tools.ant.filters.StripLineComments">
  <param type="comment" value="#"/>
  <param type="comment" value="--"/>
  <param type="comment" value="REM "/>
  <param type="comment" value="rem "/>
  <param type="comment" value="//"/>
</filterreader>
Convenience method: 
<striplinecomments>
  <comment value="#"/>
  <comment value="--"/>
  <comment value="REM "/>
  <comment value="rem "/>
  <comment value="//"/>
</striplinecomments>

TabsToSpaces

This filter replaces tabs with spaces
Parameter Name Parameter Value Required
lines tablength 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 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

Background:

With HeadFilter and TailFilter you can extract each part of a text file you want. This graphic shows the dependencies:
Content Filter
Line 1      
  
<filterchain>
    <headfilter lines="2"/>
</filterchain>
  
<filterchain>
    <tailfilter lines="-1" skip="2"/>
</filterchain>
  
<filterchain>
    <headfilter lines="-1" skip="2"/>
</filterchain>
  
<filterchain>
    <headfilter lines="-1" skip="2"/>
    <tailfilter lines="-1" skip="2"/>
</filterchain>
  
<filterchain>
    <tailfilter lines="2"/>
</filterchain>
Line 2
Line 3  
Line 4
Line 5  
Lines ...
Line 95
Line 96  
Line 97
Line 98  
Line 99

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>
This stores the last 10 lines, skipping the last 2 lines, of the supplied data in the porperty ${src.file.head}. (Means: if supplied data contains 60 lines, lines 49-58 are extracted) 
<loadfile srcfile="${src.file}" property="${src.file.head}">
  <filterchain>
    <tailfilter lines="10" skip="2"/>
  </filterchain>
</loadfile>

DeleteCharacters

This filter deletes specified characters.

since Ant 1.6

This filter is only available in the convenience form.

Parameter Name Parameter Value Required
chars The characters to delete. This attribute is backslash enabled. Yes

Examples:

Delete tabs and returns from the data. 
<deletecharacters chars="\t\r"/>

ConcatFilter

This filter prepends or appends the content file to the filtered files.

since Ant 1.6

Parameter Name Parameter Value Required
prepend The name of the file which content should be prepended to the file. No
append The name of the file which content should be appended to the file. No

Examples:

Do nothing: 
<filterchain>
    <concatfilter/>
</filterchain>
Adds a license text before each java source: 
<filterchain>
    <concatfilter prepend="apache-license-java.txt"/>
</filterchain>

TokenFilter

This filter tokenizes the inputstream into strings and passes these strings to filters of strings. Unlike the other filterreaders, this does not support params, only convenience methods are implemented. The tokenizer and the string filters are defined by nested elements.

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 proceeds until all the filters are called. If a string is returned after all the filters, the string is 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 This overrides the tokendelimiter returned by the tokenizer if it is not empty. This attribute is backslash enabled. No

The following tokenizers are provided by the default distribution.

LineTokenizer
FileTokenizer
StringTokenizer

The following string filters are provided by the default distribution.

ReplaceString
ContainsString
ReplaceRegex
ContainsRegex
Trim
IgnoreBlank
DeleteCharacters

The following string filters are provided by the optional distribution.

ScriptFilter

Some of the filters may be used directly within a filter chain. In this 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".

LineTokenizer

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 Include the line endings in the token. Default is false. No

Examples:

Convert input current line endings to unix style line endings. 
<tokenfilter delimoutput="\n"/>
Remove blank lines. 
<tokenfilter>
    <ignoreblank/>
</tokenfilter>

FileTokenizer

This tokenizer treats all the input as a token. So be careful not to use this on very large input.

Examples:

Replace the first occurance of package with //package. 
<tokenfilter>
      <filetokenizer/>
      <replaceregex pattern="([\n\r]+[ \t]*|^[ \t]*)package"
                    flags="s"
                    replace="\1//package"/>
</tokenfilter>

StringTokenizer

This tokenizer is based on java.util.StringTokenizer. It splits up the input into strings separated by white space, or by a specified list of delimiting characters. If the stream starts with delimiter characters, the first token will be the empty string (unless the delimsaretokens attribute is used).
Attribute Description Required
delims The delimiter characters. White space is used if this is not set. (White space is defined in this case by java.lang.Character.isWhitespace()). No
delimsaretokens If this is true, each delimiter character is returned as a token. Default is false. No
suppressdelims If this is true, delimiters are not returned. Default is false. No
includeDelims Include the delimiters in the token. Default is false. No

Examples:

Surround each non space token with a "[]". 
<tokenfilter>
    <stringtokenizer/>
    <replaceregex pattern="(.+)" replace="[\1]"/>
</tokenfilter>

ReplaceString

This is a simple filter to replace strings. This filter may be used directly within a filterchain.
Attribute Description Required
from The string that must be replaced. Yes
to The new value for the replaced string. When omitted an empty string is used. No

Examples:

Replace "sun" with "moon". 
<tokenfilter>
    <replacestring from="sun" to="moon"/>
</tokenfilter>

ContainsString

This is a simple filter to filter tokens that contains a specified string.
Attribute Description Required
contains The string that the token must contain. Yes

Examples:

Include only lines that contain "foo"; 
<tokenfilter>
    <containsstring contains="foo"/>
</tokenfilter>

ReplaceRegex

This string filter replaces regular expressions. See ReplaceRegexp for an explanation on regular expressions. This filter may be used directly within a filterchain.
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 ReplaceRegexp for an explanation of regex flags. No

Examples:

Replace all occurances of "hello" with "world", ignoring case. 
<tokenfilter>
    <replaceregex pattern="hello" replace="world" flags="gi"/>
</tokenfilter>

ContainsRegex

This filters strings that match regular expressions. The filter may optionally replace the matched regular expression. See ReplaceRegexp for an explanation on regular expressions. This filter may be used directly within a filterchain.
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 the orignal token is returned. No
flags See ReplaceRegexp for an explanation of regex flags. No

Examples:

Filter lines that contain "hello" or "world", ignoring case. 
<tokenfilter>
    <containsregex pattern="(hello|world)" flags="i"/>
</tokenfilter>
This example replaces lines like "SUITE(TestSuite, bits);" with "void register_bits();" and removes other lines. 
<tokenfilter>
    <containsregex
        pattern="^ *SUITE\(.*,\s*(.*)\s*\).*"
        replace="void register_\1();"/>
</tokenfilter>

Trim

This filter trims whitespace from the start and end of tokens. This filter may be used directly within a filterchain.

IgnoreBlank

This filter removes empty tokens. This filter may be used directly within a filterchain.

DeleteCharacters

This filter deletes specified characters from tokens.
Attribute Description Required
chars The characters to delete. This attribute is backslash enabled. Yes

Examples:

Delete tabs from lines, trim the lines and removes empty lines. 
<tokenfilter>
    <deletecharacters chars="\t"/>
    <trim/>
    <ignoreblank/>
</tokenfilter>

ScriptFilter

This is an optional filter that executes a script in a Apache BSF supported language.

See the Script task for an explanation of scripts and dependencies.

The script is provided with an object self that has getToken() and setToken(String) methods.

This filter may be used directly within a filterchain.

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

Examples:

Convert to uppercase. 
<tokenfilter>
    <scriptfilter language="javascript">
        self.setToken(self.getToken().toUpperCase());
    </scriptfilter>
</tokenfilter>

Custom tokenizers and string filters

Custom string filters and tokenizers may be plugged in by extending the interfaces org.apache.tools.ant.filters.TokenFilter.Filter and org.apache.tools.ant.util.Tokenizer respectly. They are defined the build file using <typedef/>. For example a string filter that capitalizes words may be declared as: 
package my.customant;
import org.apache.tools.ant.filters.TokenFilter;

public class Capitalize
    implements TokenFilter.Filter
{
    public String filter(String token) {
        if (token.length() == 0)
            return token;
        return token.substring(0, 1).toUpperCase() +
                token.substring(1);
   }
}
This may be used as follows: 
  <typedef type="capitalize" classname="my.customant.Capitalize"
           classpath="my.customant.path"/>
  <copy file="input" tofile="output">
    <filterchain>
      <tokenfilter>
        <stringtokenizer/>
        <capitalize/>
      </tokenfilter>
    </filterchain>
  </copy>

Copyright © 2002-2003 Apache Software Foundation. All rights Reserved.