Text::Filter - base class for objects that can read and write text lines

INTRODUCTION

A plethora of tools exist that operate as filters: they get data from
a source, operate on this data, and write possibly modified data to a
destination. In the Unix world, these tools can be chained using a
technique called pipelining, where the output of one filter is
connected to the input of another filter. Some non-Unix worlds are
reported to have similar provisions.

To create Perl modules for filter functionality seems trivial at
first. Just open the input file, read and process it, and write output
to a destination file. But for really reusable modules this approach
is too simple. A reusable module should not read and write files
itself, but rely on the calling program to provide input as well as to
handle the output.

Text::Filter is a base class for modules that have in common that they
process text lines by reading from some source (usually a file),
manipulating the contents and writing something back to some
destination (usually some other file).

This module can be used 'as is', but its real power shows when used to
derive modules from it. See the documentation for extensive examples.

FEATURES

Every module that derives from Text::Filter inherits the following
instance methods:

 * readline ()

   Returns the next line from the input stream, or undef if there is
   no more input.

 * writeline ($line)

   Adds $line to the output stream.

 * pushback ($line)

   Pushes a line of text back to the input stream.

 * peek ()

   Peeks at the input. Short for pushback(readline()).

When creating a new instance of this module, the input and output (or
only one of them) must be specified.

For input, this can be:

 * A scalar, containing a file name. The named file will be opened,
   input lines will be read using <>.

 * A file handle (glob). Lines will be read using <>.

 * An instance of class IO::File. Lines will be read using <>.

 * A reference to an array. Input lines will be shift()ed from the
   array.

 * A reference to an anonymous subroutine. This routine will be called
   to get the next line of data.

For output:

 * A scalar, containing a file name. The named file will be created
   automatically, output lines will be written using print().

 * A file handle (glob). Lines will be written using print().

 * An instance of class IO::File. Lines will be written using print().

 * A reference to a scalar. Output lines will be appended to the
   scalar.

 * A reference to an array. Output lines will be push()ed into the
   array.

 * A reference to an anonymous subroutine. This routine will be called
   to append a line of text to the destination.

Additional attributes can be used to specify actions to be performed
after the data is fetched, or prior to being written. For example, to
strip line endings upon input, and add them upon output.

----------------------------------------------------------------------------
Johan Vromans                                           jvromans@squirrel.nl
Squirrel Consultancy                                Haarlem, the Netherlands
http://www.squirrel.nl                http://www.squirrel.nl/people/jvromans
PGP Key 2048/4783B14D     http://www.squirrel.nl/people/jvromans/pgpkey.html
----------------------- "Arms are made for hugging" ------------------------
