Provided by: libterm-choose-perl_1.701-1_all bug

NAME

       Term::Choose - Choose items from a list interactively.

VERSION

       Version 1.701

SYNOPSIS

       Functional interface:

           use Term::Choose qw( choose );

           my $array_ref = [ qw( one two three four five ) ];

           my $choice = choose( $array_ref );                            # single choice
           print "$choice\n";

           my @choices = choose( [ 1 .. 100 ], { alignment => 1 } );       # multiple choice
           print "@choices\n";

           choose( [ 'Press ENTER to continue' ], { prompt => '' } );    # no choice

       Object-oriented interface:

           use Term::Choose;

           my $array_ref = [ qw( one two three four five ) ];

           my $new = Term::Choose->new();

           my $choice = $new->choose( $array_ref );                       # single choice
           print "$choice\n";

           my @choices = $new->choose( [ 1 .. 100 ] );                    # multiple choice
           print "@choices\n";

           my $stopp = Term::Choose->new( { prompt => '' } );
           $stopp->choose( [ 'Press ENTER to continue' ] );               # no choice

DESCRIPTION

       Choose interactively from a list of items.

       "Term::Choose" provides a functional interface ("SUBROUTINES") and an object-oriented
       interface ("METHODS").

EXPORT

       Nothing by default.

           use Term::Choose qw( choose );

METHODS

   new
           $new = Term::Choose->new( [ \%options] );

       This constructor returns a new "Term::Choose" object.

       To set the different options it can be passed a reference to a hash as an optional
       argument.

       For detailed information about the options see "OPTIONS".

   choose
       The method "choose" allows the user to choose from a list.

       The first argument is an array reference which holds the list of the available choices.

       As a second and optional argument it can be passed a reference to a hash where the keys
       are the option names and the values the option values.

       Options set with "choose" overwrite options set with "new". Before leaving "choose"
       restores the overwritten options.

           $choice = $new->choose( $array_ref [, \%options] );

           @choices= $new->choose( $array_ref [, \%options] );

                     $new->choose( $array_ref [, \%options] );

       When in the documentation is mentioned "array" or "list" or "elements" or "items" (of the
       array/list) than these refer to this array passed as a reference as the first argument.

       For more information how to use "choose" and its return values see "USAGE AND RETURN
       VALUES".

SUBROUTINES

   choose
       The function "choose" allows the user to choose from a list. It takes the same arguments
       as the method "choose".

           $choice = choose( $array_ref [, \%options] );

           @choices= choose( $array_ref [, \%options] );

                     choose( $array_ref [, \%options] );

       See the "OPTIONS" section for more details about the different options and how to set
       them.

       See also the following section "USAGE AND RETURN VALUES".

USAGE AND RETURN VALUES

       ·   If "choose" is called in a scalar context, the user can choose an item by using the
           "Keys to move around" 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 if the option include_highlighted is set to 1).

           In list context "Ctrl-SpaceBar" (or "Ctrl-@") 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 first argument refers to an empty array, "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.

       "choose" returns "undef" or an empty list in list context if the "q" key (or "Ctrl-Q") is
       pressed.

       If the mouse mode is enabled, an 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
       ·   the "Arrow" keys (or the "h,j,k,l" keys) to move up and down or to move to the right
           and to the left,

       ·   the "Tab" key (or "Ctrl-I") to move forward, the "BackSpace" key (or "Ctrl-H" or
           "Shift-Tab") to move backward,

       ·   the "PageUp" key (or "Ctrl-B") to go back one page, the "PageDown" key (or "Ctrl-F")
           to go forward one page,

       ·   the "Insert" key to go back 10 pages, the "Delete" key to go forward 10 pages,

       ·   the "Home" key (or "Ctrl-A") to jump to the beginning of the list, the "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.

       All the 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.

       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.

       ·   Tab characters in elements are replaces with a space.

               $element =~ s/\t/ /g;

       ·   Vertical spaces in elements are squashed to two spaces.

               $element =~ s/\v+/\ \ /g;

       ·   Code points from the ranges of control, surrogate and noncharacter are removed.

               $element =~ s/[\p{Cc}\p{Noncharacter_Code_Point}\p{Cs}]//g;

       ·   If the length of an element is greater than the width of the screen the element is cut
           and at the end of the string are added three dots.

