# ==================================================================
# Gossamer Threads Module Library - http://gossamer-threads.com/
#
#   GT::IPC::Filter
#   Author: Scott Beck
#   $Id: Filter.pm,v 1.3 2004/01/13 01:35:17 jagerman Exp $
#
# Copyright (c) 2004 Gossamer Threads Inc.  All Rights Reserved.
# ==================================================================
#
# Description: Does nothing for now, here as a referance.
#

package GT::IPC::Filter;
# ==================================================================

die "Do not use me";

1;

__END__

=head1 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;

=head1 DESCRIPTION

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

=head1 METHODS

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

=head2 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 C<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 C<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.

=head2 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 C<output>
code reference with the formatted data. For example GT::IPC::Filter::Line
calles the C<output> code reference with each line of data, see
L<GT::IPC::Filter::Line>. It is ok if you change the scalar reference passed
into you.

=head2 flush

C<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 C<output>
code reference at this point, after filtering it if nessisary.

=head1 SEE ALSO

See L<GT::IPC::Run>, L<GT::IPC::Filter::Line>, L<GT::IPC::Filter::Stream>,
and L<GT::IPC::Filter::Block>.

=head1 MAINTAINER

Scott Beck

=head1 COPYRIGHT

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

=head1 VERSION

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

=cut