IPC::RunExternal - Execute external (shell) command and gather stdout and stderr!
Version 0.06
use IPC::RunExternal; my $external_command = 'ls -r /'; # Any normal Shell command line my $stdin = q{}; # STDIN for the command. Must be an initialized string, e.g. q{}. my $timeout = 60; # Maximum number of seconds before forced termination. my %parameter_tags = (print_progress_indicator => 1); # Parameter tags: # print_progress_indicator [1/0]. Output something on the terminal every second during # the execution, to tell user something is still going on. # progress_indicator_char [*], What to print, default is '#'. # execute_every_second [&], instead of printing the same everytime, # execute a function. The first parameters to this function is the number of seconds passed. my ($exit_code, $stdout, $stderr, $allout) = runexternal($external_command, $stdin, $timeout, \%parameter_tags); my ($exit_code, $stdout, $stderr, $allout) = runexternal($external_command, $stdin, $timeout, {progress_indicator_char => '#'}); # Print `date` at every 10 seconds during execution my $print_date_function = sub { my $secs_run = shift; if($secs_run % 10 == 0) { print `/bin/date`; } }; ($exit_code, $stdout, $stderr, $allout) = runexternal($external_command, $stdin, $timeout, { execute_every_second => $print_date_function });
IPC::RunExternal is for executing external operating system programs more conveniently that with `` (backticks) or exec/system, and without all the hassle of IPC::Open3.
IPC::RunExternal allows: 1) Capture STDOUT and STDERR in scalar variables. 2) Capture both STDOUT and STDERR in one scalar variable, in the correct order. 3) Use timeout to break the execution of a program running too long. 4) Keep user happy by printing something (e.g. '.' or '#') every second. 5) Not happy with simply printing something? Then execute your own code (function) at every second while the program is running.
Requires Perl version 5.6.2.
Requires the following modules:
English Carp IPC::Open3; IO::Select Symbol
Exports routine runexternal().
Run an external (operating system) command. Parameters: 1. command, a system executable. 2. input (STDIN), for the command, must be an initialized string, if no input, string should be empty. 3. timeout, 0 (no timeout) or greater. 4. parameter tags (a hash) print_progress_indicator: 1/0 (TRUE/FALSE), default FALSE progress_indicator_char: default "."; printed every second. execute_every_second: parameter to a function, executed every second. Return values (an array of four items): 1. exit_status, an integer, 1 = OK 0 = timeout (process killed). "Timeout" added to $output_error and $output_all. -1 = couldn't execute (IPC:Open3 failed, other reason). Reason (given by shell) in $output_error. 2. $output_std (what the command returned) 3. $output_error (what the command returned) 4. $output_all: $output_std and $output_error mixed in order of occurrence.
Working in MSWin not guaranteed, might also not work in other Unices / OpenVMS / other systems. Tested only in Linux. Depends mostly on IPC::Open3 working in the system.
Mikko Koivunalho, <mikko.koivunalho at iki.fi>
<mikko.koivunalho at iki.fi>
Please report any bugs or feature requests to bug-ipc-runexternal at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IPC-RunExternal. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-ipc-runexternal at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc IPC::RunExternal
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=IPC-RunExternal
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/IPC-RunExternal
CPAN Ratings
http://cpanratings.perl.org/d/IPC-RunExternal
Search CPAN
http://search.cpan.org/dist/IPC-RunExternal/
Copyright 2011 Mikko Koivunalho.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install IPC::RunExternal, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IPC::RunExternal
CPAN shell
perl -MCPAN -e shell install IPC::RunExternal
For more information on module installation, please visit the detailed CPAN module installation guide.