OPTIONS

       Options which expect a number as their value expect integers.

       alignment

       0 - elements ordered in columns are aligned to the left (default)

       1 - elements ordered in columns are aligned to the right

       2 - elements ordered in columns are centered

       beep

       0 - off (default)

       1 - on

       clear_screen

       0 - off (default)

       1 - clears the screen before printing the choices

       codepage_mapping

       This option has only meaning if the operating system is MSWin32.

       If the OS is MSWin32, Win32::Console::ANSI is used. By default "Win32::Console::ANSI"
       converts the characters from Windows code page to DOS code page (the so-called ANSI to OEM
       conversion). This conversation is disabled by default in "Term::Choose" but one can enable
       it by setting this option.

       Setting this option to 1 enables the codepage mapping offered by Win32::Console::ANSI.

       0 - disable automatic codepage mapping (default)

       1 - keep automatic codepage mapping

       color

       Setting this option to 1 enables the support for color and text formatting escape
       sequences.

       0 - off (default)

       1 - on

       default

       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)

       empty

       Sets the string displayed on the screen instead an empty string.

       (default: "<empty>")

       hide_cursor

       0 - keep the terminals highlighting of the cursor position

       1 - hide the terminals highlighting of the cursor position (default)

       info

       Expects as its value a string. The info text is printed above the prompt string.

       (default: not set)

       index

       0 - off (default)

       1 - return the index of the chosen element instead of the chosen element respective the
       indices of the chosen elements instead of the chosen elements.

       justify

       The option justify is now called alignment. Use alignment instead of justify. justify will
       be removed.

       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)

       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

            .----------------------.   .----------------------.   .----------------------.   .----------------------.
            | ..                   |   | ..                   |   | ..                   |   | ..                   |
            | ..                   |   | ..                   |   | ..                   |   | ..                   |
            | ..                   |   | ..                   |   | ..                   |   | ..                   |
            |                      |   | ..                   |   | ..                   |   | ..                   |
            |                      |   |                      |   | ..                   |   | ..                   |
            |                      |   |                      |   |                      |   | ..                   |
            '----------------------'   '----------------------'   '----------------------'   '----------------------'

       lf

       If prompt lines are folded the option lf allows one to insert spaces at beginning of the
       folded lines.

       The option lf expects a reference to an 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.

       See "INITIAL_TAB" and "SUBSEQUENT_TAB" in Text::LineFold.

       (default: undefined)

       ll

       If all elements have the same length, the length can be passed with this option. "choose"
       then doesn't calculate the length of the longest element itself but uses the passed value.
       length refers here to the number of print columns the element will use on the terminal.

       If ll is set, "choose" returns always the index(es) of the chosen item(s) regardless of
       how index is set.

       Undefined list elements are not allowed.

       The replacements described in "Modifications for the output" are not applied. If elements
       contain unsupported characters the output might break.

       If ll is set to a value less than the length of the elements, the output could break.

       If ll is set and the window size has changed, choose returns immediately "-1".

       Allowed values: 1 or greater

       (default: undefined)

       max_height

       If defined sets the maximal number of rows used for printing list items.

       If the available height is less than max_height then max_height is set to the available
       height.

       Height in this context means print rows.

       max_height overwrites keep if max_height is set to a value less than keep.

       Allowed values: 1 or greater

       (default: undefined)

       max_width

       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: 1 or greater

       (default: undefined)

       mouse

       0 - off (default)

       1 - on. Enables the Any-Event-Mouse-Mode (1003) and the Extended-SGR-Mouse-Mode (1006).

       If the option mouse is enabled layers for "STDIN" are changed. Then before leaving
       "choose" as a cleanup "STDIN" is marked as "UTF-8" with ":encoding(UTF-8)". This doesn't
       apply if the OS is MSWin32.

       If the OS is MSWin32 the mouse is enabled with the help of Win32::Console.

       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.

       pad

       Sets the number of whitespaces between columns. (default: 2)

       Allowed values: 0 or greater

       page

       0 - off

       1 - print the page number on the bottom of the screen if there is more then one page.
       (default)

       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"

       undef

       Sets the string displayed on the screen instead an undefined element.

       default: "<undef>"

   Options List Context
       include_highlighted

       In list context when "Return" is pressed

       0 - "choose" returns the items marked with the "SpaceBar". (default)

       1 - "choose" returns the items marked with the "SpaceBar" plus the highlighted item.

       2 - "choose" returns the items marked with the "SpaceBar". If no items are marked with the
       "SpaceBar", the highlighted item is returned.

       mark

       mark expects as its value a reference to an array. The elements of the array are list
       indexes. "choose" preselects the list-elements correlating to these indexes.

       Elements greater than the last index of the list are ignored.

       This option has only meaning in list context.

       (default: undefined)

       meta_items

       meta_items expects as its value a reference to an array. The elements of the array are
       list indexes. These elements can not be marked with the "SpaceBar" or with the right mouse
       key but if one of these elements is the highlighted item it is added to the chosen items
       when "Return" is pressed.

       Elements greater than the last index of the list are ignored.

       This option has only meaning in list context.

       (default: undefined)

       no_spacebar

       no_spacebar expects as its value a reference to an array. The elements of the array are
       indexes of the list 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.

       no_spacebar elements greater than the last index of the list are ignored.

       This option has only meaning in list context.

       (default: undefined)

