source: release-kits/lirk3/resources/gs3-release-maker/ant/docs/manual/CoreTypes/filterchain.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

initial import of LiRK3
File size: 40.7 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2
3<HTML>
4<HEAD>
5 <TITLE>FilterChains and FilterReaders</TITLE>
6 <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
7</HEAD>
8
9<BODY>
10
11<H2>FilterChains and FilterReaders</H2>
12Look at Unix pipes - they offer you so much flexibility -
13say you wanted to copy just those lines that contained the
14string blee from the first 10 lines of a file 'foo'
15to a file 'bar' - you would do something like<P>
16<code>
17cat foo|head -n10|grep blee &gt; bar
18</code><P>
19Ant was not flexible enough. There was no way for the
20<code>&lt;copy&gt;</code> task to do something similar. If you wanted
21the <code>&lt;copy&gt;</code> task to get the first 10 lines, you would have
22had to create special attributes:<P>
23<code>
24&lt;copy file=&quot;foo&quot; tofile=&quot;bar&quot; head=&quot;10&quot; contains=&quot;blee&quot;/&gt;
25</code><P>
26The obvious problem thus surfaced: Ant tasks would not be able
27to accommodate such data transformation attributes as they would
28be endless. The task would also not know in which order these
29attributes were to be interpreted. That is, must the task execute the
30contains attribute first and then the head attribute or vice-versa?
31What Ant tasks needed was a mechanism to allow pluggable filter (data
32transformer) chains. Ant would provide a few filters for which there
33have been repeated requests. Users with special filtering needs
34would be able to easily write their own and plug them in.<P>
35
36The solution was to refactor data transformation oriented
37tasks to support FilterChains. A FilterChain is a group of
38ordered FilterReaders. Users can define their own FilterReaders
39by just extending the java.io.FilterReader class. Such custom
40FilterReaders can be easily plugged in as nested elements of
41<code>&lt;filterchain&gt;</code> by using <code>&lt;filterreader&gt;</code> elements.
42<P>
43Example:
44<BLOCKQUOTE><PRE>
45&lt;copy file=&quot;${src.file}&quot; tofile=&quot;${dest.file}&quot;&gt;
46 &lt;filterchain&gt;
47 &lt;filterreader classname=&quot;your.extension.of.java.io.FilterReader&quot;&gt;
48 &lt;param name=&quot;foo&quot; value=&quot;bar&quot;/&gt;
49 &lt;/filterreader&gt;
50 &lt;filterreader classname=&quot;another.extension.of.java.io.FilterReader&quot;&gt;
51 &lt;classpath&gt;
52 &lt;pathelement path="${classpath}"/&gt;
53 &lt;/classpath&gt;
54 &lt;param name=&quot;blah&quot; value=&quot;blee&quot;/&gt;
55 &lt;param type=&quot;abra&quot; value=&quot;cadabra&quot;/&gt;
56 &lt;/filterreader&gt;
57 &lt;/filterchain&gt;
58&lt;/copy&gt;
59</PRE></BLOCKQUOTE>
60
61Ant provides some built-in filter readers. These filter readers
62can also be declared using a syntax similar to the above syntax.
63However, they can be declared using some simpler syntax also.<P>
64Example:
65<BLOCKQUOTE><PRE>
66&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;src.file.head&quot;&gt;
67 &lt;filterchain&gt;
68 &lt;headfilter lines=&quot;15&quot;/&gt;
69 &lt;/filterchain&gt;
70&lt;/loadfile&gt;
71</PRE></BLOCKQUOTE>
72is equivalent to:
73<BLOCKQUOTE><PRE>
74&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;src.file.head&quot;&gt;
75 &lt;filterchain&gt;
76 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.HeadFilter&quot;&gt;
77 &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
78 &lt;/filterreader&gt;
79 &lt;/filterchain&gt;
80&lt;/loadfile&gt;
81</PRE></BLOCKQUOTE>
82
83The following built-in tasks support nested <code>&lt;filterchain&gt;</code> elements.<BR>
84<a href="../CoreTasks/concat.html">Concat</a>,<BR>
85<a href="../CoreTasks/copy.html">Copy</a>,<BR>
86<a href="../CoreTasks/loadfile.html">LoadFile</a>,<BR>
87<a href="../CoreTasks/loadproperties.html">LoadProperties</a>,<BR>
88<a href="../CoreTasks/move.html">Move</a><BR><BR>
89
90A FilterChain is formed by defining zero or more of the following
91nested elements.<BR>
92<a href="#filterreader">FilterReader</a><BR>
93<a href="#classconstants">ClassConstants</a><BR>
94<a href="#escapeunicode">EscapeUnicode</a><BR>
95<a href="#expandproperties">ExpandProperties</a><BR>
96<a href="#headfilter">HeadFilter</a><BR>
97<a href="#linecontains">LineContains</a><BR>
98<a href="#linecontainsregexp">LineContainsRegExp</a><BR>
99<a href="#prefixlines">PrefixLines</a><BR>
100<a href="#replacetokens">ReplaceTokens</a><BR>
101<a href="#stripjavacomments">StripJavaComments</a><BR>
102<a href="#striplinebreaks">StripLineBreaks</a><BR>
103<a href="#striplinecomments">StripLineComments</a><BR>
104<a href="#tabstospaces">TabsToSpaces</a><BR>
105<a href="#tailfilter">TailFilter</a><BR>
106<a href="#deletecharacters">DeleteCharacters</a><BR>
107<a href="#concatfilter">ConcatFilter</a><BR>
108<a href="#tokenfilter">TokenFilter</a><BR>
109
110<H3><a name="filterreader">FilterReader</a></H3>
111
112The filterreader element is the generic way to
113define a filter. User defined filter elements are
114defined in the build file using this. Please note that
115built in filter readers can also be defined using this
116syntax.
117
118A FilterReader element must be supplied with a class name as
119an attribute value. The class resolved by this name must
120extend java.io.FilterReader. If the custom filter reader
121needs to be parameterized, it must implement
122org.apache.tools.type.Parameterizable.
123
124<TABLE cellSpacing=0 cellPadding=2 border=1>
125 <TR>
126 <TD vAlign=top><B>Attribute</B></TD>
127 <TD vAlign=top><B>Description</B></TD>
128 <TD vAlign=top align="center"><B>Required</B></TD>
129 </TR>
130 <TR>
131 <TD vAlign=top>classname</TD>
132 <TD vAlign=top>The class name of the filter reader.</TD>
133 <TD vAlign=top align="center">Yes</TD>
134 </TR>
135</TABLE>
136
137<P>
138<H4>Nested Elements:</H4>
139<code>&lt;filterreader&gt;</code> supports <code>&lt;classpath&gt;</code> and <code>&lt;param&gt;</code>
140as nested elements. Each <code>&lt;param&gt;</code> element may take in the following
141attributes - name, type and value.
142<P>
143The following FilterReaders are supplied with the default
144distribution.
145
146<H3><a name="classconstants">ClassConstants</a></H3>
147<P>
148This filters basic constants defined in a Java Class,
149and outputs them in lines composed of the format name=value
150<P>
151<H4>Example:</H4>
152
153This loads the basic constants defined in a Java class as Ant properties.
154<BLOCKQUOTE><PRE>
155&lt;loadproperties srcfile=&quot;foo.class&quot;&gt;
156 &lt;filterchain&gt;
157 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ClassConstants&quot;/&gt;
158 &lt;/filterchain&gt;
159&lt;/loadproperties&gt;
160</PRE></BLOCKQUOTE>
161
162Convenience method:
163<BLOCKQUOTE><PRE>
164&lt;loadproperties srcfile=&quot;foo.class&quot;&gt;
165 &lt;filterchain&gt;
166 &lt;classconstants/&gt;
167 &lt;/filterchain&gt;
168&lt;/loadproperties&gt;
169</PRE></BLOCKQUOTE>
170
171<H3><a name="escapeunicode">EscapeUnicode</a></H3>
172<P>
173This filter converts its input by changing all non US-ASCII characters
174into their equivalent unicode escape backslash u plus 4 digits.</p>
175
176<P><em>since Ant 1.6</em></p>
177
178<H4>Example:</H4>
179
180This loads the basic constants defined in a Java class as Ant properties.
181<BLOCKQUOTE><PRE>
182&lt;loadproperties srcfile=&quot;non_ascii_property.properties&quot;&gt;
183 &lt;filterchain&gt;
184 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.EscapeUnicode&quot;/&gt;
185 &lt;/filterchain&gt;
186&lt;/loadproperties&gt;
187</PRE></BLOCKQUOTE>
188
189Convenience method:
190<BLOCKQUOTE><PRE>
191&lt;loadproperties srcfile=&quot;non_ascii_property.properties&quot;&gt;
192 &lt;filterchain&gt;
193 &lt;escapeunicode/&gt;
194 &lt;/filterchain&gt;
195&lt;/loadproperties&gt;
196</PRE></BLOCKQUOTE>
197
198<H3><a name="expandproperties">ExpandProperties</a></H3>
199<P>
200If the data contains data that represents Ant
201properties (of the form ${...}), that is substituted
202with the property's actual value.
203<P>
204<H4>Example:</H4>
205
206This results in the property modifiedmessage holding the value
207&quot;All these moments will be lost in time, like teardrops in the rain&quot;
208<BLOCKQUOTE><PRE>
209&lt;echo
210 message=&quot;All these moments will be lost in time, like teardrops in the ${weather}&quot;
211 file=&quot;loadfile1.tmp&quot;
212 /&gt;
213&lt;property name=&quot;weather&quot; value=&quot;rain&quot;/&gt;
214&lt;loadfile property=&quot;modifiedmessage&quot; srcFile=&quot;loadfile1.tmp&quot;&gt;
215 &lt;filterchain&gt;
216 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ExpandProperties&quot;/&gt;
217 &lt;/filterchain&gt;
218&lt;/loadfile&gt;
219</PRE></BLOCKQUOTE>
220
221Convenience method:
222<BLOCKQUOTE><PRE>
223&lt;echo
224 message=&quot;All these moments will be lost in time, like teardrops in the ${weather}&quot;
225 file=&quot;loadfile1.tmp&quot;
226 /&gt;
227&lt;property name=&quot;weather&quot; value=&quot;rain&quot;/&gt;
228&lt;loadfile property=&quot;modifiedmessage&quot; srcFile=&quot;loadfile1.tmp&quot;&gt;
229 &lt;filterchain&gt;
230 &lt;expandproperties/&gt;
231 &lt;/filterchain&gt;
232&lt;/loadfile&gt;
233</PRE></BLOCKQUOTE>
234
235<H3><a name="headfilter">HeadFilter</a></H3>
236
237This filter reads the first few lines from the data supplied to it.
238
239<TABLE cellSpacing=0 cellPadding=2 border=1>
240 <TR>
241 <TD vAlign=top><B>Parameter Name</B></TD>
242 <TD vAlign=top><B>Parameter Value</B></TD>
243 <TD vAlign=top align="center"><B>Required</B></TD>
244 </TR>
245 <TR>
246 <TD vAlign=top>lines</TD>
247 <TD vAlign=top align="center">Number of lines to be read.
248 Defaults to &quot;10&quot; <BR> A negative value means that all lines are
249 passed (useful with <I>skip</I>)</TD>
250 <TD vAlign=top align="center">No</TD>
251 </TR>
252 <TR>
253 <TD vAlign=top>skip</TD>
254 <TD vAlign=top align="center">Number of lines to be skipped (from the beginning).
255 Defaults to &quot;0&quot;</TD>
256 <TD vAlign=top align="center">No</TD>
257 </TR>
258</TABLE>
259<P>
260<H4>Example:</H4>
261
262This stores the first 15 lines of the supplied data in the property src.file.head
263<BLOCKQUOTE><PRE>
264&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;src.file.head&quot;&gt;
265 &lt;filterchain&gt;
266 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.HeadFilter&quot;&gt;
267 &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
268 &lt;/filterreader&gt;
269 &lt;/filterchain&gt;
270&lt;/loadfile&gt;
271</PRE></BLOCKQUOTE>
272
273Convenience method:
274<BLOCKQUOTE><PRE>
275&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;src.file.head&quot;&gt;
276 &lt;filterchain&gt;
277 &lt;headfilter lines=&quot;15&quot;/&gt;
278 &lt;/filterchain&gt;
279&lt;/loadfile&gt;
280</PRE></BLOCKQUOTE>
281
282This stores the first 15 lines, skipping the first 2 lines, of the supplied data
283in the property src.file.head. (Means: lines 3-17)
284<BLOCKQUOTE><PRE>
285&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;src.file.head&quot;&gt;
286 &lt;filterchain&gt;
287 &lt;headfilter lines=&quot;15&quot; skip=&quot;2&quot;/&gt;
288 &lt;/filterchain&gt;
289&lt;/loadfile&gt;
290</PRE></BLOCKQUOTE>
291
292See the testcases for more examples (<I>src\etc\testcases\filters\head-tail.xml</I> in the
293source distribution).
294
295<H3><a name="linecontains">LineContains</a></H3>
296
297This filter includes only those lines that contain all the user-specified
298strings.
299
300<TABLE cellSpacing=0 cellPadding=2 border=1>
301 <TR>
302 <TD vAlign=top><B>Parameter Type</B></TD>
303 <TD vAlign=top><B>Parameter Value</B></TD>
304 <TD vAlign=top align="center"><B>Required</B></TD>
305 </TR>
306 <TR>
307 <TD vAlign=top>contains</TD>
308 <TD vAlign=top align="center">Substring to be searched for.</TD>
309 <TD vAlign=top align="center">Yes</TD>
310 </TR>
311</TABLE>
312<P>
313<H4>Example:</H4>
314
315This will include only those lines that contain <code>foo</code> and
316<code>bar</code>.
317<BLOCKQUOTE><PRE>
318&lt;filterreader classname=&quot;org.apache.tools.ant.filters.LineContains&quot;&gt;
319 &lt;param type=&quot;contains&quot; value=&quot;foo&quot;/&gt;
320 &lt;param type=&quot;contains&quot; value=&quot;bar&quot;/&gt;
321&lt;/filterreader&gt;
322</PRE></BLOCKQUOTE>
323
324Convenience method:
325<BLOCKQUOTE><PRE>
326&lt;linecontains&gt;
327 &lt;contains value=&quot;foo&quot;/&gt;
328 &lt;contains value=&quot;bar&quot;/&gt;
329&lt;/linecontains&gt;
330</PRE></BLOCKQUOTE>
331
332<H3><a name="linecontainsregexp">LineContainsRegExp</a></H3>
333
334Filter which includes only those lines that contain the user-specified
335regular expression matching strings.
336
337See <a href="../CoreTypes/regexp.html">Regexp Type</a> for the description of the nested element regexp and of
338the choice of regular expression implementation.
339<H4>Example:</H4>
340
341This will fetch all those lines that contain the pattern <code>foo</code>
342<BLOCKQUOTE><PRE>
343&lt;filterreader classname=&quot;org.apache.tools.ant.filters.LineContainsRegExp&quot;&gt;
344 &lt;param type=&quot;regexp&quot; value=&quot;foo*&quot;/&gt;
345&lt;/filterreader&gt;
346</PRE></BLOCKQUOTE>
347
348Convenience method:
349<BLOCKQUOTE><PRE>
350&lt;linecontainsregexp&gt;
351 &lt;regexp pattern=&quot;foo*&quot;/&gt;
352&lt;/linecontainsregexp&gt;
353</PRE></BLOCKQUOTE>
354
355<H3><a name="prefixlines">PrefixLines</a></H3>
356
357Attaches a prefix to every line.
358
359<TABLE cellSpacing=0 cellPadding=2 border=1>
360 <TR>
361 <TD vAlign=top><B>Parameter Name</B></TD>
362 <TD vAlign=top><B>Parameter Value</B></TD>
363 <TD vAlign=top align="center"><B>Required</B></TD>
364 </TR>
365 <TR>
366 <TD vAlign=top>prefix</TD>
367 <TD vAlign=top align="center">Prefix to be attached to lines.</TD>
368 <TD vAlign=top align="center">Yes</TD>
369 </TR>
370</TABLE>
371<P>
372<H4>Example:</H4>
373
374This will attach the prefix <code>Foo</code> to all lines.
375<BLOCKQUOTE><PRE>
376&lt;filterreader classname=&quot;org.apache.tools.ant.filters.PrefixLines&quot;&gt;
377 &lt;param name=&quot;prefix&quot; value=&quot;Foo&quot;/&gt;
378&lt;/filterreader&gt;
379</PRE></BLOCKQUOTE>
380
381Convenience method:
382<BLOCKQUOTE><PRE>
383&lt;prefixlines prefix=&quot;Foo&quot;/&gt;
384</PRE></BLOCKQUOTE>
385
386<H3><a name="replacetokens">ReplaceTokens</a></H3>
387
388This filter reader replaces all strings that are
389sandwiched between begintoken and endtoken with
390user defined values.
391
392<TABLE cellSpacing=0 cellPadding=2 border=1>
393 <TR>
394 <TD vAlign=top><B>Parameter Type</B></TD>
395 <TD vAlign=top><B>Parameter Name</B></TD>
396 <TD vAlign=top><B>Parameter Value</B></TD>
397 <TD vAlign=top align="center"><B>Required</B></TD>
398 </TR>
399 <TR>
400 <TD vAlign=top>tokenchar</TD>
401 <TD vAlign=top>begintoken</TD>
402 <TD vAlign=top>Character marking the
403 beginning of a token. Defaults to @</TD>
404 <TD vAlign=top align="center">No</TD>
405 </TR>
406 <TR>
407 <TD vAlign=top>tokenchar</TD>
408 <TD vAlign=top>endtoken</TD>
409 <TD vAlign=top>Character marking the
410 end of a token. Defaults to @</TD>
411 <TD vAlign=top align="center">No</TD>
412 </TR>
413 <TR>
414 <TD vAlign=top>token</TD>
415 <TD vAlign=top>User defined String.</TD>
416 <TD vAlign=top>User defined search String</TD>
417 <TD vAlign=top align="center">Yes</TD>
418 </TR>
419</TABLE>
420<P>
421
422<H4>Example:</H4>
423
424This replaces occurrences of the string &#64;DATE&#64; in the data
425with today's date and stores it in the property ${src.file.replaced}
426<BLOCKQUOTE><PRE>
427&lt;tstamp/&gt;
428&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.replaced}&quot;&gt;
429 &lt;filterchain&gt;
430 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ReplaceTokens&quot;&gt;
431 &lt;param type=&quot;token&quot; name=&quot;DATE&quot; value=&quot;${TODAY}&quot;/&gt;
432 &lt;/filterreader&gt;
433 &lt;/filterchain&gt;
434&lt;/loadfile&gt;
435</PRE></BLOCKQUOTE>
436
437Convenience method:
438<BLOCKQUOTE><PRE>
439&lt;tstamp/&gt;
440&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.replaced}&quot;&gt;
441 &lt;filterchain&gt;
442 &lt;replacetokens&gt;
443 &lt;token key=&quot;DATE&quot; value=&quot;${TODAY}&quot;/&gt;
444 &lt;/replacetokens&gt;
445 &lt;/filterchain&gt;
446&lt;/loadfile&gt;
447</PRE></BLOCKQUOTE>
448
449<H3><a name="stripjavacomments">StripJavaComments</a></H3>
450
451This filter reader strips away comments from the data,
452using Java syntax guidelines. This filter does not
453take in any parameters.
454<P>
455<H4>Example:</H4>
456
457<BLOCKQUOTE><PRE>
458&lt;loadfile srcfile=&quot;${java.src.file}&quot; property=&quot;${java.src.file.nocomments}&quot;&gt;
459 &lt;filterchain&gt;
460 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripJavaComments&quot;/&gt;
461 &lt;/filterchain&gt;
462&lt;/loadfile&gt;
463</PRE></BLOCKQUOTE>
464
465Convenience method:
466<BLOCKQUOTE><PRE>
467&lt;loadfile srcfile=&quot;${java.src.file}&quot; property=&quot;${java.src.file.nocomments}&quot;&gt;
468 &lt;filterchain&gt;
469 &lt;stripjavacomments/&gt;
470 &lt;/filterchain&gt;
471&lt;/loadfile&gt;
472</PRE></BLOCKQUOTE>
473
474<H3><a name="striplinebreaks">StripLineBreaks</a></H3>
475
476This filter reader strips away specific characters
477from the data supplied to it.
478
479<TABLE cellSpacing=0 cellPadding=2 border=1>
480 <TR>
481 <TD vAlign=top><B>Parameter Name</B></TD>
482 <TD vAlign=top><B>Parameter Value</B></TD>
483 <TD vAlign=top align="center"><B>Required</B></TD>
484 </TR>
485 <TR>
486 <TD vAlign=top>linebreaks</TD>
487 <TD vAlign=top align="center">Characters that are to
488 be stripped out. Defaults to &quot;\r\n&quot;</TD>
489 <TD vAlign=top align="center">No</TD>
490 </TR>
491</TABLE>
492<P>
493<H4>Examples:</H4>
494
495This strips the '\r' and '\n' characters.
496<BLOCKQUOTE><PRE>
497&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.contents}&quot;&gt;
498 &lt;filterchain&gt;
499 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineBreaks&quot;/&gt;
500 &lt;/filterchain&gt;
501&lt;/loadfile&gt;
502</PRE></BLOCKQUOTE>
503
504Convenience method:
505<BLOCKQUOTE><PRE>
506&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.contents}&quot;&gt;
507 &lt;filterchain&gt;
508 &lt;striplinebreaks/&gt;
509 &lt;/filterchain&gt;
510&lt;/loadfile&gt;
511</PRE></BLOCKQUOTE>
512
513This treats the '(' and ')' characters as line break characters and
514strips them.
515<BLOCKQUOTE><PRE>
516&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.contents}&quot;&gt;
517 &lt;filterchain&gt;
518 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineBreaks&quot;&gt;
519 &lt;param name=&quot;linebreaks&quot; value=&quot;()&quot;/&gt;
520 &lt;/filterreader&gt;
521 &lt;/filterchain&gt;
522&lt;/loadfile&gt;
523</PRE></BLOCKQUOTE>
524
525<H3><a name="striplinecomments">StripLineComments</a></H3>
526
527This filter removes all those lines that begin with strings
528that represent comments as specified by the user.
529
530<TABLE cellSpacing=0 cellPadding=2 border=1>
531 <TR>
532 <TD vAlign=top><B>Parameter Type</B></TD>
533 <TD vAlign=top><B>Parameter Value</B></TD>
534 <TD vAlign=top align="center"><B>Required</B></TD>
535 </TR>
536 <TR>
537 <TD vAlign=top>comment</TD>
538 <TD vAlign=top align="center">Strings that identify a line as a comment
539 when they appear at the start of the line.</TD>
540 <TD vAlign=top align="center">Yes</TD>
541 </TR>
542</TABLE>
543<P>
544<H4>Examples:</H4>
545
546This removes all lines that begin with #, --, REM, rem and //
547<BLOCKQUOTE><PRE>
548&lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineComments&quot;&gt;
549 &lt;param type=&quot;comment&quot; value=&quot;#&quot;/&gt;
550 &lt;param type=&quot;comment&quot; value=&quot;--&quot;/&gt;
551 &lt;param type=&quot;comment&quot; value=&quot;REM &quot;/&gt;
552 &lt;param type=&quot;comment&quot; value=&quot;rem &quot;/&gt;
553 &lt;param type=&quot;comment&quot; value=&quot;//&quot;/&gt;
554&lt;/filterreader&gt;
555</PRE></BLOCKQUOTE>
556
557Convenience method:
558<BLOCKQUOTE><PRE>
559&lt;striplinecomments&gt;
560 &lt;comment value=&quot;#&quot;/&gt;
561 &lt;comment value=&quot;--&quot;/&gt;
562 &lt;comment value=&quot;REM &quot;/&gt;
563 &lt;comment value=&quot;rem &quot;/&gt;
564 &lt;comment value=&quot;//&quot;/&gt;
565&lt;/striplinecomments&gt;
566</PRE></BLOCKQUOTE>
567
568<H3><a name="tabstospaces">TabsToSpaces</a></H3>
569
570This filter replaces tabs with spaces
571
572<TABLE cellSpacing=0 cellPadding=2 border=1>
573 <TR>
574 <TD vAlign=top><B>Parameter Name</B></TD>
575 <TD vAlign=top><B>Parameter Value</B></TD>
576 <TD vAlign=top align="center"><B>Required</B></TD>
577 </TR>
578 <TR>
579 <TD vAlign=top>tablength</TD>
580 <TD vAlign=top align="center">Defaults to &quot;8&quot;</TD>
581 <TD vAlign=top align="center">No</TD>
582 </TR>
583</TABLE>
584<P>
585<H4>Examples:</H4>
586
587This replaces tabs in ${src.file} with spaces.
588<BLOCKQUOTE><PRE>
589&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.notab}&quot;&gt;
590 &lt;filterchain&gt;
591 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.TabsToSpaces&quot;/&gt;
592 &lt;/filterchain&gt;
593&lt;/loadfile&gt;
594</PRE></BLOCKQUOTE>
595
596Convenience method:
597<BLOCKQUOTE><PRE>
598&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.notab}&quot;&gt;
599 &lt;filterchain&gt;
600 &lt;tabstospaces/&gt;
601 &lt;/filterchain&gt;
602&lt;/loadfile&gt;
603</PRE></BLOCKQUOTE>
604
605<H3><a name="tailfilter">TailFilter</a></H3>
606
607This filter reads the last few lines from the data supplied to it.
608
609<TABLE cellSpacing=0 cellPadding=2 border=1>
610 <TR>
611 <TD vAlign=top><B>Parameter Name</B></TD>
612 <TD vAlign=top><B>Parameter Value</B></TD>
613 <TD vAlign=top align="center"><B>Required</B></TD>
614 </TR>
615 <TR>
616 <TD vAlign=top>lines</TD>
617 <TD vAlign=top align="center">Number of lines to be read.
618 Defaults to &quot;10&quot; <BR> A negative value means that all lines are
619 passed (useful with <I>skip</I>)</TD>
620 <TD vAlign=top align="center">No</TD>
621 </TR>
622 <TR>
623 <TD vAlign=top>skip</TD>
624 <TD vAlign=top align="center">Number of lines to be skipped (from the end).
625 Defaults to &quot;0&quot; </TD>
626 <TD vAlign=top align="center">No</TD>
627 </TR>
628</TABLE>
629<P>
630
631<H4>Background:</H4>
632With HeadFilter and TailFilter you can extract each part of a text file you want.
633This graphic shows the dependencies:
634
635<TABLE cellSpacing=0 cellPadding=2 border=1>
636<TR>
637 <TH> Content </TH>
638 <TH></TH>
639 <TH></TH>
640 <TH></TH>
641 <TH> Filter </TH>
642</TR>
643<TR>
644 <TD> Line 1 </TD>
645 <TD rowspan="2" bgcolor="#C0C0C0">&nbsp;</TD>
646 <TD rowspan="9" bgcolor="#FF00FF">&nbsp;</TD>
647 <TD rowspan="4">&nbsp;</TD>
648 <TD rowspan="11">
649 <TABLE>
650 <TR>
651 <TD bgcolor="#C0C0C0">&nbsp;</TD>
652 <TD><PRE>&lt;filterchain&gt;
653 &lt;headfilter lines="2"/&gt;
654&lt;/filterchain&gt;</PRE></TD>
655 </TR>
656 <TR>
657 <TD bgcolor="#FF00FF">&nbsp;</TD>
658 <TD><PRE>&lt;filterchain&gt;
659 &lt;tailfilter lines="-1" skip="2"/&gt;
660&lt;/filterchain&gt;</PRE></TD>
661 </TR>
662 <TR>
663 <TD bgcolor="#008000">&nbsp;</TD>
664 <TD><PRE>&lt;filterchain&gt;
665 &lt;headfilter lines="-1" skip="2"/&gt;
666&lt;/filterchain&gt;</PRE></TD>
667 </TR>
668 <TR>
669 <TD bgcolor="#0000FF">&nbsp;</TD>
670 <TD><PRE>&lt;filterchain&gt;
671 &lt;headfilter lines="-1" skip="2"/&gt;
672 &lt;tailfilter lines="-1" skip="2"/&gt;
673&lt;/filterchain&gt;</PRE></TD>
674 </TR>
675 <TR>
676 <TD bgcolor="#00FF00">&nbsp;</TD>
677 <TD><PRE>&lt;filterchain&gt;
678 &lt;tailfilter lines="2"/&gt;
679&lt;/filterchain&gt;</PRE></TD>
680 </TR>
681 </TABLE>
682 </TD>
683</TR>
684<TR>
685 <TD> Line 2 </TD>
686</TR>
687<TR>
688 <TD> Line 3 </TD>
689 <TD rowspan="9" bgcolor="#008000">&nbsp;</TD>
690</TR>
691<TR>
692 <TD> Line 4 </TD>
693</TR>
694<TR>
695 <TD> Line 5 </TD>
696 <TD rowspan="3" bgcolor="#0000FF">&nbsp;</TD>
697</TR>
698<TR>
699 <TD> Lines ... </TD>
700</TR>
701<TR>
702 <TD> Line 95 </TD>
703</TR>
704<TR>
705 <TD> Line 96 </TD>
706 <TD rowspan="4">&nbsp;</TD>
707</TR>
708<TR>
709 <TD> Line 97 </TD>
710</TR>
711<TR>
712 <TD> Line 98 </TD>
713 <TD rowspan="2" bgcolor="#00FF00">&nbsp;</TD>
714</TR>
715<TR>
716 <TD> Line 99 </TD>
717</TR>
718</TABLE>
719
720
721
722<H4>Examples:</H4>
723
724This stores the last 15 lines of the supplied data in the property ${src.file.tail}
725<BLOCKQUOTE><PRE>
726&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.tail}&quot;&gt;
727 &lt;filterchain&gt;
728 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.TailFilter&quot;&gt;
729 &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
730 &lt;/filterreader&gt;
731 &lt;/filterchain&gt;
732&lt;/loadfile&gt;
733</PRE></BLOCKQUOTE>
734
735Convenience method:
736<BLOCKQUOTE><PRE>
737&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.tail}&quot;&gt;
738 &lt;filterchain&gt;
739 &lt;tailfilter lines=&quot;15&quot;/&gt;
740 &lt;/filterchain&gt;
741&lt;/loadfile&gt;
742</PRE></BLOCKQUOTE>
743
744
745This stores the last 5 lines of the first 15 lines of the supplied
746data in the property ${src.file.mid}
747<BLOCKQUOTE><PRE>
748&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.mid}&quot;&gt;
749 &lt;filterchain&gt;
750 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.HeadFilter&quot;&gt;
751 &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
752 &lt;/filterreader&gt;
753 &lt;filterreader classname=&quot;org.apache.tools.ant.filters.TailFilter&quot;&gt;
754 &lt;param name=&quot;lines&quot; value=&quot;5&quot;/&gt;
755 &lt;/filterreader&gt;
756 &lt;/filterchain&gt;
757&lt;/loadfile&gt;
758</PRE></BLOCKQUOTE>
759
760Convenience method:
761<BLOCKQUOTE><PRE>
762&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.mid}&quot;&gt;
763 &lt;filterchain&gt;
764 &lt;headfilter lines=&quot;15&quot;/&gt;
765 &lt;tailfilter lines=&quot;5&quot;/&gt;
766 &lt;/filterchain&gt;
767&lt;/loadfile&gt;
768</PRE></BLOCKQUOTE>
769
770
771This stores the last 10 lines, skipping the last 2 lines, of the supplied data
772in the property src.file.head. (Means: if supplied data contains 60 lines,
773lines 49-58 are extracted)
774<BLOCKQUOTE><PRE>
775&lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;src.file.head&quot;&gt;
776 &lt;filterchain&gt;
777 &lt;tailfilter lines=&quot;10&quot; skip=&quot;2&quot;/&gt;
778 &lt;/filterchain&gt;
779&lt;/loadfile&gt;
780</PRE></BLOCKQUOTE>
781
782<H3><a name="deletecharacters">DeleteCharacters</a></H3>
783
784 <p>This filter deletes specified characters.</p>
785 <p><em>since Ant 1.6</em></p>
786 <p>This filter is only available in the convenience form.</p>
787
788<TABLE cellSpacing=0 cellPadding=2 border=1>
789 <TR>
790 <TD vAlign=top><B>Parameter Name</B></TD>
791 <TD vAlign=top><B>Parameter Value</B></TD>
792 <TD vAlign=top align="center"><B>Required</B></TD>
793 </TR>
794 <TR>
795 <TD vAlign=top>chars</TD>
796 <TD vAlign=top>
797 The characters to delete. This attribute is
798 <a href="#backslash">backslash enabled</a>.
799 </TD>
800 <TD vAlign=top align="center">Yes</TD>
801 </TR>
802</TABLE>
803<P>
804<H4>Examples:</H4>
805
806Delete tabs and returns from the data.
807<BLOCKQUOTE><PRE>
808&lt;deletecharacters chars="\t\r"/&gt;
809</PRE></BLOCKQUOTE>
810
811<H3><a name="concatfilter">ConcatFilter</a></H3>
812 <p>This filter prepends or appends the content file to the filtered files.</p>
813 <p><em>since Ant 1.6</em></p>
814<TABLE cellSpacing=0 cellPadding=2 border=1>
815 <TR>
816 <TD vAlign=top><B>Parameter Name</B></TD>
817 <TD vAlign=top><B>Parameter Value</B></TD>
818 <TD vAlign=top align="center"><B>Required</B></TD>
819 </TR>
820 <TR>
821 <TD vAlign=top>prepend</TD>
822 <TD vAlign=top>
823 The name of the file which content should be prepended to the file.
824 </TD>
825 <TD vAlign=top align="center">No</TD>
826 </TR>
827 <TR>
828 <TD vAlign=top>append</TD>
829 <TD vAlign=top>
830 The name of the file which content should be appended to the file.
831 </TD>
832 <TD vAlign=top align="center">No</TD>
833 </TR>
834</TABLE>
835<P>
836
837<H4>Examples:</H4>
838
839Do nothing:
840<BLOCKQUOTE><PRE>
841&lt;filterchain&gt;
842 &lt;concatfilter/&gt;
843&lt;/filterchain&gt;
844</PRE></BLOCKQUOTE>
845
846Adds a license text before each java source:
847<BLOCKQUOTE><PRE>
848&lt;filterchain&gt;
849 &lt;concatfilter prepend="apache-license-java.txt"/&gt;
850&lt;/filterchain&gt;
851</PRE></BLOCKQUOTE>
852
853
854
855<H3><a name="tokenfilter">TokenFilter</a></H3>
856This filter tokenizes the inputstream into strings and passes these
857strings to filters of strings. Unlike the other filterreaders, this does
858not support params, only convenience methods are implemented.
859The tokenizer and the string filters are defined by nested elements.
860<P><em>since Ant 1.6</em></p>
861<P>
862Only one tokenizer element may be used, the LineTokenizer is the
863default if none are specified. A tokenizer
864splits the input into token strings and trailing delimiter strings.
865<P>
866There may be zero or more string filters. A string filter processes
867a token and either returns a string or a null.
868It the string is not null it is passed to the next filter. This
869proceeds until all the filters are called.
870If a string is returned after all the filters, the string is
871outputs with its associated token delimitier
872(if one is present).
873The trailing delimiter may be overridden by the <i>delimOutput</i>
874attribute.
875<P>
876<a name="backslash"><em>blackslash interpretation</em></a>
877A number of attributes (including <i>delimOutput</i>) interpret
878backslash escapes. The following are understood: \n, \r, \f, \t
879and \\.
880
881
882<TABLE cellSpacing=0 cellPadding=2 border=1>
883 <TR>
884 <TD vAlign=top><B>Attribute</B></TD>
885 <TD vAlign=top><B>Description</B></TD>
886 <TD vAlign=top align="center"><B>Required</B></TD>
887 </TR>
888 <TR>
889 <TD vAlign=top>delimOutput</TD>
890 <TD vAlign=top>
891 This overrides the tokendelimiter
892 returned by the tokenizer if it is not empty. This
893 attribute is backslash enabled.
894</TD>
895 <TD vAlign=top align="center">No</TD>
896 </TR>
897</TABLE>
898<P>
899
900 The following tokenizers are provided by the default distribution.
901 <p>
902 <a href="#linetokenizer">LineTokenizer</a><br>
903 <a href="#filetokenizer">FileTokenizer</a><br>
904 <a href="#stringtokenizer">StringTokenizer</a><br>
905 </p>
906
907 The following string filters are provided by the default distribution.
908 <p>
909 <a href="#replacestring">ReplaceString</a><br>
910 <a href="#containsstring">ContainsString</a><br>
911 <a href="#replaceregex">ReplaceRegex</a><br>
912 <a href="#containsregex">ContainsRegex</a><br>
913 <a href="#trim">Trim</a><br>
914 <a href="#ignoreblank">IgnoreBlank</a><br>
915 <a href="#filterdeletecharacters">DeleteCharacters</a><br>
916 </p>
917
918 The following string filters are provided by the optional distribution.
919 <p>
920 <a href="#scriptfilter">ScriptFilter</a><br>
921 </p>
922
923Some of the filters may be used directly within a filter chain. In this
924case a tokenfilter is created implicitly. An extra attribute "byline"
925is added to the filter to specify whether to use a linetokenizer
926(byline="true") or a filetokenizer (byline="false"). The default
927is "true".
928<P>
929
930<p><b><em><a name="linetokenizer">LineTokenizer</a></em></b></p>
931This tokenizer splits the input into lines.
932The tokenizer delimits lines
933by "\r", "\n" or "\r\n".
934This is the default tokenizer.
935<TABLE cellSpacing=0 cellPadding=2 border=1>
936 <TR>
937 <TD vAlign=top><B>Attribute</B></TD>
938 <TD vAlign=top><B>Description</B></TD>
939 <TD vAlign=top align="center"><B>Required</B></TD>
940 </TR>
941 <TR>
942 <TD vAlign=top>includeDelims</TD>
943 <TD vAlign=top>
944 Include the line endings in the token.
945 Default is false.
946 </TD>
947 <TD vAlign=top align="center">No</TD>
948 </TR>
949</TABLE>
950<H4>Examples:</H4>
951
952Convert input current line endings to unix style line endings.
953<BLOCKQUOTE><PRE>
954&lt;tokenfilter delimoutput=&quot;\n&quot;/&gt;
955</PRE></BLOCKQUOTE>
956
957
958Remove blank lines.
959<BLOCKQUOTE><PRE>
960&lt;tokenfilter&gt;
961 &lt;ignoreblank/&gt;
962&lt;/tokenfilter&gt;
963
964</PRE></BLOCKQUOTE>
965
966<p><b><em><a name="filetokenizer">FileTokenizer</a></em></b></p>
967This tokenizer treats <b>all</b> the input as a token. So be
968careful not to use this on very large input.
969<H4>Examples:</H4>
970
971Replace the first occurrence of package with //package.
972<BLOCKQUOTE><PRE>
973&lt;tokenfilter&gt;
974 &lt;filetokenizer/&gt;
975 &lt;replaceregex pattern="([\n\r]+[ \t]*|^[ \t]*)package"
976 flags="s"
977 replace="\1//package"/&gt;
978&lt;/tokenfilter&gt;
979</PRE></BLOCKQUOTE>
980
981<p><b><em><a name="stringtokenizer">StringTokenizer</a></em></b></p>
982This tokenizer is based on java.util.StringTokenizer.
983It splits up the input into strings separated by white space, or
984by a specified list of delimiting characters.
985If the stream starts with delimiter characters, the first
986token will be the empty string (unless the <i>delimsaretokens</i>
987attribute is used).
988
989<TABLE cellSpacing=0 cellPadding=2 border=1>
990 <TR>
991 <TD vAlign=top><B>Attribute</B></TD>
992 <TD vAlign=top><B>Description</B></TD>
993 <TD vAlign=top align="center"><B>Required</B></TD>
994 </TR>
995 <TR>
996 <TD vAlign=top>delims</TD>
997 <TD vAlign=top>The delimiter characters. White space
998 is used if this is not set. (White space is defined
999 in this case by java.lang.Character.isWhitespace()).
1000 </TD>
1001 <TD vAlign=top align="center">No</TD>
1002 </TR>
1003 <tr>
1004 <td valign="top">delimsaretokens</td>
1005 <td valign="top">If this is true,
1006 each delimiter character is returned as a token.
1007 Default is false.
1008 </td>
1009 <td valign="top" align="center">No</td>
1010 </tr>
1011 <tr>
1012 <td valign="top">suppressdelims</td>
1013 <td valign="top">
1014 If this is true, delimiters are not returned.
1015 Default is false.
1016 </td>
1017 <td valign="top" align="center">No</td>
1018 </tr>
1019 <tr>
1020 <td vAlign=top>includeDelims</td>
1021 <td vAlign=top>
1022 Include the delimiters in the token.
1023 Default is false.
1024 </td>
1025 <td vAlign=top align="center">No</td>
1026 </tr>
1027</TABLE>
1028
1029<H4>Examples:</H4>
1030
1031Surround each non space token with a "[]".
1032
1033<BLOCKQUOTE><PRE>
1034&lt;tokenfilter&gt;
1035 &lt;stringtokenizer/&gt;
1036 &lt;replaceregex pattern="(.+)" replace="[\1]"/&gt;
1037&lt;/tokenfilter&gt;
1038
1039</PRE></BLOCKQUOTE>
1040
1041<p><b><em><a name="replacestring">ReplaceString</a></em></b></p>
1042This is a simple filter to replace strings.
1043This filter may be used directly within a filterchain.
1044
1045<TABLE cellSpacing=0 cellPadding=2 border=1>
1046 <TR>
1047 <TD vAlign=top><B>Attribute</B></TD>
1048 <TD vAlign=top><B>Description</B></TD>
1049 <TD vAlign=top align="center"><B>Required</B></TD>
1050 </TR>
1051 <TR>
1052 <TD vAlign=top>from</TD>
1053 <TD vAlign=top>The string that must be replaced.</TD>
1054 <TD vAlign=top align="center">Yes</TD>
1055 </TR>
1056 <tr>
1057 <td valign="top">to</td>
1058 <td valign="top">The new value for the replaced string. When omitted
1059 an empty string is used.
1060 </td>
1061 <td valign="top" align="center">No</td>
1062 </tr>
1063</TABLE>
1064
1065<H4>Examples:</H4>
1066
1067Replace "sun" with "moon".
1068
1069<BLOCKQUOTE><PRE>
1070&lt;tokenfilter&gt;
1071 &lt;replacestring from="sun" to="moon"/&gt;
1072&lt;/tokenfilter&gt;
1073</PRE></BLOCKQUOTE>
1074
1075<p><b><em><a name="containsstring">ContainsString</a></em></b></p>
1076This is a simple filter to filter tokens that contains
1077a specified string.
1078
1079<TABLE cellSpacing=0 cellPadding=2 border=1>
1080 <TR>
1081 <TD vAlign=top><B>Attribute</B></TD>
1082 <TD vAlign=top><B>Description</B></TD>
1083 <TD vAlign=top align="center"><B>Required</B></TD>
1084 </TR>
1085 <TR>
1086 <TD vAlign=top>contains</TD>
1087 <TD vAlign=top>The string that the token must contain.</TD>
1088 <TD vAlign=top align="center">Yes</TD>
1089 </TR>
1090</TABLE>
1091
1092<H4>Examples:</H4>
1093
1094Include only lines that contain "foo";
1095
1096<BLOCKQUOTE><PRE>
1097&lt;tokenfilter&gt;
1098 &lt;containsstring contains="foo"/&gt;
1099&lt;/tokenfilter&gt;
1100
1101</PRE></BLOCKQUOTE>
1102
1103<p><b><em><a name="replaceregex">ReplaceRegex</a></em></b></p>
1104This string filter replaces regular expressions.
1105This filter may be used directly within a filterchain.
1106<p>
1107 See <a href="../CoreTypes/regexp.html#implementation">Regexp Type</a>
1108concerning the choice of the implementation.
1109</p>
1110
1111<TABLE cellSpacing=0 cellPadding=2 border=1>
1112 <TR>
1113 <TD vAlign=top><B>Attribute</B></TD>
1114 <TD vAlign=top><B>Description</B></TD>
1115 <TD vAlign=top align="center"><B>Required</B></TD>
1116 </TR>
1117 <TR>
1118 <TD vAlign=top>pattern</TD>
1119 <TD vAlign=top>The regular expression pattern to match in
1120 the token.</TD>
1121 <TD vAlign=top align="center">Yes</TD>
1122 </TR>
1123 <TR>
1124 <TD vAlign=top>replace</TD>
1125 <TD vAlign=top>The substitution pattern to replace the matched
1126 regular expression. When omitted an empty string is used.</TD>
1127 <TD vAlign=top align="center">No</TD>
1128 </TR>
1129 <TR>
1130 <TD vAlign=top>flags</TD>
1131 <TD vAlign=top>See
1132<a href="../OptionalTasks/replaceregexp.html">ReplaceRegexp</a>
1133for an explanation of regex flags.</TD>
1134 <TD vAlign=top align="center">No</TD>
1135 </TR>
1136</TABLE>
1137<H4>Examples:</H4>
1138
1139Replace all occurrences of "hello" with "world", ignoring case.
1140
1141<BLOCKQUOTE><PRE>
1142&lt;tokenfilter&gt;
1143 &lt;replaceregex pattern="hello" replace="world" flags="gi"/&gt;
1144&lt;/tokenfilter&gt;
1145
1146</PRE></BLOCKQUOTE>
1147
1148<p><b><em><a name="containsregex">ContainsRegex</a></em></b></p>
1149This filters strings that match regular expressions.
1150The filter may optionally replace the matched regular expression.
1151This filter may be used directly within a filterchain.
1152<p>
1153See
1154<a href="../CoreTypes/regexp.html#implementation">Regexp Type</a>
1155concerning the choice of regular expression implementation.
1156</p>
1157<TABLE cellSpacing=0 cellPadding=2 border=1>
1158 <TR>
1159 <TD vAlign=top><B>Attribute</B></TD>
1160 <TD vAlign=top><B>Description</B></TD>
1161 <TD vAlign=top align="center"><B>Required</B></TD>
1162 </TR>
1163 <TR>
1164 <TD vAlign=top>pattern</TD>
1165 <TD vAlign=top>The regular expression pattern to match in
1166 the token.</TD>
1167 <TD vAlign=top align="center">Yes</TD>
1168 </TR>
1169 <TR>
1170 <TD vAlign=top>replace</TD>
1171 <TD vAlign=top>The substitution pattern to replace the matched
1172 regular expression. When omitted the orignal token is returned.
1173 </TD>
1174 <TD vAlign=top align="center">No</TD>
1175 </TR>
1176 <TR>
1177 <TD vAlign=top>flags</TD>
1178 <TD vAlign=top>See
1179<a href="../OptionalTasks/replaceregexp.html">ReplaceRegexp</a>
1180for an explanation of regex flags.</TD>
1181 <TD vAlign=top align="center">No</TD>
1182 </TR>
1183</TABLE>
1184
1185<H4>Examples:</H4>
1186
1187Filter lines that contain "hello" or "world", ignoring case.
1188
1189<BLOCKQUOTE><PRE>
1190&lt;tokenfilter&gt;
1191 &lt;containsregex pattern="(hello|world)" flags="i"/&gt;
1192&lt;/tokenfilter&gt;
1193
1194</PRE></BLOCKQUOTE>
1195
1196This example replaces lines like "SUITE(TestSuite, bits);" with
1197"void register_bits();" and removes other lines.
1198
1199<BLOCKQUOTE><PRE>
1200&lt;tokenfilter&gt;
1201 &lt;containsregex
1202 pattern="^ *SUITE\(.*,\s*(.*)\s*\).*"
1203 replace="void register_\1();"/&gt;
1204&lt;/tokenfilter&gt;
1205</PRE></BLOCKQUOTE>
1206
1207<p><b><em><a name="trim">Trim</a></em></b></p>
1208This filter trims whitespace from the start and end of
1209tokens.
1210This filter may be used directly within a filterchain.
1211<p><b><em><a name="ignoreblank">IgnoreBlank</a></em></b></p>
1212This filter removes empty tokens.
1213This filter may be used directly within a filterchain.
1214<p><b><em><a name="filterdeletecharacters">DeleteCharacters</a></em></b></p>
1215This filter deletes specified characters from tokens.
1216
1217<TABLE cellSpacing=0 cellPadding=2 border=1>
1218 <TR>
1219 <TD vAlign=top><B>Attribute</B></TD>
1220 <TD vAlign=top><B>Description</B></TD>
1221 <TD vAlign=top align="center"><B>Required</B></TD>
1222 </TR>
1223 <TR>
1224 <TD vAlign=top>chars</TD>
1225 <TD vAlign=top>The characters to delete. This attribute
1226 is backslash enabled.</TD>
1227 <TD vAlign=top align="center">Yes</TD>
1228 </TR>
1229</TABLE>
1230
1231<H4>Examples:</H4>
1232
1233Delete tabs from lines, trim the lines and removes empty lines.
1234
1235<BLOCKQUOTE><PRE>
1236&lt;tokenfilter&gt;
1237 &lt;deletecharacters chars="\t"/&gt;
1238 &lt;trim/&gt;
1239 &lt;ignoreblank/&gt;
1240&lt;/tokenfilter&gt;
1241
1242</PRE></BLOCKQUOTE>
1243
1244<p><b><em><a name="scriptfilter">ScriptFilter</a></em></b></p>
1245This is an optional filter that executes a script in a
1246<a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a>
1247supported language.</p>
1248See the <a href="../OptionalTasks/script.html">Script</a> task for
1249an explanation of scripts and dependencies.
1250</p>
1251<p>
1252The script is provided with an object <i>self</i> that has
1253getToken() and setToken(String) methods.
1254The getToken() method returns the current token. The setToken(String)
1255method replaces the current token.
1256</p>
1257
1258This filter may be used directly within a filterchain.<p>
1259<TABLE cellSpacing=0 cellPadding=2 border=1>
1260 <TR>
1261 <TD vAlign=top><B>Attribute</B></TD>
1262 <TD vAlign=top><B>Description</B></TD>
1263 <TD vAlign=top align="center"><B>Required</B></TD>
1264 </TR>
1265 <TR>
1266 <TD vAlign=top>language</TD>
1267 <TD vAlign=top> The programming language the script is written in.
1268Must be a supported Apache BSF language</TD>
1269 <TD vAlign=top align="center">Yes</TD>
1270 </TR>
1271 <TR>
1272 <TD vAlign=top>src</TD>
1273 <TD vAlign=top>The location of the script as a file, if not inline
1274 </TD>
1275 <TD vAlign=top align="center">No</TD>
1276 </TR>
1277 <TR>
1278</TABLE>
1279
1280<H4>Examples:</H4>
1281
1282Convert to uppercase:
1283<BLOCKQUOTE><PRE>
1284&lt;tokenfilter&gt;
1285 &lt;scriptfilter language="javascript"&gt;
1286 self.setToken(self.getToken().toUpperCase());
1287 &lt;/scriptfilter&gt;
1288&lt;/tokenfilter&gt;
1289</PRE></BLOCKQUOTE>
1290
1291Remove lines containing the string "bad" while
1292copying text files:
1293 <blockquote>
1294 <pre>
1295&lt;copy todir="dist"&gt;
1296 &lt;fileset dir="src" includes="**/*.txt"/&gt;
1297 &lt;scriptfilter language="beanshell"&gt;
1298 if (self.getToken().indexOf("bad") != -1) {
1299 self.setToken(null);
1300 }
1301 &lt;/scriptfilter&gt;
1302&lt;/copy&gt;
1303 </pre>
1304 </blockquote>
1305
1306<H4>Custom tokenizers and string filters</H4>
1307
1308Custom string filters and tokenizers may be plugged in by
1309extending the interfaces org.apache.tools.ant.filters.TokenFilter.Filter
1310and org.apache.tools.ant.util.Tokenizer respectly.
1311
1312They are defined the build file using <code>&lt;typedef/&gt;</code>. For
1313example a string filter that capitalizes words may be declared as:
1314<blockquote><pre>
1315package my.customant;
1316import org.apache.tools.ant.filters.TokenFilter;
1317
1318public class Capitalize
1319 implements TokenFilter.Filter
1320{
1321 public String filter(String token) {
1322 if (token.length() == 0)
1323 return token;
1324 return token.substring(0, 1).toUpperCase() +
1325 token.substring(1);
1326 }
1327}
1328</pre></blockquote>
1329
1330This may be used as follows:
1331<blockquote><pre>
1332 &lt;typedef type="capitalize" classname="my.customant.Capitalize"
1333 classpath="my.customant.path"/&gt;
1334 &lt;copy file="input" tofile="output"&gt;
1335 &lt;filterchain&gt;
1336 &lt;tokenfilter&gt;
1337 &lt;stringtokenizer/&gt;
1338 &lt;capitalize/&gt;
1339 &lt;/tokenfilter&gt;
1340 &lt;/filterchain&gt;
1341 &lt;/copy&gt;
1342</pre></blockquote>
1343
1344<HR>
1345
1346<P align=center>Copyright &copy; 2002-2004 The Apache Software Foundation. All rights
1347Reserved.</P></BODY></HTML>
Note: See TracBrowser for help on using the repository browser.