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
66       seconds (possibly fractional) to block for data (defaults to blocking
67       forever, 0 means completely non-blocking), and the second is the
68       maximum number of bytes to read (defaults to the value of
69       "def_max_read_chars", usually 8192). The requirement for a maximum
70       returned string length is a limitation imposed by the use of
71       "sysread()", which we use internally.
72
73       Returns "undef" on timeout, the empty string on EOF, or a string of at
74       least one character on success (this is consistent with "sysread()" and
75       Term::ReadKey).
76
77   write($buf, $timeout)
78       Writes a string to the pty.
79
80       The first argument is the string to write, which is followed by one
81       optional argument, the number of seconds (possibly fractional) to block
82       for, taking the same values as "read()".
83
84       Returns undef on timeout, 0 on failure to write, or the number of bytes
85       actually written on success (this may be less than the number of bytes
86       requested; this should be checked for).
87
88   is_active
89       Returns whether or not a subprocess is currently running on the pty.
90
91   kill($sig, $non_blocking)
92       Sends a signal to the process currently running on the pty (if any).
93       Optionally blocks until the process dies.
94
95       "kill()" takes two optional arguments. The first is the signal to send,
96       in any format that the perl "kill()" command recognizes (defaulting to
97       "TERM"). The second is a boolean argument, where false means to block
98       until the process dies, and true means to just send the signal and
99       return.
100
101       Returns 1 if a process was actually signaled, and 0 otherwise.
102
103   close
104       Kills any subprocesses and closes the pty. No other operations are
105       valid after this call.
106
107   handle_pty_size
108       Read/write accessor for the "handle_pty_size" option documented in the
109       constructor options.
110
111   def_max_read_chars
112       Read/write accessor for the "def_max_read_chars" option documented in
113       the constructor options.
114
115   pid
116       Returns the pid of the process currently running in the pty, or undef
117       if no process is running.
118

BUGS

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

SUPPORT

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

AUTHOR

160       Jesse Luehrs <doy at tozt dot net>
161

COPYRIGHT AND LICENSE

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