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

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 <[email protected]>

   *   Alceu Rodrigues de Freitas Junior <[email protected]>

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>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.