IO::Prompt(3) User Contributed Perl Documentation IO::Prompt(3)NAMEIO::Prompt - Interactively prompt for user input
VERSION
This document describes IO::Prompt version 0.997001
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.
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.
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.
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.
INTERFACE
Arguments to "prompt"
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 "-one_char" and
"-yes_no" are optional.
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.
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.
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))
"Too many -menu items"
"Too few -menu items"
A menu can't have fewer than 1 or more than 26 items.
CONFIGURATION AND ENVIRONMENTIO::Prompt requires no configuration files or environment variables.
DEPENDENCIESIO::Prompt requires the following modules:
· version
· IO::Handle
· Term::ReadKey
· POSIX
INCOMPATIBILITIES
The module requires a /dev/tty device be available. It is therefore
incompatible with any system that doesn't provide such a device.
BUGS AND LIMITATIONS
No bugs have been reported.
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.
perl v5.14.1 2011-11-05 IO::Prompt(3)
