NAME

IPC::RunExternal - Execute an external command conveniently by hiding the details of IPC::Open3.

VERSION

version 0.102

SYNOPSIS

    use IPC::RunExternal;

    my $external_command = 'ls -r /'; # Any normal Shell command line
    my $stdin = q{}; # STDIN for the command. Must be an initialised 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);
    ($exit_code, $stdout, $stderr, $allout)
            = runexternal($external_command, $stdin, $timeout, \%parameter_tags);

    # Parameter tags opened:
    ($exit_code, $stdout, $stderr, $allout)
            = runexternal($external_command, $stdin, $timeout, { progress_indicator_char => q{#} });

    # 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 than with `` or 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.

STATUS

This package is currently being developed so changes in the API and functionality are possible.

DEPENDENCIES

Requires Perl version 5.6.2.

EXPORT

Exports routine runexternal().

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.

SUBROUTINES/METHODS

runexternal

Run an external (operating system) command.

Parameters:

1. command, a system executable.

2. input (stdin), for the command, must be an initialised 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.

SEE ALSO

IPC::Run

System::Command

IPC::Open3

AUTHOR

Mikko Koivunalho <mikkoi@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Mikko Koivunalho.

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