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

NAME

6       Term::UI - Term::ReadLine UI made easy
7

SYNOPSIS

9           use Term::UI;
10           use Term::ReadLine;
11
12           my $term = Term::ReadLine->new('brand');
13
14           my $reply = $term->get_reply(
15                           prompt => 'What is your favourite colour?',
16                           choices => [qw|blue red green|],
17                           default => 'blue',
18           );
19
20           my $bool = $term->ask_yn(
21                               prompt => 'Do you like cookies?',
22                               default => 'y',
23                       );
24
25
26           my $string = q[some_command -option --no-foo --quux='this thing'];
27
28           my ($options,$munged_input) = $term->parse_options($string);
29
30
31           ### don't have Term::UI issue warnings -- default is '1'
32           $Term::UI::VERBOSE = 0;
33
34           ### always pick the default (good for non-interactive terms)
35           ### -- default is '0'
36           $Term::UI::AUTOREPLY = 1;
37
38           ### Retrieve the entire session as a printable string:
39           $hist = Term::UI::History->history_as_string;
40           $hist = $term->history_as_string;
41

DESCRIPTION

43       "Term::UI" is a transparent way of eliminating the overhead of having
44       to format a question and then validate the reply, informing the user if
45       the answer was not proper and re-issuing the question.
46
47       Simply give it the question you want to ask, optionally with choices
48       the user can pick from and a default and "Term::UI" will DWYM.
49
50       For asking a yes or no question, there's even a shortcut.
51

HOW IT WORKS

53       "Term::UI" places itself at the back of the "Term::ReadLine" @ISA
54       array, so you can call its functions through your term object.
55
56       "Term::UI" uses "Term::UI::History" to record all interactions with the
57       commandline. You can retrieve this history, or alter the filehandle the
58       interaction is printed to. See the "Term::UI::History" manpage or the
59       "SYNOPSIS" for details.
60

METHODS

