Term::Choose - Choose items from a list.
Version 1.045
use 5.10.0;
use Term::Choose qw(choose);
my $array_ref = [ qw( one two three four five ) ];
my $choice = choose( $array_ref ); # single choice
say $choice;
my @choices = choose( [ 1 .. 100 ], { justify => 1 } ); # multiple choice
say "@choices";
choose( [ 'Press ENTER to continue' ], { prompt => '' } ); # no choice
Choose from a list of items.
Based on the choose function from the Term::Clui module - for more details see "MOTIVATION".
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 a first argument an array reference. The array the reference refers to holds the list items available for selection (in void context no selection can be made).
The array the reference - passed with the first argument - refers to is called in the documentation simply array or list resp. elements (of the array).
Options can be passed with a hash reference as a second (optional) argument.
choose then returns the chosen item.
choose then returns - when "Return" is pressed - the list of marked items including the highlighted item.
In list context "Ctrl-SpaceBar" inverts the choices: marked items are unmarked and unmarked items are marked.
Called in void context choose returns nothing.
If the items of the list don't fit on 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 (or Ctrl-D) returns undef or an empty list in list context.
With a mouse mode enabled (and if supported by the terminal) the item can be chosen with the left mouse key, in list context the right mouse key can be used instead the "SpaceBar" key.
For the output on the screen the array elements are modified:
$element =~ s/\p{Space}/ /g;
$element =~ s/\P{Print}/\x{fffd}/g;
$element = substr( $element, 0, $allowed_length - 3 ) . '...';*
* Term::Choose uses its own function to cut strings which uses print columns for the arithmetic.
All these modifications are made on a copy of the original array so choose returns the chosen elements as they were passed to the function without modifications.
Options which expect a number as their value expect integers.
There is a general upper limit of one billion for options which expect a number as their value and where no upper limit is mentioned.
If prompt is undefined a default prompt-string will be shown.
If the prompt value is an empty string ("") no prompt-line will be shown.
default in list and scalar context: 'Your choice:'
default in void context: 'Close with ENTER'
From broad to narrow: 0 > 1 > 2 > 3
.----------------------. .----------------------. .----------------------. .----------------------. | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | '----------------------' '----------------------' '----------------------' '----------------------'
.----------------------. .----------------------. .----------------------. .----------------------. | .. .. .. .. .. .. .. | | .. .. .. .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. .. .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | '----------------------' '----------------------' '----------------------' '----------------------'
.----------------------. .----------------------. .----------------------. .----------------------. | .. | | .. .. | | .. .. .. .. | | .. .. .. .. .. .. .. | | .. | | .. .. | | .. .. .. .. | | .. .. .. .. .. .. .. | | .. | | .. .. | | .. .. .. .. | | .. .. .. .. .. .. .. | | .. | | .. | | .. .. .. | | .. .. .. .. .. .. .. | | .. | | | | .. .. .. | | .. .. .. .. .. .. .. | | .. | | | | | | .. .. .. .. .. .. .. | '----------------------' '----------------------' '----------------------' '----------------------'
.----------------------. .----------------------. .----------------------. .----------------------. | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | | | .. | | .. | | .. | | | | | | .. | | .. | | | | | | | | .. | '----------------------' '----------------------' '----------------------' '----------------------'
If set, restricts the screen width to the integer value of screen_width percentage of the effective screen width.
If the integer value of screen_width percentage of the screen width is zero the virtual screen width is set to one screen column.
If not defined all the screen width is used.
Allowed values: from 1 to 100
(default: undef)
If the output has more than one row and more than one column:
0 - elements are ordered horizontally
1 - elements are ordered vertically (default)
Default may change in a future release.
0 - elements ordered in columns are left justified (default)
1 - elements ordered in columns are right justified
2 - elements ordered in columns are centered
Sets the number of whitespaces between columns. (default: 2)
Allowed values: 0 or greater
Sets the number of whitespaces between elements if we have only one row. (default: value of the option pad)
Allowed values: 0 or greater
0 - off (default)
1 - clears the screen before printing the choices
With the option default can be selected an element, which will be highlighted as the default instead of the first element.
default expects a zero indexed value, so e.g. to highlight the third element the value would be 2.
If the passed value is greater than the index of the last array element the first element is highlighted.
Allowed values: 0 or greater
(default: undef)
0 - off (default)
1 - return the index of the chosen element instead of the chosen element resp. the indices of the chosen elements instead of the chosen elements.
0 - off
1 - print the page number on the bottom of the screen if there is more then one page. (default)
0 - no mouse mode (default)
1 - mouse mode 1003 enabled
2 - mouse mode 1003 enabled; maxcols/maxrows limited to 223 (mouse mode 1003 doesn't work above 223)
3 - extended mouse mode (1005) - uses utf8
4 - extended SGR mouse mode (1006)
0 - off (default)
1 - on
0 - keep the terminals highlighting of the cursor position
1 - hide the terminals highlighting of the cursor position (default)
Sets the maximal allowed length of the array. (default: 100_000)
Allowed values: 1 or greater
Sets the string displayed on the screen instead an undefined element.
default: '<undef>'
Sets the string displayed on the screen instead an empty string.
default: '<empty>'
Use head instead.
This option is experimental.
Reduces the available terminal rows by head rows.
This means that choose doesn't overwrite the head lines above the choose output.
Allowed values: 0 or greater
(default: undef)
This option is experimental.
If the length of the element with the largest length is known before calling choose it can be passed with this option.
If ll (two lowercase L) is set, then choose doesn't calculate the length of the longest element itself but uses the value passed with this option.
length refers here to the number of print columns the element will use on the terminal.
A way to determine the number of print columns is the use of columns from Unicode::GCString.
Calculating the largest length by using the number of bytes or the number of characters of the strings instead of using the number of print columns could break the output.
The length of undefined elements and elements with an empty string depends on the value of the option undef resp. on the value of the option empty.
If the option ll is set the elements must be upgraded with utf8::upgrade or with an equivalent tool and not contain any non-printing character (\P{Print}).
The upgrade with utf8::upgrade is needed because a limitation of Unicode::GCString (Bug #84661).
If ll is set to a value less than the length of the longest element all elements with a length greater than this value will be cut.
A larger value than the length of the longest element wastes space on the screen.
If the value of ll is greater than the screen width ll will be set to the screen width.
Allowed values: 1 or greater
(default: undef)
Requires Perl Version 5.10.0 or greater.
Used modules not provided as core modules:
choose expects decoded strings as array elements.
It is needed a terminal that uses a monospaced font.
Term::Choose makes use of the Perl signal handling as described in perlipc/Signals. It is needed an operating system which knows the WINCH signal: choose uses SIGWINCH to check if the windows size has changed.
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
"\e[1m" Bold
"\e[4m" Underline
"\e[7m" Inverse
If the option "hide_cursor" is enabled:
"\e[?25l" Hide Cursor
"\e[?25h" Show Cursor
If the option "clear_screen" is enabled:
"\e[2J" Clear Screen (Erase Data)
"\e[1;1H" Go to Top Left (Cursor Position)
If a "mouse" mode is enabled:
"\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.
The reason for writing Term::Choose was to get something like Term::Clui::choose but with a nicer output in the case the list doesn't fit in one row.
If the list does not fit in one row, choose from Term::Clui puts the items on the screen without ordering the items in columns. Term::Choose arranges the items in columns which makes it easier for me to find items and easier to navigate on the screen.
Term::Clui's choose expects a question as the first argument, and then the list of items. With Term::Choose the available choices are passed with an array reference as first argument. Options can be passed with a hash reference as an optional second argument. The question can be passed with the option prompt.
As mentioned above choose from Term::Clui does not order the elements in columns if there is more than one row on the screen while Term::Choose arranges the elements in such situations in columns.
Another difference is how lists which don't fit 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 with characters where length(character)* is not equal to the number of print columns of the respective character might break the output from Term::Clui. To make Term::Choose's choose function work with such kind of Unicode strings it uses the method columns from Unicode::GCString to determine the string length.
* Perl builtin function length.
Term::Clui's choose prints and returns the chosen items while choose from Term::Choose only returns the chosen items.
Term::Clui disables the mouse mode if the environment variable CLUI_MOUSE is set to off. In Term::Choose the mouse mode is set with the option mouse.
Term::Clui provides a speaking interface, offers a bundle of command-line related 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.66. For a more precise description of Term::Clui consult its own documentation.
You can find documentation for this module with the perldoc command.
perldoc Term::Choose
Matthäus Kiem <cuer2s@gmail.com>
Based on and inspired by the choose function from the Term::Clui module.
Thanks to the Perl-Community.de and the people form stackoverflow for the help.
Copyright 2012-2013 Matthäus Kiem.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
