This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update IPC::Cmd to 0.38
[perl5.git] / lib / IPC / Cmd.pm
1 package IPC::Cmd;
2
3 use strict;
4
5 BEGIN {
6
7     use constant IS_VMS   => $^O eq 'VMS'                       ? 1 : 0;    
8     use constant IS_WIN32 => $^O eq 'MSWin32'                   ? 1 : 0;
9     use constant IS_WIN98 => (IS_WIN32 and !Win32::IsWinNT())   ? 1 : 0;
10
11     use Exporter    ();
12     use vars        qw[ @ISA $VERSION @EXPORT_OK $VERBOSE $DEBUG
13                         $USE_IPC_RUN $USE_IPC_OPEN3 $WARN
14                     ];
15
16     $VERSION        = '0.38';
17     $VERBOSE        = 0;
18     $DEBUG          = 0;
19     $WARN           = 1;
20     $USE_IPC_RUN    = IS_WIN32 && !IS_WIN98;
21     $USE_IPC_OPEN3  = not IS_VMS;
22
23     @ISA            = qw[Exporter];
24     @EXPORT_OK      = qw[can_run run];
25 }
26
27 require Carp;
28 use File::Spec;
29 use Params::Check               qw[check];
30 use Module::Load::Conditional   qw[can_load];
31 use Locale::Maketext::Simple    Style => 'gettext';
32
33 =pod
34
35 =head1 NAME
36
37 IPC::Cmd - finding and running system commands made easy
38
39 =head1 SYNOPSIS
40
41     use IPC::Cmd qw[can_run run];
42
43     my $full_path = can_run('wget') or warn 'wget is not installed!';
44
45     ### commands can be arrayrefs or strings ###
46     my $cmd = "$full_path -b theregister.co.uk";
47     my $cmd = [$full_path, '-b', 'theregister.co.uk'];
48
49     ### in scalar context ###
50     my $buffer;
51     if( scalar run( command => $cmd,
52                     verbose => 0,
53                     buffer  => \$buffer )
54     ) {
55         print "fetched webpage successfully: $buffer\n";
56     }
57
58
59     ### in list context ###
60     my( $success, $error_code, $full_buf, $stdout_buf, $stderr_buf ) =
61             run( command => $cmd, verbose => 0 );
62
63     if( $success ) {
64         print "this is what the command printed:\n";
65         print join "", @$full_buf;
66     }
67
68     ### check for features
69     print "IPC::Open3 available: "  . IPC::Cmd->can_use_ipc_open3;      
70     print "IPC::Run available: "    . IPC::Cmd->can_use_ipc_run;      
71     print "Can capture buffer: "    . IPC::Cmd->can_capture_buffer;     
72
73     ### don't have IPC::Cmd be verbose, ie don't print to stdout or
74     ### stderr when running commands -- default is '0'
75     $IPC::Cmd::VERBOSE = 0;
76
77 =head1 DESCRIPTION
78
79 IPC::Cmd allows you to run commands, interactively if desired,
80 platform independent but have them still work.
81
82 The C<can_run> function can tell you if a certain binary is installed
83 and if so where, whereas the C<run> function can actually execute any
84 of the commands you give it and give you a clear return value, as well
85 as adhere to your verbosity settings.
86
87 =head1 CLASS METHODS 
88
89 =head2 $bool = IPC::Cmd->can_use_ipc_run( [VERBOSE] )
90
91 Utility function that tells you if C<IPC::Run> is available. 
92 If the verbose flag is passed, it will print diagnostic messages
93 if C<IPC::Run> can not be found or loaded.
94
95 =cut
96
97
98 sub can_use_ipc_run     { 
99     my $self    = shift;
100     my $verbose = shift || 0;
101     
102     ### ipc::run doesn't run on win98    
103     return if IS_WIN98;
104
105     ### if we dont have ipc::run, we obviously can't use it.
106     return unless can_load(
107                         modules => { 'IPC::Run' => '0.55' },        
108                         verbose => ($WARN && $verbose),
109                     );
110                     
111     ### otherwise, we're good to go
112     return 1;                    
113 }
114
115 =head2 $bool = IPC::Cmd->can_use_ipc_open3( [VERBOSE] )
116
117 Utility function that tells you if C<IPC::Open3> is available. 
118 If the verbose flag is passed, it will print diagnostic messages
119 if C<IPC::Open3> can not be found or loaded.
120
121 =cut
122
123
124 sub can_use_ipc_open3   { 
125     my $self    = shift;
126     my $verbose = shift || 0;
127
128     ### ipc::open3 works on every platform, but it can't capture buffers
129     ### on win32 :(
130     return unless can_load(
131         modules => { map {$_ => '0.0'} qw|IPC::Open3 IO::Select Symbol| },
132         verbose => ($WARN && $verbose),
133     );
134     
135     return 1;
136 }
137
138 =head2 $bool = IPC::Cmd->can_capture_buffer
139
140 Utility function that tells you if C<IPC::Cmd> is capable of
141 capturing buffers in it's current configuration.
142
143 =cut
144
145 sub can_capture_buffer {
146     my $self    = shift;
147
148     return 1 if $USE_IPC_RUN    && $self->can_use_ipc_run; 
149     return 1 if $USE_IPC_OPEN3  && $self->can_use_ipc_open3 && !IS_WIN32; 
150     return;
151 }
152
153
154 =head1 FUNCTIONS
155
156 =head2 $path = can_run( PROGRAM );
157
158 C<can_run> takes but a single argument: the name of a binary you wish
159 to locate. C<can_run> works much like the unix binary C<which> or the bash
160 command C<type>, which scans through your path, looking for the requested
161 binary .
162
163 Unlike C<which> and C<type>, this function is platform independent and
164 will also work on, for example, Win32.
165
166 It will return the full path to the binary you asked for if it was
167 found, or C<undef> if it was not.
168
169 =cut
170
171 sub can_run {
172     my $command = shift;
173
174     # a lot of VMS executables have a symbol defined
175     # check those first
176     if ( $^O eq 'VMS' ) {
177         require VMS::DCLsym;
178         my $syms = VMS::DCLsym->new;
179         return $command if scalar $syms->getsym( uc $command );
180     }
181
182     require Config;
183     require File::Spec;
184     require ExtUtils::MakeMaker;
185
186     if( File::Spec->file_name_is_absolute($command) ) {
187         return MM->maybe_command($command);
188
189     } else {
190         for my $dir (
191             (split /\Q$Config::Config{path_sep}\E/, $ENV{PATH}),
192             File::Spec->curdir
193         ) {           
194             my $abs = File::Spec->catfile($dir, $command);
195             return $abs if $abs = MM->maybe_command($abs);
196         }
197     }
198 }
199
200 =head2 $ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( command => COMMAND, [verbose => BOOL, buffer => \$SCALAR] );
201
202 C<run> takes 3 arguments:
203
204 =over 4
205
206 =item command
207
208 This is the command to execute. It may be either a string or an array
209 reference.
210 This is a required argument.
211
212 See L<CAVEATS> for remarks on how commands are parsed and their
213 limitations.
214
215 =item verbose
216
217 This controls whether all output of a command should also be printed
218 to STDOUT/STDERR or should only be trapped in buffers (NOTE: buffers
219 require C<IPC::Run> to be installed or your system able to work with
220 C<IPC::Open3>).
221
222 It will default to the global setting of C<$IPC::Cmd::VERBOSE>,
223 which by default is 0.
224
225 =item buffer
226
227 This will hold all the output of a command. It needs to be a reference
228 to a scalar.
229 Note that this will hold both the STDOUT and STDERR messages, and you
230 have no way of telling which is which.
231 If you require this distinction, run the C<run> command in list context
232 and inspect the individual buffers.
233
234 Of course, this requires that the underlying call supports buffers. See
235 the note on buffers right above.
236
237 =back
238
239 C<run> will return a simple C<true> or C<false> when called in scalar
240 context.
241 In list context, you will be returned a list of the following items:
242
243 =over 4
244
245 =item success
246
247 A simple boolean indicating if the command executed without errors or
248 not.
249
250 =item errorcode
251
252 If the first element of the return value (success) was 0, then some
253 error occurred. This second element is the error code the command
254 you requested exited with, if available.
255
256 =item full_buffer
257
258 This is an arrayreference containing all the output the command
259 generated.
260 Note that buffers are only available if you have C<IPC::Run> installed,
261 or if your system is able to work with C<IPC::Open3> -- See below).
262 This element will be C<undef> if this is not the case.
263
264 =item out_buffer
265
266 This is an arrayreference containing all the output sent to STDOUT the
267 command generated.
268 Note that buffers are only available if you have C<IPC::Run> installed,
269 or if your system is able to work with C<IPC::Open3> -- See below).
270 This element will be C<undef> if this is not the case.
271
272 =item error_buffer
273
274 This is an arrayreference containing all the output sent to STDERR the
275 command generated.
276 Note that buffers are only available if you have C<IPC::Run> installed,
277 or if your system is able to work with C<IPC::Open3> -- See below).
278 This element will be C<undef> if this is not the case.
279
280 =back
281
282 See the C<HOW IT WORKS> Section below to see how C<IPC::Cmd> decides
283 what modules or function calls to use when issuing a command.
284
285 =cut
286
287 sub run {
288     my %hash = @_;
289     
290     ### if the user didn't provide a buffer, we'll store it here.
291     my $def_buf = '';
292     
293     my($verbose,$cmd,$buffer);
294     my $tmpl = {
295         verbose => { default  => $VERBOSE,  store => \$verbose },
296         buffer  => { default  => \$def_buf, store => \$buffer },
297         command => { required => 1,         store => \$cmd,
298                      allow    => sub { !ref($_[0]) or ref($_[0]) eq 'ARRAY' } 
299         },
300     };
301
302     unless( check( $tmpl, \%hash, $VERBOSE ) ) {
303         Carp::carp(loc("Could not validate input: %1", Params::Check->last_error));
304         return;
305     };        
306
307     print loc("Running [%1]...\n", (ref $cmd ? "@$cmd" : $cmd)) if $verbose;
308
309     ### did the user pass us a buffer to fill or not? if so, set this
310     ### flag so we know what is expected of us
311     ### XXX this is now being ignored. in the future, we could add diagnostic
312     ### messages based on this logic
313     #my $user_provided_buffer = $buffer == \$def_buf ? 0 : 1;
314     
315     ### buffers that are to be captured
316     my( @buffer, @buff_err, @buff_out );
317
318     ### capture STDOUT
319     my $_out_handler = sub {
320         my $buf = shift;
321         return unless defined $buf;
322         
323         print STDOUT $buf if $verbose;
324         push @buffer,   $buf;
325         push @buff_out, $buf;
326     };
327     
328     ### capture STDERR
329     my $_err_handler = sub {
330         my $buf = shift;
331         return unless defined $buf;
332         
333         print STDERR $buf if $verbose;
334         push @buffer,   $buf;
335         push @buff_err, $buf;
336     };
337     
338
339     ### flag to indicate we have a buffer captured
340     my $have_buffer = __PACKAGE__->can_capture_buffer ? 1 : 0;
341     
342     ### flag indicating if the subcall went ok
343     my $ok;
344     
345     ### IPC::Run is first choice if $USE_IPC_RUN is set.
346     if( $USE_IPC_RUN and __PACKAGE__->can_use_ipc_run( 1 ) ) {
347         ### ipc::run handlers needs the command as a string or an array ref
348
349         __PACKAGE__->_debug( "# Using IPC::Run. Have buffer: $have_buffer" )
350             if $DEBUG;
351             
352         $ok = __PACKAGE__->_ipc_run( $cmd, $_out_handler, $_err_handler );
353
354     ### since IPC::Open3 works on all platforms, and just fails on
355     ### win32 for capturing buffers, do that ideally
356     } elsif ( $USE_IPC_OPEN3 and __PACKAGE__->can_use_ipc_open3( 1 ) ) {
357
358         __PACKAGE__->_debug( "# Using IPC::Open3. Have buffer: $have_buffer" )
359             if $DEBUG;
360
361         ### in case there are pipes in there;
362         ### IPC::Open3 will call exec and exec will do the right thing 
363         $ok = __PACKAGE__->_open3_run( 
364                                 ( ref $cmd ? "@$cmd" : $cmd ),
365                                 $_out_handler, $_err_handler, $verbose 
366                             );
367         
368     ### if we are allowed to run verbose, just dispatch the system command
369     } else {
370         __PACKAGE__->_debug( "# Using system(). Have buffer: $have_buffer" )
371             if $DEBUG;
372         $ok = __PACKAGE__->_system_run( (ref $cmd ? "@$cmd" : $cmd), $verbose );
373     }
374     
375     ### fill the buffer;
376     $$buffer = join '', @buffer if @buffer;
377     
378     ### return a list of flags and buffers (if available) in list
379     ### context, or just a simple 'ok' in scalar
380     return wantarray
381                 ? $have_buffer
382                     ? ($ok, $?, \@buffer, \@buff_out, \@buff_err)
383                     : ($ok, $? )
384                 : $ok
385     
386     
387 }
388
389 sub _open3_run { 
390     my $self            = shift;
391     my $cmd             = shift;
392     my $_out_handler    = shift;
393     my $_err_handler    = shift;
394     my $verbose         = shift || 0;
395
396     ### Following code are adapted from Friar 'abstracts' in the
397     ### Perl Monastery (http://www.perlmonks.org/index.pl?node_id=151886).
398     ### XXX that code didn't work.
399     ### we now use the following code, thanks to theorbtwo
400
401     ### define them beforehand, so we always have defined FH's
402     ### to read from.
403     use Symbol;    
404     my $kidout      = Symbol::gensym();
405     my $kiderror    = Symbol::gensym();
406
407     ### Dup the filehandle so we can pass 'our' STDIN to the
408     ### child process. This stops us from having to pump input
409     ### from ourselves to the childprocess. However, we will need
410     ### to revive the FH afterwards, as IPC::Open3 closes it.
411     ### We'll do the same for STDOUT and STDERR. It works without
412     ### duping them on non-unix derivatives, but not on win32.
413     my @fds_to_dup = ( IS_WIN32 && !$verbose 
414                             ? qw[STDIN STDOUT STDERR] 
415                             : qw[STDIN]
416                         );
417     __PACKAGE__->__dup_fds( @fds_to_dup );
418     
419
420     my $pid = IPC::Open3::open3(
421                     '<&STDIN',
422                     (IS_WIN32 ? '>&STDOUT' : $kidout),
423                     (IS_WIN32 ? '>&STDERR' : $kiderror),
424                     $cmd
425                 );
426
427     ### use OUR stdin, not $kidin. Somehow,
428     ### we never get the input.. so jump through
429     ### some hoops to do it :(
430     my $selector = IO::Select->new(
431                         (IS_WIN32 ? \*STDERR : $kiderror), 
432                         \*STDIN,   
433                         (IS_WIN32 ? \*STDOUT : $kidout)     
434                     );              
435
436     STDOUT->autoflush(1);   STDERR->autoflush(1);   STDIN->autoflush(1);
437     $kidout->autoflush(1)   if UNIVERSAL::can($kidout,   'autoflush');
438     $kiderror->autoflush(1) if UNIVERSAL::can($kiderror, 'autoflush');
439
440     ### add an epxlicit break statement
441     ### code courtesy of theorbtwo from #london.pm
442     my $stdout_done = 0;
443     my $stderr_done = 0;
444     OUTER: while ( my @ready = $selector->can_read ) {
445
446         for my $h ( @ready ) {
447             my $buf;
448             
449             ### $len is the amount of bytes read
450             my $len = sysread( $h, $buf, 4096 );    # try to read 4096 bytes
451             
452             ### see perldoc -f sysread: it returns undef on error,
453             ### so bail out.
454             if( not defined $len ) {
455                 warn(loc("Error reading from process: %1", $!));
456                 last OUTER;
457             }
458             
459             ### check for $len. it may be 0, at which point we're
460             ### done reading, so don't try to process it.
461             ### if we would print anyway, we'd provide bogus information
462             $_out_handler->( "$buf" ) if $len && $h == $kidout;
463             $_err_handler->( "$buf" ) if $len && $h == $kiderror;
464
465             ### Wait till child process is done printing to both
466             ### stdout and stderr.
467             $stdout_done = 1 if $h == $kidout   and $len == 0;
468             $stderr_done = 1 if $h == $kiderror and $len == 0;
469             last OUTER if ($stdout_done && $stderr_done);
470         }
471     }
472
473     waitpid $pid, 0; # wait for it to die
474
475     ### restore STDIN after duping, or STDIN will be closed for
476     ### this current perl process!
477     __PACKAGE__->__reopen_fds( @fds_to_dup );
478     
479     return if $?;   # some error occurred
480     return 1;
481 }
482
483
484 sub _ipc_run {  
485     my $self            = shift;
486     my $cmd             = shift;
487     my $_out_handler    = shift;
488     my $_err_handler    = shift;
489     
490     STDOUT->autoflush(1); STDERR->autoflush(1);
491
492     ### a command like:
493     # [
494     #     '/usr/bin/gzip',
495     #     '-cdf',
496     #     '/Users/kane/sources/p4/other/archive-extract/t/src/x.tgz',
497     #     '|',
498     #     '/usr/bin/tar',
499     #     '-tf -'
500     # ]
501     ### needs to become:
502     # [
503     #     ['/usr/bin/gzip', '-cdf',
504     #       '/Users/kane/sources/p4/other/archive-extract/t/src/x.tgz']
505     #     '|',
506     #     ['/usr/bin/tar', '-tf -']
507     # ]
508
509     
510     my @command; my $special_chars;
511     if( ref $cmd ) {
512         my $aref = [];
513         for my $item (@$cmd) {
514             if( $item =~ /([<>|&])/ ) {
515                 push @command, $aref, $item;
516                 $aref = [];
517                 $special_chars .= $1;
518             } else {
519                 push @$aref, $item;
520             }
521         }
522         push @command, $aref;
523     } else {
524         @command = map { if( /([<>|&])/ ) {
525                             $special_chars .= $1; $_;
526                          } else {
527                             [ split / +/ ]
528                          }
529                     } split( /\s*([<>|&])\s*/, $cmd );
530     }
531  
532     ### if there's a pipe in the command, *STDIN needs to 
533     ### be inserted *BEFORE* the pipe, to work on win32
534     ### this also works on *nix, so we should do it when possible
535     ### this should *also* work on multiple pipes in the command
536     ### if there's no pipe in the command, append STDIN to the back
537     ### of the command instead.
538     ### XXX seems IPC::Run works it out for itself if you just
539     ### dont pass STDIN at all.
540     #     if( $special_chars and $special_chars =~ /\|/ ) {
541     #         ### only add STDIN the first time..
542     #         my $i;
543     #         @command = map { ($_ eq '|' && not $i++) 
544     #                             ? ( \*STDIN, $_ ) 
545     #                             : $_ 
546     #                         } @command; 
547     #     } else {
548     #         push @command, \*STDIN;
549     #     }
550   
551  
552     # \*STDIN is already included in the @command, see a few lines up
553     return IPC::Run::run(   @command, 
554                             fileno(STDOUT).'>',
555                             $_out_handler,
556                             fileno(STDERR).'>',
557                             $_err_handler
558                         );
559 }
560
561 sub _system_run { 
562     my $self    = shift;
563     my $cmd     = shift;
564     my $verbose = shift || 0;
565
566     my @fds_to_dup = $verbose ? () : qw[STDOUT STDERR];
567     __PACKAGE__->__dup_fds( @fds_to_dup );
568     
569     ### system returns 'true' on failure -- the exit code of the cmd
570     system( $cmd );
571     
572     __PACKAGE__->__reopen_fds( @fds_to_dup );
573     
574     return if $?;
575     return 1;
576 }
577
578 {   use File::Spec;
579     use Symbol;
580
581     my %Map = (
582         STDOUT => [qw|>&|, \*STDOUT, Symbol::gensym() ],
583         STDERR => [qw|>&|, \*STDERR, Symbol::gensym() ],
584         STDIN  => [qw|<&|, \*STDIN,  Symbol::gensym() ],
585     );
586
587     ### dups FDs and stores them in a cache
588     sub __dup_fds {
589         my $self    = shift;
590         my @fds     = @_;
591
592         __PACKAGE__->_debug( "# Closing the following fds: @fds" ) if $DEBUG;
593
594         for my $name ( @fds ) {
595             my($redir, $fh, $glob) = @{$Map{$name}} or (
596                 Carp::carp(loc("No such FD: '%1'", $name)), next );
597             
598             ### MUST use the 2-arg version of open for dup'ing for 
599             ### 5.6.x compatibilty. 5.8.x can use 3-arg open
600             ### see perldoc5.6.2 -f open for details            
601             open $glob, $redir . fileno($fh) or (
602                         Carp::carp(loc("Could not dup '$name': %1", $!)),
603                         return
604                     );        
605                 
606             ### we should re-open this filehandle right now, not
607             ### just dup it
608             if( $redir eq '>&' ) {
609                 open( $fh, '>', File::Spec->devnull ) or (
610                     Carp::carp(loc("Could not reopen '$name': %1", $!)),
611                     return
612                 );
613             }
614         }
615         
616         return 1;
617     }
618
619     ### reopens FDs from the cache    
620     sub __reopen_fds {
621         my $self    = shift;
622         my @fds     = @_;
623
624         __PACKAGE__->_debug( "# Reopening the following fds: @fds" ) if $DEBUG;
625
626         for my $name ( @fds ) {
627             my($redir, $fh, $glob) = @{$Map{$name}} or (
628                 Carp::carp(loc("No such FD: '%1'", $name)), next );
629
630             ### MUST use the 2-arg version of open for dup'ing for 
631             ### 5.6.x compatibilty. 5.8.x can use 3-arg open
632             ### see perldoc5.6.2 -f open for details
633             open( $fh, $redir . fileno($glob) ) or (
634                     Carp::carp(loc("Could not restore '$name': %1", $!)),
635                     return
636                 ); 
637            
638             ### close this FD, we're not using it anymore
639             close $glob;                
640         }                
641         return 1;                
642     
643     }
644 }    
645
646 sub _debug {
647     my $self    = shift;
648     my $msg     = shift or return;
649     my $level   = shift || 0;
650     
651     local $Carp::CarpLevel += $level;
652     Carp::carp($msg);
653     
654     return 1;
655 }
656
657
658 1;
659
660
661 __END__
662
663 =head1 HOW IT WORKS
664
665 C<run> will try to execute your command using the following logic:
666
667 =over 4
668
669 =item *
670
671 If you have C<IPC::Run> installed, and the variable C<$IPC::Cmd::USE_IPC_RUN>
672 is set to true (See the C<GLOBAL VARIABLES> Section) use that to execute 
673 the command. You will have the full output available in buffers, interactive commands are sure to work  and you are guaranteed to have your verbosity
674 settings honored cleanly.
675
676 =item *
677
678 Otherwise, if the variable C<$IPC::Cmd::USE_IPC_OPEN3> is set to true 
679 (See the C<GLOBAL VARIABLES> Section), try to execute the command using
680 C<IPC::Open3>. Buffers will be available on all platforms except C<Win32>,
681 interactive commands will still execute cleanly, and also your verbosity
682 settings will be adhered to nicely;
683
684 =item *
685
686 Otherwise, if you have the verbose argument set to true, we fall back
687 to a simple system() call. We cannot capture any buffers, but
688 interactive commands will still work.
689
690 =item *
691
692 Otherwise we will try and temporarily redirect STDERR and STDOUT, do a
693 system() call with your command and then re-open STDERR and STDOUT.
694 This is the method of last resort and will still allow you to execute
695 your commands cleanly. However, no buffers will be available.
696
697 =back
698
699 =head1 Global Variables
700
701 The behaviour of IPC::Cmd can be altered by changing the following
702 global variables:
703
704 =head2 $IPC::Cmd::VERBOSE
705
706 This controls whether IPC::Cmd will print any output from the
707 commands to the screen or not. The default is 0;
708
709 =head2 $IPC::Cmd::USE_IPC_RUN
710
711 This variable controls whether IPC::Cmd will try to use L<IPC::Run>
712 when available and suitable. Defaults to true if you are on C<Win32>.
713
714 =head2 $IPC::Cmd::USE_IPC_OPEN3
715
716 This variable controls whether IPC::Cmd will try to use L<IPC::Open3>
717 when available and suitable. Defaults to true.
718
719 =head2 $IPC::Cmd::WARN
720
721 This variable controls whether run time warnings should be issued, like
722 the failure to load an C<IPC::*> module you explicitly requested.
723
724 Defaults to true. Turn this off at your own risk.
725
726 =head1 Caveats
727
728 =over 4
729
730 =item Whitespace
731
732 When you provide a string as this argument, the string will be
733 split on whitespace to determine the individual elements of your
734 command. Although this will usually just Do What You Mean, it may
735 break if you have files or commands with whitespace in them.
736
737 If you do not wish this to happen, you should provide an array
738 reference, where all parts of your command are already separated out.
739 Note however, if there's extra or spurious whitespace in these parts,
740 the parser or underlying code may not interpret it correctly, and
741 cause an error.
742
743 Example:
744 The following code
745
746     gzip -cdf foo.tar.gz | tar -xf -
747
748 should either be passed as
749
750     "gzip -cdf foo.tar.gz | tar -xf -"
751
752 or as
753
754     ['gzip', '-cdf', 'foo.tar.gz', '|', 'tar', '-xf', '-']
755
756 But take care not to pass it as, for example
757
758     ['gzip -cdf foo.tar.gz', '|', 'tar -xf -']
759
760 Since this will lead to issues as described above.
761
762 =item IO Redirect
763
764 Currently it is too complicated to parse your command for IO
765 Redirections. For capturing STDOUT or STDERR there is a work around
766 however, since you can just inspect your buffers for the contents.
767
768 =back
769
770 =head1 See Also
771
772 C<IPC::Run>, C<IPC::Open3>
773
774 =head1 ACKNOWLEDGEMENTS
775
776 Thanks to James Mastros and Martijn van der Streek for their
777 help in getting IPC::Open3 to behave nicely.
778
779 =head1 BUG REPORTS
780
781 Please report bugs or other issues to E<lt>bug-ipc-cmd@rt.cpan.orgE<gt>.
782
783 =head1 AUTHOR
784
785 This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
786
787 =head1 COPYRIGHT
788
789 This library is free software; you may redistribute and/or modify it 
790 under the same terms as Perl itself.
791
792 =cut