Provided by: libio-prompt-perl_0.997004-2_all bug

NAME

       IO::Prompt - Interactively prompt for user input

STATUS

       This module is no longer being maintained.

       Use the IO::Prompter module instead.

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.

       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 ENVIRONMENT

       IO::Prompt requires no configuration files or environment variables.

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.

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.