Expect::Simple(3pm)

💖 Expect::Simple 💖

okay bestie, so this is Expect::Simple — the manual page, aka the little doc that comes with the Perl module Expect::Simple, which is a wrapper around the Expect module. yes the header up top said Expect::Simple(3pm) and yes that's just us saying hi in manpage-speak 🫶

---

✨ SYNOPSIS ✨

no cap, here's the whole vibe in code:

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;

like, that's it. that's the whole group chat 🎀

---

🌸 DESCRIPTION 🌸

so "Expect::Simple" is literally a wrapper around the "Expect" module, and it's designed to be enough for simple applications. it hides most of the "Expect" machinery away — but the "Expect" object is still right there for tweaking if you need it. main character energy but make it modular 💅

generally you start by making an Expect::Simple object with new. that starts up the target program, and then it just waits — patiently, like a bestie holding your iced coffee — until one of the specified prompts gets output by the target. once that happens, the caller should send() commands to the program, and the results show up via the before, after, match_str, and match_idx methods.

now listen: since Expect simulates a terminal, there will be extra "\r" characters at the end of each line in the result (on UNIX at least). it's giving ✨legacy terminal✨. this is easily fixed:

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

⚠️ heads up: this is not done automatically. you gotta do it yourself, bestie.

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. so like, it cleans up after itself. we love a self-aware queen 💖

---

🦋 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. (yes, a thousand. it's got the patience of a saint 🙈)
• 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. so like, don't expect to hoard all the outputs, bestie — only the last one stays 💀

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. literally just vibes and trust, bestie 😭

---

📜 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)

---

and that's the whole page, bestie!! 🎀✨ this lil manpage was brought to you by perl v5.32.0 and it's dated 2021-01-05 — yeah it's a lil vintage but it still slays 💅🫶 k bye!!