.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Term::Choose 3pm"
.TH Term::Choose 3pm "2021-01-02" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Term::Choose \- Choose items from a list interactively.
.SH "VERSION"
.IX Header "VERSION"
Version 1.713
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Functional interface:
.PP
.Vb 1
\&    use Term::Choose qw( choose );
\&
\&    my $array_ref = [ qw( one two three four five ) ];
\&
\&    my $choice = choose( $array_ref );                            # single choice
\&    print "$choice\en";
\&
\&    my @choices = choose( [ 1 .. 100 ], { alignment => 1 } );     # multiple choice
\&    print "@choices\en";
\&
\&    choose( [ \*(AqPress ENTER to continue\*(Aq ], { prompt => \*(Aq\*(Aq } );    # no choice
.Ve
.PP
Object-oriented interface:
.PP
.Vb 1
\&    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\en";
\&
\&    my @choices = $new\->choose( [ 1 .. 100 ] );                    # multiple choice
\&    print "@choices\en";
\&
\&    my $stopp = Term::Choose\->new( { prompt => \*(Aq\*(Aq } );
\&    $stopp\->choose( [ \*(AqPress ENTER to continue\*(Aq ] );               # no choice
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Choose interactively from a list of items.
.PP
\&\f(CW\*(C`Term::Choose\*(C'\fR provides a functional interface (\*(L"\s-1SUBROUTINES\*(R"\s0) and an object-oriented interface (\*(L"\s-1METHODS\*(R"\s0).
.SH "EXPORT"
.IX Header "EXPORT"
Nothing by default.
.PP
.Vb 1
\&    use Term::Choose qw( choose );
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&    $new = Term::Choose\->new( [ \e%options] );
.Ve
.PP
This constructor returns a new \f(CW\*(C`Term::Choose\*(C'\fR object.
.PP
To set the different options it can be passed a reference to a hash as an optional argument.
.PP
For detailed information about the options see \*(L"\s-1OPTIONS\*(R"\s0.
.SS "choose"
.IX Subsection "choose"
The method \f(CW\*(C`choose\*(C'\fR allows the user to choose from a list.
.PP
The first argument is an array reference which holds the list of the available choices.
.PP
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.
.PP
Options set with \f(CW\*(C`choose\*(C'\fR overwrite options set with \f(CW\*(C`new\*(C'\fR. Before leaving \f(CW\*(C`choose\*(C'\fR restores the
overwritten options.
.PP
.Vb 1
\&    $choice = $new\->choose( $array_ref [, \e%options] );
\&
\&    @choices= $new\->choose( $array_ref [, \e%options] );
\&
\&              $new\->choose( $array_ref [, \e%options] );
.Ve
.PP
When in the documentation is mentioned \*(L"array\*(R" or \*(L"list\*(R" or \*(L"elements\*(R" or \*(L"items\*(R" (of the array/list) than these
refer to this array passed as a reference as the first argument.
.PP
For more information how to use \f(CW\*(C`choose\*(C'\fR and its return values see \*(L"\s-1USAGE AND RETURN VALUES\*(R"\s0.
.SH "SUBROUTINES"
.IX Header "SUBROUTINES"
.SS "choose"
.IX Subsection "choose"
The function \f(CW\*(C`choose\*(C'\fR allows the user to choose from a list. It takes the same arguments as the method \*(L"choose\*(R".
.PP
.Vb 1
\&    $choice = choose( $array_ref [, \e%options] );
\&
\&    @choices= choose( $array_ref [, \e%options] );
\&
\&              choose( $array_ref [, \e%options] );
.Ve
.PP
See the \*(L"\s-1OPTIONS\*(R"\s0 section for more details about the different options and how to set them.
.PP
See also the following section \*(L"\s-1USAGE AND RETURN VALUES\*(R"\s0.
.SH "USAGE AND RETURN VALUES"
.IX Header "USAGE AND RETURN VALUES"
.IP "\(bu" 4
If \f(CW\*(C`choose\*(C'\fR is called in a \fIscalar context\fR, the user can choose an item by using the \*(L"Keys to move around\*(R" and
confirming with \f(CW\*(C`Return\*(C'\fR.
.Sp
\&\f(CW\*(C`choose\*(C'\fR then returns the chosen item.
.IP "\(bu" 4
If \f(CW\*(C`choose\*(C'\fR is called in an \fIlist context\fR, the user can also mark an item with the \f(CW\*(C`SpaceBar\*(C'\fR.
.Sp
\&\f(CW\*(C`choose\*(C'\fR then returns \- when \f(CW\*(C`Return\*(C'\fR is pressed \- the list of marked items (including the highlighted item if the
option \fIinclude_highlighted\fR is set to \f(CW1\fR).
.Sp
In \fIlist context\fR \f(CW\*(C`Ctrl\-SpaceBar\*(C'\fR (or \f(CW\*(C`Ctrl\-@\*(C'\fR) inverts the choices: marked items are unmarked and unmarked items are
marked.
.IP "\(bu" 4
If \f(CW\*(C`choose\*(C'\fR is called in an \fIvoid context\fR, the user can move around but mark nothing; the output shown by \f(CW\*(C`choose\*(C'\fR
can be closed with \f(CW\*(C`Return\*(C'\fR.
.Sp
Called in void context \f(CW\*(C`choose\*(C'\fR returns nothing.
.Sp
If the first argument refers to an empty array, \f(CW\*(C`choose\*(C'\fR returns nothing.
.PP
If the items of the list don't fit on the screen, the user can scroll to the next (previous) page(s).
.PP
If the window size is changed, then as soon as the user enters a keystroke \f(CW\*(C`choose\*(C'\fR rewrites the screen.
.PP
\&\f(CW\*(C`choose\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR or an empty list in list context if the \f(CW\*(C`q\*(C'\fR key (or \f(CW\*(C`Ctrl\-Q\*(C'\fR) is pressed.
.PP
If the \fImouse\fR 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 \f(CW\*(C`SpaceBar\*(C'\fR key.
.SS "Keys to move around"
.IX Subsection "Keys to move around"
.IP "\(bu" 4
the \f(CW\*(C`Arrow\*(C'\fR keys (or the \f(CW\*(C`h,j,k,l\*(C'\fR keys) to move up and down or to move to the right and to the left,
.IP "\(bu" 4
the \f(CW\*(C`Tab\*(C'\fR key (or \f(CW\*(C`Ctrl\-I\*(C'\fR) to move forward, the \f(CW\*(C`BackSpace\*(C'\fR key (or \f(CW\*(C`Ctrl\-H\*(C'\fR or \f(CW\*(C`Shift\-Tab\*(C'\fR) to move backward,
.IP "\(bu" 4
the \f(CW\*(C`PageUp\*(C'\fR key (or \f(CW\*(C`Ctrl\-B\*(C'\fR) to go back one page, the \f(CW\*(C`PageDown\*(C'\fR key (or \f(CW\*(C`Ctrl\-F\*(C'\fR) to go forward one page,
.IP "\(bu" 4
the \f(CW\*(C`Insert\*(C'\fR key to go back 10 pages, the \f(CW\*(C`Delete\*(C'\fR key to go forward 10 pages,
.IP "\(bu" 4
the \f(CW\*(C`Home\*(C'\fR key (or \f(CW\*(C`Ctrl\-A\*(C'\fR) to jump to the beginning of the list, the \f(CW\*(C`End\*(C'\fR key (or \f(CW\*(C`Ctrl\-E\*(C'\fR) to jump to the end of
the list.
.SS "Modifications for the output"
.IX Subsection "Modifications for the output"
For the output on the screen the array elements are modified.
.PP
All the modifications are made on a copy of the original array so \f(CW\*(C`choose\*(C'\fR returns the chosen elements as they were
passed to the function without modifications.
.PP
Modifications:
.IP "\(bu" 4
If an element is not defined the value from the option \fIundef\fR is assigned to the element.
.IP "\(bu" 4
If an element holds an empty string the value from the option \fIempty\fR is assigned to the element.
.IP "\(bu" 4
Tab characters in elements are replaces with a space.
.Sp
.Vb 1
\&    $element =~ s/\et/ /g;
.Ve
.IP "\(bu" 4
Vertical spaces in elements are squashed to two spaces.
.Sp
.Vb 1
\&    $element =~ s/\ev+/\e \e /g;
.Ve
.IP "\(bu" 4
Code points from the ranges of control, surrogate and noncharacter are removed.
.Sp
.Vb 1
\&    $element =~ s/[\ep{Cc}\ep{Noncharacter_Code_Point}\ep{Cs}]//g;
.Ve
.IP "\(bu" 4
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.
.SH "OPTIONS"
.IX Header "OPTIONS"
Options which expect a number as their value expect integers.
.PP
\fIalignment\fR
.IX Subsection "alignment"
.PP
0 \- elements ordered in columns are aligned to the left (default)
.PP
1 \- elements ordered in columns are aligned to the right
.PP
2 \- elements ordered in columns are centered
.PP
\fIbeep\fR
.IX Subsection "beep"
.PP
0 \- off (default)
.PP
1 \- on
.PP
\fIclear_screen\fR
.IX Subsection "clear_screen"
.PP
0 \- off (default)
.PP
1 \- clears the screen before printing the choices
.PP
\fIcodepage_mapping\fR
.IX Subsection "codepage_mapping"
.PP
This option has only meaning if the operating system is MSWin32.
.PP
If the \s-1OS\s0 is MSWin32, Win32::Console::ANSI is used. By default \f(CW\*(C`Win32::Console::ANSI\*(C'\fR converts the characters from
Windows code page to \s-1DOS\s0 code page (the so-called \s-1ANSI\s0 to \s-1OEM\s0 conversion). This conversation is disabled by default in
\&\f(CW\*(C`Term::Choose\*(C'\fR but one can enable it by setting this option.
.PP
Setting this option to \f(CW1\fR enables the codepage mapping offered by Win32::Console::ANSI.
.PP
0 \- disable automatic codepage mapping (default)
.PP
1 \- keep automatic codepage mapping
.PP
\fIcolor\fR
.IX Subsection "color"
.PP
Enable the support for color and text formatting escape sequences.
.PP
0 \- off (default)
.PP
1 \- Enables the support for color and text formatting escape sequences except for the current selected element.
.PP
2 \- Enables the support for color and text formatting escape sequences including for the current selected element (shown
in inverted colors).
.PP
\fIdefault\fR
.IX Subsection "default"
.PP
With the option \fIdefault\fR it can be selected an element, which will be highlighted as the default instead of the first
element.
.PP
\&\fIdefault\fR expects a zero indexed value, so e.g. to highlight the third element the value would be \fI2\fR.
.PP
If the passed value is greater than the index of the last array element the first element is highlighted.
.PP
Allowed values: 0 or greater
.PP
(default: undefined)
.PP
\fIempty\fR
.IX Subsection "empty"
.PP
Sets the string displayed on the screen instead an empty string.
.PP
(default: \*(L"<empty>\*(R")
.PP
\fIfooter\fR
.IX Subsection "footer"
.PP
Add a string in the bottom line.
.PP
(default: undefined)
.PP
\fIhide_cursor\fR
.IX Subsection "hide_cursor"
.PP
0 \- keep the terminals highlighting of the cursor position
.PP
1 \- hide the terminals highlighting of the cursor position (default)
.PP
\fIinfo\fR
.IX Subsection "info"
.PP
Expects as its value a string. The info text is printed above the prompt string.
.PP
(default: not set)
.PP
\fIindex\fR
.IX Subsection "index"
.PP
0 \- off (default)
.PP
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.
.PP
\fIkeep\fR
.IX Subsection "keep"
.PP
\&\fIkeep\fR prevents that all the terminal rows are used by the prompt lines.
.PP
Setting \fIkeep\fR ensures that at least \fIkeep\fR terminal rows are available for printing list rows.
.PP
If the terminal height is less than \fIkeep\fR \fIkeep\fR is set to the terminal height.
.PP
Allowed values: 1 or greater
.PP
(default: 5)
.PP
\fIlayout\fR
.IX Subsection "layout"
.PP
From broad to narrow: 0 > 1 > 2 > 3
.IP "\(bu" 4
0 \- layout off
.Sp
.Vb 8
\& .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.
\& | .. .. .. .. .. .. .. |   | .. .. .. .. .. .. .. |   | .. .. .. .. .. .. .. |   | .. .. .. .. .. .. .. |
\& |                      |   | .. .. .. .. .. .. .. |   | .. .. .. .. .. .. .. |   | .. .. .. .. .. .. .. |
\& |                      |   |                      |   | .. .. .. .. ..       |   | .. .. .. .. .. .. .. |
\& |                      |   |                      |   |                      |   | .. .. .. .. .. .. .. |
\& |                      |   |                      |   |                      |   | .. .. .. .. .. .. .. |
\& |                      |   |                      |   |                      |   | .. .. .. .. .. .. .. |
\& \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq
.Ve
.IP "\(bu" 4
1 \- layout \*(L"H\*(R" (default)
.Sp
.Vb 8
\& .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.
\& | .. .. .. .. .. .. .. |   | .. .. .. .. ..       |   | .. .. .. .. .. ..    |   | .. .. .. .. .. .. .. |
\& |                      |   | .. .. .. .. ..       |   | .. .. .. .. .. ..    |   | .. .. .. .. .. .. .. |
\& |                      |   | .. ..                |   | .. .. .. .. .. ..    |   | .. .. .. .. .. .. .. |
\& |                      |   |                      |   | .. .. .. .. .. ..    |   | .. .. .. .. .. .. .. |
\& |                      |   |                      |   | .. .. ..             |   | .. .. .. .. .. .. .. |
\& |                      |   |                      |   |                      |   | .. .. .. .. .. .. .. |
\& \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq
.Ve
.IP "\(bu" 4
2 \- layout \*(L"V\*(R"
.Sp
.Vb 8
\& .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.
\& | .. ..                |   | .. .. ..             |   | .. .. .. ..          |   | .. .. .. .. .. .. .. |
\& | .. ..                |   | .. .. ..             |   | .. .. .. ..          |   | .. .. .. .. .. .. .. |
\& | ..                   |   | .. .. ..             |   | .. .. .. ..          |   | .. .. .. .. .. .. .. |
\& |                      |   | .. ..                |   | .. .. ..             |   | .. .. .. .. .. .. .. |
\& |                      |   |                      |   | .. .. ..             |   | .. .. .. .. .. .. .. |
\& |                      |   |                      |   |                      |   | .. .. .. .. .. .. .. |
\& \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq
.Ve
.IP "\(bu" 4
3 \- all in a single column
.Sp
.Vb 8
\& .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.   .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.
\& | ..                   |   | ..                   |   | ..                   |   | ..                   |
\& | ..                   |   | ..                   |   | ..                   |   | ..                   |
\& | ..                   |   | ..                   |   | ..                   |   | ..                   |
\& |                      |   | ..                   |   | ..                   |   | ..                   |
\& |                      |   |                      |   | ..                   |   | ..                   |
\& |                      |   |                      |   |                      |   | ..                   |
\& \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq   \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq
.Ve
.PP
\fIll\fR
.IX Subsection "ll"
.PP
If all elements have the same length, the length can be passed with this option. \f(CW\*(C`choose\*(C'\fR then doesn't calculate the
length of the longest element itself but uses the passed value. \fIlength\fR refers here to the number of print columns
the element will use on the terminal.
.PP
If \fIll\fR is set, \f(CW\*(C`choose\*(C'\fR returns always the index(es) of the chosen item(s) regardless of how \fIindex\fR is set.
.PP
Undefined list elements are not allowed.
.PP
The replacements described in \*(L"Modifications for the output\*(R" are not applied. If elements contain unsupported
characters the output might break.
.PP
If \fIll\fR is set to a value less than the length of the elements, the output could break.
.PP
If \fIll\fR is set and the window size has changed, choose returns immediately \f(CW\*(C`\-1\*(C'\fR.
.PP
Allowed values: 1 or greater
.PP
(default: undefined)
.PP
\fImax_height\fR
.IX Subsection "max_height"
.PP
If defined sets the maximal number of rows used for printing list items.
.PP
If the available height is less than \fImax_height\fR then \fImax_height\fR is set to the available height.
.PP
Height in this context means print rows.
.PP
\&\fImax_height\fR overwrites \fIkeep\fR if \fImax_height\fR is set to a value less than \fIkeep\fR.
.PP
Allowed values: 1 or greater
.PP
(default: undefined)
.PP
\fImax_width\fR
.IX Subsection "max_width"
.PP
If defined, sets the maximal output width to \fImax_width\fR if the terminal width is greater than \fImax_width\fR.
.PP
To prevent the \*(L"auto-format\*(R" to use a width less than \fImax_width\fR set \fIlayout\fR to 0.
.PP
Width refers here to the number of print columns.
.PP
Allowed values: 1 or greater
.PP
(default: undefined)
.PP
\fImouse\fR
.IX Subsection "mouse"
.PP
0 \- off (default)
.PP
1 \- on. Enables the Any-Event-Mouse-Mode (1003) and the Extended-SGR-Mouse-Mode (1006).
.PP
If the option \fImouse\fR is enabled layers for \f(CW\*(C`STDIN\*(C'\fR are changed. Then before leaving \f(CW\*(C`choose\*(C'\fR as a cleanup \f(CW\*(C`STDIN\*(C'\fR
is marked as \f(CW\*(C`UTF\-8\*(C'\fR with \f(CW\*(C`:encoding(UTF\-8)\*(C'\fR. This doesn't apply if the \s-1OS\s0 is MSWin32.
.PP
If the \s-1OS\s0 is MSWin32 the mouse is enabled with the help of Win32::Console.
.PP
\fIorder\fR
.IX Subsection "order"
.PP
If the output has more than one row and more than one column:
.PP
0 \- elements are ordered horizontally
.PP
1 \- elements are ordered vertically (default)
.PP
Default may change in a future release.
.PP
\fIpad\fR
.IX Subsection "pad"
.PP
Sets the number of whitespaces between columns. (default: 2)
.PP
Allowed values: 0 or greater
.PP
\fIpage\fR
.IX Subsection "page"
.PP
0 \- off
.PP
1 \- print the page number on the bottom of the screen if there is more then one page. (default)
.PP
\fIprompt\fR
.IX Subsection "prompt"
.PP
If \fIprompt\fR is undefined a default prompt-string will be shown.
.PP
If the \fIprompt\fR value is an empty string ("") no prompt-line will be shown.
.PP
default in list and scalar context: \f(CW\*(C`Your choice:\*(C'\fR
.PP
default in void context: \f(CW\*(C`Close with ENTER\*(C'\fR
.PP
\fItabs_info\fR
.IX Subsection "tabs_info"
.PP
If \fIinfo\fR lines are folded, the option \fItabs_info\fR allows one to insert spaces at beginning of the folded lines.
.PP
The option \fItabs_info\fR expects a reference to an array with one or two elements:
.PP
\&\- the first element (initial tab) sets the number of spaces inserted at beginning of paragraphs
.PP
\&\- a second element (subsequent tab) sets the number of spaces inserted at the beginning of all broken lines apart
from the beginning of paragraphs
.PP
Allowed values: 0 or greater. Elements beyond the second are ignored.
.PP
(default: undefined)
.PP
\fItabs_prompt\fR
.IX Subsection "tabs_prompt"
.PP
If \fIprompt\fR lines are folded, the option \fItabs_prompt\fR allows one to insert spaces at beginning of the folded lines.
.PP
The option \fItabs_prompt\fR expects a reference to an array with one or two elements:
.PP
\&\- the first element (initial tab) sets the number of spaces inserted at beginning of paragraphs
.PP
\&\- a second element (subsequent tab) sets the number of spaces inserted at the beginning of all broken lines apart
from the beginning of paragraphs
.PP
Allowed values: 0 or greater. Elements beyond the second are ignored.
.PP
(default: undefined)
.PP
\fIundef\fR
.IX Subsection "undef"
.PP
Sets the string displayed on the screen instead an undefined element.
.PP
default: \*(L"<undef>\*(R"
.SS "Options List Context"
.IX Subsection "Options List Context"
\fIinclude_highlighted\fR
.IX Subsection "include_highlighted"
.PP
In list context when \f(CW\*(C`Return\*(C'\fR is pressed
.PP
0 \- \f(CW\*(C`choose\*(C'\fR returns the items marked with the \f(CW\*(C`SpaceBar\*(C'\fR. (default)
.PP
1 \- \f(CW\*(C`choose\*(C'\fR returns the items marked with the \f(CW\*(C`SpaceBar\*(C'\fR plus the highlighted item.
.PP
2 \- \f(CW\*(C`choose\*(C'\fR returns the items marked with the \f(CW\*(C`SpaceBar\*(C'\fR. If no items are marked with the \f(CW\*(C`SpaceBar\*(C'\fR, the
highlighted item is returned.
.PP
\fImark\fR
.IX Subsection "mark"
.PP
\&\fImark\fR expects as its value a reference to an array. The elements of the array are list indexes. \f(CW\*(C`choose\*(C'\fR preselects
the list-elements correlating to these indexes.
.PP
Elements greater than the last index of the list are ignored.
.PP
This option has only meaning in list context.
.PP
(default: undefined)
.PP
\fImeta_items\fR
.IX Subsection "meta_items"
.PP
\&\fImeta_items\fR 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 \f(CW\*(C`SpaceBar\*(C'\fR or with the right mouse key but if one of these elements is the highlighted item
it is added to the chosen items when \f(CW\*(C`Return\*(C'\fR is pressed.
.PP
Elements greater than the last index of the list are ignored.
.PP
This option has only meaning in list context.
.PP
(default: undefined)
.PP
\fIno_spacebar\fR
.IX Subsection "no_spacebar"
.PP
\&\fIno_spacebar\fR 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 \f(CW\*(C`SpaceBar\*(C'\fR or with the right mouse key.
.PP
If an element is preselected with the option \fImark\fR and also marked as not selectable with the option \fIno_spacebar\fR,
the user can not remove the preselection of this element.
.PP
\&\fIno_spacebar\fR elements greater than the last index of the list are ignored.
.PP
This option has only meaning in list context.
.PP
(default: undefined)
.SH "ERROR HANDLING"
.IX Header "ERROR HANDLING"
.SS "croak"
.IX Subsection "croak"
\&\f(CW\*(C`new|choose\*(C'\fR dies if passed invalid arguments.
.SS "carp"
.IX Subsection "carp"
If pressing a key results in an undefined value \f(CW\*(C`choose\*(C'\fR warns with \f(CW\*(C`EOT: $!\*(C'\fR and returns \fIundef\fR or an empty list in
list context.
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
.SS "Perl version"
.IX Subsection "Perl version"
Requires Perl version 5.8.3 or greater.
.SS "Optional modules"
.IX Subsection "Optional modules"
\fITerm::ReadKey\fR
.IX Subsection "Term::ReadKey"
.PP
If Term::ReadKey is available it is used \f(CW\*(C`ReadKey\*(C'\fR to read the user input and \f(CW\*(C`GetTerminalSize\*(C'\fR to get the
terminal size. Without \f(CW\*(C`Term::ReadKey\*(C'\fR \f(CW\*(C`getc\*(C'\fR is used to read the input and \f(CW\*(C`stty size\*(C'\fR to get the terminal size.
.PP
If the \s-1OS\s0 is MSWin32 it is used Win32::Console to read the user input and to get the terminal size.
.SS "Decoded strings"
.IX Subsection "Decoded strings"
\&\f(CW\*(C`choose\*(C'\fR expects decoded strings as array elements.
.SS "Encoding layer for \s-1STDOUT\s0"
.IX Subsection "Encoding layer for STDOUT"
For a correct output it is required an appropriate encoding layer for \s-1STDOUT\s0 matching the terminal's character set.
.SS "Monospaced font"
.IX Subsection "Monospaced font"
It is required a terminal that uses a monospaced font which supports the printed characters.
.SS "Ambiguous width characters"
.IX Subsection "Ambiguous width characters"
By default ambiguous width characters are treated as half width. If the environment variable \f(CW\*(C`TC_AMBIGUOUS_WIDE\*(C'\fR is set
to a true value, ambiguous width characters are treated as full width.
.SS "Escape sequences"
.IX Subsection "Escape sequences"
By default \f(CW\*(C`Term::Choose\*(C'\fR uses \f(CW\*(C`tput\*(C'\fR to get the appropriate escape sequences. Setting the environment variable
\&\f(CW\*(C`TC_ANSI_ESCAPES\*(C'\fR to a true value allows one to use \s-1ANSI\s0 escape sequences directly without calling \f(CW\*(C`tput\*(C'\fR.
.PP
.Vb 4
\&    BEGIN {
\&        $ENV{TC_ANSI_ESCAPES} = 1;
\&    }
\&    use Term::Choose qw( choose );
.Ve
.PP
The escape sequences to enable the \fImouse\fR mode are always hardcoded.
.SS "MSWin32"
.IX Subsection "MSWin32"
If the \s-1OS\s0 is MSWin32 Win32::Console and Win32::Console::ANSI with \s-1ANSI\s0 escape sequences are used. See also
\&\*(L"codepage_mapping\*(R".
.SH "SUPPORT"
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&    perldoc Term::Choose
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Matthäus Kiem <cuer2s@gmail.com>
.SH "CREDITS"
.IX Header "CREDITS"
Based on the \f(CW\*(C`choose\*(C'\fR function from the Term::Clui module.
.PP
Thanks to the Perl\-Community.de <http://www.perl-community.de> and the people form
stackoverflow <http://stackoverflow.com> for the help.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (C) 2012\-2021 Matthäus Kiem.
.PP
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 \s-1LICENSE.\s0