NAME

Term::Choose - Choose items from a list.

VERSION

Version 0.7.2

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";

DESCRIPTION

Choose from a list of elements.

Requires Perl Version 5.10.1 or greater.

EXPORT

Nothing by default.

use Term::Choose qw(choose);

SUBROUTINES/METHODS

choose

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

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

The first argument (array reference) passes the elements available for selection.

If choose is called in a scalar context, the user can choose an item by using the "move-around-keys" and "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 the items of the list don't fit in the screen, the user can scroll to the next (previous) page(s).

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.

If the option extra_key is enabled pressing "e" calls exit().

Keys to move around: arrow keys (or hjkl), Tab, BackSpace, Shift-Tab.

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

  • if a list-element contains white-spaces this substitution is applied:

    $element =~ s/\p{Space}/ /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.

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 max_list items (default 100_000) choose dies.

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.

OPTIONS

All options are optional.

Defaults may change in a future release.

prompt

If prompt is undefined default prompt-string will be shown.

If prompt is 0 no prompt-line will be shown.

default: 'Your choice:'

right_justify

  • 0 - columns are left-justified (default)

  • 1 - columns are right-justified

layout

  • 0 - layout off

    .-----------------------------.   .-----------------------------.   .-----------------------------.
    |... .. .... ... .... ... ... |   |.... .... .... .... .... ....|   |.... .... .... .... .... ....|
    |                             |   |.... .... .... .... .... ....|   |.... .... .... .... .... ....|
    |                             |   |....                         |   |.... .... .... .... .... ....|
    |                             |   |                             |   |.... .... .... .... .... ....|
    |                             |   |                             |   |.... .... .... .... .... ....|
    |                             |   |                             |   |.... .... .... .... .... ....|
    |                             |   |                             |   |.... .... .... .... .... ....|
    |                             |   |                             |   |.... .... .... .... .... ....|
    '-----------------------------'   '-----------------------------'   '-----------------------------'
  • 1 - layout "H" (default)

    .-----------------------------.   .-----------------------------.   .-----------------------------.
    |... .. .... ... .... ... ... |   |.... .... .... ....          |   |.... .... .... .... .... ....|
    |                             |   |.... .... .... ....          |   |.... .... .... .... .... ....|
    |                             |   |.... .... .... ....          |   |.... .... .... .... .... ....|
    |                             |   |.... ....                    |   |.... .... .... .... .... ....|
    |                             |   |                             |   |.... .... .... .... .... ....|
    |                             |   |                             |   |.... .... .... .... .... ....|
    |                             |   |                             |   |.... .... .... .... .... ....|
    |                             |   |                             |   |.... .... .... .... .... ....|
    '-----------------------------'   '-----------------------------'   '-----------------------------'
  • 2 - all in a single column

    .-----------------------------.   .-----------------------------.   .-----------------------------.
    |....                         |   |....                         |   |....                         |
    |....                         |   |....                         |   |....                         |
    |...                          |   |...                          |   |...                          |
    |....                         |   |....                         |   |....                         |
    |                             |   |....                         |   |....                         |
    |                             |   |....                         |   |....                         |
    |                             |   |                             |   |....                         |
    |                             |   |                             |   |....                         |
    '-----------------------------'   '-----------------------------'   '-----------------------------'
  • 3 - layout "V"

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

screen_width

If set, restricts the screen width to screen_width percentage of the effective screen width.

If not defined all the screen-width is used.

Allowed values: 10 - 99

(default: undef)

vertical_order

  • 0 - items ordered horizontally

  • 1 - items ordered vertically (default)

clear_screen

  • 0 - off (default)

  • 1 - clears the screen before printing the choices

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

pad

space between columns (default: 2)

allowed values: 0 - 99

pad_one_row

space between items if we have only one row (default: 3)

allowed values: 0 - 99

extra_key

  • 0 - off

  • 1 - on: pressing key "e" calls exit() (default)

beep

  • 0 - off (default)

  • 1 - on

hide_cursor

  • 0 - off

  • 1 - on (default)

undef

string displayed on the screen instead a undefined list-element

default: '<undef>'

empty_string

string displayed on the screen instead an empty string

default: '<empty>'

max_list

maximal allowed length of the list referred by the first argument (default: 100_000)

allowed values: 1 - 999_999_999

REQUIREMENTS

Perl Version

Requires Perl Version 5.10.1 or greater.

Modules

Apart from the core-modules Exporter and Carp these modules are used:

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 option "hide_cursor" is enabled:

"\e[?25l"   Hide Cursor (DECTCEM)

"\e[?25h"   Show Cursor (DECTCEM)  

If option "clear_screen" is enabled:

"\e[2J"     Clear Screen (Erase Data)

"\e[0;0H"   Go to Top Left (Cursor Position)

If option "mouse_mode" is set:

"\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.

SUPPORT

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

perldoc Term::Choose

AUTHOR

Kuerbis 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 Kuerbis.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.