NAME
Term::Choose::Win32 - Choose items from a list.
VERSION
Version 0.005
SYNOPSIS
use 5.10.0;
use Term::Choose::Win32 qw(choose);
my $array_ref = [ qw( one two three four five ) ];
my $choice = choose( $array_ref ); # single choice
say $choice;
my @choices = choose( [ 1 .. 100 ], { justify => 1 } ); # multiple choice
say "@choices";
choose( [ 'Press ENTER to continue' ], { prompt => '' } ); # no choiceDESCRIPTION
Choose from a list of items.
This module is experimental!
Term::Choose::Win32 is intended for 'MSWin32' operating systems. For other operating system see Term::Choose.
Based on the choose function from the Term::Clui module - for more details see Term::choose#MOTIVATION.
EXPORT
Nothing by default.
use Term::Choose::Win32 qw(choose);SUBROUTINES
choose
$scalar = choose( $array_ref [, \%options] );
@array = choose( $array_ref [, \%options] );
choose( $array_ref [, \%options] );choose expects as a first argument an array reference. The array the reference refers to holds the list items available for selection (in void context no selection can be made).
The array the reference - passed with the first argument - refers to is called in the documentation simply array or list resp. elements (of the array).
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 - when "Return" is pressed - the list of marked items including the highlighted item.
In list context "Ctrl-SpaceBar" inverts the choices: marked items are unmarked and unmarked items are marked.
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 choose rewrites the screen. In list context marked items are reset.
The "q" key (or Ctrl-D) returns undef or an empty list in list context.
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:
Arrow keys (or hjkl),
Tab key (or Ctrl-I) to move forward, BackSpace key (or Ctrl-H or Shift-Tab) to move backward,
PageUp key (or Ctrl-B) to go back one page, PageDown key (or Ctrl-F) to go forward one page,
Home key (or Ctrl-A) to jump to the beginning of the list, 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:
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;non printable characters are replaced with the replacement character (U+FFFD).
$element =~ s/\P{Print}/\x{fffd}/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 ) . '...';** Term::Choose::Win32 uses its own function to cut strings which uses print columns for the arithmetic.
All these 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.
Options
Options which expect a number as their value expect integers.
There is a general upper limit of one billion 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 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'
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 defined, sets the screen width to screen_width if the screen width is greater than screen_width.
Screen width refers here to the number of print columns.
Allowed values: 1 or greater
(default: undef)
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.
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
pad
Sets the number of whitespaces between columns. (default: 2)
Allowed values: 0 or greater
pad_one_row
Sets the number of whitespaces between elements if we have only one row. (default: value of the option pad)
Allowed values: 0 or greater
clear_screen
0 - off (default)
1 - clears the screen before printing the choices
default
With the option default 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: undef)
index
0 - off (default)
1 - return the index of the chosen element instead of the chosen element resp. the indices of the chosen elements instead of the chosen elements.
page
0 - off
1 - print the page number on the bottom of the screen if there is more then one page. (default)
mouse
0 - no mouse mode (default)
1 - mouse mode enabled
2 - mouse mode enabled; maxcols and maxrows limited to 223
3 - mouse mode enabled
4 - mouse mode enabled
There is no difference between mouse mode 1, 3 and 4.
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)
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 array. (default: 100_000)
Allowed values: 1 or greater
undef
Sets the string displayed on the screen instead an undefined element.
default: '<undef>'
empty
Sets the string displayed on the screen instead an empty string.
default: '<empty>'
lf
If prompt lines are folded the option lf allows to insert spaces at beginning of the folded lines.
The option lf expects a reference to an array with two elements;
- first element (INITIAL_TAB): the number of spaces inserted at beginning of paragraphs
- second element (SUBSEQUENT_TAB): 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: undef)
ll
If all elements have the same length and this length is known before calling choose it 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 and elements with an empty string depends on the value of the option undef resp. on the value of the option empty.
If the option ll is set the elements must be upgraded with utf8::upgrade or with an equivalent tool and not contain any non-printing character.
The upgrade with utf8::upgrade is needed because a limitation of Unicode::GCString (Bug #84661).
If ll is set to a value less than the length of the elements the output will break.
If the value of ll is greater than the screen width the elements will be trimmed to fit into the screen.
Allowed values: 1 or greater
(default: undef)
Error handling
With no arguments choose dies.
With more than two arguments choose dies.
If the first argument is not a array reference choose dies.
If the array referred by the first argument is empty choose returns undef resp. an empty list and issues a warning.
If the array referred by the first argument has more than limit elements (default 100_000) choose warns and uses the first limit array elements.
If the (optional) second argument is defined and 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.
If after pressing a key Term::ReadKey::ReadKey returns undef choose warns with "EOT: $!" and returns undef resp. an empty list.
REQUIREMENTS
Perl Version
Requires Perl Version 5.10.0 or greater.
Modules
Used modules not provided as core modules:
Decoded strings
choose expects decoded strings as array elements.
Term::Choose::Win32 disables the automatic conversion done by Win32::Console::ANSI globally.
Monospaced font
It is needed a terminal that uses a monospaced font.
Escape sequences
The Terminal needs to understand the following ANSI escape sequences:
"\e[A" Cursor Up
"\e[C" Cursor Forward
"\e[D" Cursor Back
"\e[0J" Clear to End of Screen (Erase Data)
"\e[0m" Normal/Reset
"\e[1m" Bold
"\e[4m" Underline
"\e[7m" InverseTerm::Choose::Win32 uses Win32::Console::ANSI to understand these ANSI escape sequences.
The Win32::Console::ANSI::Cursor() function is used to get the cursor position.
To read key and mouse events Term::Choose::Win32 uses the Win32::Console module.
Win32::Console is also used to hide the cursor.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Term::Choose::Win32AUTHOR
Matthäus Kiem <cuer2s@gmail.com>
CREDITS
Based on and inspired by the choose function from the Term::Clui module.
Thanks to the Perl-Community.de and the people form stackoverflow for the help.
LICENSE AND COPYRIGHT
Copyright 2013 Matthäus Kiem.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.