1IO::Prompt(3) User Contributed Perl Documentation IO::Prompt(3)
2
6 IO::Prompt - Interactively prompt for user input
7
9 This module is no longer being maintained.
10 Use the IO::Prompter module instead.
12
14 This document describes IO::Prompt version 0.997004
15
17 use IO::Prompt;
18 while( prompt "next: " ) {
19 print "You said '$_'\n";
20 }
21
23 By default, this module exports a single function "prompt". It prompts
24 the user to enter some input, and returns an object that represents the
25 user input.
26 You may specify various flags to the function to affect its behaviour;
28 most notably, it defaults to automatically "chomp" the input, unless
29 the "-line" flag is specified.
30 Two other functions are exported at request: "hand_print", which
32 simulates hand-typing to the console; and "get_input", which is the
33 lower-level function that actually prompts the user for a suitable
34 input.
35 Note that this is an interim re-release. A full release with better
37 documentation will follow in the near future. Meanwhile, please consult
38 the examples directory from this module's CPAN distribution to better
39 understand how to make use of this module.
40
42 Arguments to "prompt"
43 Any argument not of the following forms is treated as part of the text
44 of the prompt itself.
45 Flag Long form Arg Effect
47 ---- --------- --- ------
48 <str> Use <str> as prompt
49 <filehandle> Prompt to specified filehandle
51 <hashref> Flatten hash entries into argument list
53 (useful for aggregating the options below)
54 -p -prompt <str> Specify prompt explicitly
56 -s -speed <num> Simulated typing speed (seconds/char)
58 -e -echo <str> What to echo for each char typed
60 -nl -newline <str> When a newline is typed, echo <str> instead
62 -d -default <str> What to return if only <return> pressed
64 -r -require <hashref> Each value of each entry must 'smartmatch'
67 the input else corresponding key is printed
68 as error message:
69 - Subs must return true when passed input
70 - Regexes must pattern match input
71 - Strings must eq match input
72 - Arrays are flattened & recursively matched
73 - Hashes must return true for input as key
74 -u -until <str|rgx> Fail if input matches <str|regex>
76 -fail_if
77 -w -while <str|rgx> Fail unless input matches <str|regex>
79 -okay_if
80 -m -menu <list|hash> Show the data specified as a menu
82 and allow one to be selected. Enter
83 an <ESC> to back up one level.
84 -1 -one_char Return immediately after first char typed
86 -x -escape Pressing <ESC> returns "\e" immediately
88 -raw -raw_input Return only the string that was input
90 (turns off context-sensitive features)
91 -c -clear Clear screen before prompt
93 -f -clear_first Clear screen before first prompt only
94 -a -argv Load @ARGV from input if @ARGV empty
96 -l -line Don't autochomp
98 -t -tty Prompt to terminal no matter what
100 -y -yes Return true if [yY] entered, false otherwise
102 -yn -yes_no Return true if [yY], false if [nN]
103 -Y -Yes Return true if 'Y' entered, false otherwise
104 -YN -Yes_No Return true if 'Y', false if 'N'
105 -num -number Accept only valid numbers as input
107 -i -integer Accept only valid integers as input
108 Note that the underscores between words in flags like "-one_char" and
110 "-yes_no" are optional.
111 Flags can be "cuddled". For example:
113 prompt("next: ", -tyn1s=>0.2) # -tty, -yes, -no, -one_char, -speed=>0.2
115 "Hand-written" printing via "hand_print()"
117 The "hand_print()" subroutine takes a string and prints it out in the
118 stop-and-start manner of hand-typed text.
119 Low-level input retrieval via "get_input()"
121 The "get_input()" subroutine is a low-level utility subroutine that
122 takes an input filehandle, an output filehandle, a reference to a hash
123 of options (as listed for "prompt()", above) and a single prompt
124 string. It prints the prompt and retreives the input. You almost
125 certainly want to use "prompt()" instead.
126
128 "Can't write prompt to read-only $_"
129 You specified a filehandle to which the prompt should be written,
130 but that filehandle was not writeable. Did you pass the wrong
131 filehandle, or open it in the wrong mode?
132 "Missing argument for %s option"
134 The flag you specified takes an argument, but you didn't provide
135 that argument.
136 "Unknown flag ($s) in prompt"
138 The flag you specified wasn't one of those that "prompt()"
139 understands. Did you misspell it, perhaps?
140 "Argument to -require must be hash reference"
142 The "-require" option takes a single argument that is a hash. You
143 tried to pass it something else. Try a hash instead.
144 "Cannot write to terminal: %s"
146 "Cannot read from terminal: %s"
147 "prompt()" attempted to access the terminal but couldn't. This may
148 mean your environment has no "/dev/tty" available, in which case
149 there isn't much you can do with this module. Sorry.
150 "Can't open %s: %s"
152 "prompt()" tried to read input via *ARGV from a file specified on
153 the command-line, but the file couldn't be opened for the reason
154 shown. This is usually either a permission problem, a non-existent
155 file, or a mistyped filepath.
156 "Argument to -menu must be hash or array reference"
158 The "-menu" option requires an argument that is either an array:
159 prompt -menu=>['yes', 'no', 'maybe'];
161 or a hash:
163 prompt -menu=>{yes=>1, no=>0, maybe=>0.5};
165 or a hash of hashes (of hashes (of array))
167 "Too many -menu items"
169 "Too few -menu items"
170 A menu can't have fewer than 1 or more than 26 items.
171
173 IO::Prompt requires no configuration files or environment variables.
174
176 IO::Prompt requires the following modules:
177 • version
179 • IO::Handle
181 • Term::ReadKey
183
185 The module requires a /dev/tty device be available. It is therefore
186 incompatible with any system that doesn't provide such a device.
187
189 No bugs have been reported.
190 Please report any bugs or feature requests to
192 "bug-io-prompt@rt.cpan.org", or through the web interface at
193 <http://rt.cpan.org>.
194
196 This is a collection of things that might help. Please send your
197 questions that are not answered here to Damian Conway
198 "<DCONWAY@cpan.org>"
199 Can I use this module with ActivePerl on Windows?
201 Up to now, the answer was 'No', but this has changed.
202 You still cannot use ActivePerl, but if you use the Cygwin environment
204 (http://sources.redhat.com), which brings its own perl, and have the
205 latest IO::Tty (v0.05 or later) installed, it should work (feedback
206 appreciated).
207
209 My deepest gratitude to Autrijus Tang and Brian Ingerson, who have
210 taken care of this module for the past twelve months, while I was off
211 trekking in the highlands of Perl 6. Now it's their turn for some
212 mountain air, I'll be looking after this module again.
213
215 Damian Conway "<DCONWAY@cpan.org>"
216
218 Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>". All rights
219 reserved.
220 This module is free software; you can redistribute it and/or modify it
222 under the same terms as Perl itself.
223
225 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
226 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
227 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
228 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
229 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
230 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
231 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
232 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
233 NECESSARY SERVICING, REPAIR, OR CORRECTION.
234 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
236 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
237 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
238 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
239 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
240 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
241 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
242 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
243 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
244 DAMAGES.
245perl v5.32.1 2021-01-27 IO::Prompt(3)