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 Exloo, the Netherlands
http://www.squirrel.nl http://johan.vromans.org
PGP Key 1024D/1298C2B4 http://johan.vromans.org/pgpkey.html
----------------------- "Arms are made for hugging" ------------------------