NAME¶

Expect - automate interactions with command line programs that expose a text terminal interface.

SYNOPSIS¶

  use Expect;
  # create an Expect object by spawning another process
  my $exp = Expect->spawn($command, @params)
    or die "Cannot spawn $command: $!\n";
  # or by using an already opened filehandle (e.g. from Net::Telnet)
  my $exp = Expect->exp_init(\*FILEHANDLE);
  # if you prefer the OO mindset:
  my $exp = Expect->new;
  $exp->raw_pty(1);
  $exp->spawn($command, @parameters)
    or die "Cannot spawn $command: $!\n";
  # send some string there:
  $exp->send("string\n");
  # or, for the filehandle mindset:
  print $exp "string\n";
  # then do some pattern matching with either the simple interface
  $patidx = $exp->expect($timeout, @match_patterns);
  # or multi-match on several spawned commands with callbacks,
  # just like the Tcl version
  $exp->expect($timeout,
             [ qr/regex1/ => sub { my $exp = shift;
                       $exp->send("response\n");
                       exp_continue; } ],
             [ "regexp2" , \&callback, @cbparms ],
            );
  # if no longer needed, do a soft_close to nicely shut down the command
  $exp->soft_close();
  # or be less patient with
  $exp->hard_close();

Expect.pm is built to either spawn a process or take an existing filehandle and interact with it such that normally interactive tasks can be done without operator assistance. This concept makes more sense if you are already familiar with the versatile Tcl version of Expect. The public functions that make up Expect.pm are:

  Expect->new()
  Expect::interconnect(@objects_to_be_read_from)
  Expect::test_handles($timeout, @objects_to_test)
  Expect::version($version_requested | undef);
  $object->spawn(@command)
  $object->clear_accum()
  $object->set_accum($value)
  $object->debug($debug_level)
  $object->exp_internal(0 | 1)
  $object->notransfer(0 | 1)
  $object->raw_pty(0 | 1)
  $object->stty(@stty_modes) # See the IO::Stty docs
  $object->slave()
  $object->before();
  $object->match();
  $object->after();
  $object->matchlist();
  $object->match_number();
  $object->error();
  $object->command();
  $object->exitstatus();
  $object->pty_handle();
  $object->do_soft_close();
  $object->restart_timeout_upon_receive(0 | 1);
  $object->interact($other_object, $escape_sequence)
  $object->log_group(0 | 1 | undef)
  $object->log_user(0 | 1 | undef)
  $object->log_file("filename" | $filehandle | \&coderef | undef)
  $object->manual_stty(0 | 1 | undef)
  $object->match_max($max_buffersize or undef)
  $object->pid();
  $object->send_slow($delay, @strings_to_send)
  $object->set_group(@listen_group_objects | undef)
  $object->set_seq($sequence,\&function,\@parameters);

There are several configurable package variables that affect the behavior of Expect. They are:

  $Expect::Debug;
  $Expect::Exp_Internal;
  $Expect::IgnoreEintr;
  $Expect::Log_Group;
  $Expect::Log_Stdout;
  $Expect::Manual_Stty;
  $Expect::Multiline_Matching;
  $Expect::Do_Soft_Close;

DESCRIPTION¶

See an explanation of What is Expect <http://code-maven.com/expect>

The Expect module is a successor of Comm.pl and a descendent of Chat.pl. It more closely resembles the Tcl Expect language than its predecessors. It does not contain any of the networking code found in Comm.pl. I suspect this would be obsolete anyway given the advent of IO::Socket and external tools such as netcat.

Expect.pm is an attempt to have more of a switch() & case feeling to make decision processing more fluid. Three separate types of debugging have been implemented to make code production easier.

It is possible to interconnect multiple file handles (and processes) much like Tcl's Expect. An attempt was made to enable all the features of Tcl's Expect without forcing Tcl on the victim programmer :-) .

Please, before you consider using Expect, read the FAQs about "I want to automate password entry for su/ssh/scp/rsh/..." and "I want to use Expect to automate [anything with a buzzword]..."

USAGE¶

new

