1Term::Clui(3) User Contributed Perl Documentation Term::Clui(3)
2
6 Term::Clui.pm - Perl module offering a Command-Line User Interface
7
9 use Term::Clui;
10 $chosen = choose("A Title", @a_list); # single choice
11 @chosen = choose("A Title", @a_list); # multiple choice
12 # multi-line question-texts are possible...
13 $x = choose("Which ?\n(Mouse, or Arrow-keys and Return)", @w);
14 $x = choose("Which ?\n".help_text(), @w);
15 if (confirm($text)) { do_something(); };
17 $answer = ask($question);
19 $answer = ask($question,$suggestion);
20 $password = ask_password("Enter password:");
21 $filename = ask_filename("Which file ?"); # with Tab-completion
22 $newtext = edit($title, $oldtext);
24 edit($filename);
25 view($title, $text) # if $title is not a filename
27 view($textfile) # if $textfile _is_ a filename
28 edit(choose("Edit which file ?", grep(-T, readdir D)));
30
32 Term::Clui offers a high-level user interface to give the user of
33 command-line applications a consistent "look and feel". Its metaphor
34 for the computer is as a human-like conversation-partner, and as each
35 question/response is completed it is summarised onto one line, and
36 remains on screen, so that the history of the session gradually
37 accumulates on the screen and is available for review, or for
38 cut/paste. This user interface can therefore be intermixed with
39 standard applications which write to STDOUT or STDERR, such as make,
40 pgp, rcs etc.
41 For the user, choose() uses either (since 1.50) the mouse; or arrow
43 keys (or hjkl) and Return; also q to quit, and SpaceBar or Button3 to
44 highlight multiple choices. confirm() expects y, Y, n or N. In
45 general, ctrl-L redraws the (currently active bit of the) screen.
46 edit() and view() use the default EDITOR and PAGER if possible.
47 It's fast, simple, and has few external dependencies. It doesn't use
49 curses (which is a whole-of-screen interface); it uses a small subset
50 of vt100 sequences (up down left right normal and reverse) which are
51 very portable, and also (since 1.50) the SET_ANY_EVENT_MOUSE and kmous
52 (terminfo) sequences, which are supported by all xterm, rxvt, konsole,
53 screen, linux, gnome and putty terminals.
54 There is an associated file selector, Term::Clui::FileSelect
56 Since version 1.60, a speaking interface is provided for the visually-
58 impaired user; it employs eflite or espeak. Speech is turned on if the
59 CLUI_SPEAK environment variable is set to any non-empty string. Since
60 version 1.62, if speakup is running, it is silenced while Term::Clui
61 runs, and then restored. Because Term::Clui's metaphor for the
62 computer is a human-like conversation-partner, this works very
63 naturally. The application needs no modification.
64 There is an equivalent Python3 module, with (as far as possible) the
66 same calling interface, at
67 http://cpansearch.perl.org/src/PJB/Term-Clui-1.71/py/TermClui.py
68 This is Term::Clui.pm version 1.71
70
72 Term::Clui attempts to handle the WINCH signal. If the window size is
73 changed, then as soon as the user enters the next keystroke (such as
74 ctrl-L) the current question/response will be redisplayed to fit the
75 new size.
76 The first line of the question, the one which will remain on-screen, is
78 not re-formatted, but is left to be dealt with by the width of the
79 window. Subsequent lines are split into blank-separated words which
80 are filled into the available width; lines beginning with white-space
81 are treated as the beginning of a new indented paragraph, individual
82 words which will not fit onto one line are truncated, and successive
83 blank lines are collapsed into one. If the question will not fit
84 within the available rows, it is truncated.
85 If the available choice items in a choose() overflow the screen, the
87 user is asked to enter "clue" letters, and as soon as the items
88 matching them will fit onto the screen they are displayed as a choice.
89
91 ask( $question ); OR ask( $question, $default );
92 Asks the user the question and returns a string answer, with no
93 newline character at the end. If the optional second argument is
94 present, it is offered to the user as a default. If the $question
95 is multi-line, the entry-field is at the top to the right of the
96 first line, and the subsequent lines are formatted within the screen
97 width and displayed beneath, as with choose.
98 For the user, left and right arrow keys move backward and forward
100 through the string, delete and backspace erase the previous
101 character, ctrl-A moves to the beginning, ctrl-E to the end, and
102 ctrl-D or ctrl-X clear the current string.
103 ask_password( $question );
105 Does the same with no echo, as used for password entry.
106 ask_filename( $question );
108 Uses Term::ReadLine::Gnu to provide filename-completion with the Tab
109 key, but also displays multi-line questions in the same way as ask
110 and choose do. This function was introduced in version 1.65.
111 choose( $question, @list );
113 Displays the question, and formats the list items onto the lines
114 beneath it.
115 If choose is called in a scalar context, the user can choose an item
117 using arrow keys (or hjkl) and Return, or cancel the choice with a
118 "q". choose then returns the chosen item, or undefined if the
119 choice was cancelled.
120 If choose is called in an array context, the user can also mark an
122 item with the SpaceBar. choose then returns the list of marked
123 items, (including the item highlit when Return was pressed), or an
124 empty array if the choice was cancelled.
125 A DBM database is maintained of the question and its chosen
127 response. The next time the user is offered a choice with the same
128 question, if that response is still in the list it is highlighted as
129 the default; otherwise the first item is highlighted. Different
130 parts of the code, or different applications using Term::Clui.pm can
131 therefore exchange defaults simply by using the same question words,
132 such as "Which printer ?". Multiple choices are not remembered, as
133 the danger exists that the user might fail to notice some of the
134 highlit items (for example, all the items might not fit onto one
135 screen).
136 The database ~/.clui_dir/choices or $ENV{CLUI_DIR}/choices is
138 available to be read or written if lower-level manipulation is
139 needed, and the EXPORT_OK routines get_default($question) and
140 set_default($question, $choice) should be used for this purpose, as
141 they handle DBM's problem with concurrent accesses. The whole
142 default database mechanism can be disabled by CLUI_DIR=OFF if you
143 really want to :-(
144 If the items won't fit on the screen, the user is asked to enter a
146 substring as a clue. As soon as the matching items will fit, they
147 are displayed to be chosen as normal. If the user pressed "q" at
148 this choice, they are asked if they wish to change their substring
149 clue; if they reply "n" to this, choose quits and returns undefined.
150 If the $question is multi-line, The first line is put at the top as
152 usual with the choices arranged beneath it; the subsequent lines are
153 formatted within the screen width and displayed at the bottom.
154 After the choice is made all but the first line is erased, and the
155 first line remains on-screen with the choice appended after it. You
156 should therefore try to arrange multi-line questions so that the
157 first line is the question in short form, and subsequent lines are
158 explanation and elaboration.
159 confirm( $question );
161 Asks the question, takes "y", "n", "Y" or "N" as a response. If the
162 $question is multi-line, after the response, all but the first line
163 is erased, and the first line remains on-screen with Yes or No
164 appended after it; you should therefore try to arrange multi-line
165 questions so that the first line is the question in short form, and
166 subsequent lines are explanation and elaboration. Returns true or
167 false.
168 edit( $title, $text ); OR edit( $filename );
170 Uses the environment variable EDITOR ( or vi :-) Uses RCS if
171 directory RCS/ exists
172 sorry( $message );
174 Similar to warn "Sorry, $message\n";
175 inform( $message );
177 Similar to warn "$message\n"; except that it doesn't add the newline
178 at the end if there already is one, and it uses /dev/tty rather than
179 STDERR if it can.
180 view( $title, $text ); OR view( $filename );
182 If the $text is longer than a screenful, uses the environment
183 variable PAGER ( or less ) to display it. If it is one or two lines
184 it just omits the title and displays it. Otherwise it uses a simple
185 built-in routine which expects either "q" or Return from the user;
186 if the user presses Return the displayed text remains on the screen
187 and the dialogue continues after it, if the user presses "q" the
188 text is erased.
189 If there is only one argument and it's a filename, then the user's
191 PAGER displays it, except (since 1.65) if it's a .doc file, when
192 either wvText, antiword or catdoc is used to extract its contents
193 first.
194 help_text( $mode );
196 This returns a short help message for the user. If mode is "ask"
197 then the text describes the keys the user has available when
198 responding to an &ask question; If mode is "multi" then the text
199 describes the keys and mouse actions the user has available when
200 responding to a multiple-choice &choose question; otherwise, the
201 text describes the keys and mouse actions the user has available
202 when responding to a single-choice &choose.
203
205 The following routines are not exported by default, but are exported
206 under the ALL tag, so if you need them you should:
207 import Term::Clui qw(:ALL);
209 beep()
211 Beeps.
212 timestamp()
214 Returns a sortable timestamp string in "YYYYMMDD hhmmss" form.
215 get_default( $question )
217 Consults the database ~/.clui_dir/choices or $ENV{CLUI_DIR}/choices
218 and returns the choice that the user made the last time this
219 question was asked. This is better than opening the database
220 directly as it handles DBM's problem with concurrent accesses.
221 set_default( $question, $new_default )
223 Opens the database ~/.clui_dir/choices or $ENV{CLUI_DIR}/choices and
224 sets the default response which will be offered to the user made the
225 next time this question is asked. This is better than opening the
226 database directly as it handles DBM's problem with concurrent
227 accesses.
228
230 It requires Exporter, which is core Perl. It uses Term::ReadKey if
231 it's available; and uses Term::Size if it's available; if not, it tries
232 tput before guessing 80x24.
233
235 The environment variable CLUI_DIR can be used (by programmer or user)
236 to override ~/.clui_dir as the directory in which choose() keeps its
237 database of previous choices. The whole default database mechanism can
238 be disabled by CLUI_DIR = OFF if you really want to :-(
239 If either the LANG or the LC_TYPE environment variables contain the
241 string utf8 or utf-8 (case insensitive), then choose() and inform()
242 open /dev/tty with a utf8 encoding.
243 If the environment variable CLUI_SPEAK is set or if EDITOR is set to
245 emacspeak, and if flite is installed, then Term::Clui will use flite to
246 speak its questions and choices out loud.
247 If the environment variable CLUI_MOUSE is set to OFF then choose() will
249 not interpret mouse-clicks as making a choice. The advantage of this
250 is that the mouse can then be used to highlight and paste text from
251 this window as usual.
252 Term::Clui also consults the environment variables HOME, LOGDIR, EDITOR
254 and PAGER, if they are set.
255
257 These scripts using Term::Clui and Term::Clui::FileSelect are to be
258 found in the examples subdirectory of the build directory.
259 linux_admin
261 I use this script a lot at work, for routine system administration
262 of linux boxes, particularly Fedora and Debian. It includes
263 crontab, chkconfig, update-rc.d, visudo, vipw, starting and stopping
264 daemons, reconfiguring squid samba or apache, editing sysconfig or
265 running any of the system-config-* utilities, and much else.
266 audio_stuff
268 This script offers an arrow-key-and-return interface integrating
269 aplaymidi, cdrecord, cdda2wav, icedax, lame, mkisofs, muscript,
270 normalize, normalize-audio, mpg123, sndfile-play, timidity, wodim
271 and so on, allowing audio files to be ripped, burned, played, or
272 converted between Muscript, MIDI, WAV and MP3 formats.
273 login_shell
275 This script offers the naive user arrow-key-and-return access to a
276 text-based browser, a mail client, a news client, ssh and ftp and
277 various other stuff.
278 test_script
280 This is the test script, as used during development.
281 choose
283 This is a script which wraps Term::Clui::choose for use at the
284 shell-script level. It can either choose between command-line
285 arguments, or, with the -f (filter) option, between lines of STDIN,
286 like grep. A -m (multiple) option allows multiple-choice. This can
287 be a very useful script, and you may want to copy it into
288 /usr/local/bin/ or elsewhere in your PATH.
289
291 Original author:
292 Peter J Billam www.pjb.com.au/comp/contact.html
294 Current maintainer:
296 Graham Ollis
298 Contributors:
300 Peter Scott
302
304 Based on some old perl 4 libraries, ask.pl, choose.pl, confirm.pl,
305 edit.pl, sorry.pl, inform.pl and view.pl, which were in turn based on
306 some even older curses-based programs in C.
307
309 Term::Clui::FileSelect
310 Term::ReadKey
311 Term::Size
312 http://www.pjb.com.au/
313 http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
314 http://search.cpan.org/~pjb
315 festival(1)
316 eflite(1)
317 espeak(1)
318 espeakup(1)
319 edbrowse(1)
320 emacspeak(1)
321 perl(1)
322 There is an equivalent Python3 module, with (as far as possible) the
324 same calling interface, at
325 https://fastapi.metacpan.org/source/PJB/Term-Clui-1.71/py/TermClui.py
326perl v5.38.0 2023-07-21 Term::Clui(3)