NAME

    IPC::Open3::Callback - An extension to IPC::Open3 that will feed out
    and err to callbacks instead of requiring the caller to handle them.

VERSION

    version 1.09

SYNOPSIS

      use IPC::Open3::Callback;
      my $runner = IPC::Open3::Callback->new( {
          out_callback => sub {
              my $data = shift;
              my $pid = shift;
    
              print( "$pid STDOUT: $data\n" );
          },
          err_callback => sub {
              my $data = shift;
              my $pid = shift;
    
              print( "$pid STDERR: $data\n" );
          } } );
      my $exit_code = $runner->run_command( 'echo Hello World' );
    
      use IPC::Open3::Callback qw(safe_open3);
      my ($pid, $in, $out, $err) = safe_open3( "echo", "Hello", "world" ); 
      $buffer = '';
      my $select = IO::Select->new();
      $select->add( $out );
      while ( my @ready = $select->can_read( 5 ) ) {
          foreach my $fh ( @ready ) {
              my $line;
              my $bytes_read = sysread( $fh, $line, 1024 );
              if ( ! defined( $bytes_read ) && !$!{ECONNRESET} ) {
                  die( "error in running ('echo $echo'): $!" );
              }
              elsif ( ! defined( $bytes_read) || $bytes_read == 0 ) {
                  $select->remove( $fh );
                  next;
              }
              else {
                  if ( $fh == $out ) {
                      $buffer .= $line;
                  }
                  else {
                      die( "impossible... somehow got a filehandle i dont know about!" );
                  }
              }
          }
      } 
      waitpid( $pid, 0 );
      my $exit_code = $? >> 8;
      print( "$pid exited with $exit_code: $buffer\n" ); # 123 exited with 0: Hello World

DESCRIPTION

    This module feeds output and error stream from a command to supplied
    callbacks. Thus, this class removes the necessity of dealing with
    IO::Select by hand and also provides a workaround for the bad
    reputation associated with Microsoft Windows' IPC.

EXPORT_OK

 safe_open3( $command, $arg1, ..., $argN )

    Passes the command and arguments on to open3 and returns a list
    containing:

    pid

      The process id of the forked process.

    stdin

      An IO::Handle to STDIN for the process.

    stdout

      An IO::Handle to STDOUT for the process.

    stderr

      An IO::Handle to STDERR for the process.

    As with open3, it is the callers responsibility to waitpid to ensure
    forked processes do not become zombies.

    This method works for both *nix and Microsoft Windows OS's. On a
    Windows system, it will use sockets per
    http://www.perlmonks.org/index.pl?node_id=811150.

CONSTRUCTORS

 new( \%options )

    The constructor creates a new Callback object and optionally sets
    global callbacks for STDOUT and STDERR streams from commands that will
    get run by this object (can be overridden per call to run_command). The
    currently available options are:

    out_callback

      out_callback

    err_callback

      err_callback

    buffer_output

      buffer_output

    buffer_size

      buffer_size

    select_timeout

      select_timeout

ATTRIBUTES

 get_buffer_output()

 set_buffer_output( $boolean )

    A boolean value, if true, will buffer output and send to callback one
    line at a time (waits for '\n'). Otherwise, sends text in the same
    chunks returned by sysread.

 get_buffer_size()

 set_buffer_size( $bytes )

    The size of the read buffer (in bytes) supplied to sysread.

 get_err_callback()

 set_err_callback( &subroutine )

    A subroutine that will be called for each chunk of text written to
    STDERR. The subroutine will be called with the same 2 arguments as
    out_callback.

 get_last_command()

    The last command run by the run_command method.

 get_out_callback()

 set_out_callback( &subroutine )

    A subroutine that will be called whenever a chunk of output is sent to
    STDOUT by the opened process. The subroutine will be called with 2
    arguments:

    data

      A chunk of text written to the stream

    pid

      The pid of the forked process

 get_pid()

    Will return the pid of the currently running process. This pid is set
    by run_command and will be cleared out when the run_command completes.

 get_select_timeout()

 set_select_timeout( $seconds )

    The timeout, in seconds, provided to IO::Select, by default 0 meaning
    no timeout which will cause the loop to block until output is ready on
    either STDOUT or STDERR.

METHODS

 run_command( $command, $arg1, ..., $argN, \%options )

    Will run the specified command with the supplied arguments by passing
    them on to safe_open3. Arguments can be embedded in the command string
    and are thus optional.

    If the last argument to this method is a hashref (ref(@_[-1]) eq
    'HASH'), then it is treated as an options hash. The supported allowed
    options are the same as the constructor and will be used in preference
    to the values set by the constructor or any of the setters. These
    options will be used for this single call, and will not modify the
    Callback object itself.

    Returns the exit code from the command.

AUTHORS

      * Lucas Theisen <lucastheisen@pastdev.com>

      * Alceu Rodrigues de Freitas Junior <arfreitas@cpan.org>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2013 by Lucas Theisen.

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

SEE ALSO

    Please see those modules/websites for more information related to this
    module.

      * IPC::Open3

      * IPC::Open3::Callback::Command

      * IPC::Open3::Callback::CommandRunner

      * https://github.com/lucastheisen/ipc-open3-callback

      * http://stackoverflow.com/q/16675950/516433