1IO::Prompt(3)         User Contributed Perl Documentation        IO::Prompt(3)
2
3
4

NAME

6       IO::Prompt - Interactively prompt for user input
7

STATUS

9       This module is no longer being maintained.
10
11       Use the IO::Prompter module instead.
12

VERSION

14       This document describes IO::Prompt version 0.997004
15

SYNOPSIS

17           use IO::Prompt;
18           while( prompt "next: " ) {
19               print "You said '$_'\n";
20           }
21

DESCRIPTION

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
27       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
31       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
36       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

INTERFACE

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
46        Flag   Long form      Arg          Effect
47        ----   ---------      ---          ------
48                              <str>        Use <str> as prompt
49
50                              <filehandle> Prompt to specified filehandle
51
52                              <hashref>    Flatten hash entries into argument list
53                                           (useful for aggregating the options below)
54
55        -p     -prompt        <str>        Specify prompt explicitly
56
57        -s     -speed         <num>        Simulated typing speed (seconds/char)
58
59        -e     -echo          <str>        What to echo for each char typed
60
61        -nl    -newline       <str>        When a newline is typed, echo <str> instead
62
63        -d     -default       <str>        What to return if only <return> pressed
64
65
66        -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
75        -u     -until         <str|rgx>    Fail if input matches <str|regex>
76               -fail_if
77
78        -w     -while         <str|rgx>    Fail unless input matches <str|regex>
79               -okay_if
80
81        -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
85        -1     -one_char                   Return immediately after first char typed
86
87        -x     -escape                     Pressing <ESC> returns "\e" immediately
88
89        -raw   -raw_input                  Return only the string that was input
90                                           (turns off context-sensitive features)
91
92        -c     -clear                      Clear screen before prompt
93        -f     -clear_first                Clear screen before first prompt only
94
95        -a     -argv                       Load @ARGV from input if @ARGV empty
96
97        -l     -line                       Don't autochomp
98
99        -t     -tty                        Prompt to terminal no matter what
100
101        -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
106        -num   -number                     Accept only valid numbers as input
107        -i     -integer                    Accept only valid integers as input
108
109       Note that the underscores between words in flags like "-one_char" and
110       "-yes_no" are optional.
111
112       Flags can be "cuddled". For example:
113
114            prompt("next: ", -tyn1s=>0.2)   # -tty, -yes, -no, -one_char, -speed=>0.2
115
116   "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
120   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

DIAGNOSTICS

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
133       "Missing argument for %s option"
134           The flag you specified takes an argument, but you didn't provide
135           that argument.
136
137       "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
141       "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
145       "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
151       "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
157       "Argument to -menu must be hash or array reference"
158           The "-menu" option requires an argument that is either an array:
159
160               prompt -menu=>['yes', 'no', 'maybe'];
161
162           or a hash:
163
164               prompt -menu=>{yes=>1, no=>0, maybe=>0.5};
165
166           or a hash of hashes (of hashes (of array))
167
168       "Too many -menu items"
169       "Too few -menu items"
170           A menu can't have fewer than 1 or more than 26 items.
171

CONFIGURATION AND ENVIRONMENT

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

DEPENDENCIES

176       IO::Prompt requires the following modules:
177
178       •   version
179
180       •   IO::Handle
181
182       •   Term::ReadKey
183

INCOMPATIBILITIES

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

BUGS AND LIMITATIONS

189       No bugs have been reported.
190
191       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

FAQ

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
200   Can I use this module with ActivePerl on Windows?
201       Up to now, the answer was 'No', but this has changed.
202
203       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

THANKS

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

AUTHOR

215       Damian Conway  "<DCONWAY@cpan.org>"
216
218       Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>". All rights
219       reserved.
220
221       This module is free software; you can redistribute it and/or modify it
222       under the same terms as Perl itself.
223

DISCLAIMER OF WARRANTY

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
235       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.
245
246
247
248perl v5.32.1                      2021-01-27                     IO::Prompt(3)
Impressum