IO::Pty::Easy(3pm)

📦
version 0.10 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 IO::Pty::Easy — bestie's guide to ptys that don't make you cry 💖

okay so you found the IO::Pty::Easy page, and honestly? iconic of you. this is the perl module that makes ptys not a whole entire nightmare. welcome 🫶

Version: 0.10 ✨

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste energy, no notes:

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;

yes it's a nethack bot. yes the Elbereth thing is real. moving on 💅

🦋 DESCRIPTION 🦋

so "IO::Pty::Easy" is basically a glow-up wrapper around IO::Pty. it hides all the ugly little details of handling ptys and instead gives you these cute simple spawn/read/write commands. it's giving "I don't want to think about this" and honestly same.

the one thing to know: "IO::Pty::Easy" uses IO::Pty internally, so it inherits all of the portability restrictions from that module. no cap, all of them. 🌈

👑 METHODS 👑

✨ new(%params) ✨

the "new" constructor initializes the pty and hands you back a fresh new "IO::Pty::Easy" object. main character energy. it recognizes these parameters:

  • handle_pty_size — a boolean option that decides whether or not changes in the size of the user's terminal should get propageted (yes, that's the spelling in the original, we keep it) to the pty object. defaults to true. 💖
  • def_max_read_chars — the max number of characters that a "read()" call will hand back. you can override this in the "read()" argument list. defaults to 8192.
  • raw — a boolean option deciding whether or not to call "set_raw()" in IO::Pty after "spawn()". defaults to true.

🌟 spawn(@argv) 🌟

forks a new subprocess, with stdin/stdout/stderr all tied to the pty. she's got three streams and they all know each other 🫶

the argument list gets passed directly to "system()".

dies on failure. like, actually dies. 😭

⭐ read($timeout, $length) ⭐

reads data from the process running on the pty.

"read()" takes two optional arguments:

  1. the number of seconds (possibly fractional, we love a fraction) to block for data. defaults to blocking forever, and 0 means completely non-blocking.
  2. 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. that's just how it is bestie.

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. consistency slay 💅

🎀 write($buf, $timeout) 🎀

writes a string to the pty.

first argument is the string to write, 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. and heads up — that number may be less than the number of bytes requested, and this should be checked for. don't skip the vibe check on that return value 🙈

💜 is_active 💜

returns whether or not a subprocess is currently running on the pty. yes or no, alive or not, simple as.

🔥 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:

  1. the signal to send, in any format that the perl "kill()" command recognizes. defaults to "TERM".
  2. a boolean. false means block until the process dies; true means just send the signal and return, we're not waiting around.

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. it's over, it's done, the pty has left the chat 💀

🌈 handle_pty_size 🌈

read/write accessor for the "handle_pty_size" option documented up in the constructor options. iykyk.

🌸 def_max_read_chars 🌸

read/write accessor for the "def_max_read_chars" option documented up in the constructor options. same deal bestie.

🍓 pid 🍓

returns the pid of the process currently running in the pty, or undef if no process is running. identity check, but for processes.

💀 BUGS 💀

no known bugs. we're clean, we're thriving, we're unbothered. ✨

but if you do find one, 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>. the RT queue is like the group chat you send bug reports to, lowkey.

🌟 SEE ALSO 🌟

  • IO::Pty — (this module is based heavily on the try script bundled with IO::Pty.) shoutout to the originator, fr fr 🫶
  • Expect
  • IO::Pty::HalfDuplex

💖 SUPPORT 💖

you can find this documentation for this module with the perldoc command:

perldoc IO::Pty::Easy

you can also look for information at:

✨ AUTHOR ✨

Jesse Luehrs <doy at tozt dot net> — thank you for your service 🫡👑

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. so generous, so legal, so iconic 💅

and that's the whole page bestie!! this was perl v5.34.0, dated 2022-06-14, and it was a genuine pleasure. go spawn something weird. bye!! 💖✨🎀🦋🌸

📦 where this page comes from