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.

cpanm Command::Interactive

perl -MCPAN -e shell
install Command::Interactive