NAME

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:

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

AUTHOR

COPYRIGHT