<!DOCTYPE html>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<html lang="en">
<head>
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
<title>FilterChains and FilterReaders</title>
</head>
<body>
<h2>FilterChains and FilterReaders</h2>
<p>Consider the flexibility of Unix pipes. If you wanted, for example, to copy just those lines
that contained the string <q>blee</q> from the first 10 lines of a text file <samp>foo</samp>
(<em>you wouldn't want to filter a binary file</em>) to a file <samp>bar</samp>, you would do
something like:</p>
<pre class="input">cat foo|head -n10|grep blee > bar</pre>
<p>Apache Ant was not flexible enough. There was no way for the <code><copy></code> task to
do something similar. If you wanted the <code><copy></code> task to get the first 10 lines,
you would have had to create special attributes:</p>
<pre><copy file="foo" tofile="bar" head="10" contains="blee"/></pre>
<p>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 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 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.</p>
<p>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 <code class="code">java.io.FilterReader</code> class. Such custom FilterReaders can
be easily plugged in as nested elements of <code><filterchain></code> by
using <code><filterreader></code> elements.</p>
<p>Example:</p>
<pre>
<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></pre>
<p>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.</p>
<p>Example:</p>
<pre>
<loadfile srcfile="${src.file}" property="src.file.head">
<filterchain>
<headfilter lines="15"/>
</filterchain>
</loadfile></pre>
<p>is equivalent to:</p>
<pre>
<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></pre>
<p>The following built-in tasks support nested <code><filterchain></code> elements.<br/>
<a href="../Tasks/concat.html">Concat</a>,<br/>
<a href="../Tasks/copy.html">Copy</a>,<br/>
<a href="../Tasks/loadfile.html">LoadFile</a>,<br/>
<a href="../Tasks/loadproperties.html">LoadProperties</a>,<br/>
<a href="../Tasks/loadresource.html">LoadResource</a>,<br/>
<a href="../Tasks/move.html">Move</a></p>
<p>A FilterChain is formed by defining zero or more of the following nested elements.<br/>
<a href="#filterreader">FilterReader</a><br/>
<a href="#classconstants">ClassConstants</a><br/>
<a href="#escapeunicode">EscapeUnicode</a><br/>
<a href="#expandproperties">ExpandProperties</a><br/>
<a href="#headfilter">HeadFilter</a><br/>
<a href="#linecontains">LineContains</a><br/>
<a href="#linecontainsregexp">LineContainsRegExp</a><br/>
<a href="#prefixlines">PrefixLines</a><br/>
<a href="#replacetokens">ReplaceTokens</a><br/>
<a href="#stripjavacomments">StripJavaComments</a><br/>
<a href="#striplinebreaks">StripLineBreaks</a><br/>
<a href="#striplinecomments">StripLineComments</a><br/>
<a href="#suffixlines">SuffixLines</a><br/>
<a href="#tabstospaces">TabsToSpaces</a><br/>
<a href="#tailfilter">TailFilter</a><br/>
<a href="#deletecharacters">DeleteCharacters</a><br/>
<a href="#concatfilter">ConcatFilter</a><br/>
<a href="#sortfilter">SortFilter</a><br/>
<a href="#tokenfilter">TokenFilter</a><br/>
<a href="../Tasks/fixcrlf.html">FixCRLF</a></p>
<h3 id="filterreader">FilterReader</h3>
<p>The <code>filterreader</code> 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.</p>
<p>A FilterReader element must be supplied with a class name as an attribute value. The class
resolved by this name must extend <code class="code">java.io.FilterReader</code>. If the custom
filter reader needs to be parameterized, it must
implement <code class="code">org.apache.tools.type.Parameterizable</code>.</p>
<table class="attr">
<tr>
<th scope="col">Attribute</th>
<th scope="col">Description</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>classname</td>
<td>The class name of the filter reader.</td>
<td>Yes</td>
</tr>
</table>
<h4>Nested elements</h4>
<p><code><filterreader></code> supports <code><classpath></code>
and <code><param></code> as nested elements. Each <code><param></code> element may take
in the following attributes—<var>name</var>, <var>type</var> and <var>value</var>.</p>
<p>The following FilterReaders are supplied with the default distribution.</p>
<h3 id="classconstants">ClassConstants</h3>
<p>This filters basic constants defined in a Java Class, and outputs them in lines composed of the
format <em>name</em>=<em>value</em>. This filter uses the BCEL library to understand the Java Class
file. See <a href="../install.html#librarydependencies">Library Dependencies</a>.</p>
<p><strong>Important</strong>: This filter is different from most of the other filters. Most of the
filters operate on a sequence of characters. This filter operates on the sequence of bytes that
makes up a class. However the bytes arrive to the filter as a sequence of characters. This means
that one must be careful on the choice of character encoding to use. Most encodings lose information
on conversion from an arbitrary sequence of bytes to characters and back again to bytes. In
particular, the usual default character encodings (CP1252 and UTF-8) do. For this reason, <em>since
Ant 1.7</em>, the character encoding <strong>ISO-8859-1</strong> is used to convert from characters
back to bytes, so one <strong>has</strong> to use this encoding for reading the Java class file.</p>
<h4>Example</h4>
<p>This loads the basic constants defined in a Java class as Ant properties.</p>
<pre>
<loadproperties srcfile="foo.class" encoding="ISO-8859-1">
<filterchain>
<classconstants/>
</filterchain>
</loadproperties></pre>
<p>This loads the constants from a Java class file as Ant properties, prepending the names with
a prefix.</p>
<pre>
<loadproperties srcfile="build/classes/org/acme/bar.class"
encoding="ISO-8859-1">
<filterchain>
<classconstants/>
<prefixlines prefix="ini."/>
</filterchain>
</loadproperties></pre>
<h3 id="escapeunicode">EscapeUnicode</h3>
<p>This filter converts its input by changing all non US-ASCII characters into their equivalent
Unicode escape backslash u plus 4 digits.</p>
<p><em>Since Ant 1.6</em></p>
<h4>Example</h4>
<p>This loads the basic constants defined in a Java class as Ant properties.</p>
<pre>
<loadproperties srcfile="non_ascii_property.properties">
<filterchain>
<filterreader classname="org.apache.tools.ant.filters.EscapeUnicode"/>
</filterchain>
</loadproperties></pre>
<p>Convenience method:</p>
<pre>
<loadproperties srcfile="non_ascii_property.properties">
<filterchain>
<escapeunicode/>
</filterchain>
</loadproperties></pre>
<h3 id="expandproperties">ExpandProperties</h3>
<p>If the data contains data that represents Ant properties (of the form <code>${...}</code>), that
is substituted with the property's actual value.</p>
<h4>Example</h4>
<p>This results in the property <code>modifiedmessage</code> holding the value <q>All these moments
will be lost in time, like teardrops in the rain</q></p>
<pre>
<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></pre>
<p>Convenience method:</p>
<pre>
<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></pre>
<p><em>Since Ant 1.8.3</em>, a nested <a href="propertyset.html">PropertySet</a> can be specified:</p>
<pre>
<property name="weather" value="rain"/>
<loadfile property="modifiedmessage" srcFile="loadfile1.tmp">
<filterchain>
<expandproperties>
<propertyset>
<propertyref name="weather"/>
</propertyset>
</expandproperties>
</filterchain>
</loadfile></pre>
<h3 id="headfilter">HeadFilter</h3>
<p>This filter reads the first few lines from the data supplied to it.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Name</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>lines</td>
<td>Number of lines to be read.<br/>
A negative value means that all lines are passed (useful with <var>skip</var>).</td>
<td>No; defaults to <q>10</q></td>
</tr>
<tr>
<td>skip</td>
<td>Number of lines to be skipped (from the beginning).</td>
<td>No; defaults to <q>0</q></td>
</tr>
</table>
<h4>Example</h4>
<p>This stores the first 15 lines of the supplied data in the property <code>src.file.head</code></p>
<pre>
<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></pre>
<p>Convenience method:</p>
<pre>
<loadfile srcfile="${src.file}" property="src.file.head">
<filterchain>
<headfilter lines="15"/>
</filterchain>
</loadfile></pre>
<p>This stores the first 15 lines, skipping the first 2 lines, of the supplied data in the
property <code>src.file.head</code> (means: lines 3-17).</p>
<pre>
<loadfile srcfile="${src.file}" property="src.file.head">
<filterchain>
<headfilter lines="15" skip="2"/>
</filterchain>
</loadfile></pre>
<p>See the testcases for more examples (<samp>src\etc\testcases\filters\head-tail.xml</samp> in
the source distribution).</p>
<h3 id="linecontains">LineContains</h3>
<p>This filter includes only those lines that contain all the user-specified strings.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Type</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>contains</td>
<td>Substring to be searched for.</td>
<td>Yes</td>
</tr>
<tr>
<td>negate</td>
<td>Whether to select <em>non-</em>matching lines only. <em>Since Ant 1.7</em></td>
<td>No</td>
</tr>
<tr>
<td>matchAny</td>
<td>If <q>false</q>, then all the strings are expected to be present in the line. If
<q>true</q>, then the presence of any of the strings in the line is considered
a successful match.<br/><em>Since Ant 1.10.4</em>
</td>
<td>No; defaults to <q>false</q></td>
</tr>
</table>
<p>
<h4>Example</h4>
<p>This will include only those lines that contain <q>foo</q> and <q>bar</q>.</p>
<pre>
<filterreader classname="org.apache.tools.ant.filters.LineContains">
<param type="contains" value="foo"/>
<param type="contains" value="bar"/>
</filterreader></pre>
<p>Convenience method:</p>
<pre>
<linecontains>
<contains value="foo"/>
<contains value="bar"/>
</linecontains></pre>
<p>Negation:</p>
<pre>
<filterreader classname="org.apache.tools.ant.filters.LineContains">
<param type="negate" value="true"/>
<param type="contains" value="foo"/>
<param type="contains" value="bar"/>
</filterreader></pre>
<p><em>or</em></p>
<pre>
<linecontains negate="true">
<contains value="foo"/>
<contains value="bar"/>
</linecontains></pre>
<h3 id="linecontainsregexp">LineContainsRegExp</h3>
<p>Filter which includes only those lines that contain the user-specified regular expression
matching strings.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Type</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>regexp</td>
<td>Regular expression to be searched for.<br/><em>Since Ant 1.10.2</em>, this also works as an
attribute on <code>linecontainsregexp</code>. In earlier versions of Ant you must use a nested
element when using the convenience method.
</td>
<td>Yes</td>
</tr>
<tr>
<td>negate</td>
<td>Whether to select <em>non-</em>matching lines only. <em>Since Ant 1.7</em></td>
<td>No</td>
</tr>
<tr>
<td>casesensitive</td>
<td>Perform a case sensitive match. <em>Since Ant 1.8.2</em></td>
<td>No; default is <q>true</q></td>
</tr>
</table>
<p>See <a href="regexp.html">Regexp Type</a> for the description of the nested element regexp
and of the choice of regular expression implementation.</p>
<h4>Example</h4>
<p>This will fetch all those lines that contain the pattern <code>foo</code></p>
<pre>
<filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp">
<param type="regexp" value="foo*"/>
</filterreader></pre>
<p>Convenience method:</p>
<pre>
<linecontainsregexp>
<regexp pattern="foo*"/>
</linecontainsregexp></pre>
<p>Negation:</p>
<pre>
<filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp">
<param type="negate" value="true"/>
<param type="regexp" value="foo*"/>
</filterreader></pre>
<p><em>or</em></p>
<pre>
<linecontainsregexp negate="true">
<regexp pattern="foo*"/>
</linecontainsregexp></pre>
<h3 id="prefixlines">PrefixLines</h3>
<p>Attaches a prefix to every line.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Name</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>prefix</td>
<td>Prefix to be attached to lines.</td>
<td>Yes</td>
</tr>
</table>
<h4>Example</h4>
<p>This will attach the prefix <code>Foo</code> to all lines.</p>
<pre>
<filterreader classname="org.apache.tools.ant.filters.PrefixLines">
<param name="prefix" value="Foo"/>
</filterreader></pre>
<p>Convenience method:</p>
<pre><prefixlines prefix="Foo"/></pre>
<h3 id="suffixlines">SuffixLines</h3>
<p><em>Since Ant 1.8.0</em></p>
<p>Attaches a suffix to every line.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Name</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>suffix</td>
<td>Suffix to be attached to lines.</td>
<td>Yes</td>
</tr>
</table>
<h4>Example</h4>
<p>This will attach the suffix <code>Foo</code> to all lines.</p>
<pre>
<filterreader classname="org.apache.tools.ant.filters.SuffixLines">
<param name="suffix" value="Foo"/>
</filterreader></pre>
<p>Convenience method:</p>
<pre><suffixlines suffix="Foo"/></pre>
<h3 id="replacetokens">ReplaceTokens</h3>
<p>This filter reader replaces all strings that are sandwiched between <var>begintoken</var>
and <var>endtoken</var> with user defined values.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Type</th>
<th scope="col">Parameter Name</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>tokenchar</td>
<td>begintoken</td>
<td>String marking the beginning of a token.</td>
<td>No; defaults to <q>@</q></td>
</tr>
<tr>
<td>tokenchar</td>
<td>endtoken</td>
<td>String marking the end of a token.</td>
<td>No; defaults to <q>@</q></td>
</tr>
<tr>
<td>token</td>
<td>User defined token string</td>
<td>Replacement value for the token.</td>
<td>Yes</td>
</tr>
<tr>
<td>propertiesfile</td>
<td rowspan="2">Not applicable</td>
<td>Properties file to take tokens and replacement values from.</td>
<td>No</td>
</tr>
<tr>
<td>propertiesResource</td>
<td>Properties resource to take tokens from.
Note this only works is you use the
"convenience" <code><replacetokens></code> syntax.
<em>since Ant 1.8.0</em></td>
<td>No</td>
</tr>
</table>
<h4>Example</h4>
<p>This replaces occurrences of the string <code>@DATE@</code> in the data with today's date and
stores it in the property <code>${src.file.replaced}</code>.</p>
<pre>
<tstamp/>
<!-- just for explaining the use of the properties -->
<property name="src.file" value="orders.csv"/>
<property name="src.file.replaced" value="orders.replaced"/>
<!-- do the loading and filtering -->
<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>
<!-- just for explaining the use of the properties -->
<echo message="${orders.replaced}"/></pre>
<p>Convenience method:</p>
<pre>
<tstamp/>
<loadfile srcfile="${src.file}" property="${src.file.replaced}">
<filterchain>
<replacetokens>
<token key="DATE" value="${TODAY}"/>
</replacetokens>
</filterchain>
</loadfile></pre>
<p>This replaces occurrences of the string <q>{{DATE}}</q> in the data with today's date and
stores it in the property <samp>${src.file.replaced}</samp>.</p>
<pre>
<loadfile srcfile="${src.file}" property="${src.file.replaced}">
<filterchain>
<filterreader classname="org.apache.tools.ant.filters.ReplaceTokens">
<param type="tokenchar" name="begintoken" value="{{"/>
<param type="tokenchar" name="endtoken" value="}}"/>
</filterreader>
</filterchain>
</loadfile></pre>
<p>Convenience method:</p>
<pre>
<tstamp/>
<loadfile srcfile="${src.file}" property="${src.file.replaced}">
<filterchain>
<replacetokens begintoken="{{" endtoken="}}">
<token key="DATE" value="${TODAY}"/>
</replacetokens>
</filterchain>
</loadfile></pre>
<p>This will treat each properties file entry in sample.properties as a token/key pair:</p>
<pre>
<loadfile srcfile="${src.file}" property="${src.file.replaced}">
<filterchain>
<filterreader classname="org.apache.tools.ant.filters.ReplaceTokens">
<param type="propertiesfile" value="sample.properties"/>
</filterreader>
</filterchain>
</loadfile></pre>
<p>This reads the properties from an Ant resource referenced by its <var>id</var>:</p>
<pre>
<string id="embedded-properties">
foo=bar
baz=xyzzy
</string>
<loadfile srcfile="${src.file}" property="${src.file.replaced}">
<filterchain>
<replacetokens propertiesResource="${ant.refid:embedded-properties}"/>
</filterchain>
</loadfile></pre>
<h3 id="stripjavacomments">StripJavaComments</h3>
<p>This filter reader strips away comments from the data, using Java syntax guidelines. This
filter does not take in any parameters.</p>
<h4>Example</h4>
<pre>
<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">
<filterchain>
<filterreader classname="org.apache.tools.ant.filters.StripJavaComments"/>
</filterchain>
</loadfile></pre>
<p>Convenience method:</p>
<pre>
<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">
<filterchain>
<stripjavacomments/>
</filterchain>
</loadfile></pre>
<h3 id="striplinebreaks">StripLineBreaks</h3>
<p>This filter reader strips away specific characters from the data supplied to it.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Name</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>linebreaks</td>
<td>Characters that are to be stripped out.</td>
<td>No; defaults to <q>\r\n</q></td>
</tr>
</table>
<h4>Examples</h4>
<p>This strips the <q>\r</q> and <q>\n</q> characters.</p>
<pre>
<loadfile srcfile="${src.file}" property="${src.file.contents}">
<filterchain>
<filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"/>
</filterchain>
</loadfile></pre>
<p>Convenience method:</p>
<pre>
<loadfile srcfile="${src.file}" property="${src.file.contents}">
<filterchain>
<striplinebreaks/>
</filterchain>
</loadfile></pre>
<p>This treats the <q>(</q> and <q>)</q> characters as line break characters and strips
them.</p>
<pre>
<loadfile srcfile="${src.file}" property="${src.file.contents}">
<filterchain>
<filterreader classname="org.apache.tools.ant.filters.StripLineBreaks">
<param name="linebreaks" value="()"/>
</filterreader>
</filterchain>
</loadfile></pre>
<h3 id="striplinecomments">StripLineComments</h3>
<p>This filter removes all those lines that begin with strings that represent comments as specified
by the user.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Type</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>comment</td>
<td>Strings that identify a line as a comment when they appear at the start of the
line.</td>
<td>Yes</td>
</tr>
</table>
<p>
<h4>Examples</h4>
<p>This removes all lines that begin with <q>#</q>, <q>--</q>, <q>REM</q>, <q>rem</q>
and <q>//</q></p>
<pre>
<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></pre>
<p>Convenience method:</p>
<pre>
<striplinecomments>
<comment value="#"/>
<comment value="--"/>
<comment value="REM "/>
<comment value="rem "/>
<comment value="//"/>
</striplinecomments></pre>
<h3 id="tabstospaces">TabsToSpaces</h3>
<p>This filter replaces tabs with spaces</p>
<table class="attr">
<tr>
<th scope="col">Parameter Name</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>tablength</td>
<td>Amount of space characters to replace a tab character with.</td>
<td>No; defaults to <q>8</q></td>
</tr>
</table>
<h4>Examples</h4>
<p>This replaces tabs in <samp>${src.file}</samp> with spaces.</p>
<pre>
<loadfile srcfile="${src.file}" property="${src.file.notab}">
<filterchain>
<filterreader classname="org.apache.tools.ant.filters.TabsToSpaces"/>
</filterchain>
</loadfile></pre>
<p>Convenience method:</p>
<pre>
<loadfile srcfile="${src.file}" property="${src.file.notab}">
<filterchain>
<tabstospaces/>
</filterchain>
</loadfile></pre>
<h3 id="tailfilter">TailFilter</h3>
<p>This filter reads the last few lines from the data supplied to it.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Name</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>lines</td>
<td>Number of lines to be read.<br/>
A negative value means that all lines are passed
(useful with <var>skip</var>)</td>
<td>No; defaults to <q>10</q></td>
</tr>
<tr>
<td>skip</td>
<td>Number of lines to be skipped (from the end).</td>
<td>No; defaults to <q>0</q></td>
</tr>
</table>
<p>
<h4>Background</h4>
<p>With HeadFilter and TailFilter you can extract each part of a text file you want. This graphic
shows the dependencies:</p>
<table>
<tr>
<th scope="col">Content</th>
<th scope="col" colspan="3">Filter</th>
</tr>
<tr>
<td>Line 1</td>
<td rowspan="2" style="background:limegreen;">
<pre style="background:limegreen;margin: 0 0 0 0;"><filterchain>
<headfilter lines="2"/>
</filterchain></pre></td>
<td rowspan="9" style="background:fuchsia;">
<pre style="background:fuchsia;margin: 0 0 0 0;"><filterchain>
<tailfilter lines="-1" skip="2"/>
</filterchain></pre>
</td>
<td rowspan="2"> </td>
</tr>
<tr>
<td>Line 2</td>
</tr>
<tr>
<td>Line 3</td>
<td rowspan="9" style="background:tomato;">
<pre style="background:tomato;margin: 0 0 0 0;"><filterchain>
<headfilter lines="-1" skip="2"/>
</filterchain></pre></td>
<td rowspan="7" style="background:dodgerblue;">
<pre style="background:dodgerblue;margin: 0 0 0 0;"><filterchain>
<headfilter lines="-1" skip="2"/>
<tailfilter lines="-1" skip="2"/>
</filterchain></pre></td>
</tr>
<tr>
<td>Line 4</td>
</tr>
<tr>
<td>Line 5</td>
</tr>
<tr>
<td>Lines ...</td>
</tr>
<tr>
<td>Line 95</td>
</tr>
<tr>
<td>Line 96</td>
</tr>
<tr>
<td>Line 97</td>
</tr>
<tr>
<td>Line 98</td>
<td rowspan="2" style="background:lime;">
<pre style="background:lime;margin: 0 0 0 0;"><filterchain>
<tailfilter lines="2"/>
</filterchain></pre></td>
<td rowspan="2"> </td>
</tr>
<tr>
<td>Line 99</td>
</tr>
</table>
<h4>Examples</h4>
<p>This stores the last 15 lines of the supplied data in the
property <samp>${src.file.tail}</samp></p>
<pre>
<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></pre>
<p>Convenience method:</p>
<pre>
<loadfile srcfile="${src.file}" property="${src.file.tail}">
<filterchain>
<tailfilter lines="15"/>
</filterchain>
</loadfile></pre>
<p>This stores the last 5 lines of the first 15 lines of the supplied data in the
property <samp>${src.file.mid}</samp></p>
<pre>
<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></pre>
<p>Convenience method:</p>
<pre>
<loadfile srcfile="${src.file}" property="${src.file.mid}">
<filterchain>
<headfilter lines="15"/>
<tailfilter lines="5"/>
</filterchain>
</loadfile></pre>
<p>This stores the last 10 lines, skipping the last 2 lines, of the supplied data in the
property <code>src.file.head</code>. (Means: if supplied data contains 60 lines, lines 49-58 are
extracted)</p>
<pre>
<loadfile srcfile="${src.file}" property="src.file.head">
<filterchain>
<tailfilter lines="10" skip="2"/>
</filterchain>
</loadfile></pre>
<h3 id="deletecharacters">DeleteCharacters</h3>
<p><em>Since Ant 1.6</em></p>
<p>This filter deletes specified characters.</p>
<p>This filter is only available in the convenience form.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Name</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>chars</td>
<td>
The characters to delete. This attribute is <a href="#backslash">backslash enabled</a>.
</td>
<td>Yes</td>
</tr>
</table>
<p>
<h4>Examples</h4>
<p>Delete tabs and returns from the data.</p>
<pre><deletecharacters chars="\t\r"/></pre>
<h3 id="concatfilter">ConcatFilter</h3>
<p><em>Since Ant 1.6</em></p>
<p>This filter prepends or appends the content file to the filtered files.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Name</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>prepend</td>
<td>
The name of the file which content should be prepended to the file.
</td>
<td>No</td>
</tr>
<tr>
<td>append</td>
<td>
The name of the file which content should be appended to the file.
</td>
<td>No</td>
</tr>
</table>
<p>
<h4>Examples</h4>
<p>Do nothing:</p>
<pre>
<filterchain>
<concatfilter/>
</filterchain></pre>
<p>Adds a license text before each Java source file:</p>
<pre>
<filterchain>
<concatfilter prepend="apache-license-java.txt"/>
</filterchain></pre>
<h3 id="sortfilter">SortFilter</h3>
<p><em>Since Ant 1.8.0</em></p>
<p>The sort filter reads all lines and sorts them. The sort order can be reversed and it is
possible to specify a custom implementation of the <code class="code">java.util.Comparator</code>
interface to get even more control.</p>
<table class="attr">
<tr>
<th scope="col">Parameter Name</th>
<th scope="col">Parameter Value</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>reverse</td>
<td>Whether to reverse the sort order.<br/><strong>Note</strong>: this parameter is ignored
if the comparator parameter is present as well.</td>
<td>No; defaults to <q>false</q></td>
</tr>
<tr>
<td>comparator</td>
<td>Class name of a class that implements <code class="code">java.util.Comparator</code> for
Strings. This class will be used to determine the sort order of lines.</td>
<td>No</td>
</tr>
</table>
<p>This filter is also available using the name <code>sortfilter</code>.
The <code>reverse</code> parameter becomes an attribute, <code>comparator</code> can be
specified by using a nested element.</p>
<h4>Examples</h4>
<pre>
<copy todir="build">
<fileset dir="input" includes="*.txt"/>
<filterchain>
<sortfilter/>
</filterchain>
</copy></pre>
<p>
Sort all files <samp>*.txt</samp> from <samp>src</samp> location into <samp>build</samp>
location. The lines of each file are sorted in ascendant order comparing the lines via the
<code>String.compareTo(Object o)</code> method.
</p>
<pre>
<copy todir="build">
<fileset dir="input" includes="*.txt"/>
<filterchain>
<sortfilter reverse="true"/>
</filterchain>
</copy></pre>
<p>
Sort all files <samp>*.txt</samp> from <samp>src</samp> location into reverse order and copy
them into <samp>build</samp> location.
</p>
<pre>
<copy todir="build">
<fileset dir="input" includes="*.txt"/>
<filterchain>
<filterreader classname="org.apache.tools.ant.filters.SortFilter">
<param name="comparator" value="org.apache.tools.ant.filters.EvenFirstCmp"/>
</filterreader>
</filterchain>
</copy></pre>
<p>
Sort all files <samp>*.txt</samp> from <samp>src</samp> location using as sorting
criterium <code class="code">EvenFirstCmp</code> class, that sorts the file lines putting even lines
first then odd lines for example. The modified files are copied into <samp>build</samp>
location. The <code class="code">EvenFirstCmp</code> has to an instanciable class
via <code class="code">Class.newInstance()</code>, therefore in case of inner class has to
be <em>static</em>. It also has to implement <code class="code">java.util.Comparator</code>
interface, for example:
</p>
<pre>
package org.apache.tools.ant.filters;
... (omitted)
public final class EvenFirstCmp implements <b>Comparator</b> {
public int compare(Object o1, Object o2) {
...(omitted)
}
}</pre>
<p>The example above is equivalent to:</p>
<pre>
<componentdef name="evenfirst"
classname="org.apache.tools.ant.filters.EvenFirstCmp"/>
<copy todir="build">
<fileset dir="input" includes="*.txt"/>
<filterchain>
<sortfilter>
<evenfirst/>
</sortfilter>
</filterchain>
</copy></pre>
<h3 id="tokenfilter">TokenFilter</h3>
<p>This filter tokenizes the InputStream into strings and passes these strings to filters of
strings. Unlike the other FilterReaders, this does not support <code>param</code>s, only
convenience methods are implemented. The tokenizer and the string filters are defined by nested
elements.</p>
<p><em>Since Ant 1.6</em></p>
<p>
Only one <code>tokenizer</code> 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.
<p>
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 delimiter (if one is present). The trailing delimiter may be
overridden by the <var>delimOutput</var> attribute.
<h4 id="backslash">Backslash interpretation</h4>
<p>
A number of attributes (including <var>delimOutput</var>) interpret backslash escapes. The
following are understood: <q>\n</q>, <q>\r</q>, <q>\f</q>, <q>\t</q> and <q>\\</q>.
</p>
<table class="attr">
<tr>
<th scope="col">Attribute</th>
<th scope="col">Description</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>delimOutput</td>
<td>
This overrides the token delimiter returned by the tokenizer if it is not empty. This
attribute is backslash enabled.
</td>
<td>No</td>
</tr>
</table>
<p>The following tokenizers are provided by the default distribution.</p>
<p>
<a href="#linetokenizer">LineTokenizer</a><br/>
<a href="#filetokenizer">FileTokenizer</a><br/>
<a href="#stringtokenizer">StringTokenizer</a>
</p>
<p>The following string filters are provided by the default distribution.</p>
<p>
<a href="#replacestring">ReplaceString</a><br/>
<a href="#containsstring">ContainsString</a><br/>
<a href="#replaceregex">ReplaceRegex</a><br/>
<a href="#containsregex">ContainsRegex</a><br/>
<a href="#trim">Trim</a><br/>
<a href="#ignoreblank">IgnoreBlank</a><br/>
<a href="#filterdeletecharacters">DeleteCharacters</a><br/>
<a href="#uniqfilter">UniqFilter</a><br/>
<a href="#native2asciifilter">Native2AsciiFilter</a>
</p>
<p>The following string filters are provided by the optional distribution.</p>
<p>
<a href="#scriptfilter">ScriptFilter</a>
</p>
<p>
<a href="#custom">Custom</a> tokenizers and string filters can be declared
using <a href="../Tasks/typedef.html">typedef</a> task.
</p>
<p>
Some of the filters may be used directly within a <code>filterchain</code>. In this case
a <code>tokenfilter</code> is created implicitly. An extra attribute <var>byline</var> is added to
the filter to specify whether to use a <code>linetokenizer</code> (<var>byline</var>=<q>true</q>) or
a <code>filetokenizer</code> (<var>byline</var>=<q>false</q>). The default is <q>true</q>.
</p>
<h4 id="linetokenizer">LineTokenizer</h4>
<p>This tokenizer splits the input into lines. The tokenizer delimits lines by <q>\r</q>, <q>\n</q>
or <q>\r\n</q>. This is the default tokenizer.</p>
<table class="attr">
<tr>
<th scope="col">Attribute</th>
<th scope="col">Description</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>includeDelims</td>
<td>
Include the line endings in the token.
</td>
<td>No; default is <q>false</q></td>
</tr>
</table>
<h5>Examples</h5>
<p>Convert input current line endings to Unix style line endings.</p>
<pre><tokenfilter delimoutput="\n"/></pre>
<p>Remove blank lines.</p>
<pre>
<tokenfilter>
<ignoreblank/>
</tokenfilter></pre>
<h4 id="filetokenizer">FileTokenizer</h4>
<p>This tokenizer treats <strong>all</strong> the input as a token. So be careful not to use
this on very large input.</p>
<h5>Examples</h5>
<p>Replace the first occurrence of <samp>package</samp> with <samp>//package</samp>.</p>
<pre>
<tokenfilter>
<filetokenizer/>
<replaceregex pattern="([\n\r]+[ \t]*|^[ \t]*)package"
flags="s"
replace="\1//package"/>
</tokenfilter></pre>
<h4 id="stringtokenizer">StringTokenizer</h4>
<p>This tokenizer is based on <code class="code">java.util.StringTokenizer</code>. 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 <var>delimsaretokens</var> attribute is used).</p>
<table class="attr">
<tr>
<th scope="col">Attribute</th>
<th scope="col">Description</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>delims</td>
<td>The delimiter characters.
</td>
<td>No; defaults to white space as defined
by <code>java.lang.Character.isWhitespace()</code></td>
</tr>
<tr>
<td>delimsaretokens</td>
<td>If this is <q>true</q>, each delimiter character is returned as a token.</td>
<td>No; default is <q>false</q></td>
</tr>
<tr>
<td>suppressdelims</td>
<td>If this is <q>true</q>, delimiters are not returned.</td>
<td>No; default is <q>false</q></td>
</tr>
<tr>
<td>includeDelims</td>
<td>Include the delimiters in the token.</td>
<td>No; default is <q>false</q></td>
</tr>
</table>
<h5>Examples</h5>
<p>Surround each non space token with a <q>[]</q>.</p>
<pre>
<tokenfilter>
<stringtokenizer/>
<replaceregex pattern="(.+)" replace="[\1]"/>
</tokenfilter></pre>
<h4 id="replacestring">ReplaceString</h4>
<p>This is a simple filter to replace strings. This filter may be used directly within
a <code>filterchain</code>.</p>
<table class="attr">
<tr>
<th scope="col">Attribute</th>
<th scope="col">Description</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>from</td>
<td>The string that must be replaced.</td>
<td>Yes</td>
</tr>
<tr>
<td>to</td>
<td>The new value for the replaced string.</td>
<td>No; defaults to empty string</td>
</tr>
</table>
<h5>Examples</h5>
<p>Replace <q>sun</q> with <q>moon</q>.</p>
<pre>
<tokenfilter>
<replacestring from="sun" to="moon"/>
</tokenfilter></pre>
<h4 id="containsstring">ContainsString</h4>
<p>This is a simple filter to filter tokens that contains a specified string.</p>
<table class="attr">
<tr>
<th scope="col">Attribute</th>
<th scope="col">Description</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>contains</td>
<td>The string that the token must contain.</td>
<td>Yes</td>
</tr>
</table>
<h5>Examples</h5>
<p>Include only lines that contain <q>foo</q></p>
<pre>
<tokenfilter>
<containsstring contains="foo"/>
</tokenfilter></pre>
<h4 id="replaceregex">ReplaceRegex</h4>
<p>
This string filter replaces regular expressions. This filter may be used directly within
a <code>filterchain</code>.
</p>
<p>
See <a href="regexp.html#implementation">Regexp Type</a> concerning the choice of the
implementation.
</p>
<table class="attr">
<tr>
<th scope="col">Attribute</th>
<th scope="col">Description</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>pattern</td>
<td>The regular expression pattern to match in the token.</td>
<td>Yes</td>
</tr>
<tr>
<td>replace</td>
<td>The substitution pattern to replace the matched regular expression.</td>
<td>No; defaults to empty string</td>
</tr>
<tr>
<td>flags</td>
<td>See <a href="../Tasks/replaceregexp.html">ReplaceRegexp</a> for an explanation of regex
flags.</td>
<td>No</td>
</tr>
</table>
<h5>Examples</h5>
<p>Replace all occurrences of <q>hello</q> with <q>world</q>, ignoring case.</p>
<pre>
<tokenfilter>
<replaceregex pattern="hello" replace="world" flags="gi"/>
</tokenfilter></pre>
<h4 id="containsregex">ContainsRegex</h4>
<p>
This filters strings that match regular expressions. The filter may optionally replace the
matched regular expression. This filter may be used directly within a <code>filterchain</code>.
</p>
<p>
See <a href="regexp.html#implementation">Regexp Type</a> concerning the choice of regular
expression implementation.
</p>
<table class="attr">
<tr>
<th scope="col">Attribute</th>
<th scope="col">Description</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>pattern</td>
<td>The regular expression pattern to match in the token.</td>
<td>Yes</td>
</tr>
<tr>
<td>replace</td>
<td>The substitution pattern to replace the matched regular expression.</td>
<td>No; defaults to returning the original token</td>
</tr>
<tr>
<td>flags</td>
<td>See <a href="../Tasks/replaceregexp.html">ReplaceRegexp</a> for an explanation of regex
flags.</td>
<td>No</td>
</tr>
</table>
<h5>Examples</h5>
<p>Filter lines that contain <q>hello</q> or <q>world</q>, ignoring case.</p>
<pre>
<tokenfilter>
<containsregex pattern="(hello|world)" flags="i"/>
</tokenfilter></pre>
<p>This example replaces lines like <code>SUITE(TestSuite, bits);</code> with <code>void
register_bits();</code> and removes other lines.</p>
<pre>
<tokenfilter>
<containsregex
pattern="^ *SUITE\(.*,\s*(.*)\s*\).*"
replace="void register_\1();"/>
</tokenfilter></pre>
<h4 id="trim">Trim</h4>
<p>This filter trims whitespace from the start and end of tokens. This filter may be used
directly within a <code>filterchain</code>.</p>
<h4 id="ignoreblank">IgnoreBlank</h4>
<p>This filter removes empty tokens. This filter may be used directly within
a <code>filterchain</code>.</p>
<h4 id="filterdeletecharacters">DeleteCharacters</h4>
<p>This filter deletes specified characters from tokens.</p>
<table class="attr">
<tr>
<th scope="col">Attribute</th>
<th scope="col">Description</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>chars</td>
<td>The characters to delete. This attribute is backslash enabled.</td>
<td>Yes</td>
</tr>
</table>
<h5>Examples</h5>
<p>Delete tabs from lines, trim the lines and removes empty lines.</p>
<pre>
<tokenfilter>
<deletecharacters chars="\t"/>
<trim/>
<ignoreblank/>
</tokenfilter></pre>
<h4 id="uniqfilter">UniqFilter</h4>
<p>Suppresses all tokens that match their ancestor token. It is most useful if combined with a
sort filter.</p>
<p>This filter may be used directly within a <code>filterchain</code>.</p>
<h5>Example</h5>
<p>This suppresses duplicate lines.</p>
<pre>
<tokenfilter>
<uniqfilter/>
</tokenfilter></pre>
<h4 id="native2asciifilter">Native2AsciiFilter</h4>
<p><em>Since Ant 1.9.8</em></p>
<p>Uses the "builtin" implementation of
the <a href="../Tasks/native2ascii.html">native2ascii</a> task.</p>
<p>Replaces non-ASCII characters by their Unicode-escapes or vice-versa.</p>
<p>This filter may be used directly within a <code>filterchain</code>.</p>
<table class="attr">
<tr>
<th scope="col">Attribute</th>
<th scope="col">Description</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>reverse</td>
<td>Reverse the sense of the conversion, i.e. convert from ASCII to native.</td>
<td>No</td>
</tr>
</table>
<h5>Example</h5>
<p>This replaces all non-ASCII characters by their Unicode-escapes.</p>
<pre>
<tokenfilter>
<native2asciifilter/>
</tokenfilter></pre>
<h4 id="scriptfilter">ScriptFilter</h4>
<p>
This is an optional filter that executes a script in a <a href="https://jakarta.apache.org/bsf"
target="_top">Apache BSF</a>
or <a href="https://jcp.org/aboutJava/communityprocess/maintenance/jsr223/223ChangeLog.html"
target="_top">JSR 223</a> supported language.
</p>
<p>
See the <a href="../Tasks/script.html">Script</a> task for an explanation of scripts and
dependencies.
</p>
<p>
The script is provided with an object <samp class="code">self</samp> that
has <code class="code">getToken()</code> and <code class="code">setToken(String)</code> methods.
The <code class="code">getToken()</code> method returns the current
token. The <code class="code">setToken(String)</code> method replaces the current token.
</p>
<p>
This filter may be used directly within a <code>filterchain</code>.
</p>
<table class="attr">
<tr>
<th scope="col">Attribute</th>
<th scope="col">Description</th>
<th scope="col">Required</th>
</tr>
<tr>
<td>language</td>
<td>Programming language the script is written in. Must be a supported Apache BSF or JSR 223
language</td>
<td>Yes</td>
</tr>
<tr>
<td>manager</td>
<td>Script engine manager to use. See the <a href="../Tasks/script.html">script</a> task for
using this attribute.</td>
<td>No; default is <q>auto</q></td>
</tr>
<tr>
<td>src</td>
<td>Location of the script as a file, if not inline.</td>
<td>No</td>
</tr>
<tr>
<td>encoding</td>
<td>Encoding of the script as a file. <em>Since Ant 1.10.2</em></td>
<td>No; defaults to default JVM character encoding</td>
</tr>
<tr>
<td>setbeans</td>
<td>Whether to have all properties, references and targets as global variables in the
script. <em>Since Ant 1.8.0</em></td>
<td>No; default is <q>true</q></td>
</tr>
<tr>
<td>classpath</td>
<td>The classpath to pass into the script.</td>
<td>No</td>
</tr>
<tr>
<td>classpathref</td>
<td>The classpath to use, given as a <a href="../using.html#references">reference</a> to a path
defined elsewhere.
<td>No</td>
</tr>
</table>
<p>
This filter can take a nested <code><classpath></code> element. See
the <a href="../Tasks/script.html">script</a> task on how to use this element.
</p>
<h5>Examples</h5>
<p>Convert to uppercase:</p>
<pre>
<tokenfilter>
<scriptfilter language="javascript">
self.setToken(self.getToken().toUpperCase());
</scriptfilter>
</tokenfilter></pre>
<p>Remove lines containing the string <q>bad</q> while copying text files:</p>
<pre>
<copy todir="dist">
<fileset dir="src" includes="**/*.txt"/>
<filterchain>
<scriptfilter language="beanshell">
if (self.getToken().indexOf("bad") != -1) {
self.setToken(null);
}
</scriptfilter>
</filterchain>
</copy></pre>
<h4 id="custom">Custom tokenizers and string filters</h4>
<p>Custom string filters and tokenizers may be plugged in by extending the
interfaces <code class="code">org.apache.tools.ant.filters.TokenFilter.Filter</code>
and <code class="code">org.apache.tools.ant.util.Tokenizer</code> respectly.</p>
<p>They are defined in the build file using <code><typedef/></code>. For example, a string
filter that capitalizes words may be declared as:</p>
<pre>
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);
}
}</pre>
<p>This may be used as follows:</p>
<pre>
<typedef name="capitalize" classname="my.customant.Capitalize"
classpath="my.customant.path"/>
<copy file="input" tofile="output">
<filterchain>
<tokenfilter>
<stringtokenizer/>
<capitalize/>
</tokenfilter>
</filterchain>
</copy></pre>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-updates
>
by-pkgid
>
8fad0817607a09309c3e5b12a09dac58
>
files
>
182
