/ 
IPC-RunExternal-0.06
River stage zero No dependents
/ IPC::RunExternal

NAME

IPC::RunExternal - Execute external (shell) command and gather stdout and stderr!

VERSION

Version 0.06

SYNOPSIS

    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
			});

DESCRIPTION

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.

DEPENDENCIES

Requires Perl version 5.6.2.

Requires the following modules:

    English Carp IPC::Open3; IO::Select Symbol

EXPORT

Exports routine runexternal().

SUBROUTINES/METHODS

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.

INCOMPATIBILITIES

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.

AUTHOR

Mikko Koivunalho, <mikko.koivunalho at iki.fi>

BUGS

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.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc IPC::RunExternal

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

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.