Term::Choose(3pm)

📦
version 1.782 · 7 versions
, in ubuntu stonking

💖 NAME 💖

Term::Choose — choose items from a list interactively. Yep, that's Term::Choose(3pm), a User Contributed Perl Documentation situation, and bestie it's about to be your new favorite module ✨

🌸 VERSION 🌸

Version 1.782 💅

🦋 SYNOPSIS 🦋

Okay so there's two whole ways to do this and both of them eat.

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. That's the whole vibe 🫶

Term::Choose gives you a functional interface (SUBROUTINES) and an object-oriented interface (METHODS). Both. At once. Iconic behavior honestly.

🍓 EXPORT 🍓

Nothing by default. Not a single thing, she's shy like that 🙈

use Term::Choose qw( choose );

So yeah — you gotta ask for choose, she's not gonna just show up.

👑 METHODS 👑

🌟 new

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

This constructor returns a new Term::Choose object. Brand new, fresh out the box 💖

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

For detailed information about the options see OPTIONS.

🌟 choose

The method choose allows the user to choose from a list. It's giving main character energy for real.

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.

Heads up bestie: options set with choose overwrite options set with new. Before leaving choose restores the overwritten options. So it's a temporary lil makeover, not a permanent one 💅
$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. So like, whenever the docs say one of those words, they mean that array. The one you handed over first. Periodt.

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. Same energy, different packaging 🎀

$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. Just the one. Singular. A whole little selection moment ✨

  • 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. Flip flopped. Reversed. Chaos mode unlocked 💀

  • 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). No bullying the user with overflow, we scroll like civilized people 🦋

If the window size is changed, then as soon as the user enters a keystroke choose rewrites the screen. She's adaptive.

choose returns undef or an empty list in list context if the q key (or Ctrl-Q) is pressed. Bailing out is valid and always allowed, no cap 🙈

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. Mouse girlies, you're covered too 🖱️

Pressing the Ctrl-F allows one to enter a regular expression so that only the items that match the regular expression are displayed. When going back to the unfiltered menu ("Enter") the item highlighted in the filtered menu keeps the highlighting. Also (in list context) marked items retain there markings. The Perl function readline is used to read the regular expression if Term::Form::ReadLine is not available. See option search. Filtering AND memory of what you were on?? That's the slay 🔥

🔑 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-P) to go to the previous page, the "PageDown" key (or Ctrl-N) to go to the next 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.

Vim keys, emacs keys, dedicated keys — pick your fighter 👑

🙈 Modifications for the output

For the output on the screen the array elements are modified. Yeah, visually. Chill.

Deep breath: 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. Your data stays exactly how you delivered it, no notes 💖

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. Truncated with a cute lil ... 🎀

⭐ OPTIONS ⭐

Options which expect a number as their value expect integers. Whole numbers only bestie, no decimals sneaking in.

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

bottom_text

Expects as its value a string. If set, the text is printed below the menu.

(default: not set)

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

Enable the support for ANSI SGR escape sequences.

  • 0 — off (default)
  • 1 — enabled but the current selected element is not colored.
  • 2 — enabled

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

Add a string in the bottom line.

If a footer string is passed with this option, the option page is automatically set to 2.

(default: undefined)

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.

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.

If max_height is set to a value less than keep, keep is set to max_height.

Allowed values: 1 or greater

(default: 5)

layout

  • 0 — layout off
.----------------------.   .----------------------.   .----------------------.   .----------------------.
| .. .. .. .. .. .. .. |   | .. .. .. .. .. .. .. |   | .. .. .. .. .. .. .. |   | .. .. .. .. .. .. .. |
|                      |   | .. .. .. .. .. .. .. |   | .. .. .. .. .. .. .. |   | .. .. .. .. .. .. .. |
|                      |   |                      |   | .. .. .. .. ..       |   | .. .. .. .. .. .. .. |
|                      |   |                      |   |                      |   | .. .. .. .. .. .. .. |
|                      |   |                      |   |                      |   | .. .. .. .. .. .. .. |
|                      |   |                      |   |                      |   | .. .. .. .. .. .. .. |
'----------------------'   '----------------------'   '----------------------'   '----------------------'
  • 1 — default


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

           2 - all in a single column

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

