.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Expect::Simple 3pm"
.TH Expect::Simple 3pm "2021-01-05" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Expect::Simple \- wrapper around the Expect module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Expect::Simple;
\&
\&  my $obj = new Expect::Simple 
\&        { Cmd => [ dmcoords => \*(Aqverbose=1\*(Aq, "infile=$infile"],
\&          Prompt => [ \-re => \*(Aqdmcoords>:\es+\*(Aq ],
\&          DisconnectCmd => \*(Aqq\*(Aq,
\&          Verbose => 0,
\&          Debug => 0,
\&          Timeout => 100
\&        };
\&
\&  $obj\->send( $cmd );
\&  print $obj\->before;
\&  print $obj\->after;
\&  print $obj\->match_str, "\en";
\&  print $obj\->match_idx, "\en";
\&  print $obj\->error_expect;
\&  print $obj\->error;
\&
\&  $expect_object = $obj\->expect_handle;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Expect::Simple\*(C'\fR is a wrapper around the \f(CW\*(C`Expect\*(C'\fR module which
should suffice for simple applications.  It hides most of the
\&\f(CW\*(C`Expect\*(C'\fR machinery; the \f(CW\*(C`Expect\*(C'\fR object is available for tweaking if
need be.
.PP
Generally, one starts by creating an \fBExpect::Simple\fR object using
\&\fBnew\fR.  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 \fB\fBsend()\fB\fR commands to the program; the results are
available via the \fBbefore\fR, \fBafter\fR, \fBmatch_str\fR, and \fBmatch_idx\fR
methods.  Since \fBExpect\fR simulates a terminal, there will be extra
\&\f(CW\*(C`\er\*(C'\fR characters at the end of each line in the result (on \s-1UNIX\s0 at
least).  This is easily fixed:
.PP
.Vb 2
\&    ($res = $obj\->before) =~ tr/\er//d;
\&    @lines = split( "\en", $res );
.Ve
.PP
This is \fBnot\fR done automatically.
.PP
Exceptions will be thrown on error (match with \f(CW\*(C`/Expect::Simple/\*(C'\fR).
Errors from \fBExpect\fR are available via the \fBerror_expect\fR method.
More human readable errors are available via the \fBerror\fR method.
.PP
The connection is automatically broken (by sending the specified
disconnect command to the target) when the \fBExpect::Simple\fR object is 
destroyed.
.SS "Methods"
.IX Subsection "Methods"
.IP "new" 8
.IX Item "new"
.Vb 1
\&    $obj = Expect::Simple\->new( \e%attr );
.Ve
.Sp
This creates a new object, starting up the program with which to
communicate (using the \fBExpect\fR \fBspawn\fR method) and waiting for a
prompt.  The passed hash reference must contain at least the
\&\fBPrompt\fR, \fBDisconnectCmd\fR, and \fBCmd\fR elements.  The available
attributes are:
.RS 8
.IP "Cmd" 8
.IX Item "Cmd"
.Vb 2
\&  Cmd => $command,
\&  Cmd => [ $command, $arg1, $arg2, ... ],
.Ve
.Sp
The command to which to connect.  The passed command may either be a
scalar or an array.
.IP "Prompt" 8
.IX Item "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,
.Sp
.Vb 2
\&  Prompt => \*(Aqprompt1> \*(Aq,
\&  Prompt => [ \*(Aqprompt1> \*(Aq, \*(Aqprompt2> \*(Aq, \-re => \*(Aqprompt\ed+>\es+\*(Aq ]
.Ve
.Sp
All prompts are taken literally, unless immediately preceded by a \f(CW\*(C`\-re\*(C'\fR flag,
in which case they are regular expressions.
.IP "DisconnectCmd" 8
.IX Item "DisconnectCmd"
This is the command to be sent to the target program which will cause
it to exit.
.IP "RawPty" 8
.IX Item "RawPty"
If set, then underlying \fBExpect\fR object's pty mode is set to raw mode
(see  \fB\fBExpect::raw_pty()\fB\fR).
.IP "Timeout" 8
.IX Item "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.
.IP "Debug" 8
.IX Item "Debug"
The value is passed to \fBExpect\fR via its \fBdebug\fR method.
.IP "Verbose" 8
.IX Item "Verbose"
This results in various messages printed to the \s-1STDERR\s0 stream.
If greater than 3, it turns on \fBExpect\fR's logging to \s-1STDOUT\s0 (via
the \fBlog_stdout\fR \fBExpect\fR method.
.RE
.RS 8
.RE
.IP "send" 8
.IX Item "send"
.Vb 2
\&   $obj\->send( $cmd );
\&   $obj\->send( @cmds );
.Ve
.Sp
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 \fBafter\fR, \fBbefore\fR, etc. methods.
.IP "match_idx" 8
.IX Item "match_idx"
This returns a unary based index indicating which prompt (in the list
of prompts specified via the \f(CW\*(C`Prompt\*(C'\fR attribute to the \fBnew\fR method)
was received after the last command was sent.  It will be undef if
none was returned.
.IP "match_str" 8
.IX Item "match_str"
This returns the prompt which was matched after the last command was sent.
.IP "before" 8
.IX Item "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!
.IP "after" 8
.IX Item "after"
This returns the 'after' string.  Please read the \fBExpect\fR docs for more
enlightenment.
.IP "error" 8
.IX Item "error"
This returns a cleaned up, more humanly readable version of the errors
from \fBExpect\fR.  It'll be undef if there was no error.
.IP "error_expect" 8
.IX Item "error_expect"
This returns the original \fBExpect\fR error.
.IP "expect_handle" 8
.IX Item "expect_handle"
This returns the \fBExpect\fR object, in case further tweaking is necessary.
.SH "BUGS"
.IX Header "BUGS"
If the command to be run does not exist (or not in the current
execution path), it's quite possible that the \fBnew\fR 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.
.SH "LICENSE"
.IX Header "LICENSE"
This software is released under the \s-1GNU\s0 General Public License.  You
may find a copy at
.PP
.Vb 1
\&   http://www.fsf.org/copyleft/gpl.html
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Diab Jerius (djerius@cpan.org)