Term::Choose - Choose items from a list interactively.
Version 0.103
use Term::Choose;
my @array = <one two three four five>;
# Functional interface:
my $choice = choose( @array, { layout => 1 } );
say $choice;
# OO interface:
my $tc = Term::Choose.new();
$choice = $tc.choose( @array, { layout => 1 } );
say $choice;
Term::Choose supports only ascii-characters strings.
Choose interactively from a list of items.
For choose, choose_multi and pause the first argument (Array) holds the list of the available choices.
With the optional second argument (Hash) it can be passed the different options. See #OPTIONS.
The return values are described in #Routines
To browse through the available list-elements use the keys described below.
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, after a keystroke the screen is rewritten.
How to choose the items is described for each method/function separately in Routines.
-
the
Arrowkeys (orh,j,k,l) to move up and down or to move to the right and to the left, -
the
Tabkey (orCtrl-I) to move forward, theBackSpacekey (orCtrl-HorShift-Tab) to move backward, -
the
PageUpkey (orCtrl-B) to go back one page, thePageDownkey (orCtrl-F) to go forward one page, -
the
Homekey (orCtrl-A) to jump to the beginning of the list, theEndkey (orCtrl-E) to jump to the end of the list.
For the usage of SpaceBar, Ctrl-SpaceBar, Return and the q-key see #choose, #choose_multi and #pause.
With mouse enabled (and if supported by the terminal) use the the left mouse key instead the Return key and the right mouse key instead of the SpaceBar key. Instead of PageUp and PageDown it can be used the mouse wheel. - Mouse wheel not yet suppoerted!
choose allows the user to choose one item from a list: the highlighted item is returned when Return is pressed.
choose returns nothing if the q key or Ctrl-D is pressed.
The user can choose many items.
To choose more than one item mark an item with the SpaceBar. choose_multi then returns the list of the marked items including the highlighted item.
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.
choose_multi returns nothing if the q key or Ctrl-D is pressed.
Nothing can be chosen, nothing is returned but the user can move around and read the output until closed with Return, q or Ctrl-D.
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 and choose_multi return the chosen elements as they were passed 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:g/\s/ /; -
Characters which match the Unicode character property
Otherare removed.$element =~ s:g/\p{C}//; -
This mapping is made before the "
substr" because it may change the print width of the elements.$element = $element.gist; -
If the length of an element is greater than the width of the screen the element is cut.
$element.=substr( 0, $allowed_length - 3 ) ~ '...';*
* Term::Choose uses its own function to cut strings which calculates width in print columns.
Options which expect a number as their value expect integers.
0 - off (default)
1 - on
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)
Sets the string displayed on the screen instead an empty string.
default: "ltemptygt"
0 - off (default)
1 - return the indices of the chosen elements instead of the chosen elements.
This option has no meaning for pause.
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 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)
From broad to narrow: 0 > 1 > 2
-
0 - layout off
.-------------------. .-------------------. .-------------------. .-------------------. | .. .. .. .. .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. | | | | .. .. .. .. .. .. | | .. .. .. .. .. .. | | .. .. .. .. .. .. | | | | | | .. .. .. .. | | .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. | '-------------------' '--- ---------------' '-------------------' '-------------------' -
1 - (default)
.-------------------. .-------------------. .-------------------. .-------------------. | .. .. .. .. .. .. | | .. .. .. .. | | .. .. .. .. .. | | .. .. .. .. .. .. | | | | .. .. .. .. | | .. .. .. .. .. | | .. .. .. .. .. .. | | | | .. .. | | .. .. .. .. .. | | .. .. .. .. .. .. | | | | | | .. .. .. .. .. | | .. .. .. .. .. .. | | | | | | .. .. .. | | .. .. .. .. .. .. | | | | | | | | .. .. .. .. .. .. | '-------------------' '-------------------' '-------------------' '-------------------' -
2 - all in a single column
.-------------------. .-------------------. .-------------------. .-------------------. | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | .. | | | | .. | | .. | | .. | | | | | | .. | | .. | | | | | | | | .. | '-------------------' '-------------------' '-------------------' '-------------------'
If prompt lines are folded, the option lf allows to insert spaces at beginning of the folded lines.
The option lf expects a 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.
(default: undefined)
This option is only available for the pause function/method.
If all elements have the same length, the length can be passed with this option.
length refers here to the number of print columns the element will use on the terminal.
If ll is set, then choose doesn't calculate the length of the longest element itself but uses the value passed with this option.
If the option ll is set, none of the substitutions described in #SUBSTITUTIONS are applied and the options empty and undef have no meaning. It is the up to the user to ensure that no control-characters and no unsupported characters (especially unsupporeted non-spacing characters) are in den passed strings.
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 and index is set to 1 a window-resize causes a return -1.
Allowed values: 1 or greater
(default: undefined)
This is a choose_multi-only option.
mark expects as its value an array. The elements of the array are list indexes. choose preselects the list-elements correlating to these indexes.
(default: undefined)
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 number of print rows.
max_height overwrites keep if max_height is set to a value less than keep.
Allowed values: 1 or greater
(default: undefined)
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: 2 or greater
(default: undefined)
0 - no mouse (default)
1 - mouse enabled
This is a choose_multi-only option.
no_spacebar expects as its value an array. The elements of the array are indexes of choices which should not be markable with the SpaceBar or with the right mouse key. 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.
(default: undefined)
If the output has more than one row and more than one column:
0 - elements are ordered horizontally
1 - elements are ordered vertically (default)
Sets the number of whitespaces between columns. (default: 2)
Allowed values: 0 or greater
Sets the number of whitespaces between elements if we have only one row. (default: value of the option pad)
Allowed values: 0 or greater
0 - off
1 - print the page number on the bottom of the screen if there is more then one page. (default)
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: multiselect == 0 ?? Close with ENTER !! Your choice:.
Sets the string displayed on the screen instead an undefined element.
default: "ltundefgt"
It is required a terminal that uses a monospaced font which supports the printed characters.
See Installation and Environment variables in NCurses.
Matthäus Kiem cuer2s@gmail.com
Based on the choose function from the Term::Clui module.
Thanks to the people from Perl-Community.de, from stackoverflow and from #perl6 on irc.freenode.net for the help.
Copyright (C) 2016 Matthäus Kiem.
This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.