NAME
Term::Choose - Choose items from a list.
VERSION
Version 0.7.5
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";
choose( [ 'Press ENTER to continue' ], { prompt => 0 } ); # no choiceDESCRIPTION
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] );
choose( $array_ref [, \%options] );choose expects as first argument an array reference which passes the list elements available for selection (in void context no selection can be made).
Options can be passed with a hash reference as a second (optional) argument.
Usage and return values
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 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".
choose then returns nothing.
If the items of the list don't fit in 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 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
white-spaces in list elements are replace with a simple space.
control characters are removed
if the length of a list element is greater than the width of the screen the element is cut
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.
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:' ('Close with ENTER' in void context)
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
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 warns and uses the first max_list list items.
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.
REQUIREMENTS
Perl Version
Requires Perl Version 5.10.1 or greater.
Modules
Used modules not provided as core modules:
Signals::XSIG
Term::ReadKey
Escape sequences
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 (SGR)
"\e[1m" Bold (SGR)
"\e[4m" Underline (SGR)
"\e[7m" Inverse (SGR)
If option "hide_cursor" is enabled:
"\e[?25l" Hide Cursor (DECTCEM)
"\e[?25h" Show Cursor (DECTCEM) If option "clear_screen" is enabled:
"\e[2J" Clear Screen (Erase Data)
"\e[1;1H" Go to Top Left (Cursor Position)If option "mouse_mode" is set:
"\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.
BUGS
Unicode
This modules uses the Perl builtin functions length to determine the length of strings, substr to cut strings and printf widths to justify strings.
Therefore strings with code points that take more or less than one print column will break the layout.
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.