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 on itself,
but it is most powerfull when used to derive modules from it.
See section EXAMPLES for an extensive example.

The main purpose of the Text::Filter class is to abstract out the details out how input and output must be done.
Although in most cases input will come from a file,
and output will be written to a file,
advanced modules require more detailed control over the input and output.
For example,
the module could be called from another module,
in this case the callee could be allowed to process only a part of the input.
Or,
a program could have prepared data in an array and wants to call the module to process this data as if it were read from a file.
Also,
the input stream provides a pushback functionality to make peeking at the input easy.

Text::Filter can be used on its own as a convenient input/output handler.
For example:

Its real power shows when such a program is turned into a module for optimal reuse.

When creating a module that is to process lines of text, it can be derived from Text::Filter, for example:

package MyFilter;
use base 'Text::Filter';

The constructor method must then call the new() method of the Text::Filter class to set up the base class. This is conveniently done by calling SUPER::new(). A hash containing attributes must be passed to this method, some of these attributes will be used by the base class setup.

The constructor is called new() and takes a hash with attributes as its parameter.

The following attributes are recognized and used by the constructor, all others are ignored.

The constructor will return a blessed hash containing all the original attributes, plus some new attributes. The names of the new attributes all start with _filter_, the new attributes should not be touched.

This designates the input source. The value must be a scalar (containing a file name), a file handle (either a glob or an instance of class IO::File), an array reference, or a reference to a subroutine, as described above.

If a subroutine is specified, it must return the next line to be processed, and undef at end.

This attribute can be used to select an action to be performed after the data has been read. Its prime purpose is to handle line endings (e.g. remove a trailing newline).

The value can be 'none' or 0 (no action), 'chomp' or 1 (standard chomp() operation), or a reference to a subroutine. Default value is 0 (no chomping).

If the value is a reference to a subroutine, this will be called with the text line that was just read as its only argument, and it must return the new contents of the text line.. If it returns undef, this line will be skipped.

If specified, a reference to a subroutine that performs filtering. It will be called after input_postread, with the text line that was just read as its only argument, and it must return the new contents of the text line. If it returns undef, this line will be skipped.

This attribute can be used to select an action to be performed just before the data is added to the output. Its prime purpose is to handle line endings (e.g. add a trailing newline). The value can be 'none' or 0 (no action) , 'newline' or 1 (append the value of $/ to the line), or a reference to a subroutine. Default value is 0 (no action).

If the value is 'newline' or 1, and the value of $/ is "" (paragraph mode), two newlines will be added.

If the value is a reference to a subroutine, this will be called with the text line as its only argument, and it must return the new contents of the line to be output. If it returns undef, no output occurs.

This program is Copyright 1998,2013 by Squirrel Consultancy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with Perl.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.