Interactively prompt for user input
This module is no longer being maintained.
Use the IO::Prompter module instead.
This document describes IO::Prompt version 0.997002
use IO::Prompt;
while( prompt "next: " ) {
print "You said '$_'\n";
}
By default, this module exports a single function \*(C`prompt\*(C'. It prompts the user to enter some input, and returns an object that represents the user input.
You may specify various flags to the function to affect its behaviour; most notably, it defaults to automatically \*(C`chomp\*(C' the input, unless the \*(C`-line\*(C' flag is specified.
Two other functions are exported at request: \*(C`hand_print\*(C', which simulates hand-typing to the console; and \*(C`get_input\*(C', which is the lower-level function that actually prompts the user for a suitable input.
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 \s-1CPAN\s0 distribution to better understand how to make use of this module.
Any argument not of the following forms is treated as part of the text of the prompt itself.
Flag Long form Arg Effect ---- --------- --- ------ <str> Use <str> as prompt
<filehandle> Prompt to specified filehandle
<hashref> Flatten hash entries into argument list (useful for aggregating the options below)
-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 <str|rgx> Fail if input matches <str|regex> -fail_if
-w -while <str|rgx> Fail unless input matches <str|regex> -okay_if
-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 \*(C`-one_char\*(C' and \*(C`-yes_no\*(C' are optional.
Flags can be \*(L"cuddled\*(R". For example:
prompt("next: ", -tyn1s=>0.2) # -tty, -yes, -no, -one_char, -speed=>0.2 The \*(C`hand_print()\*(C' subroutine takes a string and prints it out in the stop-and-start manner of hand-typed text. The \*(C`get_input()\*(C' 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 \*(C`prompt()\*(C', above) and a single prompt string. It prints the prompt and retreives the input. You almost certainly want to use \*(C`prompt()\*(C' instead.
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? The flag you specified takes an argument, but you didn't provide that argument. The flag you specified wasn't one of those that \*(C`prompt()\*(C' understands. Did you misspell it, perhaps? The \*(C`-require\*(C' option takes a single argument that is a hash. You tried to pass it something else. Try a hash instead. \*(C`prompt()\*(C' attempted to access the terminal but couldn't. This may mean your environment has no \*(C`/dev/tty\*(C' available, in which case there isn't much you can do with this module. Sorry. \*(C`prompt()\*(C' 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. The \*(C`-menu\*(C' 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)) A menu can't have fewer than 1 or more than 26 items.
IO::Prompt requires no configuration files or environment variables.
IO::Prompt requires the following modules:
version
IO::Handle
Term::ReadKey
\s-1POSIX\s0
The module requires a /dev/tty device be available. It is therefore incompatible with any system that doesn't provide such a device.
No bugs have been reported.
Please report any bugs or feature requests to \*(C`[email protected]\*(C', or through the web interface at <http://rt.cpan.org>.
This is a collection of things that might help. Please send your questions that are not answered here to Damian Conway \*(C`<[email protected]>\*(C'
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).
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.
Damian Conway \*(C`<[email protected]>\*(C'
Copyright (c) 2005, Damian Conway \*(C`<[email protected]>\*(C'. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0 \s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0 \s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0 \s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0 \s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0 \s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0 \s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0 \s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0 \s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENCE\s0, \s-1BE\s0 \s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0, \s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0 \s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A \s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0 \s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0 \s-1SUCH\s0 \s-1DAMAGES\s0.