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

       Jesse Luehrs <doy at tozt dot net>

       No known bugs.

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

       This software is copyright (c) 2016 by Jesse Luehrs.

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

perl v5.34.0                                       2022-06-14                                 IO::Pty::Easy(3pm)

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

new(%params)
       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.

       raw A boolean option which determines whether or not to call  "set_raw()"  in  IO::Pty  after  "spawn()".
           Defaults to true.

   spawn(@argv)
       Fork a new subprocess, with stdin/stdout/stderr tied to the pty.

       The argument list is passed directly to "system()".

       Dies on failure.

   read($timeout,$length)
       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($buf,$timeout)
       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($sig,$non_blocking)
       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.

   handle_pty_size
       Read/write accessor for the "handle_pty_size" option documented in the constructor options.

   def_max_read_chars
       Read/write accessor for the "def_max_read_chars" option documented in the constructor options.

   pid
       Returns the pid of the process currently running in the pty, or undef if no process is running.

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

       IO::Pty

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

       Expect

       IO::Pty::HalfDuplex

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

           perldoc IO::Pty::Easy

       You can also look for information at:

       •   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/IO-Pty-Easy>

       •   CPAN Ratings

           <http://cpanratings.perl.org/d/IO-Pty-Easy>

       •   RT: CPAN's request tracker

           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=IO-Pty-Easy>

       •   Search CPAN

           <http://search.cpan.org/dist/IO-Pty-Easy>

           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;

       version 0.10