Creates a new Expect object, i.e. a pty. You can change parameters on it before actually spawning a command. This is important if you want to modify the terminal settings for the slave. See slave() below. The object returned is actually a reblessed IO::Pty filehandle, so see there for additional methods.

Expect->exp_init(\*FILEHANDLE) or

Expect->init(\*FILEHANDLE)

Initializes $new_handle_object for use with other Expect functions. It must be passed a _reference_ to FILEHANDLE if you want it to work properly. IO::File objects are preferable. Returns a reference to the newly created object.

You can use only real filehandles, certain tied filehandles (e.g. Net::SSH2) that lack a fileno() will not work. Net::Telnet objects can be used but have been reported to work only for certain hosts. YMMV.

Expect->spawn($command, @parameters) or

$object->spawn($command, @parameters) or

Expect->new($command, @parameters)

Forks and execs $command. Returns an Expect object upon success or "undef" if the fork was unsuccessful or the command could not be found. spawn() passes its parameters unchanged to Perls exec(), so look there for detailed semantics.

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...

$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..

$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.

$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 before spawning the program.

$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.

$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).

$object->print(@strings) or

$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.

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

$object->exp_before() or

$object->before()

before() returns the 'before' part of the last expect() call. If the last expect() call didn't match anything, exp_before() will return the entire output of the object accumulated before the expect() call finished.

Note that this is something different than Tcl Expects before()!!

$object->exp_after() or

$object->after()

returns the 'after' part of the last expect() call. If the last expect() call didn't match anything, exp_after() will return undef().

$object->exp_match() or

$object->match()

returns the string matched by the last expect() call, undef if no string was matched.

$object->exp_match_number() or

$object->match_number()

exp_match_number() returns the number of the pattern matched by the last expect() call. Keep in mind that the first pattern in a list of patterns is 1, not 0. Returns undef if no pattern was matched.

$object->exp_matchlist() or

$object->matchlist()

exp_matchlist() returns a list of matched substrings from the brackets () inside the regexp that last matched. ($object->matchlist)[0] thus corresponds to $1, ($object->matchlist)[1] to $2, etc.

$object->exp_error() or

$object->error()

exp_error() returns the error generated by the last expect() call if no pattern was matched. It is typically useful to examine the value returned by before() to find out what the output of the object was in determining why it didn't match any of the patterns.

$object->clear_accum()

Clear the contents of the accumulator for $object. This gets rid of any residual contents of a handle after expect() or send_slow() such that the next expect() call will only see new data from $object. The contents of the accumulator are returned.

$object->set_accum($value)

Sets the content of the accumulator for $object to $value. The previous content of the accumulator is returned.

$object->exp_command() or

$object->command()

exp_command() returns the string that was used to spawn the command. Helpful for debugging and for reused patternmatch subroutines.

$object->exp_exitstatus() or

$object->exitstatus()

Returns the exit status of $object (if it already exited).

$object->exp_pty_handle() or

$object->pty_handle()

Returns a string representation of the attached pty, for example: `spawn id(5)' (pty has fileno 5), `handle id(7)' (pty was initialized from fileno 7) or `STDIN'. Useful for debugging.

$object->restart_timeout_upon_receive(0 | 1)

If this is set to 1, the expect timeout is retriggered whenever something is received from the spawned command. This allows one to perform some aliveness testing and still expect for patterns.

    $exp->restart_timeout_upon_receive(1);
    $exp->expect($timeout,
                 [ timeout => \&report_timeout ],
                 [ qr/pattern/ => \&handle_pattern],
                );
    

Now the timeout isn't triggered if the command produces any kind of output, i.e. is still alive, but you can act upon patterns in the output.

$object->notransfer(1 | 0)

Do not truncate the content of the accumulator after a match. Normally, the accumulator is set to the remains that come after the matched string. Note that this setting is per object and not per pattern, so if you want to have normal acting patterns that truncate the accumulator, you have to add a

    $exp->set_accum($exp->after);
    

