1Term::Prompt(3) User Contributed Perl Documentation Term::Prompt(3)
2
6 Term::Prompt - Perl extension for prompting a user for information
7
9 use Term::Prompt;
10 $value = prompt(...);
11 use Term::Prompt qw(termwrap);
13 print termwrap(...);
14 $Term::Prompt::MULTILINE_INDENT = '';
16
18 You must have Text::Wrap and Term::ReadKey available on your system.
19
21 This main function of this module is to accept interactive input. You
22 specify the type of inputs allowed, a prompt, help text and defaults
23 and it will deal with the user interface, (and the user!), by
24 displaying the prompt, showing the default, and checking to be sure
25 that the response is one of the legal choices. Additional 'types' that
26 could be added would be a phone type, a social security type, a generic
27 numeric pattern type...
28
30 prompt
31 This is the main function of the module. Its first argument determines
32 its usage and is one of the following single characters:
33 x: do not care
35 a: alpha-only
36 n: numeric-only
37 i: ignore case
38 c: case sensitive
39 r: ranged by the low and high values
40 f: floating-point
41 y: yes/no
42 e: regular expression
43 s: sub (actually, a code ref, but 'c' was taken)
44 p: password (keystrokes not echoed)
45 m: menu
46 x: do not care
48 $result = prompt('x', 'text prompt', 'help prompt', 'default' );
49 $result is whatever the user types.
51 a: alpha-only
53 $result = prompt('a', 'text prompt', 'help prompt', 'default' );
54 $result is a single 'word' consisting of [A-Za-z] only. The
56 response is rejected until it conforms.
57 n: numeric-only
59 $result = prompt('n', 'text prompt', 'help prompt', 'default' );
60 The result will be a positive integer or 0.
62 $result = prompt('-n', 'text prompt', 'help prompt', 'default' );
64 The result will be a negative integer or 0.
66 $result = prompt('+-n', 'text prompt', 'help prompt', 'default' );
68 The result will be a any integer or 0.
70 i: ignore case
72 $result = prompt('i', 'text prompt', 'help prompt', 'default',
73 'legal_options-ignore-case-list');
74 c: case sensitive
76 $result = prompt('c', 'text prompt', 'help prompt', 'default',
77 'legal_options-case-sensitive-list');
78 r: ranged by the low and high values
80 $result = prompt('r', 'text prompt', 'help prompt', 'default',
81 'low', 'high');
82 f: floating-point
84 $result = prompt('f', 'text prompt', 'help prompt', 'default');
85 The result will be a floating-point number.
87 y: yes/no
89 $result = prompt('y', 'text prompt', 'help prompt', 'default')
90 The result will be 1 for y, 0 for n. A default not starting with y,
92 Y, n or N will be treated as y for positive, n for negative.
93 e: regular expression
95 $result = prompt('e', 'text prompt', 'help prompt', 'default',
96 'regular expression');
97 The regular expression has and implicit ^ and $ surrounding it;
99 just put in .* before or after if you need to free it up before or
100 after.
101 s: sub
103 $result = prompt('s', 'text prompt', 'help prompt', 'default',
104 sub { warn 'Your input was ' . shift; 1 });
105 $result = prompt('s', 'text prompt', 'help prompt', 'default',
106 \&my_custom_validation_handler);
107 User reply is passed to given code reference as first and only
109 argument. If code returns true, input is accepted.
110 p: password
112 $result = prompt('p', 'text prompt', 'help prompt', 'default' );
113 $result is whatever the user types, but the characters are not
115 echoed to the screen.
116 m: menu
118 @results = prompt(
119 'm',
120 {
121 prompt => 'text prompt',
122 title => 'My Silly Menu',
123 items => [ qw (foo bar baz biff spork boof akak) ],
124 order => 'across',
125 rows => 1,
126 cols => 1,
127 display_base => 1,
128 return_base => 0,
129 accept_multiple_selections => 0,
130 accept_empty_selection => 0,
131 ignore_whitespace => 0,
132 separator => '[^0-9]+'
133 },
134 'help prompt',
135 'default');
136 This will create a menu with numbered items to select. You replace
138 the normal prompt argument with a hash reference containing this
139 information:
140 prompt
142 The prompt string.
143 title
145 Text printed above the menu.
146 items
148 An array reference to the list of text items to display. They
149 will be numbered ascending in the order presented.
150 order
152 If set to 'across', the item numbers run across the menu:
153 1) foo 2) bar 3) baz
155 4) biff 5) spork 6) boof
156 7) akak
157 If set to 'down', the item numbers run down the menu:
159 1) foo 4) biff 7) akak
161 2) bar 5) spork
162 3) baz 6) boof
163 'down' is the default.
165 rows,cols
167 Forces the number of rows and columns. Otherwise, the number of
168 rows and columns is determined from the number of items and the
169 maximum length of an item with its number.
170 Usually, you would set rows = 1 or cols = 1 to force a non-
172 wrapped layout. Setting both in tandem is untested. Cavet
173 programmer.
174 display_base,return_base
176 Internally, the items are indexed the 'Perl' way, from 0 to
177 scalar -1. The display_base is the number added to the index on
178 the menu display. The return_base is the number added to the
179 index before the reply is returned to the programmer.
180 The defaults are 1 and 0, respectively.
182 accept_multiple_selections
184 When set to logical true (1 will suffice), more than one menu
185 item may be selected. The return from prompt() will be an array
186 or array ref, depending on how it is called.
187 The default is 0. The return value is a single scalar
189 containing the selection.
190 accept_empty_selection
192 When set to logical true (1 will suffice), if no items are
193 selected, the menu will not be repeated and the 'empty'
194 selection will be returned. The value of an 'empty' selection
195 is an empty array or a reference to same, if
196 accept_multiple_selections is in effect, or undef if not.
197 separator
199 A regular expression that defines what characters are allowed
200 between multiple responses. The default is to allow all non-
201 numeric characters to be separators. That can cause problems
202 when a user mistakenly enters the lead letter of the menu item
203 instead of the item number. You are better off replacing the
204 default with something more reasonable, such as:
205 [,] ## Commas
207 [,/] ## Commas or slashes
208 [,/\s] ## Commas or slashes or whitespace
209 ignore_whitespace
211 When set, allows spaces between menu responses to be ignored,
212 so that
213 1, 5, 6
215 is collapsed to
217 1,5,6
219 before parsing. NOTE: Do not set this option if you are
221 including whitespace as a legal separator.
222 ignore_empties
224 When set, consecutive separators will not result in an empty
225 entry. For example, without setting this option:
226 1,,8,9
228 will result in a return of
230 (1,'',8,9)
232 When set, the return will be:
234 (1,8,9)
236 which is probably what you want.
238 Other Functions and Variables
240 termwrap
241 Part of Term::Prompt is the optionally exported function termwrap,
242 which is used to wrap lines to the width of the currently selected
243 filehandle (or to STDOUT or STDERR if the width of the current
244 filehandle cannot be determined). It uses the GetTerminalSize
245 function from Term::ReadKey then Text::Wrap.
246 MULTILINE_INDENT
248 This package variable holds the string to be used to indent lines
249 of a multiline prompt, after the first line. The default is "\t",
250 which is how the module worked before the variable was exposed. If
251 you do not want ANY indentation:
252 $Term::Prompt::MULTILINE_INDENT = '';
254 Text and Help Prompts
256 What, you might ask, is the difference between a 'text prompt' and a
257 'help prompt'? Think about the case where the 'legal_options' look
258 something like: '1-1000'. Now consider what happens when you tell
259 someone that '0' is not between 1-1000 and that the possible choices
260 are: :) 1 2 3 4 5 ..... This is what the 'help prompt' is for.
261 It will work off of unique parts of 'legal_options'.
263 Changed by Allen - if you capitalize the type of prompt, it will be
265 treated as a true 'help prompt'; that is, it will be printed ONLY if
266 the menu has to be redisplayed due to and entry error. Otherwise, it
267 will be treated as a list of options and displayed only the first time
268 the menu is displayed.
269 Capitalizing the type of prompt will also mean that a return may be
271 accepted as a response, even if there is no default; whether it
272 actually is will depend on the type of prompt. Menus, for example, do
273 not do this.
274
276 Original Author: Mark Henderson (henderson@mcs.anl.gov or
277 systems@mcs.anl.gov). Derived from im_prompt2.pl, from anlpasswd (see
278 ftp://info.mcs.anl.gov/pub/systems/), with permission.
279 Contributors:
281 E. Allen Smith (easmith@beatrice.rutgers.edu): Revisions for Perl 5,
283 additions of alternative help text presentation, floating point type,
284 regular expression type, yes/no type, line wrapping and regular
285 expression functionality added by E. Allen Smith.
286 Matthew O. Persico (persicom@cpan.org): Addition of menu functionality
288 and $Term::Prompt::MULTILINE_INDENT.
289 Tuomas Jormola (tjormola@cc.hut.fi): Addition of code refs.
291 Current maintainer: Matthew O. Persico (persicom@cpan.org)
293
295 perl, Term::ReadKey, and Text::Wrap.
296
298 Copyright (C) 2004 by Matthew O. Persico
299 This library is free software; you can redistribute it and/or modify it
301 under the same terms as Perl itself, either Perl version 5.6.1 or, at
302 your option, any later version of Perl 5 you may have available.
303perl v5.36.0 2023-01-20 Term::Prompt(3)