NAME

Proc::Lite - A lightweight module for running processes synchronously

SYNOPSIS

  use Proc::Lite;

  {
    my $proc = Proc::Lite->new(
      command => 'cat -',
      stdin   => "Useless use of cat\n",
    );

    $proc->run;
  }

  {
    my $proc = Proc::Lite->new(
      command => [qw( cat - )],
      stdin   => [ 'Another useless use of cat' ],
    )->run;
  }

  {
    my @stdin = qw( foo bar baz );
    my $proc = Proc::Lite->new(
      command => sub { while( <STDIN> ) { print } },
      stdin   => sub { pop @stdin },
    )->run;
  }

  {
    my $proc = Proc::Lite->new(
      command => [ sub {
        my ( $ppid ) = @_;
        while( <STDIN> ) {
          print "$ppid: $_"
        }
      }, $$ ],
      stdin => \*STDIN,
    )->run;
  }

  {
    # really useless use of cat
    my $proc = Proc::Lite->exec(
      'cat </dev/null 1>/dev/null 2>/dev/null' );
  }

  {
    my $proc = Proc::Lite->exec( qw( ls -l ), @ARGV );
    if( $proc->success ) {
      print "success\n";
      print " => $_\n"
        for $proc->stdout;
    }
    else {
      print "failed: ", $proc->status, "\n";
      print " => $_\n"
        for $proc->stderr;
    }
  }

  {
    sub echo { print "$_\n" for @_ }

    my $proc = Proc::Lite->exec( \&echo, @ARGV );
  }

  {
    my $proc = Proc::Lite->new(
      priority => 10,

      command => sub {
        print "In child process ($$): command\n";
      },

      parent => sub {
        my ( $pid ) = @_;

        print "In parent process ($$): child=$pid\n";
      },

      child => sub {
        my ( $ppid ) = @_;

        print "In child process ($$): parent=$ppid\n";
      },
    )->run;
  }

DESCRIPTION

Proc::Lite is a lightweight, easy-to-use wrapper around Proc::Hevy. It is meant to provide a simple interface for common use cases.

CLASS METHODS

new( %args )

Creates a Proc::Lite object. The command given is not executed at this time. See the run() method for actually running the command. %args may contain the following options:

command => $command

command => \@command

command => \&code

command => [ \&code, @args ]

Specifies the command to run. The first form may expand shell meta-characters while the second form will not. Review the documentation for exec() for more information. The third form will run the given CODE reference in the child process and the fourth form does the same, but also passes in @args as arguments to the subroutine. This option is required.

stdin => $buffer

stdin => \@buffer

stdin => \&code

stdin => \*GLOB

Specifies data that may be sent to the child process's STDIN. The first form simply sends the given string of bytes to the child process. The second form will write individual array elements to the child process. The third form will run the given CODE reference and write the return value to the child. A value of undef signals that no more input should be sent to the child process. The fourth form simply re-opens the child's STDIN handle to the given filehandle allowing a pass-through effect. If this option is not given, the child's STDIN will be reopened to '/dev/null'.

parent => \&code

If specified, the given CODE reference is called in the parent process after the fork() is performed. The child process's PID is passed in as a single argument.

child => \&code

If specified, the given CODE reference is called in the child process after the fork() is performed. The parent process's PID is passed in as a single argument.

priority => $delta

If specified, adjusts the child process's priority according to the value specified.

exec( $command )

exec( @command )

exec( \&code, @args )

This is a simple wrapper method for calling new() and run() in a single step. The three forms correspond to the ways new()'s command argument may be specified.

OBJECT METHODS

run

Runs the command specified in new(). It returns the Proc::Lite object so that it can be called in conjunction with new() (Proc::Lite->new( ... )->run).

status

Returns the exit status from the process.

stdout

Returns the STDOUT output from the child process. In list context, the output is returned as a list. In scalar context, an ARRAY reference is returned.

stderr

Similar to stdout except that the STDERR output is returned.

success

Returns true if the process exited with a status of 0. Otherwise returns false.

BUGS

None are known at this time, but if you find one, please feel free to submit a report to the author.

AUTHOR

jason hord <pravus@cpan.org>

SEE ALSO

Proc::Hevy

COPYRIGHT

Copyright (c) 2009-2014, jason hord

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

cpanm Proc::Lite

perl -MCPAN -e shell
install Proc::Lite