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

NAME

6       Term::Clui.pm - Perl module offering a Command-Line User Interface
7

SYNOPSIS

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
16        if (confirm($text)) { do_something(); };
17
18        $answer = ask($question);
19        $answer = ask($question,$suggestion);
20        $password = ask_password("Enter password:");
21        $filename = ask_filename("Which file ?");  # with Tab-completion
22
23        $newtext = edit($title, $oldtext);
24        edit($filename);
25
26        view($title, $text)  # if $title is not a filename
27        view($textfile)  # if $textfile _is_ a filename
28
29        edit(choose("Edit which file ?", grep(-T, readdir D)));
30

DESCRIPTION

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
42       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
48       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
55       There is an associated file selector, Term::Clui::FileSelect
56
57       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
65       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
69       This is Term::Clui.pm version 1.71
70

WINDOW-SIZE

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
77       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
86       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

SUBROUTINES

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
99          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
104       ask_password( $question );
105          Does the same with no echo, as used for password entry.
106
107       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
112       choose( $question, @list );
113          Displays the question, and formats the list items onto the lines
114          beneath it.
115
116          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
121          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
126          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
137          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
145          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
151          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
160       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
169       edit( $title, $text );  OR  edit( $filename );
170          Uses the environment variable EDITOR ( or vi :-) Uses RCS if
171          directory RCS/ exists
172
173       sorry( $message );
174          Similar to warn "Sorry, $message\n";
175
176       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
181       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
190          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
195       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

EXPORT_OK SUBROUTINES

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
208        import Term::Clui qw(:ALL);
209
210       beep()
211          Beeps.
212
213       timestamp()
214          Returns a sortable timestamp string in "YYYYMMDD hhmmss" form.
215
216       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
222       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

DEPENDENCIES

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

ENVIRONMENT

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
240       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
244       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
248       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
253       Term::Clui also consults the environment variables HOME, LOGDIR, EDITOR
254       and PAGER, if they are set.
255

EXAMPLES

257       These scripts using Term::Clui and Term::Clui::FileSelect are to be
258       found in the examples subdirectory of the build directory.
259
260       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
267       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
274       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
279       test_script
280          This is the test script, as used during development.
281
282       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

AUTHOR

291       Original author:
292
293       Peter J Billam www.pjb.com.au/comp/contact.html
294
295       Current maintainer:
296
297       Graham Ollis
298
299       Contributors:
300
301       Peter Scott
302

CREDITS

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

SEE ALSO

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
323       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
326
327
328
329perl v5.38.0                      2023-07-21                     Term::Clui(3)
Impressum