NAME

Text::Filter::Chain - object for chaining Text::Filter objects and running them sequentially, feeding the output of each filter to the input of the next one.

SYNOPSIS

use Text::Filter::Chain;

# let's assume this is a filter which converts text to all lowercase
$lc = new LowerCaser(input => 'foo.txt'); # reads from file foo.txt

# and assume the following filter greps for a specified pattern
$grep = new Grepper(pattern => '\bfoo\b',  
                    output  => 'foo.out'); # writes to file foo.out

# then these commands will read from foo.txt, convert the text to all
# lowercase, filter out all lines with the word 'foo' and write to foo.out
$chain = new Text::Filter::Chain(filters => [$lc,$grep]);
$chain->run(); # this invokes the run() method on $lc and $grep

DESCRIPTION

new()

Returns a new empty Text::Filter::Chain object. Optionally, an ordered array of filters can be specified by passing a filters argument to new(). All filters are checked using is_valid_filter().

add_filter($filter)

Adds the filter object $filter to the end of the array of filters. The filter is checked using is_valid_filter().

is_valid_filter($filter)

Checks whether $filter is a valid filter for inclusion in a Text::Filter::Chain. The following requirements need to be met:

a set_input() method must be available for setting the filter input;

a set_output() method must be available for setting the filter output;

a run() method must be available which runs the filter on its entire input.

Note that $filter does not need to be a Text::Filter or derived object. However, deriving at least the final filter in the chain from Text::Filter adds the benefit of automagical output buffer creation (see run()).

set_input()

Sets the arguments which will be passed to the set_input() method of the first filter in the chain in run().

set_output()

Sets the arguments which will be passed to the set_output() method of the final filter in the chain in run().

run()

Runs all filters in the chain. This means that the run() method will be invoked on each filter object, and that the data will be buffered in between the filter: the output of the first filter is written to an array, which is used as the input of the 2nd filter, and so on.

If set_input() was invoked on the chain, these arguments will be passed to the set_input() method of the first filter in the chain. If this is not the case, the input of the first filter must have been defined in some other way, or run() will fail during the processing of the first filter.

If set_output() was invoked on the chain, these arguments will be passed to the set_output() method of the final filter in the chain. If this is not the case, the output of the final filter must have been defined in some other way, or run() will fail during the processing of the final filter.

However, a fallback is provided for filters derived from the Text::Filter class. If no output is specified for the final filter, and no chain output is given, the chain output will default to an empty array before processing all filters. This array is accessible as the 1st element in the ref to array kept in the output field of the chain.

SEE ALSO

More info on text filters is found in Text::Filter.

AUTHOR

Wim Verhaegen <wim.verhaegen@ieee.org>

COPYRIGHT

Copyright (c) 2000 Wim Verhaegen. All rights reserved. This program is free software; you can redistribute and/or modify it under the same terms as Perl itself.