1IO::Prompt(3) User Contributed Perl Documentation IO::Prompt(3)
2
6 IO::Prompt - Interactively prompt for user input
7
9 This document describes IO::Prompt version 0.99.4
10
12 use IO::Prompt;
13 while( prompt "next: " ) {
14 print "You said '$_'\n";
15 }
16
18 By default, this module exports a single function "prompt". It prompts
19 the user to enter some input, and returns an object that represents the
20 user input.
21 You may specify various flags to the function to affect its behaviour;
23 most notably, it defaults to automatically "chomp" the input, unless
24 the "-line" flag is specified.
25 Two other functions are exported at request: "hand_print", which simu‐
27 lates hand-typing to the console; and "get_input", which is the lower-
28 level function that actually prompts the user for a suitable input.
29 Note that this is an interim re-release. A full release with better
31 documentation will follow in the near future. Meanwhile, please consult
32 the examples directory from this module's CPAN distribution to better
33 understand how to make use of this module.
34
36 Arguments to "prompt"
37 Any argument not of the following forms is treated as part of the text
39 of the prompt itself.
40 Flag Long form Arg Effect
42 ---- --------- --- ------
43 <str> Use <str> as prompt
44 <filehandle> Prompt to specified filehandle
46 <hashref> Flatten hash entries into argument list
48 (useful for aggregating the options below)
49 -p -prompt <str> Specify prompt explicitly
51 -s -speed <num> Simulated typing speed (seconds/char)
53 -e -echo <str> What to echo for each char typed
55 -nl -newline <str> When a newline is typed, echo <str> instead
57 -d -default <str> What to return if only <return> pressed
59 -r -require <hashref> Each value of each entry must 'smartmatch'
61 the input else corresponding key is printed
62 as error message:
63 - Subs must return true when passed input
64 - Regexes must pattern match input
65 - Strings must eq match input
66 - Arrays are flattened & recursively matched
67 - Hashes must return true for input as key
68 -u -until <str⎪rgx> Fail if input matches <str⎪regex>
70 -u -fail_if <str⎪rgx> Fail if input matches <str⎪regex>
71 -w -while <str⎪rgx> Fail unless input matches <str⎪regex>
73 -w -okay_if <str⎪rgx> Fail unless input matches <str⎪regex>
74 -m -menu <list⎪hash> Show the data specified as a menu
76 and allow one to be selected. Enter
77 an <ESC> to back up one level.
78 -1 -one_char Return immediately after first char typed
80 -x -escape Pressing <ESC> returns "\e" immediately
82 -c -clear Clear screen before prompt
84 -f -clear_first Clear screen before first prompt only
85 -a -argv Load @ARGV from input if @ARGV empty
87 -l -line Don't autochomp
89 -t -tty Prompt to terminal no matter what
91 -y -yes Return true if [yY] entered, false otherwise
93 -yn -yes_no Return true if [yY], false if [nN]
94 -Y -Yes Return true if 'Y' entered, false otherwise
95 -YN -Yes_No Return true if 'Y', false if 'N'
96 -num -number Accept only valid numbers as input
98 -i -integer Accept only valid integers as input
99 Note that the underscores between words in flags like "-one_char" and
101 "-yes_no" are optional.
102 Flags can be "cuddled". For example:
104 prompt("next: ", -tyn1s=>0.2) # -tty, -yes, -no, -one_char, -speed=>0.2
106 "Hand-written" printing via "hand_print()"
108 The "hand_print()" subroutine takes a string and prints it out in the
110 stop-and-start manner of hand-typed text.
111 Low-level input retrieval via "get_input()"
113 The "get_input()" subroutine is a low-level utility subroutine that
115 takes an input filehandle, an output filehandle, a reference to a hash
116 of options (as listed for "prompt()", above) and a single prompt
117 string. It prints the prompt and retreives the input. You almost cer‐
118 tainly want to use "prompt()" instead.
119
121 "Can't write prompt to read-only $_"
122 You specified a filehandle to which the prompt should be written,
123 but that filehandle was not writeable. Did you pass the wrong file‐
124 handle, or open it in the wrong mode?
125 "Missing argument for %s option"
127 The flag you specified takes an argument, but you didn't provide
128 that argument.
129 "Unknown flag ($s) in prompt"
131 The flag you specified wasn't one of those that "prompt()" under‐
132 stands. Did you misspell it, perhaps?
133 "Argument to -require must be hash reference"
135 The "-require" option takes a single argument that is a hash. You
136 tried to pass it something else. Try a hash instead.
137 "Cannot write to terminal: %s"
139 "Cannot read from terminal: %s"
140 "prompt()" attempted to access the terminal but couldn't. This may
141 mean your environment has no "/dev/tty" available, in which case
142 there isn't much you can do with this module. Sorry.
143 "Can't open %s: %s"
145 "prompt()" tried to read input via *ARGV from a file specified on
146 the command-line, but the file couldn't be opened for the reason
147 shown. This is usually either a permission problem, a non-existent
148 file, or a mistyped filepath.
149 "Argument to -menu must be hash or array reference"
151 The "-menu" option requires an argument that is either an array:
152 prompt -menu=>['yes', 'no', 'maybe'];
154 or a hash:
156 prompt -menu=>{yes=>1, no=>0, maybe=>0.5};
158 or a hash of hashes (of hashes (of array))
160 "Too many -menu items"
162 "Too few -menu items"
163 A menu can't have fewer than 1 or more than 26 items.
164
166 IO::Prompt requires no configuration files or environment variables.
167
169 IO::Prompt requires the following modules:
170 · version
172 · IO::Handle
174 · Term::ReadKey
176 · POSIX
178
180 None reported.
181
183 No bugs have been reported.
184 Please report any bugs or feature requests to
186 "bug-io-prompt@rt.cpan.org", or through the web interface at
187 <http://rt.cpan.org>.
188
190 My deepest gratitude to Autrijus Tang and Brian Ingerson, who have
191 taken care of this module for the past twelve months, while I was off
192 trekking in the highlands of Perl 6. Now it's their turn for some moun‐
193 tain air, I'll be looking after this module again.
194
196 Damian Conway "<DCONWAY@cpan.org>"
197
199 Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>". All rights
200 reserved.
201 This module is free software; you can redistribute it and/or modify it
203 under the same terms as Perl itself.
204
206 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
207 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
208 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
209 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
210 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
211 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
212 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
213 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
214 NECESSARY SERVICING, REPAIR, OR CORRECTION.
215 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
217 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
218 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
219 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CON‐
220 SEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFT‐
221 WARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
222 INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
223 THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER
224 OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
225perl v5.8.8 2006-02-16 IO::Prompt(3)