NAME
    Pipe - Framework to create pipes using iterators

SYNOPSIS
     use Pipe;
     my @input = Pipe->cat("t/data/file1", "t/data/file2");
     my @lines = Pipe->cat("t/data/file1", "t/data/file2")->chomp;
     my @uniqs = Pipe->cat("t/data/file1", "t/data/file2")->chomp->uniq;

     Pipe->cat("t/data/file1", "t/data/file2")->uniq->print("t/data/out");

WARNING
    This is Alpha version. The user API might still change

DESCRIPTION
    Building an iterating pipe with prebuilt and home made tubes.

    Tubes available in this distibution:

  cat
    Read in the lines of one or more file.

  chomp
    Remove trailing newlines from each line.

  find
    Pipe->find(".")

    Returns every file, directory, etc. under the directory tree passed to
    it.

  for
    Pipe->for(@array)

    Iterates over the elements of an array. Basically the same as the for or
    foreach loop of Perl.

  glob
    Implements the Perl glob function.

  grep
    Selectively pass on values.

    Can be used either with a regex:

     ->grep( qr/regex/ )

    Or with a sub:

     ->grep( sub { length($_[0]) > 12 } )

    Very similar to the built-in grep command of Perl but instead of regex
    you have to pass a compiled regex using qr// and instead of a block you
    have to pass an anonymous sub {}

  map
    Similar to the Perl map construct, except that instead of a block you
    pass an anonymous function sub {}.

     ->map(  sub {  length $_[0] } );

  print
    TODO Not implemented yet

    Prints out its input. By default it prints to STDOUT but the user can
    supply a filename or a filehandle.

     Pipe->cat("t/data/file1", "t/data/file2")->print;
     Pipe->cat("t/data/file1", "t/data/file2")->print("out.txt");
     Pipe->cat("t/data/file1", "t/data/file2")->print(':a', "out.txt");

  say
    It is the same as print but adds a newline at the end of each line. The
    name is Perl6 native.

  sort
    Similar to the built in sort function of Perl. As sort needs to have all
    the data in the memory, once you use sort in the Pipe it stops being an
    iterator for the rest of the pipe.

    By default it sorts based on ascii table but you can provide your own
    sorting function. The two values to be compared are passed to this
    function.

     Pipe->cat("t/data/numbers1")->chomp->sort( sub { $_[0] <=> $_[1] } );

  tuple
    Given one or more array references, on every iteration it will return an
    n-tuple (n is the number of arrays), one value from each source array.

        my @a = qw(foo bar baz moo);
        my @b = qw(23  37  77  42);

        my @one_tuple = Pipe->tuple(\@a);
        # @one_tuple is ['foo'], ['bar'], ['baz'], ['moo']

        my @two_tuple = Pipe->tuple(\@a, \@b);
        # @two_tuple is ['foo', 23], ['bar', 37], ['baz', 77], ['moo', 42]

    Input: disregards any input so it can be used as a starting element of a
    Pipe

    Ouput: array refs of n elements

  uniq
    Similary to the unix uniq command eliminate duplicate consecutive
    values.

    23, 23, 19, 23 becomes 23, 19, 23

    Warning: as you can see from the example this method does not give real
    unique values, it only eliminates consecutive duplicates.

Building your own tube
    If you would like to build a tube called "thing" create a module called
    Pipe::Tube::Thing that inherits from Pipe::Tube, our abstract Tube.

    Implement one or more of these methods in your subclass as you please.

  init
    Will be called once when initializing the pipeline. It will get ($self,
    @args) where $self is the Pipe::Tube::Thing object and @args are the
    values given as parameters to the ->thing(@args) call in the pipeline.

  run
    Will be called every time the previous tube in the pipe returns one or
    more values. It can return a list of values that will be passed on to
    the next tube. If based on the current state of Thing there is nothing
    to do you should call return; with no parameters.

  finish
    Will be called once when the Pipe Manager notices that this Thing should
    be finished. This happens when Thing is the first active element in the
    pipe (all the previous tubes have already finshed) and its run() method
    returns an empty list.

    The finish() method should return a list of values that will be passed
    on to the next tube in the pipe. This is especially useful for Tubes
    such as sort that can to their thing only after they have received all
    the input.

  Debugging your tube
    You can call $self->logger("some message") from your tube. It will be
    printed to pipe.log if someone sets $Pipe::DEBUG = 1;

Examples
    A few examples of UNIX Shell commands combined with pipelines

    *   cat several files together

        UNIX:

         cat file1 file2 > filenew

        Perl:

         open my $out, ">", "filenew" or die $!;
         while (<>) {
            print $out $_;
         }

        Perl with Pipe:

         perl -MPipe 'Pipe->cat(@ARG)->print("filenew")'

    *   UNIX:

         grep REGEX file* | uniq

        Perl:

         my $last;
         while (<>) {
            next if not /REGEX/;

            if (not defined $last) {
                $last = $_;
                print;
                next;
            }
            next if $last eq $_;
            $last = $_;
            print;
         }

        Perl with Pipe:

        one of these will work, we hope:

         Pipe->grep(qr/REGEX/, <file*>)->uniq->print
         Pipe->cat(<file*>)->grep(qr/REGEX/)->uniq->print
         Pipe->files("file*")->cat->grep(qr/REGEX/)->uniq->print

    *   UNIX:

         find / -name filename -print 

        Perl with Pipe:

         perl -MPipe -e'Pipe->find("/")->grep(qr/filename/)->print'

    *   Delete all the CVS directories in a directory tree (from the journal
        of brian_d_foy) http://use.perl.org/~brian_d_foy/journal/29267

        UNIX:

         find . -name CVS | xargs rm -rf

         find . -name CVS -type d -exec rm -rf '{}' \;

        Perlish:

         find2perl . -name CVS -type d -exec rm -rf '{}' \; > rm-cvs.pl
         perl rm-cvs.pl

        Perl with Pipe:

         perl -MPipe -e'Pipe->find(".")->grep(qr/^CVS$/)->rmtree;

BUGS
    Probably plenty but nothing I know of. Please report them to the author.

Development
    The Subversion repository is here:
    http://svn1.hostlocal.com/szabgab/trunk/Pipe/

Thanks
    to Gaal Yahas

AUTHOR
    Gabor Szabo <gabor@pti.co.il>

Copyright
    Copyright 2006 by Gabor Szabo <gabor@pti.co.il>.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    See http://www.perl.com/perl/misc/Artistic.html

See Also
    Shell::Autobox