to their callback, e.g.

    $exp->notransfer(1);
    $exp->expect($timeout,
                 # accumulator not truncated, pattern1 will match again
                 [ "pattern1" => sub { my $self = shift;
                                       ...
                                     } ],
                 # accumulator truncated, pattern2 will not match again
                 [ "pattern2" => sub { my $self = shift;
                                       ...
                                       $self->set_accum($self->after());
                                     } ],
                );
    

This is only a temporary fix until I can rewrite the pattern matching part so it can take that additional -notransfer argument.

Expect::interconnect(@objects);

Read from @objects and print to their @listen_groups until an escape sequence is matched from one of @objects and the associated function returns 0 or undef. The special escape sequence 'EOF' is matched when an object's handle returns an end of file. Note that it is not necessary to include objects that only accept data in @objects since the escape sequence is _read_ from an object. Further note that the listen_group for a write-only object is always empty. Why would you want to have objects listening to STDOUT (for example)? By default every member of @objects _as well as every member of its listen group_ will be set to 'raw -echo' for the duration of interconnection. Setting $object->manual_stty() will stop this behavior per object. The original tty settings will be restored as interconnect exits.

For a generic way to interconnect processes, take a look at IPC::Run.

Expect::test_handles(@objects)

Given a set of objects determines which objects' handles have data ready to be read. Returns an array who's members are positions in @objects that have ready handles. Returns undef if there are no such handles ready.

Expect::version($version_requested or undef);

Returns current version of Expect. As of .99 earlier versions are not supported. Too many things were changed to make versioning possible.

$object->interact( "\*FILEHANDLE, $escape_sequence")

interact() is essentially a macro for calling interconnect() for connecting 2 processes together. \*FILEHANDLE defaults to \*STDIN and $escape_sequence defaults to undef. Interaction ceases when $escape_sequence is read from FILEHANDLE, not $object. $object's listen group will consist solely of \*FILEHANDLE for the duration of the interaction. \*FILEHANDLE will not be echoed on STDOUT.

$object->log_group(0 | 1 | undef)

Set/unset logging of $object to its 'listen group'. If set all objects in the listen group will have output from $object printed to them during $object->expect(), $object->send_slow(), and "Expect::interconnect($object , ...)". Default value is on. During creation of $object the setting will match the value of $Expect::Log_Group, normally 1.

$object->log_user(0 | 1 | undef) or

$object->log_stdout(0 | 1 | undef)

Set/unset logging of object's handle to STDOUT. This corresponds to Tcl's log_user variable. Returns current setting if called without parameters. Default setting is off for initialized handles. When a process object is created (not a filehandle initialized with exp_init) the log_stdout setting will match the value of $Expect::Log_Stdout variable, normally 1. If/when you initialize STDIN it is usually associated with a tty which will by default echo to STDOUT anyway, so be careful or you will have multiple echoes.

$object->log_file("filename" | $filehandle | \&coderef | undef)

Log session to a file. All characters send to or received from the spawned process are written to the file. Normally appends to the logfile, but you can pass an additional mode of "w" to truncate the file upon open():

  $object->log_file("filename", "w");
    

Returns the logfilehandle.

If called with an undef value, stops logging and closes logfile:

  $object->log_file(undef);
    

If called without argument, returns the logfilehandle:

  $fh = $object->log_file();
    

Can be set to a code ref, which will be called instead of printing to the logfile:

  $object->log_file(\&myloggerfunc);
    

$object->print_log_file(@strings)

Prints to logfile (if opened) or calls the logfile hook function. This allows the user to add arbitrary text to the logfile. Note that this could also be done as $object->log_file->print() but would only work for log files, not code hooks.

$object->set_seq($sequence, \&function, \@function_parameters)

During Expect->interconnect() if $sequence is read from $object &function will be executed with parameters @function_parameters. It is _highly recommended_ that the escape sequence be a single character since the likelihood is great that the sequence will be broken into to separate reads from the $object's handle, making it impossible to strip $sequence from getting printed to $object's listen group. \&function should be something like 'main::control_w_function' and @function_parameters should be an array defined by the caller, passed by reference to set_seq(). Your function should return a non-zero value if execution of interconnect() is to resume after the function returns, zero or undefined if interconnect() should return after your function returns. The special sequence 'EOF' matches the end of file being reached by $object. See interconnect() for details.

