NAME
Term::Choose - Choose items from a list.
VERSION
Version 0.7.1
SYNOPSIS
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";DESCRIPTION
Choose from a list of elements.
Requires Perl Version 5.10.1 or greater.
EXPORT
Nothing by default.
use Term::Choose qw(choose);SUBROUTINES/METHODS
choose
$scalar = choose( $array_ref [, \%options] );
@array = choose( $array_ref [, \%options] );The first argument (array reference) passes the elements available for selection.
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 the items of the list don't fit in the screen, the user can scroll to the next (previous) page(s).
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
if a list-element contains white-spaces this substitution is applied:
$element =~ s/\p{Space}/ /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.
Error handling
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 dies.
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.
OPTIONS
All options are optional.
Defaults may change in a future release.
prompt
If prompt is undefined default prompt-string will be shown.
If prompt is 0 no prompt-line will be shown.
default: 'Your choice:'
right_justify
0 - columns are left-justified (default)
1 - columns are right-justified
layout
0 - layout off
.-----------------------------. .-----------------------------. .-----------------------------. |... .. .... ... .... ... ... | |.... .... .... .... .... ....| |.... .... .... .... .... ....| | | |.... .... .... .... .... ....| |.... .... .... .... .... ....| | | |.... | |.... .... .... .... .... ....| | | | | |.... .... .... .... .... ....| | | | | |.... .... .... .... .... ....| | | | | |.... .... .... .... .... ....| | | | | |.... .... .... .... .... ....| | | | | |.... .... .... .... .... ....| '-----------------------------' '-----------------------------' '-----------------------------'1 - layout "H" (default)
.-----------------------------. .-----------------------------. .-----------------------------. |... .. .... ... .... ... ... | |.... .... .... .... | |.... .... .... .... .... ....| | | |.... .... .... .... | |.... .... .... .... .... ....| | | |.... .... .... .... | |.... .... .... .... .... ....| | | |.... .... | |.... .... .... .... .... ....| | | | | |.... .... .... .... .... ....| | | | | |.... .... .... .... .... ....| | | | | |.... .... .... .... .... ....| | | | | |.... .... .... .... .... ....| '-----------------------------' '-----------------------------' '-----------------------------'2 - all in a single column
.-----------------------------. .-----------------------------. .-----------------------------. |.... | |.... | |.... | |.... | |.... | |.... | |... | |... | |... | |.... | |.... | |.... | | | |.... | |.... | | | |.... | |.... | | | | | |.... | | | | | |.... | '-----------------------------' '-----------------------------' '-----------------------------'3 - layout "V"
.-----------------------------. .-----------------------------. .-----------------------------. |.... | |.... .... | |.... .... .... .... .... ....| |.... | |.... .... | |.... .... .... .... .... ....| |... | |.... .... | |.... .... .... .... .... ....| |.... | |.... .... | |.... .... .... .... .... ....| |.... | |.... .... | |.... .... .... .... .... ....| |.... | |.... | |.... .... .... .... .... ....| |... | | | |.... .... .... .... .... ....| |.... | | | |.... .... .... .... .... ....| '-----------------------------' '-----------------------------' '-----------------------------'
screen_width
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)
vertical_order
0 - items ordered horizontally
1 - items ordered vertically (default)
clear_screen
0 - off (default)
1 - clears the screen before printing the choices
mouse_mode
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
pad
space between columns (default: 2)
allowed values: 0 - 99
pad_one_row
space between items if we have only one row (default: 3)
allowed values: 0 - 99
extra_key
0 - off
1 - on: pressing key "e" calls exit() (default)
beep
0 - off (default)
1 - on
hide_cursor
0 - off
1 - on (default)
undef
string displayed on the screen instead a undefined list-element
default: '<undef>'
empty_string
string displayed on the screen instead an empty string
default: '<empty>'
max_list
maximal allowed length of the list referred by the first argument (default: 100_000)
allowed values: 1 - 999_999_999
REQUIREMENTS
Perl Version
Requires Perl Version 5.10.1 or greater.
Modules
Apart from the core-modules Exporter and Carp these modules are used:
Escape sequences
The Terminal needs to understand the following ANSI escape sequences:
Cursor Up
"\e[A"Cursor Forward
"\e[C"Clear Screen (Erase Data)
"\e[0J"Select Graphic Rendition
Reset / Normal
"\e[0m"Bright (increased intensity) or Bold
"\e[1m"Underline: Single
"\e[4m"Image: Negative (Reverse)
"\e[7m"
If option "hide_cursor" is enabled:
Hide Cursor (DECTCEM)
"\e[?25lShow Cursor (DECTCEM)
"\e[?25h"
If option "clear_screen" is enabled:
Clear Screen (Erase Data)
"\e[2J"Go to Top Left (Cursor Position)
"\e[0;0H"
If option "mouse_mode" is set:
Get Cursor Position (Device Status Report)
"\e[6n"
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.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Term::ChooseAUTHOR
Kuerbis cuer2s@gmail.com
CREDITS
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.
LICENSE AND COPYRIGHT
Copyright 2012 Kuerbis.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.