NAME

IO::Prompt - Interactively prompt for user input

VERSION

This document describes version 0.01 of IO::Prompt, released September 28, 2004.

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.

Please consult the examples directory from this module's CPAN distribution to better understand how to make use of this module.

Arguments to prompt

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>
-w     -while         <str|rgx>    Fail unless input matches <str|regex>

-1     -onechar                    Return immediately after first char typed

-w     -wipe                       Clear screen before prompt
-f     -wipefirst                  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    -yesno                      Return true if [yY], false if [nN]
-Y     -Yes                        Return true if 'Y' entered, false otherwise
-YN    -YesNo                      Return true if 'Y', false if 'N'

-num   -number                     Accept only valid numbers as input
-i     -integer                    Accept only valid integers as input

Flags can be "cuddled". For example:

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

CAVEATS

Currently, there are no meaningful tests and documentation for this module. Contributions will be very much appreciated.

AUTHOR

Damian Conway (damian@conway.org)

MAINTAINERS

Autrijus Tang <autrijus@autrijus.org>, Brian Ingerson <INGY@cpan.org>.

COPYRIGHT

  Copyright (c) 2004, Damian Conway. All Rights Reserved.
This module is free software. It may be used, redistributed
    and/or modified under the same terms as Perl itself.