/ 
IO-Pty-Easy-0.05
River stage two • 4 direct dependents • 15 total dependents
/ IO::Pty::Easy

NAME

IO::Pty::Easy - Easy interface to IO::Pty

VERSION

Version 0.05 released 2/5/2009

SYNOPSIS

use IO::Pty::Easy;

my $pty = IO::Pty::Easy->new;
$pty->spawn("nethack");

while ($pty->is_active) {
    my $input = # read a key here...
    $input = 'Elbereth' if $input eq "\ce";
    my $chars = $pty->write($input, 0);
    last if defined($chars) && $chars == 0;
    my $output = $pty->read(0);
    last if defined($output) && $output eq '';
    $output =~ s/Elbereth/\e[35mElbereth\e[m/;
    print $output;
}

$pty->close;

DESCRIPTION

IO::Pty::Easy provides an interface to IO::Pty which hides most of the ugly details of handling ptys, wrapping them instead in simple spawn/read/write commands.

IO::Pty::Easy uses IO::Pty internally, so it inherits all of the portability restrictions from that module.

CONSTRUCTOR

new()

The new constructor initializes the pty and returns a new IO::Pty::Easy object. The constructor recognizes these parameters:

handle_pty_size

A boolean option which determines whether or not changes in the size of the user's terminal should be propageted to the pty object. Defaults to true.

def_max_read_chars

The maximum number of characters returned by a read() call. This can be overridden in the read() argument list. Defaults to 8192.

METHODS

spawn()

Fork a new subprocess, with stdin/stdout/stderr tied to the pty.

The argument list is passed directly to exec().

Returns true on success, false on failure.

read()

Read data from the process running on the pty.

read() takes two optional arguments: the first is the number of seconds (possibly fractional) to block for data (defaults to blocking forever, 0 means completely non-blocking), and the second is the maximum number of bytes to read (defaults to the value of def_max_read_chars, usually 8192). The requirement for a maximum returned string length is a limitation imposed by the use of sysread(), which we use internally.

Returns undef on timeout, the empty string on EOF, or a string of at least one character on success (this is consistent with sysread() and Term::ReadKey).

write()

Writes a string to the pty.

The first argument is the string to write, which is followed by one optional argument, the number of seconds (possibly fractional) to block for, taking the same values as read().

Returns undef on timeout, 0 on failure to write, or the number of bytes actually written on success (this may be less than the number of bytes requested; this should be checked for).

is_active()

Returns whether or not a subprocess is currently running on the pty.

kill()

Sends a signal to the process currently running on the pty (if any). Optionally blocks until the process dies.

kill() takes two optional arguments. The first is the signal to send, in any format that the perl kill() command recognizes (defaulting to "TERM"). The second is a boolean argument, where false means to block until the process dies, and true means to just send the signal and return.

Returns 1 if a process was actually signaled, and 0 otherwise.

close()

Kills any subprocesses and closes the pty. No other operations are valid after this call.

SEE ALSO

IO::Pty

Expect

AUTHOR

Jesse Luehrs, <doy at tozt dot net>

This module is based heavily on the try script bundled with IO::Pty.

BUGS

If the pty is capable of reading some, but not all data given in a write() call, the call to write() will write what it can, and then block indefinitely, regardless of the given timeout parameter (the timeout parameter is only passed to the select() call used internally, syswrite() has no timeout mechanism).

Please report any bugs through RT: email bug-io-pty-easy at rt.cpan.org, or browse to http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IO-Pty-Easy.

SUPPORT

You can find this documentation for this module with the perldoc command.

perldoc IO::Pty::Easy

You can also look for information at:

COPYRIGHT AND LICENSE

Copyright 2007-2009 Jesse Luehrs.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.