.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "IO::Pty::Easy 3pm" .TH IO::Pty::Easy 3pm "2022-06-14" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" IO::Pty::Easy \- Easy interface to IO::Pty .SH "VERSION" .IX Header "VERSION" version 0.10 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use IO::Pty::Easy; \& \& my $pty = IO::Pty::Easy\->new; \& $pty\->spawn("nethack"); \& \& while ($pty\->is_active) { \& my $input = # read a key here... \& $input = \*(AqElbereth\*(Aq if $input eq "\ece"; \& my $chars = $pty\->write($input, 0); \& last if defined($chars) && $chars == 0; \& my $output = $pty\->read(0); \& last if defined($output) && $output eq \*(Aq\*(Aq; \& $output =~ s/Elbereth/\ee[35mElbereth\ee[m/; \& print $output; \& } \& \& $pty\->close; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`IO::Pty::Easy\*(C'\fR 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. .PP \&\f(CW\*(C`IO::Pty::Easy\*(C'\fR uses IO::Pty internally, so it inherits all of the portability restrictions from that module. .SH "METHODS" .IX Header "METHODS" .SS "new(%params)" .IX Subsection "new(%params)" The \f(CW\*(C`new\*(C'\fR constructor initializes the pty and returns a new \f(CW\*(C`IO::Pty::Easy\*(C'\fR object. The constructor recognizes these parameters: .IP "handle_pty_size" 4 .IX Item "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. .IP "def_max_read_chars" 4 .IX Item "def_max_read_chars" The maximum number of characters returned by a \f(CW\*(C`read()\*(C'\fR call. This can be overridden in the \f(CW\*(C`read()\*(C'\fR argument list. Defaults to 8192. .IP "raw" 4 .IX Item "raw" A boolean option which determines whether or not to call \*(L"\fBset_raw()\fR\*(R" in IO::Pty after \f(CW\*(C`spawn()\*(C'\fR. Defaults to true. .SS "spawn(@argv)" .IX Subsection "spawn(@argv)" Fork a new subprocess, with stdin/stdout/stderr tied to the pty. .PP The argument list is passed directly to \f(CW\*(C`system()\*(C'\fR. .PP Dies on failure. .ie n .SS "read($timeout, $length)" .el .SS "read($timeout, \f(CW$length\fP)" .IX Subsection "read($timeout, $length)" Read data from the process running on the pty. .PP \&\f(CW\*(C`read()\*(C'\fR 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 \f(CW\*(C`def_max_read_chars\*(C'\fR, usually 8192). The requirement for a maximum returned string length is a limitation imposed by the use of \&\f(CW\*(C`sysread()\*(C'\fR, which we use internally. .PP Returns \f(CW\*(C`undef\*(C'\fR on timeout, the empty string on \s-1EOF,\s0 or a string of at least one character on success (this is consistent with \f(CW\*(C`sysread()\*(C'\fR and Term::ReadKey). .ie n .SS "write($buf, $timeout)" .el .SS "write($buf, \f(CW$timeout\fP)" .IX Subsection "write($buf, $timeout)" Writes a string to the pty. .PP 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 \f(CW\*(C`read()\*(C'\fR. .PP 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). .SS "is_active" .IX Subsection "is_active" Returns whether or not a subprocess is currently running on the pty. .ie n .SS "kill($sig, $non_blocking)" .el .SS "kill($sig, \f(CW$non_blocking\fP)" .IX Subsection "kill($sig, $non_blocking)" Sends a signal to the process currently running on the pty (if any). Optionally blocks until the process dies. .PP \&\f(CW\*(C`kill()\*(C'\fR takes two optional arguments. The first is the signal to send, in any format that the perl \f(CW\*(C`kill()\*(C'\fR command recognizes (defaulting to \*(L"\s-1TERM\*(R"\s0). 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. .PP Returns 1 if a process was actually signaled, and 0 otherwise. .SS "close" .IX Subsection "close" Kills any subprocesses and closes the pty. No other operations are valid after this call. .SS "handle_pty_size" .IX Subsection "handle_pty_size" Read/write accessor for the \f(CW\*(C`handle_pty_size\*(C'\fR option documented in the constructor options. .SS "def_max_read_chars" .IX Subsection "def_max_read_chars" Read/write accessor for the \f(CW\*(C`def_max_read_chars\*(C'\fR option documented in the constructor options. .SS "pid" .IX Subsection "pid" Returns the pid of the process currently running in the pty, or undef if no process is running. .SH "BUGS" .IX Header "BUGS" No known bugs. .PP Please report any bugs through \s-1RT:\s0 email \&\f(CW\*(C`bug\-io\-pty\-easy at rt.cpan.org\*(C'\fR, or browse to . .SH "SEE ALSO" .IX Header "SEE ALSO" IO::Pty .PP (This module is based heavily on the \fItry\fR script bundled with IO::Pty.) .PP Expect .PP IO::Pty::HalfDuplex .SH "SUPPORT" .IX Header "SUPPORT" You can find this documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc IO::Pty::Easy .Ve .PP You can also look for information at: .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "AUTHOR" .IX Header "AUTHOR" Jesse Luehrs .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2016 by Jesse Luehrs. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.