NAME
Command::Interactive- handles interactive (and non-interactive) process invocation through a reliable and easily configured interface.
SYNOPSIS
This module can be used to invoke both interactive and non-interactive commands with predicatable results.
use Command::Interactive;
use Carp;
# Simple, non-interactive usage
my $result = Command::Interactive->new->run("cp foo /tmp/");
croak "Could not copy foo to /tmp/: $result!" if($result);
# Interactive usage supports output parsing
# and automated responses to discovered strings
my $password_prompt = Command::Interactive::Interaction->new({
expected_string => 'Please enter your password:',
response => 'secret',
});
my $my_logging_fh;
my $command = Command::Interactive->new({
echo_output => 1,
output_stream => $my_logging_fh,
interactions => [ $password_prompt ],
});
my $restart_result = $command->run("ssh user\@somehost 'service apachectl restart'");
if($restart_result)
{
warn "Couldn't restart server!";
}FIELDS
always_use_expect (DEFAULT: FALSE)
Whether to use the Expect module to execute system commands. By default, Expect is only used if one or more interactions() are specified.
debug_logfile (DEFAULT: undef)
The name of a file to which lots of debugging information should be written. Typically useful only for maintainers. If you want to see what your command is doing, use echo_output() and a debugging filehandle (or just STDOUT).
echo_output (DEFAULT: FALSE)
Whether to echo output to the specified output_stream(). This allows users of Command::Interactive to see what is going on, but it also can clutter an interface with lots of superfluous command output. Use it wisely.
See web_format() for a discussion about how to format command output for web interfaces.
interactions (DEFAULT: [], the empty arrayref)
An array reference of Command::Interactive::Interaction objects that specify the interactions that may (or must) occur during the execution of the command. See Command::Interactive::Interaction for more information on specifying rules about command interactions.
output_stream (DEFAULT: STDOUT)
The stream object to which output should be sent when echo_output() is enabled. This is any object with a print() method; it needn't have a full IO-compliant interface.
timeout (DEFAULT: undef)
If defined, represents the timeout (in seconds) that Command::Interactive will wait for output when run() is called.
web_format (DEFAULT: FALSE)
Whether to format strings for web output when print command output as a result of echo_output(). If this is true, \r, \n, and \r\n will be replaced with "<br/>\n".
METHODS
run($command)
This method does the heavy lifting of Command::Interactive. If one or more interactions() are specified (or if always_use_expect() is true), then the heavy lifting is dispatched to _run_via_expect(); otherwise this method uses traditional perl open("$command |") approach.
$command is expected to be a scalar (string), properly escaped, that could be executed (e.g.) via system() or ``. No matter what command you provide, the bash file descriptors for stdout and stderr are tied together using '2>&1' unless you have done so already. This allows Command::Interactive to capture and react to both regular output and errors using the same mechanism.
run() returns undef if the command is successful, otherwise it returns a string describing why the command failed (or was thought to have failed).
The command you pass in via $command is expected to exit with status code 0 on success. If it returns something different, Command::Interactive will incorrectly conclude that the command failed and will return a message to that effect.
_show_output($chunk_of_output)
If echo_output() is true, this command prints any output from $command to the chosen output_stream(). If web_format() is true, the output is first formatted for HTML by replacing end-of-line characters with "<br/>\n".
_run_via_expect($command)
This method handles running commands with one or more interactions() (or for which always_use_expect() is true) via the Perl module Expect.
The return semantics of _run_via_expect() are identical to those of run().
_generate_instruction_list()
This method returns information to be passed to Expect's expect() method, as well as a bookkeeping array using for tracking number of times a given interaction has occurred.
_fixup_command_to_catch_stderr($original_command)
This method appends '2>&1' to the end of any command submitted to run(), except when that filehandle-tying string is already present in the command.
Returns the modified version of $original_command.
_log($line_to_log)
Used for internal logging purposes when debug_logfile() is defined. See the discussion of debug_logfile() for a better way to debug YOUR command's execution; this method is intended for consumption by developers of Command::Interactive.
AUTHOR
Binary.com, <perl@binary.com>
LICENSE
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.