Mikko Koivunalho > IPC-RunExternal-0.03 > IPC::RunExternal

Download:
IPC-RunExternal-0.03.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.03   Source   Latest Release: IPC-RunExternal-0.09

NAME ^

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

VERSION ^

Version 0.03

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

syntax highlighting: