Term::Choose - Choose items from a list interactively.
Version 1.200
Functional interface:
use Term::Choose qw( choose ); my $array_ref = [ qw( one two three four five ) ]; my $choice = choose( $array_ref ); # single choice print "$choice\n"; my @choices = choose( [ 1 .. 100 ], { justify => 1 } ); # multiple choice print "@choices\n"; choose( [ 'Press ENTER to continue' ], { prompt => '' } ); # no choice
Object-oriented interface:
use Term::Choose; my $array_ref = [ qw( one two three four five ) ]; my $new = Term::Choose->new(); my $choice = $new->choose( $array_ref ); # single choice print "$choice\n"; $new->config( { justify => 1 } ); my @choices = $new->choose( [ 1 .. 100 ] ); # multiple choice print "@choices\n"; my $stopp = Term::Choose->new( { prompt => '' } ); $stopp->choose( [ 'Press ENTER to continue' ] ); # no choice
Choose interactively from a list of items.
Term::Choose provides a functional interface ("SUBROUTINES") and an object-oriented interface ("METHODS").
Term::Choose
Nothing by default.
use Term::Choose qw( choose );
$new = Term::Choose->new( [ \%options] );
This constructor returns a new Term::Choose object.
To set the different options it can be passed a reference to a hash as an optional argument.
For detailed information about the options see "OPTIONS".
$new->config( \%options );
The config method is meant to set the different options. The options are passed as a hash reference.
config
Options set with config overwrite options set with the new method.
new
For detailed information about the different options, their allowed and default values see "OPTIONS".
The method choose allows the user to choose from a list.
choose
The first argument is an array reference which holds the list of the available choices.
As a second and optional argument it can be passed a reference to a hash where the keys are the option names and the values the option values.
Options set with choose overwrite options set with new or config. Before leaving choose restores the overwritten options.
$choice = $new->choose( $array_ref [, \%options] ); @choices= $new->choose( $array_ref [, \%options] ); $new->choose( $array_ref [, \%options] );
When in the documentation is mentioned "array" or "list" or "elements" or "items" (of the array/list) than these refer to this array passed as a reference as the first argument.
For more information how to use choose and its return values see "USAGE AND RETURN VALUES".
The function choose allows the user to choose from a list. It takes the same arguments as the method "choose".
$choice = choose( $array_ref [, \%options] ); @choices= choose( $array_ref [, \%options] ); choose( $array_ref [, \%options] );
See the "OPTIONS" section for more details about the different options and how to set them.
See also the following section "USAGE AND RETURN VALUES".
If choose is called in a scalar context, the user can choose an item by using the "Keys to move around" and confirming with Return.
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.
SpaceBar
choose then returns - when Return is pressed - the list of marked items including the highlighted item.
In list context Ctrl-SpaceBar (or Ctrl-@) inverts the choices: marked items are unmarked and unmarked items are marked. If the cursor is on the first row, Ctrl-SpaceBar inverts the choices for the whole list else Ctrl-SpaceBar inverts the choices for the current page.
Ctrl-SpaceBar
Ctrl-@
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.
Called in void context choose returns nothing.
If the first argument refers to an empty array, 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.
choose returns undef or an empty list in list context if the q key (or Ctrl-D) is pressed.
undef
q
Ctrl-D
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.
the Arrow keys (or the h,j,k,l keys) to move up and down or to move to the right and to the left,
Arrow
h,j,k,l
the Tab key (or Ctrl-I) to move forward, the BackSpace key (or Ctrl-H or Shift-Tab) to move backward,
Tab
Ctrl-I
BackSpace
Ctrl-H
Shift-Tab
the PageUp key (or Ctrl-B) to go back one page, the PageDown key (or Ctrl-F) to go forward one page,
PageUp
Ctrl-B
PageDown
Ctrl-F
the Home key (or Ctrl-A) to jump to the beginning of the list, the End key (or Ctrl-E) to jump to the end of the list.
Home
Ctrl-A
End
Ctrl-E
For the output on the screen the array elements are modified.
All the 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.
Modifications:
If an element is not defined the value from the option undef is assigned to the element.
If an element holds an empty string the value from the option empty is assigned to the element.
White-spaces in elements are replaced with simple spaces.
$element =~ s/\p{Space}/ /g;
If the length of an element is greater than the width of the screen the element is cut.
$element = substr( $element, 0, $allowed_length - 3 ) . '...';*
* Term::Choose uses its own function to cut strings which uses columns from Unicode::GCString to determine the string length.
columns
The following should be without meaning if you comply with the requirements.
Characters which match the Unicode character property Other are removed.
Other
$element =~ s/\p{C}//g;
If an element is a reference it will be replaced with a string: the reference type followed with the hexadecimal value of the reference enclosed in parentheses.
if ( ref $element ) { $element = sprintf "%s(0x%x)", ref $element, $element; }
The category of utf8 warnings is disabled.
utf8
warnings
no warnings 'utf8';
Options which expect a number as their value expect integers.
0 - off (default)
1 - on
1 - clears the screen before printing the choices
With the option default it 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: undefined)
Sets the string displayed on the screen instead an empty string.
default: "<empty>"
0 - keep the terminals highlighting of the cursor position
1 - hide the terminals highlighting of the cursor position (default)
1 - return the index of the chosen element instead of the chosen element respective the indices of the chosen elements instead of the chosen elements.
0 - elements ordered in columns are left justified (default)
1 - elements ordered in columns are right justified
2 - elements ordered in columns are centered
keep prevents that all the terminal rows are used by the prompt lines.
Setting keep ensures that at least keep terminal rows are available for printing list rows.
If the terminal height is less than keep keep is set to the terminal height.
Allowed values: 1 or greater
(default: 5)
From broad to narrow: 0 > 1 > 2 > 3
0 - layout off
.----------------------. .----------------------. .----------------------. .----------------------. | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | '----------------------' '----------------------' '----------------------' '----------------------'
1 - layout "H" (default)
.----------------------. .----------------------. .----------------------. .----------------------. | .. .. .. .. .. .. .. | | .. .. .. .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. .. .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | '----------------------' '----------------------' '----------------------' '----------------------'
2 - layout "V"
.----------------------. .----------------------. .----------------------. .----------------------. | .. .. | | .. .. .. | | .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. | | .. .. .. | | .. .. .. .. | | .. .. .. .. .. .. .. | | .. | | .. .. .. | | .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. | | .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | '----------------------' '----------------------' '----------------------' '----------------------'
3 - all in a single column
.----------------------. .----------------------. .----------------------. .----------------------. | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | | | .. | | .. | | .. | | | | | | .. | | .. | | | | | | | | .. | '----------------------' '----------------------' '----------------------' '----------------------'
If prompt lines are folded the option lf allows to insert spaces at beginning of the folded lines.
The option lf expects a reference to an array with one or two elements:
- the first element (INITIAL_TAB) sets the number of spaces inserted at beginning of paragraphs
INITIAL_TAB
- a second element (SUBSEQUENT_TAB) sets the number of spaces inserted at the beginning of all broken lines apart from the beginning of paragraphs
SUBSEQUENT_TAB
Allowed values for the two elements are: 0 or greater.
See INITIAL_TAB and SUBSEQUENT_TAB in Text::LineFold.
If all elements have the same length and this length is known before calling choose the length can be passed with this option.
If ll 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.
The length of undefined elements and elements with an empty string depends on the value of the option undef respective on the value of the option empty.
If the option ll is set the replacements described in "Modifications for the output" are not applied.
If elements contain unsupported characters the output might break if the width (number of print columns) of the replacement character does not correspond to the width of the replaced character - for example when a unsupported non-spacing character is replaced by a replacement character with a normal width.
If ll is set to a value less than the length of the elements the output could break.
If the value of ll is greater than the screen width the elements will be trimmed to fit into the screen.
mark expects as its value a reference to an array. The elements of the array are list indexes. choose preselects the list-elements correlating to these indexes. This option has only meaning in list context.
If defined sets the maximal number of rows used for printing list items.
If the available height is less than max_height max_height is set to the available height.
Height in this context means print rows.
max_height overwrites keep if max_height is set and less than keep.
If defined, sets the maximal output width to max_width if the terminal width is greater than max_width.
To prevent the "auto-format" to use a width less than max_width set layout to 0.
Width refers here to the number of print columns.
For MSWin32 see also the end of this section.
0 - no mouse mode (default)
1 - mouse mode 1003 enabled
2 - mouse mode 1003 enabled; the output width is limited to 223 print-columns and the height to 223 rows (mouse mode 1003 doesn't work above 223)
3 - extended mouse mode (1005) - uses utf8
4 - extended SGR mouse mode (1006)
If a mouse mode is enabled layers for STDIN are changed. Then before leaving choose as a cleanup STDIN is marked as UTF-8 with :encoding(UTF-8). This doesn't apply if the OS is MSWin32.
STDIN
UTF-8
:encoding(UTF-8)
If the OS is MSWin32 there is no difference between the mouse modes 1, 3, and 4 - the all enable the mouse with the help of Win32::Console.
no_spacebar expects as its value a reference to an array. The elements of the array are indexes of choices which should not be markable with the SpaceBar or with the right mouse key. This option has only meaning in list context. If an element is preselected with the option mark and also marked as not selectable with the option no_spacebar, the user can not remove the preselection of this element.
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.
Sets the number of whitespaces between columns. (default: 2)
Sets the number of whitespaces between elements if we have only one row. (default: value of the option pad)
0 - off
1 - print the page number on the bottom of the screen if there is more then one page. (default)
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:
Your choice:
default in void context: Close with ENTER
Close with ENTER
Sets the string displayed on the screen instead an undefined element.
default: "<undef>"
new|config|choose dies if
new|config|choose
passed an invalid number of arguments.
passed an invalid argument.
passed an invalid option name.
passed an invalid option value.
If after pressing a key Term::ReadKey::ReadKey returns undef choose warns with EOT: $! and returns undef or an empty list in list context.
EOT: $!
Requires Perl version 5.8.3 or greater.
Used modules not provided as core modules:
Text::LineFold
Unicode::GCString
Additionally, if the OS is MSWin32
Win32::Console
is required. Else
Term::ReadKey
is additionally required.
choose expects decoded strings as array elements.
For a correct output it is required an appropriate encoding layer for STDOUT matching the terminal's character set.
It is required a terminal that uses a monospaced font which supports the printed characters.
The following ANSI escape sequences are used:
"\e[A" Cursor Up "\e[C" Cursor Forward "\e[D" Cursor Back "\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 the OS is MSWin32 Win32::Console is used, to emulate these escape sequences.
If a mouse mode is enabled
"\e[6n" Get Cursor Position (Device Status Report) "\e[?1003h", "\e[?1005h", "\e[?1006h" Enable Mouse Tracking "\e[?1003l", "\e[?1005l", "\e[?1006l" Disable Mouse Tracking
are used to enable/disable the different mouse modes.
To read key and mouse events with an MSWin32 OS Win32::Console is used instead.
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 (C) 2012-2015 Matthäus Kiem.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For details, see the full text of the licenses in the file LICENSE.
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.