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

NAME

6       Term::Prompt - Perl extension for prompting a user for information
7

SYNOPSIS

9           use Term::Prompt;
10           $value = prompt(...);
11
12           use Term::Prompt qw(termwrap);
13           print termwrap(...);
14
15           $Term::Prompt::MULTILINE_INDENT = '';
16

PREREQUISITES

18       You must have Text::Wrap and Term::ReadKey available on your system.
19

DESCRIPTION

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

FUNCTIONS

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
34        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
47       x: do not care
48            $result = prompt('x', 'text prompt', 'help prompt', 'default' );
49
50           $result is whatever the user types.
51
52       a: alpha-only
53            $result = prompt('a', 'text prompt', 'help prompt', 'default' );
54
55           $result is a single 'word' consisting of [A-Za-z] only. The
56           response is rejected until it conforms.
57
58       n: numeric-only
59            $result = prompt('n', 'text prompt', 'help prompt', 'default' );
60
61           The result will be a positive integer or 0.
62
63            $result = prompt('-n', 'text prompt', 'help prompt', 'default' );
64
65           The result will be a negative integer or 0.
66
67            $result = prompt('+-n', 'text prompt', 'help prompt', 'default' );
68
69           The result will be a any integer or 0.
70
71       i: ignore case
72            $result = prompt('i', 'text prompt', 'help prompt', 'default',
73                                 'legal_options-ignore-case-list');
74
75       c: case sensitive
76            $result = prompt('c', 'text prompt', 'help prompt', 'default',
77                                 'legal_options-case-sensitive-list');
78
79       r: ranged by the low and high values
80            $result = prompt('r', 'text prompt', 'help prompt', 'default',
81                             'low', 'high');
82
83       f: floating-point
84            $result = prompt('f', 'text prompt', 'help prompt', 'default');
85
86           The result will be a floating-point number.
87
88       y: yes/no
89            $result = prompt('y', 'text prompt', 'help prompt', 'default')
90
91           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
94       e: regular expression
95            $result = prompt('e', 'text prompt', 'help prompt', 'default',
96                             'regular expression');
97
98           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
102       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
108           User reply is passed to given code reference as first and only
109           argument.  If code returns true, input is accepted.
110
111       p: password
112            $result = prompt('p', 'text prompt', 'help prompt', 'default' );
113
114           $result is whatever the user types, but the characters are not
115           echoed to the screen.
116
117       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
137           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
141           prompt
142               The prompt string.
143
144           title
145               Text printed above the menu.
146
147           items
148               An array reference to the list of text items to display. They
149               will be numbered ascending in the order presented.
150
151           order
152               If set to 'across', the item numbers run across the menu:
153
154                1) foo    2) bar    3) baz
155                4) biff   5) spork  6) boof
156                7) akak
157
158               If set to 'down', the item numbers run down the menu:
159
160                1) foo    4) biff   7) akak
161                2) bar    5) spork
162                3) baz    6) boof
163
164               'down' is the default.
165
166           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
171               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
175           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
181               The defaults are 1 and 0, respectively.
182
183           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
188               The default is 0. The return value is a single scalar
189               containing the selection.
190
191           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
198           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
206                [,]    ## Commas
207                [,/]   ## Commas or slashes
208                [,/\s] ## Commas or slashes or whitespace
209
210           ignore_whitespace
211               When set, allows spaces between menu responses to be ignored,
212               so that
213
214                1, 5, 6
215
216               is collapsed to
217
218                1,5,6
219
220               before parsing. NOTE: Do not set this option if you are
221               including whitespace as a legal separator.
222
223           ignore_empties
224               When set, consecutive separators will not result in an empty
225               entry. For example, without setting this option:
226
227                1,,8,9
228
229               will result in a return of
230
231                (1,'',8,9)
232
233               When set, the return will be:
234
235                (1,8,9)
236
237               which is probably what you want.
238
239   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
247       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
253            $Term::Prompt::MULTILINE_INDENT = '';
254
255   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
262       It will work off of unique parts of 'legal_options'.
263
264       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
270       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

AUTHOR

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
280       Contributors:
281
282       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
287       Matthew O. Persico (persicom@cpan.org): Addition of menu functionality
288       and $Term::Prompt::MULTILINE_INDENT.
289
290       Tuomas Jormola (tjormola@cc.hut.fi): Addition of code refs.
291
292       Current maintainer: Matthew O. Persico (persicom@cpan.org)
293

SEE ALSO

295       perl, Term::ReadKey, and Text::Wrap.
296
298       Copyright (C) 2004 by Matthew O. Persico
299
300       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.
303
304
305
306perl v5.36.0                      2023-01-20                   Term::Prompt(3)
Impressum