view release on metacpan or  search on metacpan

lib/Expect.pm  view on Meta::CPAN

Note that if spawn cannot exec() the given command, the Expect object
is still valid and the next expect() will see "Cannot exec", so you
can use that for error handling.

Also note that you cannot reuse an object with an already spawned
command, even if that command has exited.  Sorry, but you have to
allocate a new object...


=item $object->debug(0 | 1 | 2 | 3 | undef)

Sets debug level for $object. 1 refers to general debugging
information, 2 refers to verbose debugging and 0 refers to no
debugging. If you call debug() with no parameters it will return the
current debugging level.  When the object is created the debugging
level will match that $Expect::Debug, normally 0.

The '3' setting is new with 1.05, and adds the additional
functionality of having the _full_ accumulated buffer printed every
time data is read from an Expect object. This was implemented by
request. I recommend against using this unless you think you need it
as it can create quite a quantity of output under some circumstances..


=item $object->exp_internal(1 | 0)

Sets/unsets 'exp_internal' debugging. This is similar in nature to its Tcl
counterpart. It is extremely valuable when debugging expect() sequences.
When the object is created the exp_internal setting will match the value of
$Expect::Exp_Internal, normally 0. Returns the current setting if called
without parameters. It is highly recommended that you make use of the
debugging features lest you have angry code.


=item $object->raw_pty(1 | 0)

Set pty to raw mode before spawning.  This disables echoing, CR->LF
translation and an ugly hack for broken Solaris TTYs (which send
<space><backspace> to slow things down) and thus gives a more
pipe-like behaviour (which is important if you want to transfer binary
content).  Note that this must be set I<before> spawning the program.


=item $object->stty(qw(mode1 mode2...))

Sets the tty mode for $object's associated terminal to the given
modes.  Note that on many systems the master side of the pty is not a
tty, so you have to modify the slave pty instead, see next item.  This
needs IO::Stty installed, which is no longer required.


=item $object->slave()

Returns a filehandle to the slave part of the pty.  Very useful in modifying
the terminal settings:

  $object->slave->stty(qw(raw -echo));

Typical values are 'sane', 'raw', and 'raw -echo'.  Note that I
recommend setting the terminal to 'raw' or 'raw -echo', as this avoids
a lot of hassle and gives pipe-like (i.e. transparent) behaviour
(without the buffering issue).


=item $object->print(@strings) I<or>

=item $object->send(@strings)

Sends the given strings to the spawned command.  Note that the strings
are not logged in the logfile (see print_log_file) but will probably
be echoed back by the pty, depending on pty settings (default is echo)
and thus end up there anyway.  This must also be taken into account
when expect()ing for an answer: the next string will be the command
just sent.  I suggest setting the pty to raw, which disables echo and
makes the pty transparently act like a bidirectional pipe.


=item $object->expect($timeout, @match_patterns)

=over 4

=item Simple interface

Given $timeout in seconds Expect will wait for $object's handle to produce
one of the match_patterns, which are matched exactly by default. If you
want a regexp match, use a regexp object (C<qr//>) or prefix the pattern with '-re'.

  $object->expect(15, 'match me exactly', qr/match\s+me\s+exactly/);
  $object->expect(15, 'match me exactly','-re','match\s+me\s+exactly');

Due to o/s limitations $timeout should be a round number. If $timeout
is 0 Expect will check one time to see if $object's handle contains
any of the match_patterns. If $timeout is undef Expect
will wait forever for a pattern to match. If you don't want to 
explicitly put the timeout on all calls to C<expect>, you can set 
it via the C<timeout> method . If the first argument of C<expect> 
doesn't look like a number, that value will be used.

  $object->timeout(15);
  $object->expect('match me exactly','-re','match\s+me\s+exactly');


If called in a scalar context, expect() will return the position of
the matched pattern within @matched_patterns, or undef if no pattern was
matched. This is a position starting from 1, so if you want to know
which of an array of @matched_patterns matched you should subtract one
from the return value.

If called in an array context expect() will return
($matched_pattern_position, $error, $successfully_matching_string,
$before_match, and $after_match).

C<$matched_pattern_position> will contain the value that would have been
returned if expect() had been called in a scalar context.

C<$error> is
the error that occurred that caused expect() to return. $error will
contain a number followed by a string equivalent expressing the nature
of the error. Possible values are undef, indicating no error,
'1:TIMEOUT' indicating that $timeout seconds had elapsed without a
match, '2:EOF' indicating an eof was read from $object, '3: spawn
id($fileno) died' indicating that the process exited before matching
and '4:$!' indicating whatever error was set in $ERRNO during the last
read on $object's handle or during select(). All handles indicated by
set_group plus STDOUT will have all data to come out of $object
printed to them during expect() if log_group and log_stdout are set.

C<$successfully_matching_string>
C<$before_match>
C<$after_match>

Changed from older versions is the regular expression handling. By
default now all strings passed to expect() are treated as literals. To
match a regular expression pass '-re' as a parameter in front of the
pattern you want to match as a regexp.