1Term::UI(3) User Contributed Perl Documentation Term::UI(3)
2
6 Term::UI - Term::ReadLine UI made easy
7
9 use Term::UI;
10 use Term::ReadLine;
11 my $term = Term::ReadLine->new('brand');
13 my $reply = $term->get_reply(
15 prompt => 'What is your favourite colour?',
16 choices => [qw|blue red green|],
17 default => 'blue',
18 );
19 my $bool = $term->ask_yn(
21 prompt => 'Do you like cookies?',
22 default => 'y',
23 );
24 my $string = q[some_command -option --no-foo --quux='this thing'];
27 my ($options,$munged_input) = $term->parse_options($string);
29 ### don't have Term::UI issue warnings -- default is '1'
32 $Term::UI::VERBOSE = 0;
33 ### always pick the default (good for non-interactive terms)
35 ### -- default is '0'
36 $Term::UI::AUTOREPLY = 1;
37 ### Retrieve the entire session as a printable string:
39 $hist = Term::UI::History->history_as_string;
40 $hist = $term->history_as_string;
41
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 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 For asking a yes or no question, there's even a shortcut.
51
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 "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
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 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 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 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 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 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 See the "EXAMPLES" section for samples of how to use this function.
92 $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 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 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 See the "EXAMPLES" section for samples of how to use this function.
109 ($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 Consider this example:
116 my $str = q[command --no-foo --baz --bar=0 --quux=bleh ] .
118 q[--option="some'thing" -one-dash -single=blah' arg];
119 my ($options,$munged) = $term->parse_options($str);
121 ### $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 ### 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 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 $str = $term->history_as_string
144 Convenience wrapper around "Term::UI::History->history_as_string".
145 Consult the "Term::UI::History" man page for details.
147
149 The behaviour of Term::UI can be altered by changing the following
150 global variables:
151 $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 $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 $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 $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 This defaults to *STDOUT.
174
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 which would look like:
181 Your favourite colour?
183 and $reply would hold the text the user typed.
185 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 which would look like:
193 1> red
195 2> green
196 3> blue
197 Your favourite colour?
199 $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 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 which would look like:
213 1> red
215 2> green
216 3> blue
217 Your favourite colour? [3]:
219 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 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 which would look like:
234 Tell us what colours you like
236 1> red
237 2> green
238 3> blue
239 Your favourite colours?
241 An answer of "3 2 1" would fill @reply with "blue green red"
243 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 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 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 would print:
265 Cookies are LOVELY!!!
267 Do you like cookies? [Y/n]:
268 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 We could later retrieve this interaction by printing out the Q&A
274 history as follows:
275 print $term->history_as_string;
277 which would then print:
279 Cookies are LOVELY!!!
281 Do you like cookies? [Y/n]: y
282 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 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
292 "Params::Check", "Term::ReadLine", "Term::UI::History"
293
295 Please report bugs or other issues to <bug-term-ui@rt.cpan.org<gt>.
296
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.
303perl v5.32.1 2021-01-27 Term::UI(3)