$object->set_group(@listener_objects)

@listener_objects is the list of objects that should have their handles printed to by $object when Expect::interconnect, $object->expect() or $object->send_slow() are called. Calling w/out parameters will return the current list of the listener objects.

$object->manual_stty(0 | 1 | undef)

Sets/unsets whether or not Expect should make reasonable guesses as to when and how to set tty parameters for $object. Will match $Expect::Manual_Stty value (normally 0) when $object is created. If called without parameters manual_stty() will return the current manual_stty setting.

$object->match_max($maximum_buffer_length | undef) or

$object->max_accum($maximum_buffer_length | undef)

Set the maximum accumulator size for object. This is useful if you think that the accumulator will grow out of hand during expect() calls. Since the buffer will be matched by every match_pattern it may get slow if the buffer gets too large. Returns current value if called without parameters. Not defined by default.

$object->notransfer(0 | 1)

If set, matched strings will not be deleted from the accumulator. Returns current value if called without parameters. False by default.

$object->exp_pid() or

$object->pid()

Return pid of $object, if one exists. Initialized filehandles will not have pids (of course).

$object->send_slow($delay, @strings);

print each character from each string of @strings one at a time with $delay seconds before each character. This is handy for devices such as modems that can be annoying if you send them data too fast. After each character $object will be checked to determine whether or not it has any new data ready and if so update the accumulator for future expect() calls and print the output to STDOUT and @listen_group if log_stdout and log_group are appropriately set.

CONTRIBUTIONS¶

Lee Eakin <leakin@japh.itg.ti.com> has ported the kibitz script from Tcl/Expect to Perl/Expect.

Jeff Carr <jcarr@linuxmachines.com> provided a simple example of how handle terminal window resize events (transmitted via the WINCH signal) in a ssh session.

You can find both scripts in the examples/ subdir. Thanks to both!

Historical notes:

There are still a few lines of code dating back to the inspirational Comm.pl and Chat.pl modules without which this would not have been possible. Kudos to Eric Arnold <Eric.Arnold@Sun.com> and Randal 'Nuke your NT box with one line of perl code' Schwartz<merlyn@stonehenge.com> for making these available to the perl public.

As of .98 I think all the old code is toast. No way could this have been done without it though. Special thanks to Graham Barr for helping make sense of the IO::Handle stuff as well as providing the highly recommended IO::Tty module.

REFERENCES¶

Mark Rogaski <rogaski@att.com> wrote:

"I figured that you'd like to know that Expect.pm has been very useful to AT&T Labs over the past couple of years (since I first talked to Austin about design decisions). We use Expect.pm for managing the switches in our network via the telnet interface, and such automation has significantly increased our reliability. So, you can honestly say that one of the largest digital networks in existence (AT&T Frame Relay) uses Expect.pm quite extensively."

FAQ - Frequently Asked Questions¶

