ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Magesh Umasankar" <umag...@apache.org>
Subject [VOTE] Promotion of FilterReaders proposal to main development tree.
Date Thu, 28 Feb 2002 02:05:49 GMT
Hi,

I would like to call upon a vote for the promotion of
the FilterReaders proposal from the sandbox to the main
development tree.

Here is a summary of what this proposal is (as taken from the README):

============================================================================
===

Usecase:
========
* Usage of filtering has become a common pattern in
  Ant's tasks.  Filtering is being performed one way or
  another in tasks like <copy>, <move>, <fixcrlf>,
  <loadfile>, etc.

* There is no generic way to add custom filters
  currently to these tasks.  User has to either extend
  the task to add custom filter processing or add
  more attributes as needed to the task itself.

* If user is provided with a pluggable filtering
  mechanism, changes to built-in tasks can be mininized,
  while at the same time providing increased flexibility
  to the user.

Design:
======
* FilterChain is an ordered collection of 'AntFilterReader's and
  'java.io.FilterReader's

* Each AntFilterReader encloses the custom class representing
  the actual java.io.FilterReader and contains configuration
  parameters that may be used by the custom class if it
  implements the org.apache.tools.ant.types.Parameterizable
  interface.

* For ease of use, Ant's core filter readers can
  be used with a filter-reader-specific syntax also.
  although the long form can also be used.

* Custom filter readers can be created easily even
  without using any of Ant's API - all one needs to
  do to create a custom filter is to extend
  java.io.FilterReader.

* If the extended class also implements Parameterizable,
  operation parameters can be made available to the
  custom filter.

* Each FilterReader is piped through the other, if any, in
  the chain, in the order of declaration.

Example:
=======

<loadfile srcFile="foo" property="bar">
    <filterchain>
        <filterreader
classname="org.apache.tools.ant.filters.StripLineComments">
            <param type="comment" value="//"/>
            <param type="comment" value="REM "/>
            <param type="comment" value="--"/>
        </filterreader>
        <filterreader
classname="org.apache.tools.ant.filters.StripLineBreaks"/>
    </filterchain>
</loadfile>

The above example loads the contents of the file foo,
filters out the lines that begin with //, REM and --,
removes line breaks and then stores the result in
the property named bar.

Since StripLineComments and StripLineBreaks are built-in
Ant filter readers, the same can also be represented as:

<loadfile srcFile="foo" property="bar">
    <filterchain>
        <striplinecomments>
            <comment value="//"/>
            <comment value="REM "/>
            <comment value="--"/>
        </striplinecomments>
        <striplinebreaks/>
    </filterchain>
</loadfile>

============================================================================
===

The following filterreaders have currently been added to
the proposal based on the following use cases:

HeadFilter:
==========
A head task has been accepted for Ant2.  This will make the need
for an individual task to go away.

LineContains:
============
This may be used to get just those lines which contain
specific strings.  This may be useful in the context
of the <loadproperties> task where only those keys that
contain a specific string must be loaded.

PrefixLines:
===========
This may also be used while using <loadproperties>
to perform transformation of the key before loading.
Filters to add suffix to a key, value, etc. will also
be useful, though they are not available currently.
PrefixLines and StripLineComments combined with
<loadproperties> provides the same output as <property>
with the prefix attribute set.

ReplaceTokens:
=============
This finds keys embedded within begintoken and endtoken
and replaces them with user defined values.  Rough
equivalent of <filterset>, <filter>.

StripJavaComments:
=================
This strips out from the data all comments embedded
using Java's commenting syntax.  I think Steve requested
this...

StripLineBreaks:
===============
This strips line break characters.  This obsoletes
the need for the makeoneline attribute of <loadfile>

StripLineComments:
=================
Jason van Zyl had requested a way to be able to
strip out comments from a file while loading it up
using <loadfile>.  This need was the primary motivator
of this proposal.

TabsToSpaces:
============
Tabs are converted into spaces by this filter reader.

TailFilter:
==========
A tail task has been accepted for Ant2.  This will make the need
for an individual task to go away.


The following tasks have been modified/added:

LoadFile:
========
makeoneline attribute has been removed and task has been
made <filterchain> aware.

LoadProperties:
==============
New task that is <filterchain> aware.  This can be
used in cases when transformations have to be done to
the data before they are read in as Ant properties.

Documentation:
=============
Alpha document is in proposal.

Testcases:
=========
Currently none.  Planning to add a few in the near future.

Your votes/comments/reviews/questions on relevant portions please.

Cheers,
Magesh




--
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