Provided by: libterm-choose-perl_1.511-1_all 
NAME
Term::Choose - Choose items from a list interactively.
VERSION
Version 1.511
SYNOPSIS
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";
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
DESCRIPTION
Choose interactively from a list of items.
"Term::Choose" provides a functional interface ("SUBROUTINES") and an object-oriented
interface ("METHODS").
EXPORT
Nothing by default.
use Term::Choose qw( choose );
METHODS
new
$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".
config DEPRECATED
$new->config( \%options );
The "config" method is meant to set the different options. The options are passed as a
hash reference.
Options set with "config" overwrite options set with the "new" method.
For detailed information about the different options, their allowed and default values see
"OPTIONS".
choose
The method "choose" allows the user to choose from a list.
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".
SUBROUTINES
choose
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".
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".
"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 - 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.
• 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.
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.
Keys to move around
• 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,
• the "Tab" key (or "Ctrl-I") to move forward, the "BackSpace" key (or "Ctrl-H" or
"Shift-Tab") to move backward,
• the "PageUp" key (or "Ctrl-B") to go back one page, the "PageDown" key (or "Ctrl-F")
to go forward one page,
• 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.
Modifications for the output
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 ) . '...';*
* It is used a function to cut strings which uses "columns" from Unicode::GCString to
determine the string length.
The following should be without meaning if you comply with the requirements.
• Characters which match the Unicode character property "Other" are removed.
$element =~ s/\p{C}//g;
"ESC" characters are removed by this substitution so it is not possible to color the
output with ANSI escape sequences. For colored output see Term::Choose_HAE.
• 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.
no warnings 'utf8';
OPTIONS
Options which expect a number as their value expect integers.
beep
0 - off (default)
1 - on
clear_screen
0 - off (default)
1 - clears the screen before printing the choices
default
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)
empty
Sets the string displayed on the screen instead an empty string.
default: "<empty>"
hide_cursor
0 - keep the terminals highlighting of the cursor position
1 - hide the terminals highlighting of the cursor position (default)
index
0 - off (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.
justify
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
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)
layout
From broad to narrow: 0 > 1 > 2 > 3
• 0 - layout off
.----------------------. .----------------------. .----------------------. .----------------------.
| .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. |
| | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. | | .. .. .. .. .. .. .. |
| | | | | .. .. .. .. .. | | .. .. .. .. .. .. .. |
| | | | | | | .. .. .. .. .. .. .. |
| | | | | | | .. .. .. .. .. .. .. |
| | | | | | | .. .. .. .. .. .. .. |
'----------------------' '----------------------' '----------------------' '----------------------'
• 1 - layout "H" (default)
.----------------------. .----------------------. .----------------------. .----------------------.
| .. .. .. .. .. .. .. | | .. .. .. .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. |
| | | .. .. .. .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. |
| | | .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. |
| | | | | .. .. .. .. .. .. | | .. .. .. .. .. .. .. |
| | | | | .. .. .. | | .. .. .. .. .. .. .. |
| | | | | | | .. .. .. .. .. .. .. |
'----------------------' '----------------------' '----------------------' '----------------------'
• 2 - layout "V"
.----------------------. .----------------------. .----------------------. .----------------------.
| .. .. | | .. .. .. | | .. .. .. .. | | .. .. .. .. .. .. .. |
| .. .. | | .. .. .. | | .. .. .. .. | | .. .. .. .. .. .. .. |
| .. | | .. .. .. | | .. .. .. .. | | .. .. .. .. .. .. .. |
| | | .. .. | | .. .. .. | | .. .. .. .. .. .. .. |
| | | | | .. .. .. | | .. .. .. .. .. .. .. |
| | | | | | | .. .. .. .. .. .. .. |
'----------------------' '----------------------' '----------------------' '----------------------'
• 3 - all in a single column
.----------------------. .----------------------. .----------------------. .----------------------.
| .. | | .. | | .. | | .. |
| .. | | .. | | .. | | .. |
| .. | | .. | | .. | | .. |
| | | .. | | .. | | .. |
| | | | | .. | | .. |
| | | | | | | .. |
'----------------------' '----------------------' '----------------------' '----------------------'
lf
If prompt lines are folded the option lf allows one 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
- a second element ("SUBSEQUENT_TAB") sets the number of spaces inserted at the beginning
of all broken lines apart from the beginning of paragraphs
Allowed values for the two elements are: 0 or greater.
See "INITIAL_TAB" and "SUBSEQUENT_TAB" in Text::LineFold.
(default: undefined)
ll
If all elements have the same length, 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 depends on the value of the option undef.
If the option ll is set, only undefined values are replaced. 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.
If ll is set, "choose" returns (in list or scalar context) always the indexes of the
chosen items regardless of how index is set.
If ll is set and the window size has changed, choose returns immediately "-1".
Allowed values: 1 or greater
(default: undefined)
mark
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. Elements greater than the last index of the list are
ignored.
(default: undefined)
max_height
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 to a value less than keep.
Allowed values: 1 or greater
(default: undefined)
max_width
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.
Allowed values: 1 or greater
(default: undefined)
mouse
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.
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
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. 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. no_spacebar elements greater than
the last index of the list are ignored.
(default: undefined)
order
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.
pad
Sets the number of whitespaces between columns. (default: 2)
Allowed values: 0 or greater
page
0 - off
1 - print the page number on the bottom of the screen if there is more then one page.
(default)
prompt
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"
undef
Sets the string displayed on the screen instead an undefined element.
default: "<undef>"
ERROR HANDLING
croak
"new|config|choose" dies if passed invalid arguments.
carp
If after pressing a key Term::ReadKey::ReadKey returns "undef" "choose" warns with "EOT:
$!" and returns undef or an empty list in list context.
REQUIREMENTS
Perl version
Requires Perl version 5.8.3 or greater.
Decoded strings
"choose" expects decoded strings as array elements.
Encoding layer for STDOUT
For a correct output it is required an appropriate encoding layer for STDOUT matching the
terminal's character set.
Monospaced font
It is required a terminal that uses a monospaced font which supports the printed
characters.
Escape sequences
It is required a terminal that supports ANSI escape sequences.
If the option "hide_cursor" is enabled, it is also required the support for the following
escape sequences:
"\e[?25l" Hide Cursor
"\e[?25h" Show Cursor
If a mouse mode is enabled
"\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.
If the OS is MSWin32 Win32::Console is used, to emulate the behavior of the escape
sequences.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Term::Choose
AUTHOR
Matthäus Kiem <cuer2s@gmail.com>
CREDITS
Based on the "choose" function from the Term::Clui module.
Thanks to the Perl-Community.de <http://www.perl-community.de> and the people form
stackoverflow <http://stackoverflow.com> for the help.
LICENSE AND COPYRIGHT
Copyright (C) 2012-2018 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.