ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From umag...@apache.org
Subject cvs commit: jakarta-ant/docs/manual/CoreTypes filterchain.html
Date Thu, 07 Mar 2002 03:09:59 GMT
umagesh     02/03/06 19:09:59

  Added:       docs/manual/CoreTypes filterchain.html
  Log:
  Missed adding Filter Chain earlier.
  
  Revision  Changes    Path
  1.1                  jakarta-ant/docs/manual/CoreTypes/filterchain.html
  
  Index: filterchain.html
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  
  <HTML>
  <HEAD>
    <TITLE>FilterChains and FilterReaders</TITLE>
  </HEAD>
  
  <BODY>
  
  <H2>FilterChains and FilterReaders</H2>
  Look at Unix pipes - they offer you so much flexibility -
  say you wanted to copy just those lines that contained the
  string blee from the first 10 lines of a file 'foo'
  to a file 'bar' - you would do something like<P>
  <code>
  cat foo|head -n10|grep blee > bar
  </code><P>
  Ant was not flexible enough.  There was no way for the
  &lt;copy&gt; task to do something similar.  If you wanted
  the &lt;copy&gt; task to get the first 10 lines, you would have
  had to create special attributes:<P>
  <code>
  &lt;copy file=&quot;foo&quot; tofile=&quot;bar&quot; head=&quot;10&quot;
