IO::Interactive(3)

📦
version 1.027 · 8 versions
, in epel 9

💅 IO::Interactive — wait bestie, is this even a terminal?? 🖥️✨

Okay so this is the manual page for IO::Interactive, living in the User Contributed Perl Documentation corner of the world. Grab a strawberry drink 🍓 and let's get into it.

✨ NAME ✨

IO::Interactive — literally just utilities for interactive I/O. That's it, that's the whole vibe. 🎀

🌸 VERSION 🌸

This doc right here describes IO::Interactive version 1.02. Slay. 💅

🦋 SYNOPSIS 🦋

use IO::Interactive qw(is_interactive interactive busy);

if ( is_interactive() ) {
    print "Running interactively\n";
}

# or...

print {interactive} "Running interactively\n";

$fh = busy {
    do_noninteractive_stuff();
};

Three subs, three moods, all iconic. 👑

💖 DESCRIPTION 💖

This module hands you three utility subroutines so building interactive apps stops being a whole thing. Honestly, obsessed. 🫶

So here's the tea about the ARGV filehandle — you know, the one that <> or an empty readline() uses. It has so much magic attached to it, it's giving main character energy. It's not actually opened until you try to read from it. Which means if you check -t ARGV before you've tried reading from it, you might get the wrong answer. 😭 Not only that — you might not even read from ARGV at all! If the value in @ARGV is the magic filename - (which is the convention meaning "yo, use the standard filehandle for input or output"), then ARGV might actually be STDIN. And you do not want to think about all of that. Bestie, don't do that to yourself.

This module gets discussed in Perl Best Practices on page 218. Also go peek at the "ARGV" entry in perlvar and the "readline" entry in perlfunc. iykyk 📚

⭐ "is_interactive()"

This subroutine returns true if *ARGV and the currently selected filehandle (usually *STDOUT) are connected to the terminal. And the test it runs is considerably more sophisticated than this tired little line:

-t *ARGV && -t *STDOUT

…because it actually takes into account the whole magic behaviour of *ARGV. No cap. ✨

You can also pass "is_interactive" a writable filehandle, and in that case it requires that filehandle to be connected to a terminal (instead of the currently selected one). The usual suspect here, obviously, is *STDERR:

if ( is_interactive(*STDERR) ) {
    carp $warning;
}
Heads up bestie 🚨 — "is_interactive" may return true in a Windows Scheduled Task. That's a real thing. See Github #6 at https://github.com/briandfoy/io-interactive/issues/6.

🌈 "interactive()"

This one returns *STDOUT if "is_interactive" is true. But if "is_interactive()" is false, "interactive" returns a filehandle that does not print. Nothing. Silence. A void. 💀

Which is honestly so convenient, because now making apps that only print when they're actually interactive is a one-liner:

print {interactive} "Please enter a value: ";
my $value = <>;

You can also pass "interactive" a writable filehandle, and then it writes to that filehandle if it's connected to a terminal (instead of writing to *STDOUT). And once again — you guessed it — the usual suspect is *STDERR:

print {interactive(*STDERR)} $warning;

🧚 "busy {...}"

This subroutine takes a block as its single argument and just… executes it. Simple. But while the block is executing, *ARGV is temporarily replaced by a closed filehandle. So like — no input from *ARGV is possible inside a "busy" block, periodt. 🚫

Furthermore, any attempts to send input into the "busy" block through *ARGV get intercepted, and a warning message gets printed to *STDERR. And the "busy" call returns a filehandle containing all that intercepted input. Like a little swear jar for stdin. 🫙

So a "busy" block is genuinely useful for preventing attempts at input while the program is busy grinding on some non-interactive task. Protect your program's focus. Main character energy only. 👑

🔥 DIAGNOSTICS 🔥

  • Unknown subroutine (%s) requested — bestie, this module only exports the three subroutines described above. You asked for something else. Maybe you misspelled the subroutine you wanted? 🙈

🎀 CONFIGURATION AND ENVIRONMENT 🎀

IO::Interactive requires no configuration files and no environment variables. Zero setup, we love a low-maintenance icon. ✨

⭐ DEPENDENCIES ⭐

This module requires the "openhandle()" subroutine from the Scalar::Util module. That's the one. 💜

💀 INCOMPATIBILITIES 💀

None reported. 🦋

😭 BUGS AND LIMITATIONS 😭

No bugs have been reported. (Iconic behaviour, honestly.)

Please report any bugs or feature requests to Github at https://github.com/briandfoy/io-interactive/issues. 🐛

🌟 SOURCE AVAILABILITY 🌟

This code is in GitHub:

https://github.com/briandfoy/io-interactive

Go star it, bestie. ⭐

👑 AUTHOR 👑

Damian Conway "<DCONWAY@cpan.org>" 🧚

Currently maintained by brian d foy "<briandfoy@pobox.com>". 🫶

1.01 patch by DMUEY "dmuey@cpan.org" 💅

Copyright © 2005-2021, Damian Conway "<DCONWAY@cpan.org>". All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Slay. 🌸

🚨 DISCLAIMER OF WARRANTY 🚨

Okay bestie, this part is in ALL CAPS for a reason, so read it carefully — it's the legal bit, keep every word 💀:

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

💅 and that's the whole page, bestie — this was perl v5.32.1, dated 2025-04-17, and you just read IO::Interactive(3). go be interactive. 🦋✨

📦 where this page comes from