- NAME
- SYNOPSIS
- DESCRIPTION
- FUNCTIONS
  - safe_open3( $command, $arg1, ..., $argN )
- CONSTRUCTOR
  - new( \%options )
- METHODS
  - run_command( $command, $arg1, ..., $argN, \%options )
- AUTHOR
- COPYRIGHT
- SEE ALSO

# 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.

# 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 Windows systems.

# FUNCTIONS

## 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 Windows sytems. On a windows system, it will use sockets per http://www.perlmonks.org/index.pl?node_id=811150.

# CONSTRUCTOR

## 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).

out_callback

  A subroutine to call for each chunk of text written to `STDOUT`. This subroutine will be called with 2 arguments:

  data

    A chunk of text written to the stream

  pid

    The pid of the forked process

err_callback

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

buffer_output

  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.

select_timeout

  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 in the constructor for this call.

Returns the exit code from the command.

# AUTHOR

Lucas Theisen (lucastheisen@pastdev.com)

# COPYRIGHT

Copyright 2013 pastdev.com. All rights reserved.

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

# SEE ALSO

IPC::Open3 IPC::Open3::Callback::Command IPC::Open3::Callback::CommandRunner https://github.com/lucastheisen/ipc-open3-callback http://stackoverflow.com/q/16675950/516433