IO::Pty::Easy(3pm)

1IO::Pty::Easy(3)      User Contributed Perl Documentation     IO::Pty::Easy(3)
2
3
4

NAME

6       IO::Pty::Easy - Easy interface to IO::Pty
7

VERSION

9       version 0.10
10

SYNOPSIS

12           use IO::Pty::Easy;
13
14           my $pty = IO::Pty::Easy->new;
15           $pty->spawn("nethack");
16
17           while ($pty->is_active) {
18               my $input = # read a key here...
19               $input = 'Elbereth' if $input eq "\ce";
20               my $chars = $pty->write($input, 0);
21               last if defined($chars) && $chars == 0;
22               my $output = $pty->read(0);
23               last if defined($output) && $output eq '';
24               $output =~ s/Elbereth/\e[35mElbereth\e[m/;
25               print $output;
26           }
27
28           $pty->close;
29

DESCRIPTION

31       "IO::Pty::Easy" provides an interface to IO::Pty which hides most of
32       the ugly details of handling ptys, wrapping them instead in simple
33       spawn/read/write commands.
34
35       "IO::Pty::Easy" uses IO::Pty internally, so it inherits all of the
36       portability restrictions from that module.
37

METHODS

39   new(%params)
40       The "new" constructor initializes the pty and returns a new
41       "IO::Pty::Easy" object. The constructor recognizes these parameters:
42
43       handle_pty_size
44           A boolean option which determines whether or not changes in the
45           size of the user's terminal should be propageted to the pty object.
46           Defaults to true.
47
48       def_max_read_chars
49           The maximum number of characters returned by a read() call. This
50           can be overridden in the read() argument list. Defaults to 8192.
51
52       raw A boolean option which determines whether or not to call
53           "set_raw()" in IO::Pty after spawn(). Defaults to true.
54
55   spawn(@argv)
56       Fork a new subprocess, with stdin/stdout/stderr tied to the pty.
57
58       The argument list is passed directly to system().
59
60       Dies on failure.
61
62   read($timeout, $length)
63       Read data from the process running on the pty.
64
65       read() takes two optional arguments: the first is the number of seconds
66       (possibly fractional) to block for data (defaults to blocking forever,
67       0 means completely non-blocking), and the second is the maximum number
68       of bytes to read (defaults to the value of "def_max_read_chars",
69       usually 8192). The requirement for a maximum returned string length is
70       a limitation imposed by the use of sysread(), which we use internally.
71
72       Returns "undef" on timeout, the empty string on EOF, or a string of at
73       least one character on success (this is consistent with sysread() and
74       Term::ReadKey).
75
76   write($buf, $timeout)
77       Writes a string to the pty.
78
79       The first argument is the string to write, which is followed by one
80       optional argument, the number of seconds (possibly fractional) to block
81       for, taking the same values as read().
82
83       Returns undef on timeout, 0 on failure to write, or the number of bytes
84       actually written on success (this may be less than the number of bytes
85       requested; this should be checked for).
86
87   is_active
88       Returns whether or not a subprocess is currently running on the pty.
89
90   kill($sig, $non_blocking)
91       Sends a signal to the process currently running on the pty (if any).
92       Optionally blocks until the process dies.
93
94       kill() takes two optional arguments. The first is the signal to send,
95       in any format that the perl kill() command recognizes (defaulting to
96       "TERM"). The second is a boolean argument, where false means to block
97       until the process dies, and true means to just send the signal and
98       return.
99
100       Returns 1 if a process was actually signaled, and 0 otherwise.
101
102   close
103       Kills any subprocesses and closes the pty. No other operations are
104       valid after this call.
105
106   handle_pty_size
107       Read/write accessor for the "handle_pty_size" option documented in the
108       constructor options.
109
110   def_max_read_chars
111       Read/write accessor for the "def_max_read_chars" option documented in
112       the constructor options.
113
114   pid
115       Returns the pid of the process currently running in the pty, or undef
116       if no process is running.
117

BUGS

119       No known bugs.
120
121       Please report any bugs through RT: email "bug-io-pty-easy at
122       rt.cpan.org", or browse to
123       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IO-Pty-Easy>.
124

SUPPORT

135       You can find this documentation for this module with the perldoc
136       command.
137
138           perldoc IO::Pty::Easy
139
140       You can also look for information at:
141
142       •   AnnoCPAN: Annotated CPAN documentation
143
144           <http://annocpan.org/dist/IO-Pty-Easy>
145
146       •   CPAN Ratings
147
148           <http://cpanratings.perl.org/d/IO-Pty-Easy>
149
150       •   RT: CPAN's request tracker
151
152           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=IO-Pty-Easy>
153
154       •   Search CPAN
155
156           <http://search.cpan.org/dist/IO-Pty-Easy>
157

AUTHOR

159       Jesse Luehrs <doy at tozt dot net>
160

COPYRIGHT AND LICENSE

162       This software is copyright (c) 2016 by Jesse Luehrs.
163
164       This is free software; you can redistribute it and/or modify it under
165       the same terms as the Perl 5 programming language system itself.
166
167
168
169perl v5.36.0                      2023-01-20                  IO::Pty::Easy(3)