| Ant Filter Readers |
| ================== |
| |
| 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. |
| |
| * 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> |