ERROR HANDLING

   croak
       "new|choose" dies if passed invalid arguments.

   carp
       If pressing a key results in an undefined value "choose" warns with "EOT: $!" and returns
       undef or an empty list in list context.

REQUIREMENTS

   Perl version
       Requires Perl version 5.8.3 or greater.

   Optional modules
       Term::ReadKey

       If Term::ReadKey is available it is used "ReadKey" to read the user input and
       "GetTerminalSize" to get the terminal size. Without "Term::ReadKey" "getc" is used to read
       the input and "stty size" to get the terminal size.

       If the OS is MSWin32 it is used Win32::Console to read the user input and to get the
       terminal size.

   Decoded strings
       "choose" expects decoded strings as array elements.

   Encoding layer for STDOUT
       For a correct output it is required an appropriate encoding layer for STDOUT matching the
       terminal's character set.

   Monospaced font
       It is required a terminal that uses a monospaced font which supports the printed
       characters.

   Ambiguous width characters
       By default ambiguous width characters are treated as half width. If the environment
       variable "TC_AMBIGUOUS_WIDE" is set to a true value, ambiguous width characters are
       treated as full width.

   Escape sequences
       By default "Term::Choose" uses "tput" to get the appropriate escape sequences. Setting the
       environment variable "TC_ANSI_ESCAPES" to a true value allows one to use ANSI escape
       sequences directly without calling "tput".

           BEGIN {
               $ENV{TC_ANSI_ESCAPES} = 1;
           }
           use Term::Choose qw( choose );

       The escape sequences to enable the mouse mode are always hardcoded.

   MSWin32
       If the OS is MSWin32 Win32::Console and Win32::Console::ANSI with ANSI escape sequences
       are used. See also "codepage_mapping".

SUPPORT

       You can find documentation for this module with the perldoc command.

           perldoc Term::Choose

AUTHOR

       Matthäus Kiem <cuer2s@gmail.com>

CREDITS

       Based on the "choose" function from the Term::Clui module.

       Thanks to the Perl-Community.de <http://www.perl-community.de> and the people form
       stackoverflow <http://stackoverflow.com> for the help.

LICENSE AND COPYRIGHT

       Copyright (C) 2012-2019 Matthäus Kiem.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl 5.10.0. For details, see the full text of the licenses in the file LICENSE.