So yeah, layout 2 is the single-column glow-up, and layout 1 is the one where things fill down each column first. Slay.

Oh and super important: if layout is 0 or 1 and your unformatted list items happen to fit in one row, they get put in one row with no column formatting at all ✨. You can turn that lil behaviour off by setting max_cols. iykyk.

  • ll — okay so this one is for when literally every element is the same length 💅

If all elements have the same length, you can just pass that length in with this option. Then choose doesn't go calculate the length of the longest element itself — it just uses the value you handed it. length here means the number of print columns the element is gonna take up on the terminal, fr fr.

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

Undefined list elements are not allowed. Nope. Not today.

The replacements described in "Modifications for the output" are not applied. And if your elements contain unsupported characters, the output might just 💀 break.

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

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

Allowed values: 1 or greater

(default: undefined)

  • margin — personal space for your UI 🎀

The option margin lets you set a margin on all four sides. Iconic.

margin expects a reference to an array with four elements, in this exact order:

  1. top margin (number of terminal lines)
  2. right margin (number of terminal columns)
  3. bottom margin (number of terminal lines)
  4. left margin (number of terminal columns)

See also "tabs_info", "tabs_prompt" and "tabs_bottom_text".

Allowed values: 0 or greater. Elements beyond the fourth are just ignored, they don't get a say.

(default: undefined)

  • max_cols — caps how many columns you're allowed to have 🌈

Limit the number of columns to max_cols.

And psst — layout set to 2 has always one column. Always. No negotiation.

Allowed values: 1 or greater

(default: undefined)

  • max_height — a height limit but make it print rows 🦋

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

If the available height is less than max_height, then max_height gets set to the available height. The terminal said no and honestly, fair.

Height in this context means print rows.

Heads up: max_height overwrites keep if max_height is set to a value less than keep. 😭

Allowed values: 2 or greater

(default: undefined)

  • max_width — width cap bestie ✨

If defined, sets the maximal output width to max_width if the terminal width is greater than max_width.

To prevent the "auto-format" from using a width less than max_width, set layout to 0. Not me telling you the cheat code.

Width here means the number of print columns.

Allowed values: 2 or greater

(default: undefined)

  • mouse — do you want the mouse in on this or not 🐭💖
    • 0 — off (default)
    • 1 — on. This 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. Cute.

  • order — which way do the elements flow bestie ⭐

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. So like, don't get too attached. 🙈

  • pad — the lil breathing room between your columns 🍓

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

Allowed values: 0 or greater

  • page — page numbers, but make it a vibe 📄✨
    • 0 — off
    • 1 — print the page number on the bottom of the screen. If all the choices fit into one page, the page number is not displayed. (default)
    • 2 — the page number is always displayed even with only one page. Setting page to 2 automatically enables the option "clear_screen".
  • prompt — the lil text asking you what you want 🫶

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. Just pure silence. Peaceful honestly.

default in list and scalar context: "Your choice:"

default in void context: "Close with ENTER"

  • search — how Ctrl-F is gonna behave 🔍
    • 0 — off
    • 1 — case-insensitive search (default)
    • 2 — case-sensitive search
  • skip_items — these elements are getting ghosted 👻

When navigating through the list, the elements that match the regex pattern passed with this option will be skipped.

In list context: these elements cannot be marked.

Expected value: a regex quoted with the qr operator.

(default: undefined)

  • tabs_bottom_text — tab formatting for your bottom text 🎀

Expects a reference to an array with one to five elements:

  • The 1st element (initial tab) specifies the number of spaces inserted at the beginning of paragraphs.
  • The 2nd element (subsequent tab) specifies the number of spaces inserted at the beginning of wrapped lines (excluding paragraph starts).
  • The 3rd element specifies the number of spaces used as the left margin.
  • The 4th element specifies the number of spaces used as the right margin.
  • The 5th element specifies the maximum output width.

Allowed values:

  • For the first four elements: 0 or greater
  • For the fifth element: 2 or greater

