diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Types/filterchain.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Types/filterchain.html | 1739 |
1 files changed, 1739 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/filterchain.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/filterchain.html new file mode 100644 index 00000000..4de10ea3 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/filterchain.html @@ -0,0 +1,1739 @@ +<!-- + 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 + + http://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. +--> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> + +<html> +<head> + <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>FilterChains and FilterReaders</title> +</head> + +<body> + +<h2>FilterChains and FilterReaders</h2> +Consider the flexibility of Unix pipes. If you wanted, +for example, to copy just those lines that contained the +string blee from the first 10 lines of a text file 'foo' +(<em>you wouldn't want to filter a binary file</em>) +to a file 'bar', you would do something like:<p> +<code> +cat foo|head -n10|grep blee > bar +</code><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> +<code> +<copy file="foo" tofile="bar" head="10" contains="blee"/> +</code><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> + +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 +<code><filterchain></code> by using <code><filterreader></code> elements. +<p> +Example: +<blockquote><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></blockquote> + +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> +Example: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="src.file.head"> + <filterchain> + <headfilter lines="15"/> + </filterchain> +</loadfile> +</pre></blockquote> +is equivalent to: +<blockquote><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></blockquote> + +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><br><br> + +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="#tokenfilter">TokenFilter</a><br> +<a href="../Tasks/fixcrlf.html">FixCRLF</a><br> +<a href="#sortfilter">SortFilter</a><br> + +<h3><a name="filterreader">FilterReader</a></h3> + +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. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>classname</td> + <td vAlign=top>The class name of the filter reader.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> + +<p> +<h4>Nested Elements:</h4> +<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 - name, type and value. +<p> +The following FilterReaders are supplied with the default +distribution. + +<h3><a name="classconstants">ClassConstants</a></h3> +<p> + This filters basic constants defined in a Java Class, + and outputs them in lines composed of the format <i>name</i>=<i>value</i>. + This filter uses the <em>bcel</em> library to understand the Java Class file. + See <a href="../install.html#librarydependencies">Library Dependencies</a>. +<p> + <p> + <em><b>Important:</b></em> + 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 encoding lose information + on conversion from an arbitrary sequence of bytes to characters + and back again to bytes. In particular the usual default + character encodings (CP152 and UTF-8) do. + For this reason, <em>since Ant 1.7</em>, the character + encoding <b>ISO-8859-1</b> is used to convert from characters back to + bytes, so one <b>has</b> to use this encoding for reading the java + class file. +<h4>Example:</h4> + +This loads the basic constants defined in a Java class as Ant properties. + +<blockquote><pre> +<loadproperties srcfile="foo.class" encoding="ISO-8859-1"> + <filterchain> + <classconstants/> + </filterchain> +</loadproperties> +</pre></blockquote> + +This loads the constants from a Java class file as Ant properties, +prepending the names with a prefix. + + <blockquote><pre> +<loadproperties srcfile="build/classes/org/acme/bar.class" + encoding="ISO-8859-1"> + <filterchain> + <classconstants/> + <prefixlines prefix="ini."/> + </filterchain> +</loadproperties> +</pre></blockquote> +<h3><a name="escapeunicode">EscapeUnicode</a></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> + +This loads the basic constants defined in a Java class as Ant properties. +<blockquote><pre> +<loadproperties srcfile="non_ascii_property.properties"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.EscapeUnicode"/> + </filterchain> +</loadproperties> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<loadproperties srcfile="non_ascii_property.properties"> + <filterchain> + <escapeunicode/> + </filterchain> +</loadproperties> +</pre></blockquote> + +<h3><a name="expandproperties">ExpandProperties</a></h3> +<p> +If the data contains data that represents Ant +properties (of the form ${...}), that is substituted +with the property's actual value. +<p> +<h4>Example:</h4> + +This results in the property modifiedmessage holding the value +"All these moments will be lost in time, like teardrops in the rain" +<blockquote><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></blockquote> + +Convenience method: +<blockquote><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></blockquote> + +<p>As of Ant <strong>1.8.3</strong>, a nested + <a href="propertyset.html">PropertySet</a> can be specified: + +<blockquote><pre> +<property name="weather" value="rain"/> +<loadfile property="modifiedmessage" srcFile="loadfile1.tmp"> + <filterchain> + <expandproperties> + <propertyset> + <propertyref name="weather" /> + </propertyset> + </expandproperties> + </filterchain> +</loadfile> +</pre></blockquote> + +<h3><a name="headfilter">HeadFilter</a></h3> + +This filter reads the first few lines from the data supplied to it. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>lines</td> + <td vAlign=top align="center">Number of lines to be read. + Defaults to "10" <br> A negative value means that all lines are + passed (useful with <i>skip</i>)</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>skip</td> + <td vAlign=top align="center">Number of lines to be skipped (from the beginning). + Defaults to "0"</td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> +<h4>Example:</h4> + +This stores the first 15 lines of the supplied data in the property src.file.head +<blockquote><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></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="src.file.head"> + <filterchain> + <headfilter lines="15"/> + </filterchain> +</loadfile> +</pre></blockquote> + +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) +<blockquote><pre> +<loadfile srcfile="${src.file}" property="src.file.head"> + <filterchain> + <headfilter lines="15" skip="2"/> + </filterchain> +</loadfile> +</pre></blockquote> + +See the testcases for more examples (<i>src\etc\testcases\filters\head-tail.xml</i> in the +source distribution). + +<h3><a name="linecontains">LineContains</a></h3> + +This filter includes only those lines that contain all the user-specified +strings. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Type</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>contains</td> + <td vAlign=top align="center">Substring to be searched for.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td vAlign=top>negate</td> + <td vAlign=top align="center">Whether to select + <i>non-</i>matching lines only. <b>Since Ant 1.7</b></td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> +<h4>Example:</h4> + +This will include only those lines that contain <code>foo</code> and +<code>bar</code>. +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.LineContains"> + <param type="contains" value="foo"/> + <param type="contains" value="bar"/> +</filterreader> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<linecontains> + <contains value="foo"/> + <contains value="bar"/> +</linecontains> +</pre></blockquote> + +Negation: +<blockquote><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></blockquote> +<i>or</i> +<blockquote><pre> +<linecontains negate="true"> + <contains value="foo"/> + <contains value="bar"/> +</linecontains> +</pre></blockquote> + +<h3><a name="linecontainsregexp">LineContainsRegExp</a></h3> + +Filter which includes only those lines that contain the user-specified +regular expression matching strings. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Type</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>regexp</td> + <td vAlign=top align="center">Regular expression to be searched for.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td vAlign=top>negate</td> + <td vAlign=top align="center">Whether to select + <i>non-</i>matching lines only. <b>Since Ant 1.7</b></td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>casesensitive</td> + <td vAlign=top align="center">Perform a case sensitive + match. Default is true. <b>Since Ant 1.8.2</b></td> + <td vAlign=top align="center">No</td> + </tr> +</table> + +See <a href="regexp.html">Regexp Type</a> for the description of the nested element regexp and of +the choice of regular expression implementation. +<h4>Example:</h4> + +This will fetch all those lines that contain the pattern <code>foo</code> +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp"> + <param type="regexp" value="foo*"/> +</filterreader> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<linecontainsregexp> + <regexp pattern="foo*"/> +</linecontainsregexp> +</pre></blockquote> + +Negation: +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp"> + <param type="negate" value="true"/> + <param type="regexp" value="foo*"/> +</filterreader> +</pre></blockquote> +<i>or</i> +<blockquote><pre> +<linecontainsregexp negate="true"> + <regexp pattern="foo*"/> +</linecontainsregexp> +</pre></blockquote> + +<h3><a name="prefixlines">PrefixLines</a></h3> + +Attaches a prefix to every line. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>prefix</td> + <td vAlign=top align="center">Prefix to be attached to lines.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> +<p> +<h4>Example:</h4> + +This will attach the prefix <code>Foo</code> to all lines. +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.PrefixLines"> + <param name="prefix" value="Foo"/> +</filterreader> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<prefixlines prefix="Foo"/> +</pre></blockquote> + +<h3><a name="suffixlines">SuffixLines</a></h3> + +Attaches a suffix to every line. + +<p><em>since Ant 1.8.0</em></p> + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>suffix</td> + <td vAlign=top align="center">Suffix to be attached to lines.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> +<p> +<h4>Example:</h4> + +This will attach the suffix <code>Foo</code> to all lines. +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.SuffixLines"> + <param name="suffix" value="Foo"/> +</filterreader> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<suffixlines suffix="Foo"/> +</pre></blockquote> + +<h3><a name="replacetokens">ReplaceTokens</a></h3> + +This filter reader replaces all strings that are +sandwiched between begintoken and endtoken with +user defined values. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Type</b></td> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>tokenchar</td> + <td vAlign=top>begintoken</td> + <td vAlign=top>String marking the + beginning of a token. Defaults to @</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>tokenchar</td> + <td vAlign=top>endtoken</td> + <td vAlign=top>String marking the + end of a token. Defaults to @</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>User defined String.</td> + <td vAlign=top>token</td> + <td vAlign=top>User defined search String.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td vAlign=top>Not applicable.</td> + <td vAlign=top>propertiesfile</td> + <td vAlign=top>Properties file to take tokens from.</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>Not applicable.</td> + <td vAlign=top>propertiesResource</td> + <td vAlign=top>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 vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>User defined String.</td> + <td vAlign=top>value</td> + <td vAlign=top>Replace-value for the token</td> + <td vAlign=top align="center">No</td> + </tr></table> +<p> + +<h4>Example:</h4> + +This replaces occurrences of the string @DATE@ in the data +with today's date and stores it in the property ${src.file.replaced}. +<blockquote><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></blockquote> + +Convenience method: +<blockquote><pre> +<tstamp/> +<loadfile srcfile="${src.file}" property="${src.file.replaced}"> + <filterchain> + <replacetokens> + <token key="DATE" value="${TODAY}"/> + </replacetokens> + </filterchain> +</loadfile> +</pre></blockquote> + +This replaces occurrences of the string {{DATE}} in the data +with today's date and stores it in the property ${src.file.replaced}. +<blockquote><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></blockquote> + +Convenience method: +<blockquote><pre> +<tstamp/> +<loadfile srcfile="${src.file}" property="${src.file.replaced}"> + <filterchain> + <replacetokens begintoken="{{" endtoken="}}"> + <token key="DATE" value="${TODAY}"/> + </replacetokens> + </filterchain> +</loadfile> +</pre></blockquote> + +This will treat each properties file entry in sample.properties as a token/key pair : +<blockquote><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></blockquote> + +This reads the properties from an Ant resource referenced by its id: +<blockquote><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></blockquote> + +<h3><a name="stripjavacomments">StripJavaComments</a></h3> + +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> + +<blockquote><pre> +<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.StripJavaComments"/> + </filterchain> +</loadfile> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}"> + <filterchain> + <stripjavacomments/> + </filterchain> +</loadfile> +</pre></blockquote> + +<h3><a name="striplinebreaks">StripLineBreaks</a></h3> + +This filter reader strips away specific characters +from the data supplied to it. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>linebreaks</td> + <td vAlign=top align="center">Characters that are to + be stripped out. Defaults to "\r\n"</td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> +<h4>Examples:</h4> + +This strips the '\r' and '\n' characters. +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.contents}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"/> + </filterchain> +</loadfile> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.contents}"> + <filterchain> + <striplinebreaks/> + </filterchain> +</loadfile> +</pre></blockquote> + +This treats the '(' and ')' characters as line break characters and +strips them. +<blockquote><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></blockquote> + +<h3><a name="striplinecomments">StripLineComments</a></h3> + +This filter removes all those lines that begin with strings +that represent comments as specified by the user. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Type</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>comment</td> + <td vAlign=top align="center">Strings that identify a line as a comment + when they appear at the start of the line.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> +<p> +<h4>Examples:</h4> + +This removes all lines that begin with #, --, REM, rem and // +<blockquote><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></blockquote> + +Convenience method: +<blockquote><pre> +<striplinecomments> + <comment value="#"/> + <comment value="--"/> + <comment value="REM "/> + <comment value="rem "/> + <comment value="//"/> +</striplinecomments> +</pre></blockquote> + +<h3><a name="tabstospaces">TabsToSpaces</a></h3> + +This filter replaces tabs with spaces + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>tablength</td> + <td vAlign=top align="center">Defaults to "8"</td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> +<h4>Examples:</h4> + +This replaces tabs in ${src.file} with spaces. +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.notab}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.TabsToSpaces"/> + </filterchain> +</loadfile> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.notab}"> + <filterchain> + <tabstospaces/> + </filterchain> +</loadfile> +</pre></blockquote> + +<h3><a name="tailfilter">TailFilter</a></h3> + +This filter reads the last few lines from the data supplied to it. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>lines</td> + <td vAlign=top align="center">Number of lines to be read. + Defaults to "10" <br> A negative value means that all lines are + passed (useful with <i>skip</i>)</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>skip</td> + <td vAlign=top align="center">Number of lines to be skipped (from the end). + Defaults to "0" </td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> + +<h4>Background:</h4> +With HeadFilter and TailFilter you can extract each part of a text file you want. +This graphic shows the dependencies: + +<table cellSpacing=0 cellPadding=2 border=1> +<tr> + <th> Content </th> + <th></th> + <th></th> + <th></th> + <th> Filter </th> +</tr> +<tr> + <td> Line 1 </td> + <td rowspan="2" bgcolor="#C0C0C0"> </td> + <td rowspan="9" bgcolor="#FF00FF"> </td> + <td rowspan="4"> </td> + <td rowspan="11"> + <table> + <tr> + <td bgcolor="#C0C0C0"> </td> + <td><pre><filterchain> + <headfilter lines="2"/> +</filterchain></pre></td> + </tr> + <tr> + <td bgcolor="#FF00FF"> </td> + <td><pre><filterchain> + <tailfilter lines="-1" skip="2"/> +</filterchain></pre></td> + </tr> + <tr> + <td bgcolor="#008000"> </td> + <td><pre><filterchain> + <headfilter lines="-1" skip="2"/> +</filterchain></pre></td> + </tr> + <tr> + <td bgcolor="#0000FF"> </td> + <td><pre><filterchain> + <headfilter lines="-1" skip="2"/> + <tailfilter lines="-1" skip="2"/> +</filterchain></pre></td> + </tr> + <tr> + <td bgcolor="#00FF00"> </td> + <td><pre><filterchain> + <tailfilter lines="2"/> +</filterchain></pre></td> + </tr> + </table> + </td> +</tr> +<tr> + <td> Line 2 </td> +</tr> +<tr> + <td> Line 3 </td> + <td rowspan="9" bgcolor="#008000"> </td> +</tr> +<tr> + <td> Line 4 </td> +</tr> +<tr> + <td> Line 5 </td> + <td rowspan="3" bgcolor="#0000FF"> </td> +</tr> +<tr> + <td> Lines ... </td> +</tr> +<tr> + <td> Line 95 </td> +</tr> +<tr> + <td> Line 96 </td> + <td rowspan="4"> </td> +</tr> +<tr> + <td> Line 97 </td> +</tr> +<tr> + <td> Line 98 </td> + <td rowspan="2" bgcolor="#00FF00"> </td> +</tr> +<tr> + <td> Line 99 </td> +</tr> +</table> + + + +<h4>Examples:</h4> + +This stores the last 15 lines of the supplied data in the property ${src.file.tail} +<blockquote><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></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.tail}"> + <filterchain> + <tailfilter lines="15"/> + </filterchain> +</loadfile> +</pre></blockquote> + + +This stores the last 5 lines of the first 15 lines of the supplied +data in the property ${src.file.mid} +<blockquote><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></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.mid}"> + <filterchain> + <headfilter lines="15"/> + <tailfilter lines="5"/> + </filterchain> +</loadfile> +</pre></blockquote> + + +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) +<blockquote><pre> +<loadfile srcfile="${src.file}" property="src.file.head"> + <filterchain> + <tailfilter lines="10" skip="2"/> + </filterchain> +</loadfile> +</pre></blockquote> + +<h3><a name="deletecharacters">DeleteCharacters</a></h3> + + <p>This filter deletes specified characters.</p> + <p><em>since Ant 1.6</em></p> + <p>This filter is only available in the convenience form.</p> + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>chars</td> + <td vAlign=top> + The characters to delete. This attribute is + <a href="#backslash">backslash enabled</a>. + </td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> +<p> +<h4>Examples:</h4> + +Delete tabs and returns from the data. +<blockquote><pre> +<deletecharacters chars="\t\r"/> +</pre></blockquote> + +<h3><a name="concatfilter">ConcatFilter</a></h3> + <p>This filter prepends or appends the content file to the filtered files.</p> + <p><em>since Ant 1.6</em></p> +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>prepend</td> + <td vAlign=top> + The name of the file which content should be prepended to the file. + </td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>append</td> + <td vAlign=top> + The name of the file which content should be appended to the file. + </td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> + +<h4>Examples:</h4> + +Do nothing: +<blockquote><pre> +<filterchain> + <concatfilter/> +</filterchain> +</pre></blockquote> + +Adds a license text before each java source: +<blockquote><pre> +<filterchain> + <concatfilter prepend="apache-license-java.txt"/> +</filterchain> +</pre></blockquote> + + + +<h3><a name="tokenfilter">TokenFilter</a></h3> +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. +<p><em>since Ant 1.6</em></p> +<p> +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. +<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 <i>delimOutput</i> +attribute. +<p> +<a name="backslash"><em>backslash interpretation</em></a> +A number of attributes (including <i>delimOutput</i>) interpret +backslash escapes. The following are understood: \n, \r, \f, \t +and \\. + + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>delimOutput</td> + <td vAlign=top> + This overrides the tokendelimiter + returned by the tokenizer if it is not empty. This + attribute is backslash enabled. +</td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> + + The following tokenizers are provided by the default distribution. + <p> + <a href="#linetokenizer">LineTokenizer</a><br> + <a href="#filetokenizer">FileTokenizer</a><br> + <a href="#stringtokenizer">StringTokenizer</a><br> + </p> + + The following string filters are provided by the default distribution. + <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> + </p> + + The following string filters are provided by the optional distribution. + <p> + <a href="#scriptfilter">ScriptFilter</a><br> + </p> + +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". +<p> + +<p><b><em><a name="linetokenizer">LineTokenizer</a></em></b></p> +This tokenizer splits the input into lines. +The tokenizer delimits lines +by "\r", "\n" or "\r\n". +This is the default tokenizer. +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>includeDelims</td> + <td vAlign=top> + Include the line endings in the token. + Default is false. + </td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<h4>Examples:</h4> + +Convert input current line endings to unix style line endings. +<blockquote><pre> +<tokenfilter delimoutput="\n"/> +</pre></blockquote> + + +Remove blank lines. +<blockquote><pre> +<tokenfilter> + <ignoreblank/> +</tokenfilter> + +</pre></blockquote> + +<p><b><em><a name="filetokenizer">FileTokenizer</a></em></b></p> +This tokenizer treats <b>all</b> the input as a token. So be +careful not to use this on very large input. +<h4>Examples:</h4> + +Replace the first occurrence of package with //package. +<blockquote><pre> +<tokenfilter> + <filetokenizer/> + <replaceregex pattern="([\n\r]+[ \t]*|^[ \t]*)package" + flags="s" + replace="\1//package"/> +</tokenfilter> +</pre></blockquote> + +<p><b><em><a name="stringtokenizer">StringTokenizer</a></em></b></p> +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 <i>delimsaretokens</i> +attribute is used). + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>delims</td> + <td vAlign=top>The delimiter characters. White space + is used if this is not set. (White space is defined + in this case by java.lang.Character.isWhitespace()). + </td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td valign="top">delimsaretokens</td> + <td valign="top">If this is true, + each delimiter character is returned as a token. + Default is false. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">suppressdelims</td> + <td valign="top"> + If this is true, delimiters are not returned. + Default is false. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td vAlign=top>includeDelims</td> + <td vAlign=top> + Include the delimiters in the token. + Default is false. + </td> + <td vAlign=top align="center">No</td> + </tr> +</table> + +<h4>Examples:</h4> + +Surround each non space token with a "[]". + +<blockquote><pre> +<tokenfilter> + <stringtokenizer/> + <replaceregex pattern="(.+)" replace="[\1]"/> +</tokenfilter> + +</pre></blockquote> + +<p><b><em><a name="replacestring">ReplaceString</a></em></b></p> +This is a simple filter to replace strings. +This filter may be used directly within a filterchain. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>from</td> + <td vAlign=top>The string that must be replaced.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td valign="top">to</td> + <td valign="top">The new value for the replaced string. When omitted + an empty string is used. + </td> + <td valign="top" align="center">No</td> + </tr> +</table> + +<h4>Examples:</h4> + +Replace "sun" with "moon". + +<blockquote><pre> +<tokenfilter> + <replacestring from="sun" to="moon"/> +</tokenfilter> +</pre></blockquote> + +<p><b><em><a name="containsstring">ContainsString</a></em></b></p> +This is a simple filter to filter tokens that contains +a specified string. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>contains</td> + <td vAlign=top>The string that the token must contain.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> + +<h4>Examples:</h4> + +Include only lines that contain "foo"; + +<blockquote><pre> +<tokenfilter> + <containsstring contains="foo"/> +</tokenfilter> + +</pre></blockquote> + +<p><b><em><a name="replaceregex">ReplaceRegex</a></em></b></p> +This string filter replaces regular expressions. +This filter may be used directly within a filterchain. +<p> + See <a href="regexp.html#implementation">Regexp Type</a> +concerning the choice of the implementation. +</p> + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>pattern</td> + <td vAlign=top>The regular expression pattern to match in + the token.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td vAlign=top>replace</td> + <td vAlign=top>The substitution pattern to replace the matched + regular expression. When omitted an empty string is used.</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>flags</td> + <td vAlign=top>See +<a href="../Tasks/replaceregexp.html">ReplaceRegexp</a> +for an explanation of regex flags.</td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<h4>Examples:</h4> + +Replace all occurrences of "hello" with "world", ignoring case. + +<blockquote><pre> +<tokenfilter> + <replaceregex pattern="hello" replace="world" flags="gi"/> +</tokenfilter> + +</pre></blockquote> + +<p><b><em><a name="containsregex">ContainsRegex</a></em></b></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 filterchain. +<p> +See +<a href="regexp.html#implementation">Regexp Type</a> +concerning the choice of regular expression implementation. +</p> +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>pattern</td> + <td vAlign=top>The regular expression pattern to match in + the token.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td vAlign=top>replace</td> + <td vAlign=top>The substitution pattern to replace the matched + regular expression. When omitted the original token is returned. + </td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>flags</td> + <td vAlign=top>See +<a href="../Tasks/replaceregexp.html">ReplaceRegexp</a> +for an explanation of regex flags.</td> + <td vAlign=top align="center">No</td> + </tr> +</table> + +<h4>Examples:</h4> + +Filter lines that contain "hello" or "world", ignoring case. + +<blockquote><pre> +<tokenfilter> + <containsregex pattern="(hello|world)" flags="i"/> +</tokenfilter> + +</pre></blockquote> + +This example replaces lines like "SUITE(TestSuite, bits);" with +"void register_bits();" and removes other lines. + +<blockquote><pre> +<tokenfilter> + <containsregex + pattern="^ *SUITE\(.*,\s*(.*)\s*\).*" + replace="void register_\1();"/> +</tokenfilter> +</pre></blockquote> + +<p><b><em><a name="trim">Trim</a></em></b></p> +This filter trims whitespace from the start and end of +tokens. +This filter may be used directly within a filterchain. +<p><b><em><a name="ignoreblank">IgnoreBlank</a></em></b></p> +This filter removes empty tokens. +This filter may be used directly within a filterchain. +<p><b><em><a name="filterdeletecharacters">DeleteCharacters</a></em></b></p> +This filter deletes specified characters from tokens. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>chars</td> + <td vAlign=top>The characters to delete. This attribute + is backslash enabled.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> + +<h4>Examples:</h4> + +Delete tabs from lines, trim the lines and removes empty lines. + +<blockquote><pre> +<tokenfilter> + <deletecharacters chars="\t"/> + <trim/> + <ignoreblank/> +</tokenfilter> + +</pre></blockquote> + +<p><b><em><a name="uniqfilter">UniqFilter</a></em></b></p> + +<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 filterchain.</p> + +<h4>Example:</h4> + +This suppresses duplicate lines. +<blockquote><pre> +<tokenfilter> + <uniqfilter/> +</tokenfilter> +</pre></blockquote> + +<p><b><em><a name="scriptfilter">ScriptFilter</a></em></b></p> +This is an optional filter that executes a script in a +<a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a> + or + <a href="https://scripting.dev.java.net">JSR 223</a> +supported language.</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 <i>self</i> that has +getToken() and setToken(String) methods. +The getToken() method returns the current token. The setToken(String) +method replaces the current token. +</p> + +This filter may be used directly within a filterchain.<p> +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>language</td> + <td vAlign=top> The programming language the script is written in. +Must be a supported Apache BSF or JSR 223 language</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td valign="top">manager</td> + <td valign="top"> + The script engine manager to use. + See the <a href="../Tasks/script.html">script</a> task + for using this attribute. + </td> + <td valign="top" align="center">No - default is "auto"</td> + </tr> + <tr> + <td vAlign=top>src</td> + <td vAlign=top>The location of the script as a file, if not inline + </td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td valign="top">setbeans</td> + <td valign="top">whether to have all properties, references and targets as + global variables in the script. <em>since Ant 1.8.0</em></td> + <td valign="top" align="center">No, default is "true".</td> + </tr> + <tr> + <td valign="top">classpath</td> + <td valign="top"> + The classpath to pass into the script. + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">classpathref</td> + <td valign="top">The classpath to use, given as a + <a href="../using.html#references">reference</a> to a path defined elsewhere. + <td align="center" valign="top">No</td> + </tr> +</table> + <p> + This filter can take a nested <classpath> element. + See the <a href="../Tasks/script.html">script</a> task + on how to use this element. + </p> +<h4>Examples:</h4> + +Convert to uppercase: +<blockquote><pre> +<tokenfilter> + <scriptfilter language="javascript"> + self.setToken(self.getToken().toUpperCase()); + </scriptfilter> +</tokenfilter> +</pre></blockquote> + +Remove lines containing the string "bad" while +copying text files: + <blockquote> + <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> + </blockquote> + +<h4>Custom tokenizers and string filters</h4> + +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 <code><typedef/></code>. For +example a string filter that capitalizes words may be declared as: +<blockquote><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></blockquote> + +This may be used as follows: +<blockquote><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></blockquote> + + +<h3><a name="sortfilter">SortFilter</a></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>java.util.Comparator</code> interface to get even more + control.</p> + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>reverse</td> + <td vAlign=top align="center">whether to reverse the sort order, + defaults to false. <b>Note:</b> this parameter is ignored if + the comparator parameter is present as well.</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>comparator</td> + <td vAlign=top align="center">Class name of a class that + implements <code>java.util.Comparator</code> for Strings. This + class will be used to determine the sort order of lines.</td> + <td vAlign=top align="center">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> + +<blockquote><pre> + <copy todir="build"> + <fileset dir="input" includes="*.txt"/> + <filterchain> + <sortfilter/> + </filterchain> + </copy> +</pre></blockquote> + +<p> +Sort all files <code>*.txt</code> from <i>src</i> location +into <i>build</i> location. The lines of each file are sorted in +ascendant order comparing the lines via the +<code>String.compareTo(Object o)</code> method. +</p> + +<blockquote><pre> + <copy todir="build"> + <fileset dir="input" includes="*.txt"/> + <filterchain> + <sortfilter reverse="true"/> + </filterchain> + </copy> +</pre></blockquote> + +<p> +Sort all files <code>*.txt</code> from <i>src</i> location into reverse +order and copy them into <i>build</i> location. +</p> + +<blockquote><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></blockquote> + +<p> +Sort all files <code>*.txt</code> from <i>src</i> location using as +sorting criterium <code>EvenFirstCmp</code> class, that sorts the file +lines putting even lines first then odd lines for example. The modified files +are copied into <i>build</i> location. The <code>EvenFirstCmp</code>, +has to an instanciable class via <code>Class.newInstance()</code>, +therefore in case of inner class has to be <em>static</em>. It also has to +implement <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> + +<blockquote><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></blockquote> + +</body></html> |