Term::Choose::Util - TUI-related functions for selecting directories, files, numbers and subsets of lists.
Version 0.103
Functional interface:
use Term::Choose::Util qw( choose_a_directory ); my $chosen_directory = choose_a_directory();
Object-oriented interface:
use Term::Choose::Util; my $ob = Term::Choose->new (); my $chosen_directory = $ob->choose_a_directory();
See "SUBROUTINES".
This module provides TUI-related functions for selecting directories, files, numbers and subsets of lists.
Nothing by default.
Values in brackets are default values.
Options are passed as a hash reference. The options argument is the last (or the only) argument.
clear_screen
If enabled, the screen is cleared before the output.
Values: [0],1.
color
Enables the support for color and text formatting escape sequences.
hide_cursor
Hide the cursor
Values: 0,[1].
info
A string placed on top of of the output.
Default: undef
mouse
Enable the mouse mode. An item can be chosen with the left mouse key, the right mouse key can be used instead of the SpaceBar key.
current_selection_label
The value of current_selection_label is a string which is placed in front of the "chosen so far" info output.
With settings_menu the "chosen so far" info output is only shown if current_selection_label is defined.
settings_menu
Defaults: choose_directories: 'Dirs: ', choose_a_directory: 'Dir: ', choose_a_file: 'File: ', choose_a_number: ' >', choose_a_subset: '', settings_menu: undef
choose_directories
choose_a_directory
choose_a_file
choose_a_number
choose_a_subset
The "chosen so far" info output is placed between the info string and the prompt string.
prompt
A string placed on top of the available choices.
back
Customize the string of the menu entry "back".
Default: BACK
BACK
confirm
Customize the string of the menu entry "confirm".
Default: CONFIRM.
CONFIRM
$ob = Term::Choose::Util->new( { mouse => 1, ... } );
Returns a new Term::Choose::Util object.
Options: all
$chosen_directory = choose_a_directory( { layout => 1, ... } )
With choose_a_directory the user can browse through the directory tree and choose a directory which is then returned.
To move around in the directory tree:
- select a directory and press Return to enter in the selected directory.
Return
- choose the "parent_dir" menu entry to move upwards.
To return the current working-directory as the chosen directory choose the "confirm" menu entry.
The "back" menu entry causes choose_a_directory to return nothing.
Options:
alignment
Elements in columns are aligned to the left if set to 0, aligned to the right if set to 1 and centered if set to 2.
Values: [0],1,2.
decoded
If enabled, the directory name is returned decoded with locale_fs form Encode::Locale.
locale_fs
enchanted
If set to 1, the default cursor position is on the "parent_dir" menu entry. If the directory name remains the same after an user input, the default cursor position changes to "back".
If set to 0, the default cursor position is on the "back" menu entry.
init_dir
Set the starting point directory. Defaults to the home directory.
If the option decoded is enabled (default), init_dir expects the directory path as a decoded string.
layout
See the option layout in Term::Choose
Values: 0,[1],2,3.
order
If set to 1, the items are ordered vertically else they are ordered horizontally.
This option has no meaning if layout is set to 3.
show_hidden
If enabled, hidden directories are added to the available directories.
parent_dir
Customize the string of the menu entry "parent_dir".
Default: PARENT
PARENT
$chosen_file = choose_a_file( { show_hidden => 0, ... } )
Browse the directory tree the same way as described for choose_a_directory. Select the "show_files" menu entry to get the files of the current directory. To return the chosen file select the "confirm" menu entry.
Options as in "choose_a_directory" plus
show_files
Customize the string of the menu entry "show_files".
Default: SHOW_FILES
SHOW_FILES
$chosen_directories = choose_directories( { mouse => 1, ... } )
choose_directories is similar to choose_a_directory but it is possible to return multiple directories.
Use the "add_dir" menu entry to add the current directory to the list of chosen directories.
To return the list of chosen directories (as an array reference) select the "confirm" menu entry.
The "back" menu entry removes the last added directory. If the list of chosen directories is empty, "back" causes choose_directories to return nothing.
add_dir
Customize the string of the menu entry "add_dir".
Default: ADD_DIR
ADD_DIR
$new = choose_a_number( 5, { current_selection_label => 'Number: ', ... } );
This function lets you choose/compose a number (unsigned integer) which is returned.
The fist argument is an integer and determines the range of the available numbers. For example setting the first argument to 4 would offer a range from 0 to 9999.
small_first
Put the small number ranges on top.
thousands_separator
Sets the thousands separator.
Default: ,
,
$subset = choose_a_subset( \@available_items, { current_selection_label => 'new> ', ... } )
choose_a_subset lets you choose a subset from a list.
The first argument is a reference to an array which provides the available list.
index
If true, the index positions in the available list of the made choices are returned.
keep_chosen
If enabled, the chosen items are not removed from the available choices.
Values: [0],1;
See the option layout in Term::Choose.
Values: 0,1,2,[3].
mark
Expects as its value a reference to an array with indexes. Elements corresponding to these indexes are pre-selected when choose_a_subset is called.
prefix
prefix expects as its value a string. This string is put in front of the elements of the available list in the menu. The chosen elements are returned without this prefix.
Default: empty string.
current_selection_begin
Info output: the current_selection_begin string is placed between the current_selection_label string and the chosen elements as soon as an element has been chosen.
Default: empty string
current_selection_separator
Info output: current_selection_separator is placed between the chosen list elements.
current_selection_end
Info output: as soon as elements have been chosen the current_selection_end string is placed at the end of the chosen elements.
To return the chosen subset (as an array reference) select the "confirm" menu entry.
The "back" menu entry removes the last added chosen items. If the list of chosen items is empty, "back" causes choose_a_subset to return nothing.
$menu = [ [ 'enable_logging', "- Enable logging", [ 'NO', 'YES' ] ], [ 'case_sensitive', "- Case sensitive", [ 'NO', 'YES' ] ], [ 'attempts', "- Attempts" , [ '1', '2', '3' ] ] ]; $config = { 'enable_logging' => 1, 'case_sensitive' => 1, 'attempts' => 2 }; settings_menu( $menu, $config );
The first argument is a reference to an array of arrays. These arrays have three elements:
the unique name of the option
the prompt string
an array reference with the available values of the option.
The second argument is a hash reference:
the keys are the option names
the values (0 if not defined) are the indexes of the current value of the respective key/option.
0
When settings_menu is called, it displays for each array entry a row with the prompt string and the current value. It is possible to scroll through the rows. If a row is selected, the set and displayed value changes to the next. After scrolling through the list once the cursor jumps back to the top row.
If the "back" menu entry is chosen, settings_menu does not apply the made changes and returns nothing. If the "confirm" menu entry is chosen, settings_menu applies the made changes in place to the passed configuration hash-reference (second argument) and returns the number of made changes.
Setting the option current_selection_label to a defined value adds an info output line.
choose_a_dir
The function choose_a_dir is deprecated. Use choose_a_directory instead.
choose_dirs
The function choose_dirs is deprecated. Use choose_directories instead.
justify
The option justify is deprecated. Use alignment instead.
dir
The option dir is deprecated. Use init_dir instead.
up
The option up is deprecated. Use parent_dir instead.
name
The option name is deprecated. Use current_selection_label instead.
thsd_sep
The option thsd_sep is deprecated. Use thousands_separator instead.
sofar_begin
The option sofar_begin is deprecated. Use current_selection_begin instead.
sofar_separator
The option sofar_separator is deprecated. Use current_selection_separator instead.
sofar_end
The option sofar_end is deprecated. Use current_selection_end instead.
Deprecated functions and options will be removed.
Requires Perl version 5.8.3 or greater.
Ensure the encoding layer for STDOUT, STDERR and STDIN are set to the correct value.
You can find documentation for this module with the perldoc command.
perldoc Term::Choose::Util
Matthäus Kiem <cuer2s@gmail.com>
Thanks to the Perl-Community.de and the people form stackoverflow for the help.
Copyright 2014-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.
To install Term::Choose::Util, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Term::Choose::Util
CPAN shell
perl -MCPAN -e shell install Term::Choose::Util
For more information on module installation, please visit the detailed CPAN module installation guide.