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'];
26 my ($options,$munged_input) = $term->parse_options($string);
28 ### don't have Term::UI issue warnings -- default is '1'
30 $Term::UI::VERBOSE = 0;
31 ### always pick the default (good for non-interactive terms)
33 ### -- default is '0'
34 $Term::UI::AUTOREPLY = 1;
35 ### Retrieve the entire session as a printable string:
37 $hist = Term::UI::History->history_as_string;
38 $hist = $term->history_as_string;
39
41 "Term::UI" is a transparent way of eliminating the overhead of having
42 to format a question and then validate the reply, informing the user if
43 the answer was not proper and re-issuing the question.
44 Simply give it the question you want to ask, optionally with choices
46 the user can pick from and a default and "Term::UI" will DWYM.
47 For asking a yes or no question, there's even a shortcut.
49
51 "Term::UI" places itself at the back of the "Term::ReadLine" @ISA
52 array, so you can call its functions through your term object.
53 "Term::UI" uses "Term::UI::History" to record all interactions with the
55 commandline. You can retrieve this history, or alter the filehandle the
56 interaction is printed to. See the "Term::UI::History" manpage or the
57 "SYNOPSIS" for details.
58
60 $reply = $term->get_reply( prompt => 'question?', [choices => \@list,
61 default => $list[0], multi => BOOL, print_me => "extra text to print &
62 record", allow => $ref] );
63 "get_reply" asks a user a question, and then returns the reply to the
65 caller. If the answer is invalid (more on that below), the question
66 will be reposed, until a satisfactory answer has been entered.
67 You have the option of providing a list of choices the user can pick
69 from using the "choices" argument. If the answer is not in the list of
70 choices presented, the question will be reposed.
71 If you provide a "default" answer, this will be returned when either
73 $AUTOREPLY is set to true, (see the "GLOBAL VARIABLES" section further
74 below), or when the user just hits "enter".
75 You can indicate that the user is allowed to enter multiple answers by
77 toggling the "multi" flag. Note that a list of answers will then be
78 returned to you, rather than a simple string.
79 By specifying an "allow" hander, you can yourself validate the answer a
81 user gives. This can be any of the types that the Params::Check "allow"
82 function allows, so please refer to that manpage for details.
83 Finally, you have the option of adding a "print_me" argument, which is
85 simply printed before the prompt. It's printed to the same file handle
86 as the rest of the questions, so you can use this to keep track of a
87 full session of Q&A with the user, and retrieve it later using the
88 "Term::UI->history_as_string" function.
89 See the "EXAMPLES" section for samples of how to use this function.
91 $bool = $term->ask_yn( prompt => "your question", [default =>
93 (y⎪1,n⎪0), print_me => "extra text to print & record"] )
94 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
113 a hash reference. If called in list context it will also return the
114 part of the input string that it found no options in.
115 Consider this example:
117 my $str = q[command --no-foo --baz --bar=0 --quux=bleh ] .
119 q[--option="some'thing" -one-dash -single=blah' arg];
120 my ($options,$munged) = $term->parse_options($str);
122 ### $options would contain: ###
124 $options = {
125 'foo' => 0,
126 'bar' => 0,
127 'one-dash' => 1,
128 'baz' => 1,
129 'quux' => 'bleh',
130 'single' => 'blah\'',
131 'option' => 'some\'thing'
132 };
133 ### and this is the munged version of the input string,
135 ### ie what's left of the input minus the options
136 $munged = 'command arg';
137 As you can see, you can either use a single or a double "-" to indicate
139 an option. If you prefix an option with "no-" and do not give it a
140 value, it will be set to 0. If it has no prefix and no value, it will
141 be set to 1. Otherwise, it will be set to its value. Note also that it
142 can deal fine with single/double quoting issues.
143 $str = $term->history_as_string
145 Convenience wrapper around "Term::UI::History->history_as_string".
147 Consult the "Term::UI::History" man page for details.
149
151 The behaviour of Term::UI can be altered by changing the following
152 global variables:
153 $Term::UI::VERBOSE
155 This controls whether Term::UI will issue warnings and explanations as
157 to why certain things may have failed. If you set it to 0, Term::UI
158 will not output any warnings. The default is 1;
159 $Term::UI::AUTOREPLY
161 This will make every question be answered by the default, and warn if
163 there was no default provided. This is particularly useful if your pro‐
164 gram is run in non-interactive mode. The default is 0;
165 $Term::UI::INVALID
167 This holds the string that will be printed when the user makes an
169 invalid choice. You can override this string from your program if you,
170 for example, wish to do localization. The default is "Invalid selec‐
171 tion, please try again: "
172 $Term::UI::History::HISTORY_FH
174 This is the filehandle all the print statements from this module are
176 being sent to. Please consult the "Term::UI::History" manpage for
177 details.
178 This defaults to *STDOUT.
180
182 Basic get_reply sample
183 ### ask a user (with an open question) for their favourite colour
185 $reply = $term->get_reply( prompt => 'Your favourite colour? );
186 which would look like:
188 Your favourite colour?
190 and $reply would hold the text the user typed.
192 get_reply with choices
194 ### 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!
216 $reply = $term->get_reply(
217 prompt => 'Your favourite colour?',
218 choices => [qw⎪red green blue⎪],
219 default => 'blue' );
220 which would look like:
222 1> red
224 2> green
225 3> blue
226 Your favourite colour? [3]:
228 Note the default answer after the prompt. A user can now just hit
230 "enter" (or set $Term::UI::AUTOREPLY -- see the "GLOBAL VARIABLES" sec‐
231 tion) and the sensible answer 'blue' will be returned.
232 get_reply using print_me & multi
234 ### allow the user to pick more than one colour and add an
236 ### introduction text
237 @reply = $term->get_reply(
238 print_me => 'Tell us what colours you like',
239 prompt => 'Your favourite colours?',
240 choices => [qw⎪red green blue⎪],
241 multi => 1 );
242 which would look like:
244 Tell us what colours you like
246 1> red
247 2> green
248 3> blue
249 Your favourite colours?
251 An answer of "3 2 1" would fill @reply with "blue green red"
253 get_reply & allow
255 ### pose an open question, but do a custom verification on
257 ### the answer, which will only exit the question loop, if
258 ### the answer matches the allow handler.
259 $reply = $term->get_reply(
260 prompt => "What is the magic number?",
261 allow => 42 );
262 Unless the user now enters 42, the question will be reposed over and
264 over again. You can use more sophisticated "allow" handlers (even sub‐
265 routines can be used). The "allow" handler is implemented using
266 "Params::Check"'s "allow" function. Check its manpage for details.
267 an elaborate ask_yn sample
269 ### ask a user if he likes cookies. Default to a sensible 'yes'
271 ### and inform him first what cookies are.
272 $bool = $term->ask_yn( prompt => 'Do you like cookies?',
273 default => 'y',
274 print_me => 'Cookies are LOVELY!!!' );
275 would print:
277 Cookies are LOVELY!!!
279 Do you like cookies? [Y/n]:
280 If a user then simply hits "enter", agreeing with the default, $bool
282 would be set to "true". (Simply hitting 'y' would also return "true".
283 Hitting 'n' would return "false")
284 We could later retrieve this interaction by printing out the Q&A his‐
286 tory as follows:
287 print $term->history_as_string;
289 which would then print:
291 Cookies are LOVELY!!!
293 Do you like cookies? [Y/n]: y
294 There's a chance we're doing this non-interactively, because a console
296 is missing, the user indicated he just wanted the defaults, etc.
297 In this case, simply setting $Term::UI::AUTOREPLY to true, will return
299 from every question with the default answer set for the question. Do
300 note that if "AUTOREPLY" is true, and no default is set, "Term::UI"
301 will warn about this and return "undef".
302
304 "Params::Check", "Term::ReadLine", "Term::UI::History"
305
307 This module by Jos Boumans <kane@cpan.org>.
308
310 This module is copyright (c) 2002 - 2005 Jos Boumans <kane@cpan.org>.
311 All rights reserved.
312 This library is free software; you may redistribute and/or modify it
314 under the same terms as Perl itself.
315perl v5.8.8 2006-09-04 Term::UI(3)