NAME

       Expect::Simple - wrapper around the Expect module

SYNOPSIS

         use Expect::Simple;

         my $obj = new Expect::Simple
               { Cmd => [ dmcoords => 'verbose=1', "infile=$infile"],
                 Prompt => [ -re => 'dmcoords>:\s+' ],
                 DisconnectCmd => 'q',
                 Verbose => 0,
                 Debug => 0,
                 Timeout => 100
               };

         $obj->send( $cmd );
         print $obj->before;
         print $obj->after;
         print $obj->match_str, "\n";
         print $obj->match_idx, "\n";
         print $obj->error_expect;
         print $obj->error;

         $expect_object = $obj->expect_handle;

DESCRIPTION

       "Expect::Simple" is a wrapper around the "Expect" module which should suffice for simple
       applications.  It hides most of the "Expect" machinery; the "Expect" object is available
       for tweaking if need be.

       Generally, one starts by creating an Expect::Simple object using new.  This will start up
       the target program, and will wait until one of the specified prompts is output by the
       target.  At that point the caller should send() commands to the program; the results are
       available via the before, after, match_str, and match_idx methods.  Since Expect simulates
       a terminal, there will be extra "\r" characters at the end of each line in the result (on
       UNIX at least).  This is easily fixed:

           ($res = $obj->before) =~ tr/\r//d;
           @lines = split( "\n", $res );

       This is not done automatically.

       Exceptions will be thrown on error (match with "/Expect::Simple/").  Errors from Expect
       are available via the error_expect method.  More human readable errors are available via
       the error method.

       The connection is automatically broken (by sending the specified disconnect command to the
       target) when the Expect::Simple object is destroyed.

   Methods
       new
                   $obj = Expect::Simple->new( \%attr );

               This creates a new object, starting up the program with which to communicate
               (using the Expect spawn method) and waiting for a prompt.  The passed hash
               reference must contain at least the Prompt, DisconnectCmd, and Cmd elements.  The
               available attributes are:

               Cmd
                         Cmd => $command,
                         Cmd => [ $command, $arg1, $arg2, ... ],

                       The command to which to connect.  The passed command may either be a
                       scalar or an array.

               Prompt  This specifies one or more prompts to scan for.  For a single prompt, the
                       value may be a scalar; for more, or for matching of regular expressions,
                       it should be an array reference.  For example,

                         Prompt => 'prompt1> ',
                         Prompt => [ 'prompt1> ', 'prompt2> ', -re => 'prompt\d+>\s+' ]

                       All prompts are taken literally, unless immediately preceded by a "-re"
                       flag, in which case they are regular expressions.

               DisconnectCmd
                       This is the command to be sent to the target program which will cause it
                       to exit.

               RawPty  If set, then underlying Expect object's pty mode is set to raw mode (see
                       Expect::raw_pty()).

               Timeout The time in seconds to wait until giving up on the target program
                       responding.  This is used during program startup and when any commands are
                       sent to the program.  It defaults to 1000 seconds.

               Debug   The value is passed to Expect via its debug method.

               Verbose This results in various messages printed to the STDERR stream.  If greater
                       than 3, it turns on Expect's logging to STDOUT (via the log_stdout Expect
                       method.

       send
                  $obj->send( $cmd );
                  $obj->send( @cmds );

               Send one or more commands to the target.  After each command is sent, it waits for
               a prompt from the target.  Only the output resulting from the last command is
               available via the after, before, etc. methods.

       match_idx
               This returns a unary based index indicating which prompt (in the list of prompts
               specified via the "Prompt" attribute to the new method) was received after the
               last command was sent.  It will be undef if none was returned.

       match_str
               This returns the prompt which was matched after the last command was sent.

       before  This returns the string received before the prompt.  If no prompt was seen, it
               returns all output accumulated.  This is usually what the caller wants to parse.
               Note that the first line will (usually) be the command that was sent to the
               target, because of echoing.  Check this out to be sure!

       after   This returns the 'after' string.  Please read the Expect docs for more
               enlightenment.

       error   This returns a cleaned up, more humanly readable version of the errors from
               Expect.  It'll be undef if there was no error.

       error_expect
               This returns the original Expect error.

       expect_handle
               This returns the Expect object, in case further tweaking is necessary.

BUGS

       If the command to be run does not exist (or not in the current execution path), it's quite
       possible that the new method will not throw an exception.  It's up to the caller to make
       sure that the command will run!  There's no known workaround for this.

LICENSE

       This software is released under the GNU General Public License.  You may find a copy at

          http://www.fsf.org/copyleft/gpl.html

AUTHOR

       Diab Jerius (djerius@cpan.org)