File Coverage

lib/IPC/Run3/Simple.pm

Criterion	Covered	Total	%
statement	56	76	73.6
branch	16	38	42.1
condition	2	23	8.7
subroutine	14	15	93.3
pod	7	7	100.0
total	95	159	59.7

package IPC::Run3::Simple;

# ABSTRACT: Simple utility module to make the easy to use IPC::Run3 even more easy to use.

use strict;
use warnings;

use Carp;
use IPC::Run3 ();
use Exporter 'import';

our $VERSION = '0.011'; # VERSION

our @EXPORT = qw( run3 );

our @EXPORT_OK = qw(

  chomp_err chomp_out croak_on_err default_stderr default_stdin default_stdout
  tee_systemcall

);

our %EXPORT_TAGS = ( 'all' => [ @EXPORT, @EXPORT_OK ] );

our $CHOMP_ERR      = 1;
our $CHOMP_OUT      = 1;
our $CROAK_ON_ERR   = 0;
our $DEFAULT_STDIN  = undef;
our $DEFAULT_STDOUT = \my $out;
our $DEFAULT_STDERR = \my $err;
our $TEE_SYSTEMCALL = 0;

BEGIN {

  # Is Capture::Tiny available?

  if ( eval { require Capture::Tiny } ) {

    Capture::Tiny->import( 'tee' );
    *tee_systemcall = sub { $TEE_SYSTEMCALL = ! ! +shift };

  } else {

    *tee_systemcall = sub { $TEE_SYSTEMCALL = 0 };

  }

  # Is Time::HiRes available?

  if ( eval { require Time::HiRes } ) {

    Time::HiRes->import( qw( gettimeofday tv_interval ) );

  } else {

    *gettimeofday = sub { time, 0 };

    *tv_interval = sub {
      my ( $t0, $t1 ) = @_;
      $t1 = [ gettimeofday() ] unless defined $t1;
      $t1->[ 0 ] - $t0->[ 0 ];
    };

  }
}


# '!! +shift' forces the value to be either undef or 1;

sub chomp_err      { $CHOMP_ERR      = ! ! +shift }
sub chomp_out      { $CHOMP_OUT      = ! ! +shift }
sub croak_on_err   { $CROAK_ON_ERR   = ! ! +shift }
sub default_stderr { $DEFAULT_STDERR = shift }
sub default_stdin  { $DEFAULT_STDIN  = shift }
sub default_stdout { $DEFAULT_STDOUT = shift }


sub run3 {

  my $arg = shift;
  my $ref = ref $arg;

  my $return_array = 0;

  my ( $cmd, $stdin, $stdout, $stderr, $options );

  if ( $ref eq 'ARRAY' ) {

    $return_array++;
    $cmd     = $arg;
    $stdin   = $DEFAULT_STDIN;
    $stdout  = $DEFAULT_STDOUT;
    $stderr  = $DEFAULT_STDERR;
    $options = {};

  } elsif ( $ref eq 'HASH' ) {

    croak "'cmd' required and must be a reference to an array"
      unless exists $arg->{ 'cmd' } && ref $arg->{ 'cmd' } eq 'ARRAY';

    $cmd     = $arg->{ 'cmd' };
    $stdin   = $arg->{ 'stdin' } || $DEFAULT_STDIN;
    $stdout  = $arg->{ 'stdout' } || $DEFAULT_STDOUT;
    $stderr  = $arg->{ 'stderr' } || $DEFAULT_STDERR;
    $options = $arg->{ 'options' } || {};

    chomp_err( $arg->{ 'CHOMP_ERR' } )
      if exists $arg->{ 'CHOMP_ERR' };

    chomp_out( $arg->{ 'CHOMP_OUT' } )
      if exists $arg->{ 'CHOMP_OUT' };

    croak_on_err( $arg->{ 'CROAK_ON_ERR' } )
      if exists $arg->{ 'CROAK_ON_ERR' };

  } else {

    croak "Expecting either an array ref or a hash ref";

  }

  my $t0 = [ gettimeofday() ];

  if ( exists $ENV{ DEBUG_IPCR3S_CALL } ) {

    $stdout = $cmd;

  } elsif ( $TEE_SYSTEMCALL ) {

    # If you run 'perl -M-indirect -c thispackage' you will see a warning
    # about this line.  This shouldn't be a problem because, hopefully,
    # execution will never get here if Capture::Tiny isn't available.

    ( $stdout, $stderr ) = tee { IPC::Run3::run3( $cmd, $stdin, undef, undef, $options ) };

  } else {

    IPC::Run3::run3( $cmd, $stdin, $stdout, $stderr, $options );

  }

  my $time = tv_interval( $t0 );

  my $syserr = $?;

  croak $$stderr
    if $CROAK_ON_ERR && $$stderr ne '';

  if ( ref $stdout eq 'SCALAR' ) {

    $stdout = $$stdout;
    chomp $stdout if $CHOMP_OUT;

  } elsif ( ref $stdout eq 'ARRAY' && $CHOMP_OUT ) {

    chomp @$stdout;

  }

  if ( ref $stderr eq 'SCALAR' ) {

    $stderr = $$stderr;
    chomp $stderr if $CHOMP_OUT;

  } elsif ( ref $stderr eq 'ARRAY' && $CHOMP_OUT ) {

    chomp @$stderr;

  }

  return ( $stdout, $stderr, $syserr, $time )
    if $return_array;

} ## end sub run3

1;


__END__