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

Site Menu

Software & Tools

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.

Current version: 1.7
Archived: CPAN sites. The MetaCPAN search engine will find it for you.