62   $reply = $term->get_reply( prompt => 'question?', [choices => \@list,
63       default => $list[0], multi => BOOL, print_me => "extra text to print &
64       record", allow => $ref] );
65       "get_reply" asks a user a question, and then returns the reply to the
66       caller. If the answer is invalid (more on that below), the question
67       will be reposed, until a satisfactory answer has been entered.
68
69       You have the option of providing a list of choices the user can pick
70       from using the "choices" argument. If the answer is not in the list of
71       choices presented, the question will be reposed.
72
73       If you provide a "default"  answer, this will be returned when either
74       $AUTOREPLY is set to true, (see the "GLOBAL VARIABLES" section further
75       below), or when the user just hits "enter".
76
77       You can indicate that the user is allowed to enter multiple answers by
78       toggling the "multi" flag. Note that a list of answers will then be
79       returned to you, rather than a simple string.
80
81       By specifying an "allow" handler, you can yourself validate the answer
82       a user gives. This can be any of the types that the Params::Check
83       "allow" function allows, so please refer to that manpage for details.
84
85       Finally, you have the option of adding a "print_me" argument, which is
86       simply printed before the prompt. It's printed to the same file handle
87       as the rest of the questions, so you can use this to keep track of a
88       full session of Q&A with the user, and retrieve it later using the
89       "Term::UI->history_as_string" function.
90
91       See the "EXAMPLES" section for samples of how to use this function.
92
93   $bool = $term->ask_yn( prompt => "your question", [default => (y|1,n|0),
94       print_me => "extra text to print & record"] )
95       Asks a simple "yes" or "no" question to the user, returning a boolean
96       indicating "true" or "false" to the caller.
97
98       The "default" answer will automatically returned, if the user hits
99       "enter" or if $AUTOREPLY is set to true. See the "GLOBAL VARIABLES"
100       section further below.
101
102       Also, you have the option of adding a "print_me" argument, which is
103       simply printed before the prompt. It's printed to the same file handle
104       as the rest of the questions, so you can use this to keep track of a
105       full session of Q&A with the user, and retrieve it later using the
106       "Term::UI->history_as_string" function.
107
108       See the "EXAMPLES" section for samples of how to use this function.
109
110   ($opts, $munged) = $term->parse_options( STRING );
111       "parse_options" will convert all options given from an input string to
112       a hash reference. If called in list context it will also return the
113       part of the input string that it found no options in.
114
115       Consider this example:
116
117           my $str =   q[command --no-foo --baz --bar=0 --quux=bleh ] .
118                       q[--option="some'thing" -one-dash -single=blah' arg];
119
120           my ($options,$munged) =  $term->parse_options($str);
121
122           ### $options would contain: ###
123           $options = {
124                       'foo'       => 0,
125                       'bar'       => 0,
126                       'one-dash'  => 1,
127                       'baz'       => 1,
128                       'quux'      => 'bleh',
129                       'single'    => 'blah\'',
130                       'option'    => 'some\'thing'
131           };
132
133           ### and this is the munged version of the input string,
134           ### ie what's left of the input minus the options
135           $munged = 'command arg';
136
137       As you can see, you can either use a single or a double "-" to indicate
138       an option.  If you prefix an option with "no-" and do not give it a
139       value, it will be set to 0.  If it has no prefix and no value, it will
140       be set to 1.  Otherwise, it will be set to its value. Note also that it
141       can deal fine with single/double quoting issues.
142
143   $str = $term->history_as_string
144       Convenience wrapper around "Term::UI::History->history_as_string".
145
146       Consult the "Term::UI::History" man page for details.
147

GLOBAL VARIABLES

149       The behaviour of Term::UI can be altered by changing the following
150       global variables:
151
152   $Term::UI::VERBOSE
153       This controls whether Term::UI will issue warnings and explanations as
154       to why certain things may have failed. If you set it to 0, Term::UI
155       will not output any warnings.  The default is 1;
156
157   $Term::UI::AUTOREPLY
158       This will make every question be answered by the default, and warn if
159       there was no default provided. This is particularly useful if your
160       program is run in non-interactive mode.  The default is 0;
161
162   $Term::UI::INVALID
163       This holds the string that will be printed when the user makes an
164       invalid choice.  You can override this string from your program if you,
165       for example, wish to do localization.  The default is "Invalid
166       selection, please try again: "
167
168   $Term::UI::History::HISTORY_FH
169       This is the filehandle all the print statements from this module are
170       being sent to. Please consult the "Term::UI::History" manpage for
171       details.
172
173       This defaults to *STDOUT.
174

EXAMPLES

176   Basic get_reply sample
177           ### ask a user (with an open question) for their favourite colour
178           $reply = $term->get_reply( prompt => 'Your favourite colour? );
179
180       which would look like:
181
182           Your favourite colour?
183
184       and $reply would hold the text the user typed.
185
186   get_reply with choices
187           ### now provide a list of choices, so the user has to pick one
188           $reply = $term->get_reply(
189                       prompt  => 'Your favourite colour?',
190                       choices => [qw|red green blue|] );
191
192       which would look like:
193
194             1> red
195             2> green
196             3> blue
197
198           Your favourite colour?
199
200       $reply will hold one of the choices presented. "Term::UI" will repose
201       the question if the user attempts to enter an answer that's not in the
202       list of choices. The string presented is held in the $Term::UI::INVALID
203       variable (see the "GLOBAL VARIABLES" section for details.
204
205   get_reply with choices and default
206           ### provide a sensible default option -- everyone loves blue!
207           $reply = $term->get_reply(
208                       prompt  => 'Your favourite colour?',
209                       choices => [qw|red green blue|],
210                       default => 'blue' );
211
212       which would look like:
213
214             1> red
215             2> green
216             3> blue
217
218           Your favourite colour? [3]:
219
220       Note the default answer after the prompt. A user can now just hit
221       "enter" (or set $Term::UI::AUTOREPLY -- see the "GLOBAL VARIABLES"
222       section) and the sensible answer 'blue' will be returned.
223
224   get_reply using print_me & multi
225           ### allow the user to pick more than one colour and add an
226           ### introduction text
227           @reply = $term->get_reply(
228                       print_me    => 'Tell us what colours you like',
229                       prompt      => 'Your favourite colours?',
230                       choices     => [qw|red green blue|],
231                       multi       => 1 );
232
233       which would look like:
234
235           Tell us what colours you like
236             1> red
237             2> green
238             3> blue
239
240           Your favourite colours?
241
242       An answer of "3 2 1" would fill @reply with "blue green red"
243
244   get_reply & allow
245           ### pose an open question, but do a custom verification on
246           ### the answer, which will only exit the question loop, if
247           ### the answer matches the allow handler.
248           $reply = $term->get_reply(
249                       prompt  => "What is the magic number?",
250                       allow   => 42 );
251
252       Unless the user now enters 42, the question will be reposed over and
253       over again. You can use more sophisticated "allow" handlers (even
254       subroutines can be used). The "allow" handler is implemented using
255       "Params::Check"'s "allow" function. Check its manpage for details.
256
257   an elaborate ask_yn sample
258           ### ask a user if he likes cookies. Default to a sensible 'yes'
259           ### and inform him first what cookies are.
260           $bool = $term->ask_yn( prompt   => 'Do you like cookies?',
261                                  default  => 'y',
262                                  print_me => 'Cookies are LOVELY!!!' );
263
264       would print:
265
266           Cookies are LOVELY!!!
267           Do you like cookies? [Y/n]:
268
269       If a user then simply hits "enter", agreeing with the default, $bool
270       would be set to "true". (Simply hitting 'y' would also return "true".
271       Hitting 'n' would return "false")
272
273       We could later retrieve this interaction by printing out the Q&A
274       history as follows:
275
276           print $term->history_as_string;
277
278       which would then print:
279
280           Cookies are LOVELY!!!
281           Do you like cookies? [Y/n]:  y
282
283       There's a chance we're doing this non-interactively, because a console
284       is missing, the user indicated he just wanted the defaults, etc.
285
286       In this case, simply setting $Term::UI::AUTOREPLY to true, will return
287       from every question with the default answer set for the question.  Do
288       note that if "AUTOREPLY" is true, and no default is set, "Term::UI"
289       will warn about this and return "undef".
290

See Also

292       "Params::Check", "Term::ReadLine", "Term::UI::History"
293

BUG REPORTS

295       Please report bugs or other issues to <bug-term-ui@rt.cpan.org<gt>.
296

AUTHOR

298       This module by Jos Boumans <kane@cpan.org>.
299
301       This library is free software; you may redistribute and/or modify it
302       under the same terms as Perl itself.
303
304
305
306perl v5.32.0                      2020-07-28                       Term::UI(3)
Impressum