File Coverage

blib/lib/Piper/Process.pm

Criterion	Covered	Total	%
statement	30	32	93.7
branch	1	2	50.0
condition			n/a
subroutine	11	11	100.0
pod			n/a
total	42	45	93.3

#####################################################################
## AUTHOR: Mary Ehlers, [e-mail]
## ABSTRACT: A data-processing unit for the Piper pipeline system
#####################################################################

package Piper::Process;

use v5.10;
use strict;
use warnings;

use Carp;
use Piper::Instance;
use Types::Standard qw(CodeRef);

use Moo;
use namespace::clean;

with qw(Piper::Role::Segment);

use overload (
    q{""} => sub { $_[0]->label },
    fallback => 1,
);

our $VERSION = '0.05'; # from Piper-0.05.tar.gz

my $CONFIG;
sub import {
    my $class = shift;
    if (@_) {
        require Piper::Config;
        $CONFIG = Piper::Config->new(@_);
    }
    return 1;
}

#pod =head1 CONSTRUCTOR
#pod
#pod =head2 new(@args)
#pod
#pod The constructor accepts the following patterns for C<@args>:
#pod
#pod     Piper::Process->new({
#pod         label      => $label,    # recommended
#pod         handler    => $handler,  # required
#pod         batch_size => $num,      # optional
#pod         allow      => $allow,    # optional
#pod         enabled    => $enabled,  # default: 1
#pod     });
#pod
#pod     Piper::Process->new(
#pod         $label => {
#pod             handler    => $handler,
#pod             batch_size => $num,
#pod             allow      => $allow,
#pod             enabled    => $enabled,
#pod         }
#pod     );
#pod
#pod     Piper::Process->new($label => $handler);
#pod
#pod =cut

around BUILDARGS => sub {
    my ($orig, $self, @args) = @_;

    croak 'ERROR: Too many arguments to constructor of '.__PACKAGE__
        if @args > 2;

    croak 'ERROR: Last argument must be a CODE ref or HASH ref'
        unless (ref $args[-1] eq 'CODE') or (ref $args[-1] eq 'HASH');

    my %hash;
    if (ref $args[-1] eq 'CODE') {
        $hash{handler} = pop @args;
    }
    else {
        %hash = %{pop @args};
    }

    if (@args) {
        croak 'ERROR: Labels may not be a reference' if ref $args[0];
        $hash{label} = shift @args;
    }

    $hash{config} = $CONFIG if defined $CONFIG;

    return $self->$orig(%hash);
};

#pod =head1 ATTRIBUTES
#pod
#pod =head2 allow
#pod
#pod An optional coderef used to subset the items which are I to be processed by the segment.
#pod
#pod The coderef runs on each item attempting to queue to the segment.  If it returns true, the item is queued.  Otherwise, the item skips the segment and proceeds to the next adjacent segment.
#pod
#pod Each item is localized to C<$_>, and is also passed in as the first argument.  These example C subroutines are equivalent:
#pod
#pod     # This segment only accepts digit inputs
#pod     sub { /^\d+$/ }
#pod     sub { $_ =~ /^\d+$/ }
#pod     sub { $_[0] =~ /^\d+$/ }
#pod
#pod =head2 batch_size
#pod
#pod The number of items to process at a time for the segment.  Once initialized, a segment inherits the C of its parent(s) if not provided.
#pod
#pod =head2 enabled
#pod
#pod Boolean indicating that the segment is enabled and can accept items for processing.  Defaults to true.
#pod
#pod =head2 handler
#pod
#pod The data-processing subroutine for this segment.
#pod
#pod The arguments provided to the handler are as follows:
#pod
#pod     $instance - the instance corresponding to the segment
#pod     $batch    - an arrayref of items to process
#pod     @args     - the init arguments (if any) provided
#pod                 at the initialization of the pipeline
#pod
#pod Via the provided C<$instance> object (L), the handler has several options for sending data to other pipes or processes in the pipeline:
#pod
#pod     $instance->eject(@data)
#pod     $instance->emit(@data)
#pod     $instance->inject(@data)
#pod     $instance->injectAfter($location, @data)
#pod     $instance->injectAt($location, @data)
#pod     $instance->recycle(@data)
#pod
#pod See L or L for an explanation of these methods.
#pod
#pod Example handler:
#pod
#pod     sub {
#pod         my ($instance, $batch) = @_;
#pod         $instance->emit(map { ... } @$batch);
#pod     }
#pod
#pod =cut

has handler => (
    is => 'ro',
    isa => CodeRef,
    required => 1,
);

#pod =head2 id
#pod
#pod A globally unique ID for the segment.  This is primarily useful for debugging only.
#pod
#pod =head2 label
#pod
#pod A label for this segment.  If no label is provided, the segment's C will be used.
#pod
#pod Labels are necessary if any handlers wish to use the C or C methods.  Otherwise, labels are primarily useful for logging and/or debugging.
#pod
#pod Stringification of a L object is overloaded to return its label:
#pod
#pod     my $process = Piper::Process->new($label => sub {...});
#pod
#pod     $process->label; # $label
#pod     "$process";      # $label
#pod
#pod =head1 METHODS
#pod
#pod =head2 has_allow
#pod
#pod A boolean indicating whether or not an C attribute exists for this segment.
#pod
#pod =head2 has_batch_size
#pod
#pod A boolean indicating whether the segment has an assigned C.
#pod
#pod =head2 init
#pod
#pod Returns a L object for this segment.
#pod
#pod =cut

sub init {
    my ($self) = @_;

    return Piper::Instance->new(
        segment => $self,
    );
}

1;

__END__