- SYNOPSIS
- DESCRIPTION
- METHODS

- new
- put
- flush

- SEE ALSO
- MAINTAINER
- COPYRIGHT
- VERSION

# SYNOPSIS

        use GT::IPC::Filter::Foo;

        my $filter = new GT::IPC::Filter::Foo(sub { my $out = shift ... });
        # -or-
        my $filter = new GT::IPC::Filter::Foo(
            output => sub { my $out = shift; .. },
            %options
        );

        $filter->put(\$data);

        $filter->flush;

# DESCRIPTION

This documents how to create a filter. The filter system documented here is used for GT::IPC::Run, the GT::IPC::Run manpage, currently but could be useful for other things relating to IO and IPC.

# METHODS

You will need to impliment three methods to create a filter. These methods are pretty simple and strait forward.

## new

This is your constructor. You will need to return an object. You should be able to take a sigle argument as well as a hash of options. It isn't manditory but it will keep the filter interface consistent.

The one argument form of `new()` is a code reference. This code reference will be called with the data (in whatever form) after you filter it. You should default the rest of your arguments to something reasonable. If there are no reasonable defaults for your options you can stray from this and require the hash form, but you should have a nice error for people that call you with the one argument form:

        $class->fatal(
            BADARGS => "This class does not accept the one argument form for filters"
        ) if @_ == 1;

The hash form should take a key `output` which will be the code reference output will go to once you filter it. The rest of the keys are up to you. Try to have reasonable defaults for the other keys, but fatal if there are any that are required and not present.

## put

This method is called with a scaler reference of the data you will be filtering. You are expect to make changes to the data and call the `output` code reference with the formatted data. For example GT::IPC::Filter::Line calles the `output` code reference with each line of data, see the GT::IPC::Filter::Line manpage. It is ok if you change the scalar reference passed into you.

## flush

`flush()` if called when the stream of data is at an end. Not arguments are passed to it. You are expected send any data you are buffering to the `output` code reference at this point, after filtering it if nessisary.

# SEE ALSO

See the GT::IPC::Run manpage, the GT::IPC::Filter::Line manpage, the GT::IPC::Filter::Stream manpage, and the GT::IPC::Filter::Block manpage.

# MAINTAINER

Scott Beck

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: Filter.pm,v 1.3 2004/01/13 01:35:17 jagerman Exp $