README
1Text::Filter - base class for objects that can read and write text lines
2
3INTRODUCTION
4
5A plethora of tools exist that operate as filters: they get data from
6a source, operate on this data, and write possibly modified data to a
7destination. In the Unix world, these tools can be chained using a
8technique called pipelining, where the output of one filter is
9connected to the input of another filter. Some non-Unix worlds are
10reported to have similar provisions.
11
12To create Perl modules for filter functionality seems trivial at
13first. Just open the input file, read and process it, and write output
14to a destination file. But for really reusable modules this approach
15is too simple. A reusable module should not read and write files
16itself, but rely on the calling program to provide input as well as to
17handle the output.
18
19Text::Filter is a base class for modules that have in common that they
20process text lines by reading from some source (usually a file),
21manipulating the contents and writing something back to some
22destination (usually some other file).
23
24This module can be used 'as is', but its real power shows when used to
25derive modules from it. See the documentation for extensive examples.
26
27FEATURES
28
29Every module that derives from Text::Filter inherits the following
30instance methods:
31
32 * readline ()
33
34 Returns the next line from the input stream, or undef if there is
35 no more input.
36
37 * writeline ($line)
38
39 Adds $line to the output stream.
40
41 * pushback ($line)
42
43 Pushes a line of text back to the input stream.
44
45 * peek ()
46
47 Peeks at the input. Short for pushback(readline()).
48
49When creating a new instance of this module, the input and output (or
50only one of them) must be specified.
51
52For input, this can be:
53
54 * A scalar, containing a file name. The named file will be opened,
55 input lines will be read using <>.
56
57 * A file handle (glob). Lines will be read using <>.
58
59 * An instance of class IO::File. Lines will be read using <>.
60
61 * A reference to an array. Input lines will be shift()ed from the
62 array.
63
64 * A reference to an anonymous subroutine. This routine will be called
65 to get the next line of data.
66
67For output:
68
69 * A scalar, containing a file name. The named file will be created
70 automatically, output lines will be written using print().
71
72 * A file handle (glob). Lines will be written using print().
73
74 * An instance of class IO::File. Lines will be written using print().
75
76 * A reference to a scalar. Output lines will be appended to the
77 scalar.
78
79 * A reference to an array. Output lines will be push()ed into the
80 array.
81
82 * A reference to an anonymous subroutine. This routine will be called
83 to append a line of text to the destination.
84
85Additional attributes can be used to specify actions to be performed
86after the data is fetched, or prior to being written. For example, to
87strip line endings upon input, and add them upon output.
88
89----------------------------------------------------------------------------
90Johan Vromans jvromans@squirrel.nl
91Squirrel Consultancy Exloo, the Netherlands
92http://www.squirrel.nl http://johan.vromans.org
93PGP Key 1024D/1298C2B4 http://johan.vromans.org/pgpkey.html
94----------------------- "Arms are made for hugging" ------------------------
95