If tabs_bottom_text is not defined:

  • If margin is defined, its values are used for the left and right margins.
  • If max_width is defined, it is used as the maximum output width.
  • tabs_info — works the exact same way as "tabs_bottom_text" 💫
  • tabs_prompt — also works the exact same way as "tabs_bottom_text" 💫
  • undef — what shows up when a thing is undefined 💀

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

default: "<undef>"

💖 Options List Context 💖

okay so these ones only hit different in list context, got it?

  • include_highlighted — what happens when you hit Return in list context ⭐

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 — preselecting your faves ahead of time 💅

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. They simply do not exist to this option.

This option has only meaning in list context.

(default: undefined)

  • meta_items — special lil items that play by their own rules 👑

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 — these ones are un-markable bestie, sorry 🙈

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. Stuck with it. Periodt.

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" croaks if passed invalid arguments. So like, don't do that. It will yell at you.

carp 🐟

If pressing a key results in an undefined value, choose carps with "EOT: $!" and returns undef or an empty list in list context. Rude but honest. 😭

🫶 REQUIREMENTS 🫶

okay bestie, before you go feral with this module, here's the vibe check on what you actually need 💅

💜 Perl version

Requires Perl version 5.10.1 or higher. no ancient perls allowed, sorry babe 🎀

✨ Optional modules ✨

  • Term::Choose::LineFold::XS — if it's installed, its functions get used automatically in place of the pure-Perl implementations, and that gives you faster performance. lowkey iconic. heads up though: "Term::Choose::LineFold::XS" requires Perl version 5.16.0 or higher 🌸
  • Term::ReadKey — if it's available, ReadKey is used to read the user input and GetTerminalSize to get the terminal size. no Term::ReadKey? then it's getc for reading the input and stty size for the terminal size. she adapts, she's flexible 😌
  • and if the OS is MSWin32, it is used Win32::Console to read the user input and to get the terminal size. Windows girlies, you're covered 💖

🌈 Decoded strings

choose expects decoded strings as array elements. like, genuinely decoded. don't come at her with bytes, she will not be serving that 🙈

🦋 Encoding layer for STDOUT

for a correct output it is required an appropriate encoding layer for STDOUT matching the terminal's character set. match the vibe of your terminal or the output gets weird, fr fr 💀

🎀 Monospaced font

it is required a terminal that uses a monospaced font which supports the printed characters. non-mono fonts? that's a no from her ✋

📏 Minimum terminal size

the minimum terminal size is 4 x 2. that's it. that's the whole floor. tiny window, cute, valid 🫶

💅 Ambiguous width characters

by default ambiguous width characters are treated as half width. but if the environment variable TC_AMBIGUOUS_WIDTH_IS_WIDE is set to a true value, ambiguous width characters are treated as full width.

heads up bestie: the support for the old variable name TC_AMBIGUOUS_WIDE will be removed. so stop using it, queen, it's on the way out 😭

💀 Escape sequences

by default Term::Choose uses tput to get the appropriate escape sequences. if the environment variable TC_ANSI_ESCAPES is set to a true value, hardcoded ANSI escape sequences are used directly without calling tput.

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

🍓 Other environment variables

if the environment variable TC_RESET_AUTO_UP existed when calling choose:

  • TC_RESET_AUTO_UP is set to 0 if the LINE_FEED/CARRIAGE_RETURN key was the only key pressed
  • TC_RESET_AUTO_UP is set to 1 if other keys than LINE_FEED/CARRIAGE_RETURN were also pressed

that's the whole little bookkeeping situation, no cap 📝

🧚 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. look at her, documented AND accessible, we stan 👑

perldoc Term::Choose

👑 AUTHOR 👑

Matthäus Kiem <cuer2s@gmail.com>

the mastermind. the moment. the author 💜

🌟 CREDITS 🌟

based on the choose function from the Term::Clui module. everything starts somewhere bestie 🦋

thanks to the Perl-Community.de <http://www.perl-community.de> and the people at stackoverflow <http://stackoverflow.com> for the help. real ones fr fr 🙌

copyright (C) 2012-2026 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. go read it, it's giving legally binding but make it fashion 💅📜

and that's the whole page, bestie 🎀 this was Term::Choose(3pm) from perl v5.40.1, dated 2026-05-06. now go pick some stuff on a terminal and absolutely ate ✨🫶💖

📦 where this page comes from