Term::Choose - Choose items from a list.
Version 0.7.11
use 5.10.1; use Term::Choose qw(choose); my $list = [ qw( one two three four five ) ]; my $choice = choose( $list ); # single choice say $choice; my @choices = choose( [ 1 .. 100 ], { right_justify => 1 } ); # multiple choice say "@choices"; choose( [ 'Press ENTER to continue' ], { prompt => 0 } ); # no choice
Choose from a list of elements.
Requires Perl Version 5.10.1 or greater.
Based on the choose function from Term::Clui module.
Differences between Term::Clui and Term::Choose:
Term::Clui's choose expects a question as the first argument, and then the list of items. With Term::Choose the first argument is the list of items passed as an array reference. Options can be passed with a hash reference as an optional second argument. The question can be passed as an option (prompt).
The reason for writing Term::Choose was to get a nicer output. If the list does not fit in one row, choose from Term::Clui puts the elements on the screen without ordering the items in columns. Term::Choose arranges the elements in columns which makes it easier for me to find elements and easier to navigate on the screen.
Another difference is how lists which don't find on the screen are handled. Term::Clui::choose asks the user to enter a substring as a clue. As soon as the matching items will fit, they are displayed as normal. choose from Term::Choose skips - when scrolling and reaching the end (resp. the begin) of the screen - to the next (resp. previous) page.
Strings where the number of characters are not equal to the number of columns on the screen break the output from Term::Clui and Term::Choose. Term::Choose::GC tries to get along with such situations - see "BUGS AND LIMITATIONS".
Term::Clui's choose prints and returns the chosen items, while choose from Term::Choose only returns the chosen items.
Only in Term::Clui:
Term::Clui provides a speaking interface, offers a bundle of functions and has a fallback to work when only Perl core modules are available.
The choose function from Term::Clui can remember choices made in scalar context and allows multiline question - the first line is put on the top, the subsequent lines are displayed below the list.
These differences refer to Term::Clui version 1.65. For a more precise description of Term::Clui consult its own documentation.
Nothing by default.
use Term::Choose qw(choose);
$scalar = choose( $array_ref [, \%options] ); @array = choose( $array_ref [, \%options] ); choose( $array_ref [, \%options] );
choose expects as first argument an array reference which passes the list elements available for selection (in void context no selection can be made).
Options can be passed with a hash reference as a second (optional) argument.
If choose is called in a scalar context, the user can choose an item by using the "move-around-keys" and "Return".
choose then returns the chosen item.
If choose is called in an list context, the user can also mark an item with the "SpaceBar".
choose then returns the list of marked items, (including the item highlight when "Return" was pressed).
If choose is called in an void context, the user can move around but mark nothing; the output shown by choose can be closed with "Return".
choose then returns nothing.
If the items of the list don't fit in the screen, the user can scroll to the next (previous) page(s).
If the window size is changed, then as soon as the user enters a keystroke choose rewrites the screen. In list context marked items are reset.
The "q" key returns undef or an empty list in list context.
With a mouse_mode enabled (and if supported by the terminal) the element can be chosen with the left mouse key, in list context the right mouse key can be used instead the "SpaceBar" key.
If the option extra_key is enabled pressing "e" calls exit().
Keys to move around: arrow keys (or hjkl), Tab, BackSpace, Shift-Tab.
For the output on the screen the list elements are modified:
if a list element is not defined the value from the option undef is assigned to the element.
if a list element holds an empty string the value from the option empty_string is assigned to the element.
spaces in list elements are replace with simple spaces.
$element =~ s/\p{Space}/ /g;
control characters are removed.
$element =~ s/\p{Cntrl}//g;
if the length of a list element is greater than the width of the screen the element is cut.
$element = substr( $element, 0, $allowed_length - 3 ) . '...';
All these modifications are made on a copy of the original list so choose returns the chosen elements as they were passed to the function without modifications.
All options are optional.
Defaults may change in a future release.
If prompt is undefined default prompt-string will be shown.
If prompt is 0 no prompt-line will be shown.
default in list and scalar context: 'Your choice:'
default in void context: 'Close with ENTER'
0 - columns are left justified (default)
1 - columns are right justified
0 - layout off
.----------------------. .----------------------. .----------------------. .----------------------. | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | '----------------------' '----------------------' '----------------------' '----------------------'
1 - layout "H" (default)
.----------------------. .----------------------. .----------------------. .----------------------. | .. .. .. .. .. .. .. | | .. .. .. .. | | .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. .. .. | | .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. | | .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | '----------------------' '----------------------' '----------------------' '----------------------'
2 - all in a single column
.----------------------. .----------------------. .----------------------. .----------------------. | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | | | .. | | .. | | .. | | | | | | .. | | .. | | | | | | | | .. | '----------------------' '----------------------' '----------------------' '----------------------'
3 - layout "V"
.----------------------. .----------------------. .----------------------. .----------------------. | .. | | .. .. | | .. .. .. | | .. .. .. .. .. .. .. | | .. | | .. .. | | .. .. .. | | .. .. .. .. .. .. .. | | .. | | .. .. | | .. .. .. | | .. .. .. .. .. .. .. | | .. | | .. | | .. .. .. | | .. .. .. .. .. .. .. | | .. | | | | .. .. | | .. .. .. .. .. .. .. | | .. | | | | | | .. .. .. .. .. .. .. | '----------------------' '----------------------' '----------------------' '----------------------'
If set, restricts the screen width to screen_width percentage of the effective screen width.
If not defined all the screen width is used.
Allowed values: 10 - 99
(default: undef)
0 - items ordered horizontally
1 - items ordered vertically (default)
0 - off (default)
1 - clears the screen before printing the choices
0 - no mouse mode (default)
1 - mouse mode 1003 enabled
2 - mouse mode 1003 enabled; maxcols/maxrows limited to 224 (mouse mode 1003 doesn't work above 224)
3 - extended mouse mode (1005) - uses utf8
4 - extended SGR mouse mode (1006); mouse mode 1003 if mouse mode 1006 is not supported
space between columns (default: 2)
allowed values: 0 - 99
space between items if we have only one row (default: 3)
0 - off
1 - on: pressing key "e" calls exit() (default)
1 - on
1 - on (default)
string displayed on the screen instead a undefined list element
default: '<undef>'
string displayed on the screen instead an empty string
default: '<empty>'
maximal allowed length of the list referred by the first argument (default: 100_000)
allowed values: 1 - 999_999_999
With no arguments choose dies.
If the first argument is not a array reference choose dies.
If the list referred by the first argument is empty choose returns undef resp. an empty list and issues a warning.
If the list referred by the first argument has more than max_list items (default 100_000) choose warns and uses the first max_list list items.
If the (optional) second argument is not a hash reference choose dies.
If an option does not exist choose warns.
If an option value is not valid choose warns an falls back to the default value.
Used modules not provided as core modules:
Signals::XSIG
Term::ReadKey
The Terminal needs to understand the following ANSI escape sequences:
"\e[A" Cursor Up "\e[C" Cursor Forward "\e[0J" Clear to End of Screen (Erase Data) "\e[0m" Normal/Reset (SGR) "\e[1m" Bold (SGR) "\e[4m" Underline (SGR) "\e[7m" Inverse (SGR)
If option "hide_cursor" is enabled:
"\e[?25l" Hide Cursor (DECTCEM) "\e[?25h" Show Cursor (DECTCEM)
If option "clear_screen" is enabled:
"\e[2J" Clear Screen (Erase Data) "\e[1;1H" Go to Top Left (Cursor Position)
If option "mouse_mode" is set:
"\e[6n" Get Cursor Position (Device Status Report)
Mouse Tracking: The escape sequences
"\e[?1003h", "\e[?1005h", "\e[?1006h"
and
"\e[?1003l", "\e[?1005l", "\e[?1006l"
are used to enable/disable the different mouse modes.
This modules uses the Perl builtin functions length to determine the length of strings, substr to cut strings and sprintf widths to justify strings. Therefore strings with characters that take more or less than one print column will break the layout. Using Term::Choose::GC instead improves the layout in such conditions. It determines the string length by using the columns method from Unicode::GCString module.
use Term::Choose:GC qw(choose);
Usage and options are the same as for Term::Choose.
The use of Term::Choose::GC needs additionally the Unicode::GCString module to be installed.
Known drawbacks:
Term::Choose::GC's choose is probably slower than choose from Term::Choose.
You can find documentation for this module with the perldoc command.
perldoc Term::Choose
Kürbis cuer2s@gmail.com
Based on and inspired by the choose function from Term::Clui module.
Thanks to the http://www.perl-community.de and the people form http://stackoverflow.com for the help.
Copyright 2012 Kürbis.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Term::Choose, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Term::Choose
CPAN shell
perl -MCPAN -e shell install Term::Choose
For more information on module installation, please visit the detailed CPAN module installation guide.