view release on metacpan or  search on metacpan

lib/Data/Tubes/Plugin/Plumbing.pod  view on Meta::CPAN

(in particular, it will return two elements, the first is the string
C<iterator> and the second is an iterator sub reference).

Arguments can be passed through a single reference to a hash, or as a
sequence of key/value pairs. The following options are supported:

=over

=item C<gate>

a sub ref that is called over each intermediate record to establish if
it can continue down the sequence or it should be returned immediately,
depending on the truth of the returned value. The sub reference is
passed the record and might change it. Defaults to C<undef>, which means
that no gating function is invoked;

=item C<name>

set a name for the sequence, which might come handy when debugging.
Defaults to C<sequence>;

=item C<logger>

can be optionally set to a function that will be called for each input
record, being passed the record itself and a reference to the hash of
arguments. Use this if you want to do some logging, ignore otherwise;

=item C<tubes>

an array reference containing the list of tubes part of the sequence.
These can be either direct tubes (i.e. references to subroutines) or
definitions suitable for calling L<Data::Tubes/tube>. This parameter can
also be passed as the first unnamed argument in the call to the
function.

=back

The sequence makes no assumption as to the input record, although the
first element in the provided list might do.

Note that the last I<tube> in the sequence might actually return an
output record with an C<undef> or otherwise false value (Perl-wise). To
cope with this, when called in list context, the iterator is guaranteed
to either return one single output record, or the empty list when the
iterator is exhausted.

The suggested idiom for taking items from the iterator is then the
following:

   my $it1 = $sequence1->($input_record)->{iterator};
   while (my ($output_record) = $it1->()) {
      # work with $output_record here, it's your output record!
   }

   # if you're waiting for a single output record, use if
   my $it2 = $sequence2->($input_record)->{iterator};
   if (my ($output_record) = $it2->()) {
      # work with $output_record here, it's your output record!
   }

=head1 BUGS AND LIMITATIONS

Report bugs either through RT or GitHub (patches welcome).

=head1 AUTHOR

Flavio Poletti <polettix@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2016 by Flavio Poletti <polettix@cpan.org>

This module is free software. You can redistribute it and/or modify it
under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.

=cut