Term::Choose - Choose items from a list interactively.
Version 1.762
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 ], { alignment => 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"; 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".
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. Before leaving choose restores the overwritten options.
new
$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 if the option include_highlighted is set to 1).
1
In list context Ctrl-SpaceBar (or Ctrl-@) inverts the choices: marked items are unmarked and unmarked items are marked.
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-Q) is pressed.
undef
q
Ctrl-Q
If the mouse mode is enabled, an item can be chosen with the left mouse key, in list context the right mouse key can be used instead the SpaceBar key.
Pressing the Ctrl-F allows one to enter a regular expression so that only the items that match the regular expression are displayed. When going back to the unfiltered menu (Enter) the item highlighted in the filtered menu keeps the highlighting. Also (in list context) marked items retain there markings. The Perl function readline is used to read the regular expression if Term::Form::ReadLine is not available. See option search.
Ctrl-F
Enter
readline
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-P) to go to the previous page, the PageDown key (or Ctrl-N) to go to the next page,
PageUp
Ctrl-P
PageDown
Ctrl-N
the Insert key to go back 10 pages, the Delete key to go forward 10 pages,
Insert
Delete
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.
Tab characters in elements are replaces with a space.
$element =~ s/\t/ /g;
Vertical spaces in elements are squashed to two spaces.
$element =~ s/\v+/\ \ /g;
Code points from the ranges of control, surrogate and noncharacter are removed.
$element =~ s/[\p{Cc}\p{Noncharacter_Code_Point}\p{Cs}]//g;
If the length of an element is greater than the width of the screen the element is cut and at the end of the string are added three dots.
Options which expect a number as their value expect integers.
0 - elements ordered in columns are aligned to the left (default)
1 - elements ordered in columns are aligned to the right
2 - elements ordered in columns are centered
0 - off (default)
1 - on
1 - clears the screen before printing the choices
This option has only meaning if the operating system is MSWin32.
If the OS is MSWin32, Win32::Console::ANSI is used. By default Win32::Console::ANSI converts the characters from Windows code page to DOS code page (the so-called ANSI to OEM conversion). This conversation is disabled by default in Term::Choose but one can enable it by setting this option.
Win32::Console::ANSI
Setting this option to 1 enables the codepage mapping offered by Win32::Console::ANSI.
0 - disable automatic codepage mapping (default)
1 - keep automatic codepage mapping
Enable the support for ANSI SGR escape sequences.
1 - enabled but the current selected element is not colored.
2 - enabled
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>")
Add a string in the bottom line.
If a footer string is passed with this option, the option page is automatically set to 2.
2
0 - keep the terminals highlighting of the cursor position
1 - hide the terminals highlighting of the cursor position (default)
Expects as its value a string. The info text is printed above the prompt string.
(default: not set)
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.
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)
0 - layout off
.----------------------. .----------------------. .----------------------. .----------------------. | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | '----------------------' '----------------------' '----------------------' '----------------------'
1 - default
.----------------------. .----------------------. .----------------------. .----------------------. | .. .. .. .. .. .. .. | | .. .. .. .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. .. .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | | | | | .. .. .. | | .. .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. .. | '----------------------' '----------------------' '----------------------' '----------------------'
2 - all in a single column
.----------------------. .----------------------. .----------------------. .----------------------. | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | | | .. | | .. | | .. | | | | | | .. | | .. | | | | | | | | .. | '----------------------' '----------------------' '----------------------' '----------------------'
If layout is set to 0 or 1 and the unformatted list items fit in one row, the list items are placed in one row without column formatting. This behavior can be disabled by setting max_cols.
0
If all elements have the same length, the length can be passed with this option. choose then doesn't calculate the length of the longest element itself but uses the passed value. length refers here to the number of print columns the element will use on the terminal.
If ll is set, choose returns always the index(es) of the chosen item(s) regardless of how index is set.
Undefined list elements are not allowed.
The replacements described in "Modifications for the output" are not applied. If elements contain unsupported characters the output might break.
If ll is set to a value less than the length of the elements, the output could break.
If ll is set and the window size has changed, choose returns immediately -1.
-1
The option margin allows one to set a margin on all four sides.
margin expects a reference to an array with four elements in the following order:
- top margin (number of terminal lines)
- right margin (number of terminal columns)
- botton margin (number of terminal lines)
- left margin (number of terminal columns)
margin does not affect the info and prompt string. To add margins to the info and prompt string see tabs_info and tabs_prompt.
Allowed values: 0 or greater. Elements beyond the fourth are ignored.
Limit the number of columns to max_cols.
layout set to 2 has always one column.
If defined sets the maximal number of rows used for printing list items.
If the available height is less than max_height then max_height is set to the available height.
Height in this context means print rows.
max_height overwrites keep if max_height is set to a value 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.
1 - on. Enables the Any-Event-Mouse-Mode (1003) and the Extended-SGR-Mouse-Mode (1006).
If the option mouse 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 the mouse is enabled with the help of Win32::Console.
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)
0 - off
1 - print the page number on the bottom of the screen. If all the choices fit into one page, the page number is not displayed. (default)
2 - the page number is always displayed even with only one page. Setting page to 2 automatically enables the option clear_screen.
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
Set the behavior of Ctrl-F.
1 - case-insensitive search (default)
2 - case-sensitive search
When navigating through the list, the elements that match the regex pattern passed with this option will be skipped.
In list context: these elements cannot be marked.
Expected value: a regex quoted with the qr operator.
qr
The option tabs_info allows one to insert spaces at the beginning and the end of info lines.
tabs_info expects a reference to an array with one to three elements:
- the first element (initial tab) sets the number of spaces inserted at beginning of paragraphs
- the second element (subsequent tab) sets the number of spaces inserted at the beginning of all broken lines apart from the beginning of paragraphs
- the third element sets the number of spaces used as a right margin.
Allowed values: 0 or greater. Elements beyond the third are ignored.
default: If margin is defined, the initial tab and the subsequent tab are set to left-margin and the right margin is set to right-margin. If margin is not defined, the default is undefined.
The option tabs_prompt allows one to insert spaces at the beginning and the end of prompt lines.
tabs_prompt expects a reference to an array with one to three elements:
Sets the string displayed on the screen instead an undefined element.
default: "<undef>"
In list context when Return is pressed
0 - choose returns the items marked with the SpaceBar. (default)
1 - choose returns the items marked with the SpaceBar plus the highlighted item.
2 - choose returns the items marked with the SpaceBar. If no items are marked with the SpaceBar, the highlighted item is returned.
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.
Elements greater than the last index of the list are ignored.
This option has only meaning in list context.
meta_items expects as its value a reference to an array. The elements of the array are list indexes. These elements can not be marked with the SpaceBar or with the right mouse key but if one of these elements is the highlighted item it is added to the chosen items when Return is pressed.
no_spacebar expects as its value a reference to an array. The elements of the array are indexes of the list which should not be markable with the SpaceBar or with the right mouse key.
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.
no_spacebar elements greater than the last index of the list are ignored.
new|choose croaks if passed invalid arguments.
new|choose
If pressing a key results in an undefined value choose carps with EOT: $! and returns undef or an empty list in list context.
EOT: $!
Requires Perl version 5.10.0 or greater.
If Term::ReadKey is available it is used ReadKey to read the user input and GetTerminalSize to get the terminal size. Without Term::ReadKey getc is used to read the input and stty size to get the terminal size.
ReadKey
GetTerminalSize
Term::ReadKey
getc
stty size
If the OS is MSWin32 it is used Win32::Console to read the user input and to get the terminal size.
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.
By default ambiguous width characters are treated as half width. If the environment variable TC_AMBIGUOUS_WIDE is set to a true value, ambiguous width characters are treated as full width.
TC_AMBIGUOUS_WIDE
By default Term::Choose uses tput to get the appropriate escape sequences. If the environment variable TC_ANSI_ESCAPES is set to a true value, hardcoded ANSI escape sequences are used directly without calling tput.
tput
TC_ANSI_ESCAPES
The escape sequences to enable the mouse mode are always hardcoded.
If the environment variable TC_RESET_AUTO_UP existed when calling choose: TC_RESET_AUTO_UP is set to 0 if the LINE_FEED/CARRIAGE_RETURN key was the only key pressed and TC_RESET_AUTO_UP is set ot 1 if other keys than LINE_FEED/CARRIAGE_RETURN were also pressed.
TC_RESET_AUTO_UP
LINE_FEED
CARRIAGE_RETURN
If the OS is MSWin32 Win32::Console and Win32::Console::ANSI with ANSI escape sequences are used. See also "codepage_mapping".
You can find documentation for this module with the perldoc command.
perldoc Term::Choose
Matthäus Kiem <cuer2s@gmail.com>
Based on 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-2023 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.