This is a growing collection of things that might help. Please send you questions that are not answered here to RGiersig@cpan.org

  $Expect::Exp_Internal = 1;

  $exp->exp_internal(1);

  $Expect::Debug = 1;  # or 2, 3 for more verbose output

  $exp->debug(1);

  $Expect::Log_Stdout = 0;

   $exp->log_stdout(0);

  print $exp "\cC";

  $exp->send("\cC");

  "Thinking of mixing fork() and threads?  Please lie down and wait until the feeling passes."

  $exp->log_file("filename");

  $exp->log_file($filehandle);

  $exp->log_file(\&log_procedure);

  $exp->log_file("filename", "w");

  $exp->log_file(undef);

  $Expect::Multiline_Matching = 0;

  $process->expect(undef); # Forever until EOF
  $process->expect($timeout); # For a few seconds
  $process->expect(0); # Is there anything ready on the handle now?

  $read = $process->before();

  $process->soft_close();

  $process->expect(undef);

  $process->expect(undef);

  $process->expect(0);

  $exp = Expect->new;
  $exp->raw_pty(1);
  $exp->spawn(...);

  $exp->slave->stty(qw(-echo));

  my $exp = Expect->new;
  $exp->slave->clone_winsize_from(\*STDIN);
  $exp->spawn("telnet somehost);

  my $exp = Expect->new;
  $exp->slave->clone_winsize_from(\*STDIN);
  $exp->spawn("ssh somehost);
  $SIG{WINCH} = \&winch;
  sub winch {
    $exp->slave->clone_winsize_from(\*STDIN);
    kill WINCH => $exp->pid if $exp->pid;
    $SIG{WINCH} = \&winch;
  }
  $exp->interact();

  $process = Expect->spawn('telnet somehost; echo ____END____');

Source Examples¶

  my $telnet = Net::Telnet->new("remotehost") # see Net::Telnet
    or die "Cannot telnet to remotehost: $!\n";;
  my $exp = Expect->exp_init($telnet);
  # deprecated use of spawned telnet command
  # my $exp = Expect->spawn("telnet localhost")
  #   or die "Cannot spawn telnet: $!\n";;
  my $spawn_ok;
  $exp->expect($timeout,
           [
        qr'login: $',
        sub {
                  $spawn_ok = 1;
          my $fh = shift;
          $fh->send("$username\n");
                  exp_continue;
        }
           ],
           [
        'Password: $',
        sub {
          my $fh = shift;
          print $fh "$password\n";
                  exp_continue;
        }
           ],
           [
        eof =>
        sub {
                  if ($spawn_ok) {
            die "ERROR: premature EOF in login.\n";
                  } else {
            die "ERROR: could not spawn telnet.\n";
                  }
        }
           ],
           [
        timeout =>
        sub {
          die "No login.\n";
        }
           ],
           '-re', qr'[#>:] $', #' wait for shell prompt, then exit expect
          );

  foreach my $cmd (@list_of_commands) {
    push @commands, Expect->spawn($cmd);
  }
  expect($timeout,
     '-i', \@commands,
     [
      qr"pattern",        # find this pattern in output of all commands
      sub {
        my $obj = shift;    # object that matched
        print $obj "something\n";
        exp_continue;    # we don't want to terminate the expect call
      }
     ],
     '-i', $some_other_command,
     [
      "some other pattern",
      sub {
        my ($obj, $parmref) = @_;
        # ...
        # now we exit the expect command
      },
      \$parm
     ],
    );

  my $exp = Expect->new;
  $exp->slave->clone_winsize_from(\*STDIN);
  $exp->spawn("ssh somehost);
  $SIG{WINCH} = \&winch;
  sub winch {
    $exp->slave->clone_winsize_from(\*STDIN);
    kill WINCH => $exp->pid if $exp->pid;
    $SIG{WINCH} = \&winch;
  }
  $exp->interact();

HOMEPAGE¶

<http://sourceforge.net/projects/expectperl/> though the source code is now in GitHub: <https://github.com/jacoby/expect.pm>

MAILING LISTS¶

There are two mailing lists available, expectperl-announce and expectperl-discuss, at

  http://lists.sourceforge.net/lists/listinfo/expectperl-announce

and

  http://lists.sourceforge.net/lists/listinfo/expectperl-discuss

BUG TRACKING¶

You can use the CPAN Request Tracker http://rt.cpan.org/ and submit new bugs under

  http://rt.cpan.org/Ticket/Create.html?Queue=Expect

AUTHORS¶

(c) 1997 Austin Schutz <ASchutz@users.sourceforge.net> (retired)

expect() interface & functionality enhancements (c) 1999-2006 Roland Giersig.

This module is now maintained by Dave Jacoby <jacoby@cpan.org>

LICENSE¶

This module can be used under the same terms as Perl.

DISCLAIMER¶

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

In other words: Use at your own risk. Provided as is. Your mileage may vary. Read the source, Luke!

And finally, just to be sure:

Any Use of This Product, in Any Manner Whatsoever, Will Increase the Amount of Disorder in the Universe. Although No Liability Is Implied Herein, the Consumer Is Warned That This Process Will Ultimately Lead to the Heat Death of the Universe.