IO::Prompt(3pm)

💖 IO::Prompt — interactively prompt for user input ✨

okay bestie, welcome to IO::Prompt(3pm) — the Perl module that literally asks the user for stuff and hands you back their answer. it's giving "conversational UI, but make it 2005". let's get into it 🫶

---

🌸 STATUS 🌸

This module is no longer being maintained. 😭

Use the IO::Prompter module instead. periodt. 💅

---

🎀 VERSION 🎀

This document describes IO::Prompt version 0.997004. ✨

---

🦋 SYNOPSIS 🦋

use IO::Prompt;
while( prompt "next: " ) {
    print "You said '$_'\n";
}

---

🌈 DESCRIPTION 🌈

By default, this module exports a single function prompt. It prompts the user to enter some input, and returns an object that represents the user input. it's literally that simple, no cap. ✨

You may specify various flags to the function to affect its behaviour; most notably, it defaults to automatically chomp the input, unless the -line flag is specified. (yes, the newline is getting got by default — you're welcome. 🍓)

Two other functions are exported at request: hand_print, which simulates hand-typing to the console; and get_input, which is the lower-level function that actually prompts the user for a suitable input. 👑

heads up: Note that this is an interim re-release. A full release with better documentation will follow in the near future. Meanwhile, please consult the examples directory from this module's CPAN distribution to better understand how to make use of this module. iykyk. 🙈

---

💅 INTERFACE 💅

✨ Arguments to prompt ✨

Any argument not of the following forms is treated as part of the text of the prompt itself. (so if it's not a flag or a special thing, congrats, it's just prompt text now. slay.)

• <str> — Use <str> as prompt
• <filehandle> — Prompt to specified filehandle
• <hashref> — Flatten hash entries into argument list (useful for aggregating the options below)

and now the actual flags, bestie, all of them, no skipping 👇

• -p, -prompt <str> — Specify prompt explicitly
• -s, -speed <num> — Simulated typing speed (seconds/char)
• -e, -echo <str> — What to echo for each char typed
• -nl, -newline <str> — When a newline is typed, echo <str> instead
• -d, -default <str> — What to return if only <return> pressed
• -r, -require <hashref> — Each value of each entry must 'smartmatch' the input else corresponding key is printed as error message:
  • Subs must return true when passed input
  • Regexes must pattern match input
  • Strings must eq match input
  • Arrays are flattened & recursively matched
  • Hashes must return true for input as key
• -u, -until, -fail_if <str|rgx> — Fail if input matches <str|regex>
• -w, -while, -okay_if <str|rgx> — Fail unless input matches <str|regex>
• -m, -menu <list|hash> — Show the data specified as a menu and allow one to be selected. Enter an <ESC> to back up one level.
• -1, -one_char — Return immediately after first char typed
• -x, -escape — Pressing <ESC> returns "\e" immediately
• -raw, -raw_input — Return only the string that was input (turns off context-sensitive features)
• -c, -clear — Clear screen before prompt
• -f, -clear_first — Clear screen before first prompt only
• -a, -argv — Load @ARGV from input if @ARGV empty
• -l, -line — Don't autochomp
• -t, -tty — Prompt to terminal no matter what
• -y, -yes — Return true if [yY] entered, false otherwise
• -yn, -yes_no — Return true if [yY], false if [nN]
• -Y, -Yes — Return true if 'Y' entered, false otherwise
• -YN, -Yes_No — Return true if 'Y', false if 'N'
• -num, -number — Accept only valid numbers as input
• -i, -integer — Accept only valid integers as input

Note that the underscores between words in flags like -one_char and -yes_no are optional. ✨ (so -onechar and -yesno are valid too, live your truth.)

Flags can be "cuddled". For example:

prompt("next: ", -tyn1s=>0.2)   # -tty, -yes, -no, -one_char, -speed=>0.2

🖊️ "Hand-written" printing via hand_print() 🖊️

The hand_print() subroutine takes a string and prints it out in the stop-and-start manner of hand-typed text. it's giving ✨dramatic reveal✨ energy.

🔍 Low-level input retrieval via get_input() 🔍

The get_input() subroutine is a low-level utility subroutine that takes an input filehandle, an output filehandle, a reference to a hash of options (as listed for prompt(), above) and a single prompt string. It prints the prompt and retreives the input. You almost certainly want to use prompt() instead. fr fr, just use prompt(). 🫶

---

💀 DIAGNOSTICS 💀

• "Can't write prompt to read-only $_" — You specified a filehandle to which the prompt should be written, but that filehandle was not writeable. Did you pass the wrong filehandle, or open it in the wrong mode? 🥲
• "Missing argument for %s option" — The flag you specified takes an argument, but you didn't provide that argument.
• "Unknown flag ($s) in prompt" — The flag you specified wasn't one of those that prompt() understands. Did you misspell it, perhaps? 🙈
• "Argument to -require must be hash reference" — The -require option takes a single argument that is a hash. You tried to pass it something else. Try a hash instead.
• "Cannot write to terminal: %s"
• "Cannot read from terminal: %s" — prompt() attempted to access the terminal but couldn't. This may mean your environment has no /dev/tty available, in which case there isn't much you can do with this module. Sorry. 😭
• "Can't open %s: %s" — prompt() tried to read input via *ARGV from a file specified on the command-line, but the file couldn't be opened for the reason shown. This is usually either a permission problem, a non-existent file, or a mistyped filepath.
• "Argument to -menu must be hash or array reference" — The -menu option requires an argument that is either an array:

prompt -menu=>['yes', 'no', 'maybe'];

or a hash:

prompt -menu=>{yes=>1, no=>0, maybe=>0.5};

or a hash of hashes (of hashes (of array)) — yes, it goes that deep, main character recursion energy 💅

• "Too many -menu items"
• "Too few -menu items" — A menu can't have fewer than 1 or more than 26 items. (26! one for every letter of the alphabet, iconic.) 👑

---

🧚 CONFIGURATION AND ENVIRONMENT 🧚

IO::Prompt requires no configuration files or environment variables. lowkey the easiest setup ever. ✨

---

🌸 DEPENDENCIES 🌸

IO::Prompt requires the following modules:

• version
• IO::Handle
• Term::ReadKey

---

💜 INCOMPATIBILITIES 💜

The module requires a /dev/tty device be available. It is therefore incompatible with any system that doesn't provide such a device. no tty, no vibes, sorry bestie. 😭

---

🔥 BUGS AND LIMITATIONS 🔥

No bugs have been reported. (iconic behaviour, honestly. 👑)

Please report any bugs or feature requests to bug-io-prompt@rt.cpan.org, or through the web interface at <http://rt.cpan.org>.

---

⭐ FAQ ⭐

This is a collection of things that might help. Please send your questions that are not answered here to Damian Conway <DCONWAY@cpan.org>

🦋 Can I use this module with ActivePerl on Windows? 🦋

Up to now, the answer was 'No', but this has changed. ✨

You still cannot use ActivePerl, but if you use the Cygwin environment (<http://sources.redhat.com>), which brings its own perl, and have the latest IO::Tty (v0.05 or later) installed, it should work (feedback appreciated). 🫶

---

🎀 THANKS 🎀

My deepest gratitude to Autrijus Tang and Brian Ingerson, who have taken care of this module for the past twelve months, while I was off trekking in the highlands of Perl 6. Now it's their turn for some mountain air, I'll be looking after this module again. 🏔️✨

---

👑 AUTHOR 👑

Damian Conway <DCONWAY@cpan.org>

---

💖 LICENCE AND COPYRIGHT 💖

Copyright (c) 2005, 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.

---

🌈 DISCLAIMER OF WARRANTY 🌈

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. 💀 (yes it's all caps, that's the legal drama of it all, no notes.)

---

and that's the whole page bestie!! 💅 this doc was brought to you by perl v5.34.0, dated 2022-06-14, and filed under IO::Prompt(3pm). go forth and prompt. 🫶✨🎀