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], preput => "text to put as default user input",
64 multi => BOOL, print_me => "extra text to print & record", allow =>
65 $ref] );
66 "get_reply" asks a user a question, and then returns the reply to the
67 caller. If the answer is invalid (more on that below), the question
68 will be reposed, until a satisfactory answer has been entered.
69 You have the option of providing a list of choices the user can pick
71 from using the "choices" argument. If the answer is not in the list of
72 choices presented, the question will be reposed.
73 If you provide a "default" answer, this will be returned when either
75 $AUTOREPLY is set to true, (see the "GLOBAL VARIABLES" section further
76 below), or when the user just hits "enter".
77 The "preput" argument allows to specify a text that will be inserted to
79 the prompt line as the initial input which may be edited, deleted or
80 accepted by the user. If you supply the empty string as the "preput"
81 argument then the "default" value will be preputted. It will only work
82 if the underlying readline module provide support for it (now it is
83 supported only by the "Term::Readline::Gnu").
84 You can indicate that the user is allowed to enter multiple answers by
86 toggling the "multi" flag. Note that a list of answers will then be
87 returned to you, rather than a simple string.
88 By specifying an "allow" handler, you can yourself validate the answer
90 a user gives. This can be any of the types that the Params::Check
91 "allow" function allows, so please refer to that manpage for details.
92 Finally, you have the option of adding a "print_me" argument, which is
94 simply printed before the prompt. It's printed to the same file handle
95 as the rest of the questions, so you can use this to keep track of a
96 full session of Q&A with the user, and retrieve it later using the
97 "Term::UI->history_as_string" function.
98 See the "EXAMPLES" section for samples of how to use this function.
100 $bool = $term->ask_yn( prompt => "your question", [default => (y|1,n|0),
102 print_me => "extra text to print & record"] )
103 Asks a simple "yes" or "no" question to the user, returning a boolean
104 indicating "true" or "false" to the caller.
105 The "default" answer will automatically returned, if the user hits
107 "enter" or if $AUTOREPLY is set to true. See the "GLOBAL VARIABLES"
108 section further below.
109 Also, you have the option of adding a "print_me" argument, which is
111 simply printed before the prompt. It's printed to the same file handle
112 as the rest of the questions, so you can use this to keep track of a
113 full session of Q&A with the user, and retrieve it later using the
114 "Term::UI->history_as_string" function.
115 See the "EXAMPLES" section for samples of how to use this function.
117 ($opts, $munged) = $term->parse_options( STRING );
119 "parse_options" will convert all options given from an input string to
120 a hash reference. If called in list context it will also return the
121 part of the input string that it found no options in.
122 Consider this example:
124 my $str = q[command --no-foo --baz --bar=0 --quux=bleh ] .
126 q[--option="some'thing" -one-dash -single=blah' arg];
127 my ($options,$munged) = $term->parse_options($str);
129 ### $options would contain: ###
131 $options = {
132 'foo' => 0,
133 'bar' => 0,
134 'one-dash' => 1,
135 'baz' => 1,
136 'quux' => 'bleh',
137 'single' => 'blah\'',
138 'option' => 'some\'thing'
139 };
140 ### and this is the munged version of the input string,
142 ### ie what's left of the input minus the options
143 $munged = 'command arg';
144 As you can see, you can either use a single or a double "-" to indicate
146 an option. If you prefix an option with "no-" and do not give it a
147 value, it will be set to 0. If it has no prefix and no value, it will
148 be set to 1. Otherwise, it will be set to its value. Note also that it
149 can deal fine with single/double quoting issues.
150 $str = $term->history_as_string
152 Convenience wrapper around "Term::UI::History->history_as_string".
153 Consult the "Term::UI::History" man page for details.
155
157 The behaviour of Term::UI can be altered by changing the following
158 global variables:
159 $Term::UI::VERBOSE
161 This controls whether Term::UI will issue warnings and explanations as
162 to why certain things may have failed. If you set it to 0, Term::UI
163 will not output any warnings. The default is 1;
164 $Term::UI::AUTOREPLY
166 This will make every question be answered by the default, and warn if
167 there was no default provided. This is particularly useful if your
168 program is run in non-interactive mode. The default is 0;
169 $Term::UI::INVALID
171 This holds the string that will be printed when the user makes an
172 invalid choice. You can override this string from your program if you,
173 for example, wish to do localization. The default is "Invalid
174 selection, please try again: "
175 $Term::UI::History::HISTORY_FH
177 This is the filehandle all the print statements from this module are
178 being sent to. Please consult the "Term::UI::History" manpage for
179 details.
180 This defaults to *STDOUT.
182
184 Basic get_reply sample
185 ### ask a user (with an open question) for their favourite colour
186 $reply = $term->get_reply( prompt => 'Your favourite colour? );
187 which would look like:
189 Your favourite colour?
191 and $reply would hold the text the user typed.
193 get_reply with choices
195 ### now provide a list of choices, so the user has to pick one
196 $reply = $term->get_reply(
197 prompt => 'Your favourite colour?',
198 choices => [qw|red green blue|] );
199 which would look like:
201 1> red
203 2> green
204 3> blue
205 Your favourite colour?
207 $reply will hold one of the choices presented. "Term::UI" will repose
209 the question if the user attempts to enter an answer that's not in the
210 list of choices. The string presented is held in the $Term::UI::INVALID
211 variable (see the "GLOBAL VARIABLES" section for details.
212 get_reply with choices and default
214 ### provide a sensible default option -- everyone loves blue!
215 $reply = $term->get_reply(
216 prompt => 'Your favourite colour?',
217 choices => [qw|red green blue|],
218 default => 'blue' );
219 which would look like:
221 1> red
223 2> green
224 3> blue
225 Your favourite colour? [3]:
227 Note the default answer after the prompt. A user can now just hit
229 "enter" (or set $Term::UI::AUTOREPLY -- see the "GLOBAL VARIABLES"
230 section) and the sensible answer 'blue' will be returned.
231 get_reply using print_me & multi
233 ### allow the user to pick more than one colour and add an
234 ### introduction text
235 @reply = $term->get_reply(
236 print_me => 'Tell us what colours you like',
237 prompt => 'Your favourite colours?',
238 choices => [qw|red green blue|],
239 multi => 1 );
240 which would look like:
242 Tell us what colours you like
244 1> red
245 2> green
246 3> blue
247 Your favourite colours?
249 An answer of "3 2 1" would fill @reply with "blue green red"
251 get_reply & allow
253 ### pose an open question, but do a custom verification on
254 ### the answer, which will only exit the question loop, if
255 ### the answer matches the allow handler.
256 $reply = $term->get_reply(
257 prompt => "What is the magic number?",
258 allow => 42 );
259 Unless the user now enters 42, the question will be reposed over and
261 over again. You can use more sophisticated "allow" handlers (even
262 subroutines can be used). The "allow" handler is implemented using
263 "Params::Check"'s "allow" function. Check its manpage for details.
264 an elaborate ask_yn sample
266 ### ask a user if he likes cookies. Default to a sensible 'yes'
267 ### and inform him first what cookies are.
268 $bool = $term->ask_yn( prompt => 'Do you like cookies?',
269 default => 'y',
270 print_me => 'Cookies are LOVELY!!!' );
271 would print:
273 Cookies are LOVELY!!!
275 Do you like cookies? [Y/n]:
276 If a user then simply hits "enter", agreeing with the default, $bool
278 would be set to "true". (Simply hitting 'y' would also return "true".
279 Hitting 'n' would return "false")
280 We could later retrieve this interaction by printing out the Q&A
282 history as follows:
283 print $term->history_as_string;
285 which would then print:
287 Cookies are LOVELY!!!
289 Do you like cookies? [Y/n]: y
290 There's a chance we're doing this non-interactively, because a console
292 is missing, the user indicated he just wanted the defaults, etc.
293 In this case, simply setting $Term::UI::AUTOREPLY to true, will return
295 from every question with the default answer set for the question. Do
296 note that if "AUTOREPLY" is true, and no default is set, "Term::UI"
297 will warn about this and return "undef".
298
300 "Params::Check", "Term::ReadLine", "Term::UI::History"
301
303 Please report bugs or other issues to <bug-term-ui@rt.cpan.org<gt>.
304
306 This module by Jos Boumans <kane@cpan.org>.
307
309 This library is free software; you may redistribute and/or modify it
310 under the same terms as Perl itself.
311perl v5.34.0 2022-01-21 Term::UI(3)