NAME
Term::Choose - Choose items from a list.
VERSION
Version 1.009
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.
Based on the choose function from the Term::Clui module - for more details see "MOTIVATION".
EXPORT
Nothing by default.
use Term::Choose qw(choose);SUBROUTINES
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 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 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".
Called in void context 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. 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.
Keys to move around: arrow keys (or hjkl), Tab, BackSpace (or Shift-Tab or Ctrl-H), PageUp and PageDown (or Ctrl+B/Ctrl+F).
Modifications for the output
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 replaced with simple spaces.
$element =~ s/\p{Space}/ /g;control characters are removed.
$element =~ s/\p{Cntrl}//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.
Options
All options are optional.
Defaults may change in a future release.
Options which expect a number as their value expect integers.
There is a general upper limit of 1_000_000_000 for options which expect a number as their value and where no upper limit is mentioned.
prompt
If prompt is undefined a default prompt-string will be shown.
If prompt is 0 no prompt-line will be shown.
default in list and scalar context: 'Your choice:'
default in void context: 'Close with ENTER'
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
.----------------------. .----------------------. .----------------------. .----------------------. | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | | | .. | | .. | | .. | | | | | | .. | | .. | | | | | | | | .. | '----------------------' '----------------------' '----------------------' '----------------------'
screen_width
If set, restricts the screen width to the integer value of screen_width percentage of the effective screen width.
If the result of int screen_width percentage of the screen width is zero the virtual screen width is set to one screen column.
If not defined all the screen width is used.
Allowed values: from 1 to 100
(default: undef)
vertical
0 - items are ordered horizontally
1 - items are ordered vertically (default)
right_justify
0 - items ordered in columns are left justified (default)
1 - items ordered in columns are right justified
pad
Sets the number of whitespaces between columns. (default: 2)
Allowed values: 0 or greater
pad_one_row
Sets the number of whitespaces between items if we have only one row. (default: 3)
Allowed values: 0 or greater
clear_screen
0 - off (default)
1 - clears the screen before printing the choices
length_longest
If the length of the longest element of the list is known before calling choose it can be passed with this option.
If length_longest is set, then choose doesn't calculate the length of the longest element itself but uses the value passed with this option.
If length_longest is set to a value less than the length of the longest element all elements which a length greater than this value will be cut.
A larger value than the length of the longest element wastes space on the screen.
If the value of length_longest is greater than the screen width length_longest will be set to the screen width.
Allowed values: 1 or greater
(default: undef)
default
With the option default can be selected a list item, which will be highlighted as the default instead of the first item.
default expects a zero indexed value, so e.g. to highlight the third item the value would be 2.
If the passed value is greater than the index of the last listelement the first item is highlighted.
Allowed values: 0 or greater
(default: undef)
page
0 - off
1 - print the page number on the bottom of the screen if there is more then one page. (default)
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
undef
Sets the string displayed on the screen instead an undefined list element.
default: '<undef>'
empty_string
Sets the string displayed on the screen instead an empty string.
default: '<empty>'
beep
0 - off (default)
1 - on
hide_cursor
0 - keep the terminals highlighting of the cursor position
1 - hide the terminals highlighting of the cursor position (default)
limit
Sets the maximal allowed length of the list referred by the first argument. (default: 100_000)
Allowed values: 1 or greater
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 limit items (default 100_000) choose warns and uses the first limit 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:
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 the option "hide_cursor" is enabled:
"\e[?25l" Hide Cursor (DECTCEM)
"\e[?25h" Show Cursor (DECTCEM)If the option "clear_screen" is enabled:
"\e[2J" Clear Screen (Erase Data)
"\e[1;1H" Go to Top Left (Cursor Position)If a "mouse_mode" is enabled:
"\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.
Monospaced font
It is needed a terminal that uses a monospaced font.
SIGWINCH
Term::Choose makes use of the Perl signal handling as described in perlipc/Signals. It is needed an operating system which knows the WINCH signal: choose uses SIGWINCH to check if the windows size has changed.
BUGS AND LIMITATIONS
Unicode
This modules uses the Perl builtin functions length to determine the length of strings, substr to cut strings and sprintf widths to justify strings. Therefore strings with characters that take more or less than one print column will break the layout. Using Term::Choose::GC instead improves the layout in such conditions. It determines the string length by using the columns method from the Unicode::GCString module.
use Term::Choose:GC qw(choose);Usage and options are the same as for Term::Choose.
The use of Term::Choose::GC needs additionally the Unicode::GCString module to be installed.
Known drawbacks:
Term::Choose::GC's choose is probably slower than choose from Term::Choose.
MOTIVATION
The reason for writing Term::Choose was to get something like Term::Clui::choose but with a nicer output in the case the list doesn't fit in one row.
If the list does not fit in one row, choose from Term::Clui puts the elements on the screen without ordering the items in columns. Term::Choose arranges the elements in columns which makes it easier for me to find elements and easier to navigate on the screen.
- Differences between Term::Clui and Term::Choose
-
Term::Clui's choose expects a question as the first argument, and then the list of items. With Term::Choose the first argument is the list of items passed as an array reference. Options can be passed with a hash reference as an optional second argument. The question can be passed as an option (prompt).
As mentioned above choose from Term::Clui does not order the elements in columns if there is more than one row on the screen while Term::Choose in such situations arranges the elements in columns.
Another difference is how lists which don't fit on the screen are handled. Term::Clui::choose asks the user to enter a substring as a clue. As soon as the matching items will fit, they are displayed as normal. choose from Term::Choose skips - when scrolling and reaching the end (resp. the begin) of the screen - to the next (resp. previous) page.
Strings where the number of characters are not equal to the number of columns on the screen break the output from Term::Clui and Term::Choose. Term::Choose::GC uses the method columns from Unicode::GCString for the determination of the string-length to get along with such situations - see "BUGS AND LIMITATIONS".
Term::Clui's choose prints and returns the chosen items while choose from Term::Choose only returns the chosen items.
Term::Clui disables the mouse mode if the environment variable CLUI_MOUSE is set to off. In Term::Choose the mouse mode is set with the option mouse_mode.
- Only in Term::Clui
-
Term::Clui provides a speaking interface, offers a bundle of functions and has a fallback to work when only Perl core modules are available.
The choose function from Term::Clui can remember choices made in scalar context and allows multiline question - the first line is put on the top, the subsequent lines are displayed below the list.
These differences refer to Term::Clui version 1.66. For a more precise description of Term::Clui consult its own documentation.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Term::ChooseAUTHOR
Matthäus Kiem <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 Matthäus Kiem.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.