NAME
Term::Choose::Util - TUI-related functions for selecting directories, files, numbers and subsets of lists.
VERSION
Version 0.142
SYNOPSIS
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".
DESCRIPTION
This module provides TUI-related functions for selecting directories, files, numbers and subsets of lists.
EXPORT
Nothing by default.
SUBROUTINES
Values in brackets are default values.
Options are passed as a hash reference. The options argument is the last (or the only) argument.
Options available for all subroutines
back
Customize the string of the menu entry "back".
Default:
BACK
clear_screen
If enabled, the screen is cleared before the output.
Values: [0],1,2.
color
Setting color to
1
enables the support for color and text formatting escape sequences except for the current selected element. If set to2
, also for the current selected element the color support is enabled (inverted colors).Values: [0],1,2.
confirm
Customize the string of the menu entry "confirm".
Default:
CONFIRM
.cs_label
The value of cs-label (current selection label) is a string which is placed in front of the current selection.
Defaults:
choose_directories
: 'Chosen Dirs: ',choose_a_directory
: 'Directory: ',choose_a_file
: 'File: '. Forchoose_a_number
,choose_a_subset
andsettings_menu
the default is undefined.The current-selection output is placed between the info string and the prompt string.
hide_cursor
Hide the cursor
Values: 0,[1].
info
A string placed on top of of the output.
Default: undef
margin
The option margin allows one to set a margin on all four sides.
margin expects a reference to an array with four elements in the following order:
- top margin (number of terminal lines)
- right margin (number of terminal columns)
- botton margin (number of terminal lines)
- left margin (number of terminal columns)
margin does not affect the info string. To add margins to the info string see tabs_info.
margin changes the default values of tabs_prompt.
Allowed values: 0 or greater. Elements beyond the fourth are ignored.
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.
Values: [0],1.
prompt
A string placed on top of the available choices. prompt set to the empty string means no prompt line.
Default:
Your choice:
tabs_info
The option tabs_info allows one to insert spaces at the beginning and the end of info lines.
tabs_info expects a reference to an array with one to three elements:
- the first element (initial tab) sets the number of spaces inserted at beginning of paragraphs
- the second element (subsequent tab) sets the number of spaces inserted at the beginning of all broken lines apart from the beginning of paragraphs
- the third element sets the number of spaces used as a right margin.
Allowed values: 0 or greater. Elements beyond the third are ignored.
Default: undef
default: If margin is defined, the initial tab and the subsequent tab are set to left-margin and the right margin is et to right-margin. If margin is not defined the default is undefined.
tabs_prompt
The option tabs_prompt allows one to insert spaces at the beginning and the end of prompt lines.
tabs_prompt expects a reference to an array with one to three elements:
- the first element (initial tab) sets the number of spaces inserted at beginning of paragraphs
- the second element (subsequent tab) sets the number of spaces inserted at the beginning of all broken lines apart from the beginning of paragraphs
- the third element sets the number of spaces used as a right margin.
Allowed values: 0 or greater. Elements beyond the third are ignored.
default: If margin is defined, the initial tab and the subsequent tab are set to left-margin and the right margin is set to right-margin.
choose-directories
andchoose-a-subset
: +2 for the subsequent tab. Else the default is undefined.
new
$ob = Term::Choose::Util->new( { mouse => 1, ... } );
Returns a new Term::Choose::Util object.
Options: all
choose_a_directory
$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.
- choose the "..
" (parent directory) 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.
These options can be passed in a hash-reference:
alignment
Elements in columns are aligned to the left if set to
0
, aligned to the right if set to1
and centered if set to2
.Values: [0],1,2.
decoded
If enabled, the directory name is returned decoded with
locale_fs
form Encode::Locale.Values: 0,[1].
init_dir
Set the starting point directory. Defaults to the home directory.
init_dir expects the directory path as a decoded string.
layout
See the option layout in Term::Choose
Values: 0,[1],2.
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
2
.Values: 0,[1].
parent_dir
Customize the string of the menu entry "parent_dir".
Default:
..
show_hidden
If enabled, hidden directories are added to the available directories.
Values: 0,[1].
choose_a_file
$chosen_file = choose_a_file( { show_hidden => 0, ... } )
Choose the file directory and then choose a file from the chosen directory. To return the chosen file select the "confirm" menu entry.
These options can be passed in a hash-reference:
alignment
Elements in columns are aligned to the left if set to
0
, aligned to the right if set to1
and centered if set to2
.Values: [0],1,2.
decoded
If enabled, the directory name is returned decoded with
locale_fs
form Encode::Locale.Values: 0,[1].
filter
If set, the value of this option is used as a glob pattern. Only files matching this pattern will be displayed.
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.
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
2
.Values: 0,[1].
prompt2
While prompt is used in the directory menu, prompt2 is the prompt in the menu where you select the file.
If prompt2 is set to the empty string, no prompt line is displayed.
Default: value of prompt
show_hidden
If enabled, hidden directories are added to the available directories.
Values: 0,[1].
choose_directories
$chosen_directories = choose_directories( { mouse => 1, ... } )
choose_directories
is similar to choose_a_directory
but it is possible to return multiple directories.
Options:
alignment
Elements in columns are aligned to the left if set to
0
, aligned to the right if set to1
and centered if set to2
.Values: [0],1,2.
decoded
If enabled, the directory name is returned decoded with
locale_fs
form Encode::Locale.Values: 0,[1].
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.
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
2
.Values: 0,[1].
prompt2
While prompt is used in the "Change Location" menu, prompt2 is the prompt in the menu where you select the directories.
If prompt2 is set to the empty string, no prompt line is displayed.
Default: value of prompt
show_hidden
If enabled, hidden directories are added to the available directories.
Values: 0,[1].
choose_a_number
$new = choose_a_number( 5, { cs_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.
With the optional second argument (hash-reference), these options can be passed:
default_number
Set a default number (unsigned integer in the range of the available numbers).
Default: undef
small_first
Put the small number ranges on top.
Default: off
thousands_separator
Sets the thousands separator.
Default:
,
The current-selection line is shown if cs_label is defined or as soon as a number has been chosen.
choose_a_subset
$subset = choose_a_subset( \@available_items, { cs_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.
With the optional second argument (hash-reference), these options can be passed:
all_by_default
If enabled, all elements are selected if CONFIRM is chosen without any selected elements.
Values: [0],1.
alignment
Elements in columns are aligned to the left if set to
0
, aligned to the right if set to1
and centered if set to2
.Values: [0],1,2.
cs_begin
Current selection: the cs_begin string is placed between the cs_label string and the chosen elements as soon as an element has been chosen.
Default: empty string
cs_end
Current selection: as soon as elements have been chosen the cs_end string is placed at the end of the chosen elements.
Default: empty string
cs_separator
Current selection: the cs_separator is placed between the chosen list elements.
Default:
,
index
If true, the index positions in the available list of the made choices are returned.
Values: [0],1.
keep_chosen
If enabled, the chosen items are not removed from the available choices.
Values: [0],1;
layout
See the option layout in Term::Choose.
Values: 0,1,[2].
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.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 2.
Values: 0,[1].
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.
The current-selection line is shown if cs_label is defined or as soon as elements have been chosen.
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.
settings_menu
$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.If an index is out of bonds, it is set to
0
.
With the optional third argument (hash-reference), these options can be passed:
cs_begin
Current selection: the cs_begin string is placed between the cs_label string and the chosen elements as soon as an element has been chosen.
Default: empty string
cs_end
Current selection: as soon as elements have been chosen the cs_end string is placed at the end of the chosen elements.
Default: empty string
cs_separator
Current selection: the cs_separator is placed between the chosen list elements.
Default:
,
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 (undefined values are skipped). 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 cs_label to a defined value adds an info output line.
REQUIREMENTS
Perl version
Requires Perl version 5.10.0 or greater.
Encoding layer
Ensure the encoding layer for STDOUT, STDERR and STDIN are set to the correct value.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Term::Choose::Util
AUTHOR
Matthäus Kiem <cuer2s@gmail.com>
CREDITS
Thanks to the Perl-Community.de and the people form stackoverflow for the help.
LICENSE AND COPYRIGHT
Copyright 2014-2024 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.