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.997
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
27 simulates hand-typing to the console; and "get_input", which is the
28 lower-level function that actually prompts the user for a suitable
29 input.
30 Note that this is an interim re-release. A full release with better
32 documentation will follow in the near future. Meanwhile, please consult
33 the examples directory from this module's CPAN distribution to better
34 understand how to make use of this module.
35
37 Arguments to "prompt"
38 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'
62 the input else corresponding key is printed
63 as error message:
64 - Subs must return true when passed input
65 - Regexes must pattern match input
66 - Strings must eq match input
67 - Arrays are flattened & recursively matched
68 - Hashes must return true for input as key
69 -u -until <str|rgx> Fail if input matches <str|regex>
71 -fail_if
72 -w -while <str|rgx> Fail unless input matches <str|regex>
74 -okay_if
75 -m -menu <list|hash> Show the data specified as a menu
77 and allow one to be selected. Enter
78 an <ESC> to back up one level.
79 -1 -one_char Return immediately after first char typed
81 -x -escape Pressing <ESC> returns "\e" immediately
83 -raw -raw_input Return only the string that was input
85 (turns off context-sensitive features)
86 -c -clear Clear screen before prompt
88 -f -clear_first Clear screen before first prompt only
89 -a -argv Load @ARGV from input if @ARGV empty
91 -l -line Don't autochomp
93 -t -tty Prompt to terminal no matter what
95 -y -yes Return true if [yY] entered, false otherwise
97 -yn -yes_no Return true if [yY], false if [nN]
98 -Y -Yes Return true if 'Y' entered, false otherwise
99 -YN -Yes_No Return true if 'Y', false if 'N'
100 -num -number Accept only valid numbers as input
102 -i -integer Accept only valid integers as input
103 Note that the underscores between words in flags like "-one_char" and
105 "-yes_no" are optional.
106 Flags can be "cuddled". For example:
108 prompt("next: ", -tyn1s=>0.2) # -tty, -yes, -no, -one_char, -speed=>0.2
110 "Hand-written" printing via "hand_print()"
112 The "hand_print()" subroutine takes a string and prints it out in the
113 stop-and-start manner of hand-typed text.
114 Low-level input retrieval via "get_input()"
116 The "get_input()" subroutine is a low-level utility subroutine that
117 takes an input filehandle, an output filehandle, a reference to a hash
118 of options (as listed for "prompt()", above) and a single prompt
119 string. It prints the prompt and retreives the input. You almost
120 certainly want to use "prompt()" instead.
121
123 "Can't write prompt to read-only $_"
124 You specified a filehandle to which the prompt should be written,
125 but that filehandle was not writeable. Did you pass the wrong
126 filehandle, or open it in the wrong mode?
127 "Missing argument for %s option"
129 The flag you specified takes an argument, but you didn't provide
130 that argument.
131 "Unknown flag ($s) in prompt"
133 The flag you specified wasn't one of those that "prompt()"
134 understands. Did you misspell it, perhaps?
135 "Argument to -require must be hash reference"
137 The "-require" option takes a single argument that is a hash. You
138 tried to pass it something else. Try a hash instead.
139 "Cannot write to terminal: %s"
141 "Cannot read from terminal: %s"
142 "prompt()" attempted to access the terminal but couldn't. This may
143 mean your environment has no "/dev/tty" available, in which case
144 there isn't much you can do with this module. Sorry.
145 "Can't open %s: %s"
147 "prompt()" tried to read input via *ARGV from a file specified on
148 the command-line, but the file couldn't be opened for the reason
149 shown. This is usually either a permission problem, a non-existent
150 file, or a mistyped filepath.
151 "Argument to -menu must be hash or array reference"
153 The "-menu" option requires an argument that is either an array:
154 prompt -menu=>['yes', 'no', 'maybe'];
156 or a hash:
158 prompt -menu=>{yes=>1, no=>0, maybe=>0.5};
160 or a hash of hashes (of hashes (of array))
162 "Too many -menu items"
164 "Too few -menu items"
165 A menu can't have fewer than 1 or more than 26 items.
166
168 IO::Prompt requires no configuration files or environment variables.
169
171 IO::Prompt requires the following modules:
172 · version
174 · IO::Handle
176 · Term::ReadKey
178 · POSIX
180
182 The module requires a /dev/tty device be available. It is therefore
183 incompatible with any system that doesn't provide such a device.
184
186 No bugs have been reported.
187 Please report any bugs or feature requests to
189 "bug-io-prompt@rt.cpan.org", or through the web interface at
190 <http://rt.cpan.org>.
191
193 This is a collection of things that might help. Please send your
194 questions that are not answered here to Damian Conway
195 "<DCONWAY@cpan.org>"
196 Can I use this module with ActivePerl on Windows?
198 Up to now, the answer was 'No', but this has changed.
199 You still cannot use ActivePerl, but if you use the Cygwin environment
201 (http://sources.redhat.com), which brings its own perl, and have the
202 latest IO::Tty (v0.05 or later) installed, it should work (feedback
203 appreciated).
204
206 My deepest gratitude to Autrijus Tang and Brian Ingerson, who have
207 taken care of this module for the past twelve months, while I was off
208 trekking in the highlands of Perl 6. Now it's their turn for some
209 mountain air, I'll be looking after this module again.
210
212 Damian Conway "<DCONWAY@cpan.org>"
213
215 Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>". All rights
216 reserved.
217 This module is free software; you can redistribute it and/or modify it
219 under the same terms as Perl itself.
220
222 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
223 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
224 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
225 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
226 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
227 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
228 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
229 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
230 NECESSARY SERVICING, REPAIR, OR CORRECTION.
231 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
233 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
234 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
235 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
236 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
237 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
238 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
239 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
240 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
241 DAMAGES.
242perl v5.12.0 2010-01-29 IO::Prompt(3)