Answer the question: "So what are filterreadersets and filterreaders anyway?"

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271415 13f79535-47bb-0310-9956-ffa450edef68
23 years ago · defe5f24dc
--- a/proposal/sandbox/filterreaders/docs/manual/CoreTasks/loadfile.html
+++ b/proposal/sandbox/filterreaders/docs/manual/CoreTasks/loadfile.html
@@ -0,0 +1,101 @@
 <html>
 <head>
 <title>LoadFile Task</title>
 </head>

 <body>


 <h2><a name="loadfile">LoadFile</a></h2>
 <h3>Description</h3>
 <p>
 Load a text file into a single property. Unless an encoding is specified,
 the encoding of the current locale is used.

 </p>

 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">srcFile</td>
    <td valign="top">source file</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">property</td>
    <td valign="top">property to save to</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">encoding</td>
    <td valign="top">encoding to use when loading the file</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">failonerror</td>
    <td valign="top">Whether to halt the build on failure</td>
    <td align="center" valign="top">No, default "true"</td>
  </tr>
  <tr>
    <td valign="top">evaluateProperties</td>
    <td valign="top">flag to enable property evalation in the file</td>
    <td align="center" valign="top">No, default "false"</td>
  </tr>
 </table>
 <p>
 The LoadFile task supports nested <a href="../CoreTypes/filterreaderset.html">
 FilterReaderSet</a>s.

 <h3>Examples</h3>
 <pre>    &lt;loadfile property="message"
      srcFile="message.txt" /&gt;
 </pre>
 Load file message.txt into property "message"; an <tt>&lt;echo&gt;</tt>
 can print this.

 <pre>    &lt;loadfile property="encoded-file"
      srcFile="loadfile.xml"
      encoding="ISO-8859-1" /&gt;
 </pre>
 Load a file using the latin-1 encoding

 <pre>    &lt;loadfile
      property="optional.value"
      srcFile="optional.txt"
      failonerror="false" /&gt;
 </pre>
 Load a file, don't fail if it is missing (a message is printed, though)

 <pre>    &lt;loadfile
      property="mail.recipients"
      srcFile="recipientlist.txt"&gt;
      &lt;filterreaderset&gt;
        &lt;filterreader classname="org.apache.tools.ant.filters.<a href="../CoreTypes/filterreaderset.html#StripLineBreaks">StripLineBreaks</a>" /&gt;
      &lt;/filterreaderset&gt;
    &lt;/loadfile&gt;
 </pre>
 Load a property which can be used as a parameter for another task (in this case mail),
 merging lines to ensure this happens.

 <pre>    &lt;loadfile
      property="system.configuration.xml"
      srcFile="configuration.xml"
      evaluateProperties="true" /&gt;
 </pre>
 Load an XML file into a property, expanding all properties declared
 in the file in the process.


 <hr>

 <p align="center">Copyright &copy; 2001-2002 Apache Software Foundation. All rights
 Reserved.</p>

 </body>
 </html>

--- a/proposal/sandbox/filterreaders/docs/manual/CoreTypes/filterreaderset.html
+++ b/proposal/sandbox/filterreaders/docs/manual/CoreTypes/filterreaderset.html
@@ -0,0 +1,231 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

 <HTML>
 <HEAD>
  <TITLE>FilterReaderSet Type</TITLE>
 </HEAD>

 <BODY>
 <H2><A name="filterreaderset">FilterReaderSet</A></H2>

 <P>FilterReaderSets are groups of FilterReaders. FilterReaderSets can appear
 inside tasks that support this feature. <BR>FilterReaderSets are used for
 filtering file contents read in by tasks like LoadFile, etc.<BR>

 Each FilterReaderSet is composed of nested <a name="filterreader">FilterReader</a> elements.

 <H2>FilterReader</H2>

 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>
 The following FilterReaders are supplied with the default
 distribution.

 <H3>org.apache.tools.ant.filters.<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;filterreaderset&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineBreaks&quot;/&gt;
  &lt;/filterreaderset&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;filterreaderset&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;/filterreaderset&gt;
 &lt;/loadfile&gt;
 </PRE></BLOCKQUOTE>

 <H3>org.apache.tools.ant.filters.<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;filterreaderset&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripJavaComments&quot;/&gt;
  &lt;/filterreaderset&gt;
 &lt;/loadfile&gt;
 </PRE></BLOCKQUOTE>

 <H3>org.apache.tools.ant.filters.<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;filterreaderset&gt;
    &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ReplaceTokens&quot;&gt;
      &lt;param type="token" name=&quot;DATE&quot; value=&quot;${TODAY}&quot;/&gt;
    &lt;filterreader/&gt;
  &lt;/filterreaderset&gt;
 &lt;/loadfile&gt;
 </PRE></BLOCKQUOTE>

 <H3>org.apache.tools.ant.filters.<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;filterreaderset&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;/filterreaderset&gt;
 &lt;/loadfile&gt;
 </PRE></BLOCKQUOTE>

 <H3>org.apache.tools.ant.filters.<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;filterreaderset&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;/filterreaderset&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;filterreaderset&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;/filterreaderset&gt;
 &lt;/loadfile&gt;
 </PRE></BLOCKQUOTE>

 <HR>

 <P align=center>Copyright &copy; 2001 Apache Software Foundation. All rights
 Reserved.</P></BODY></HTML>