NAME

Data::Transform::Stackable - combine multiple Data::Transform objects

SYNOPSIS

DESCRIPTION

Data::Transform::Stackable combines multiple filters together in such a way that they appear to be a single filter. All the usual Data::Transform methods work, but data is secretly passed through the stacked filters before it is returned.

Data added by get_one_start() will flow through the filter array in increasing index order. Filter #0 will have first crack at it, followed by filter #1 and so. The get_one() call will return an item after it has passed through the last filter.

put() passes data through the filters in descending index order. Data will go through the filter with the highest index first, and put() will return the results after data has passed through filter #0.

PUBLIC FILTER METHODS

Data::Transform::Stackable implements the Data::Transform API. Only differences and additions are documented here.

new

By default, new() creates an empty filter stack that behaves like Data::Transform::Stream. It may be given optional parameters to initialize the stack with an array of filters.

  my $sudo_lines = Data::Transform::Stackable->new(
    Filters => [
      Data::Transform::Line->new(),
      Data::Transform::Grep->new(
        Put => sub { 1 }, # put all items
        Get => sub { shift() =~ /sudo\[\d+\]/i },
      ),
    ]
  );

filter_types

filter_types() returns a list of class names for each filter in the stack, in the stack's native order.

filters

filters() returns a list of the filters inside the Stackable filter, in the stack's native order.

shift

Behaves like Perl's built-in shift() for the filter stack. The 0th filter is removed from the stack and returned. Any data remaining in the filter's input buffer is passed to the new head of the stack, or it is lost if the stack becomes empty. An application may also call "get_pending" in Data::Transform on the returned filter to examine the filter's input buffer.

  my $first_filter = $stackable->shift();
  my $first_buffer = $first_filter->get_pending();

unshift FILTER[, FILTER]

unshift() adds one or more new FILTERs to the beginning of the stack. The newly unshifted FILTERs will process input first, and they will handle output last.

push FILTER[, FILTER]

push() adds one or more new FILTERs to the end of the stack. The newly pushed FILTERs will process input last, and they will handle output first.

  # Reverse data read through the stack.
  # rot13 encode data sent through the stack.
  $stackable->push(
    Data::Transform::Map->(
      Get => sub { return scalar reverse shift() },
      Put => sub { local $_ = shift(); tr[a-zA-Z][n-za-mN-ZA-M]; $_ },
    )
  );

pop

Behaves like Perl's built-in pop() for the filter stack. The highest-indexed filter is removed from the stack and returned. Any data remaining in the filter's input buffer is lost, but an application may always call "get_pending" in Data::Transform on the returned filter.

  my $last_filter = $stackable->pop();
  my $last_buffer = $last_filter->get_pending();

SEE ALSO

Data::Transform for more information about filters in general.

AUTHORS & COPYRIGHTS

The Stackable filter was contributed by Dieter Pearcey. Documentation provided by Rocco Caputo.

cpanm Data::Transform

perl -MCPAN -e shell
install Data::Transform