contains=&quot;blee&quot;/&gt;
  </code><P>
  The obvious problem thus surfaced: Ant tasks would not be able
  to accomodate such data transformation attributes as they would
  be endless.  The task would also not know in which order these
  attributes were to be interpreted.  That is, must the task execute the
  contains attribute first and then the head attribute or vice-versa?
  What Ant tasks needed was a mechanism to allow pluggable filter (data
  tranformer) chains.  Ant would provide a few filters for which there
  have been repeated requests.  Users with special filtering needs
  would be able to easily write their own and plug them in.<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
  &lt;filterchain&gt; by using &lt;filterreader&gt; elements.
  <P>
  Example:
  <BLOCKQUOTE><PRE>
  &lt;copy file=&quot;${src.file}&quot; tofile=&quot;${dest.file}&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;your.extension.of.java.io.FilterReader&quot;&gt;
        &lt;param name=&quot;foo&quot; value=&quot;bar&quot;/&gt;
      &lt;/filterreader&gt;
      &lt;filterreader classname=&quot;another.extension.of.java.io.FilterReader&quot;&gt;
        &lt;classpath&gt;
          &lt;pathelement path="${classpath}"/&gt;
        &lt;/classpath&gt;
        &lt;param name=&quot;blah&quot; value=&quot;blee&quot;/&gt;
        &lt;param type=&quot;abra&quot; value=&quot;cadabra&quot;/&gt;
      &lt;/filterreader&gt;
    &lt;/filterchain&gt;
  &lt;/copy&gt;
  </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>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.head}&quot;&gt;
    &lt;filterchain&gt;
      &lt;headfilter lines=&quot;15&quot;/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  is equivalent to:
  <BLOCKQUOTE><PRE>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.head}&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.HeadFilter&quot;&gt;
        &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
      &lt;/filterreader&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  
  The following built-in tasks support nested &lt;filterchain&gt; elements.<BR>
  <a href="../CoreTasks/copy.html">Copy</a>,<BR>
  <a href="../CoreTasks/loadfile.html">LoadFile</a>,<BR>
  <a href="../CoreTasks/loadproperties.html">LoadProperties</a>,<BR>
  <a href="../CoreTasks/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="#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="#tabstospaces">TabsToSpaces</a><BR>
  <a href="#tailfilter">TailFilter</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>
  &lt;filterreader&gt; supports &lt;classpath&gt; and &lt;param&gt;
  as nested elements.  Each &lt;param&gt; 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 name=value
  <P>
  <H4>Example:</H4>
  
  This loads the basic constants defined in a Java class as Ant properties.
  <BLOCKQUOTE><PRE>
  &lt;loadproperties srcfile=&quot;foo.class&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ClassConstants&quot;/&gt;
    &lt;/filterchain&gt;
  &lt;/loadproperties&gt;
  </PRE></BLOCKQUOTE>
  
  Convenience method:
  <BLOCKQUOTE><PRE>
  &lt;loadproperties srcfile=&quot;foo.class&quot;&gt;
    &lt;filterchain&gt;
      &lt;classconstants/&gt;
    &lt;/filterchain&gt;
  &lt;/loadproperties&gt;
  </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
  &quot;All these moments will be lost in time, like teardrops in the rain&quot;
  <BLOCKQUOTE><PRE>
  &lt;echo
    message=&quot;All these moments will be lost in time, like teardrops in the ${weather}&quot;
    file=&quot;loadfile1.tmp&quot;
    /&gt;
  &lt;property name=&quot;weather&quot; value=&quot;rain&quot; /&gt;
  &lt;loadfile property=&quot;modifiedmessage&quot; srcFile=&quot;loadfile1.tmp&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ExpandProperties&quot;/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  
  Convenience method:
  <BLOCKQUOTE><PRE>
  &lt;echo
    message=&quot;All these moments will be lost in time, like teardrops in the ${weather}&quot;
    file=&quot;loadfile1.tmp&quot;
    /&gt;
  &lt;property name=&quot;weather&quot; value=&quot;rain&quot; /&gt;
  &lt;loadfile property=&quot;modifiedmessage&quot; srcFile=&quot;loadfile1.tmp&quot;&gt;
    &lt;filterchain&gt;
      &lt;expandproperties/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </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 &quot;10&quot;</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>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.head}&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.HeadFilter&quot;&gt;
        &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
      &lt;/filterreader&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  
  Convenience method:
  <BLOCKQUOTE><PRE>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.head}&quot;&gt;
    &lt;filterchain&gt;
      &lt;headfilter lines=&quot;15&quot;/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </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>Character 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>Character marking the
      end of a token.  Defaults to @</TD>
      <TD vAlign=top align="center">No</TD>
    </TR>
    <TR>
      <TD vAlign=top>token</TD>
      <TD vAlign=top>User defined String.</TD>
      <TD vAlign=top>User defined search String</TD>
      <TD vAlign=top align="center">Yes</TD>
    </TR>
  </TABLE>
  <P>
  
  <H4>Example:</H4>
  
  This replaces occurences of the string @DATE@ in the data
  with today's date and stores it in the property ${src.file.replaced}
  <BLOCKQUOTE><PRE>
  &lt;tstamp/&gt;
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.replaced}&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ReplaceTokens&quot;&gt;
        &lt;param type=&quot;token&quot; name=&quot;DATE&quot; value=&quot;${TODAY}&quot;/&gt;
      &lt;/filterreader&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  
  Convenience method:
  <BLOCKQUOTE><PRE>
  &lt;tstamp/&gt;
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.replaced}&quot;&gt;
    &lt;filterchain&gt;
      &lt;replacetokens&gt;
        &lt;token key=&quot;DATE&quot; value=&quot;${TODAY}&quot;/&gt;
      &lt;/replacetokens&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </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>
  &lt;loadfile srcfile=&quot;${java.src.file}&quot; property=&quot;${java.src.file.nocomments}&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripJavaComments&quot;/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  
  Convenience method:
  <BLOCKQUOTE><PRE>
  &lt;loadfile srcfile=&quot;${java.src.file}&quot; property=&quot;${java.src.file.nocomments}&quot;&gt;
    &lt;filterchain&gt;
      &lt;stripjavacomments/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </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 &quot;\r\n&quot;</TD>
      <TD vAlign=top align="center">No</TD>
    </TR>
  </TABLE>
  <P>
  <H4>Examples:</H4>
  
  This strips the '\r' and '\n' characters.
  <BLOCKQUOTE><PRE>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.contents}&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineBreaks&quot;/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  
  Convenience method:
  <BLOCKQUOTE><PRE>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.contents}&quot;&gt;
    &lt;filterchain&gt;
      &lt;striplinebreaks/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  
  This treats the '(' and ')' characters as line break characters and
  strips them.
  <BLOCKQUOTE><PRE>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.contents}&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineBreaks&quot;&gt;
        &lt;param name=&quot;linebreaks&quot; value=&quot;()&quot;/&gt;
      &lt;/filterreader&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </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>lines</TD>
      <TD vAlign=top align="center">tablength
      Defaults to &quot;8&quot;</TD>
      <TD vAlign=top align="center">No</TD>
    </TR>
  </TABLE>
  <P>
  <H4>Examples:</H4>
  
  This replaces tabs in ${src.file} with spaces.
  <BLOCKQUOTE><PRE>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.notab}&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.TabsToSpaces&quot;/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  
  Convenience method:
  <BLOCKQUOTE><PRE>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.notab}&quot;&gt;
    &lt;filterchain&gt;
      &lt;tabstospaces/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </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 &quot;10&quot;</TD>
      <TD vAlign=top align="center">No</TD>
    </TR>
  </TABLE>
  <P>
  <H4>Examples:</H4>
  
  This stores the last 15 lines of the supplied data in the property ${src.file.tail}
  <BLOCKQUOTE><PRE>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.tail}&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.TailFilter&quot;&gt;
        &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
      &lt;/filterreader&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  
  Convenience method:
  <BLOCKQUOTE><PRE>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.tail}&quot;&gt;
    &lt;filterchain&gt;
      &lt;tailfilter lines=&quot;15&quot;/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </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>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.mid}&quot;&gt;
    &lt;filterchain&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.HeadFilter&quot;&gt;
        &lt;param name=&quot;lines&quot; value=&quot;15&quot;/&gt;
      &lt;/filterreader&gt;
      &lt;filterreader classname=&quot;org.apache.tools.ant.filters.TailFilter&quot;&gt;
        &lt;param name=&quot;lines&quot; value=&quot;5&quot;/&gt;
      &lt;/filterreader&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  
  Convenience method:
  <BLOCKQUOTE><PRE>
  &lt;loadfile srcfile=&quot;${src.file}&quot; property=&quot;${src.file.mid}&quot;&gt;
    &lt;filterchain&gt;
      &lt;HeadFilter lines=&quot;15&quot;/&gt;
      &lt;TailFilter lines=&quot;5&quot;/&gt;
    &lt;/filterchain&gt;
  &lt;/loadfile&gt;
  </PRE></BLOCKQUOTE>
  
  <HR>
  
  <P align=center>Copyright &copy; 2002 Apache Software Foundation. All rights
  Reserved.</P></BODY></HTML>
  
  
  

--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message