NAME
Term::Choose::Util - CLI related functions.
VERSION
Version 0.003
SYNOPSIS
See "SUBROUTINES".
DESCRIPTION
This module is experimental.
This module provides some CLI related functions required by App::DBBrowser, Term::TablePrint and App::YTDL.
EXPORT
Nothing by default.
SUBROUTINES
Ensure the encoding layer for STDOUT, STDERR and STDIN are set to the correct value.
Values in brackets are default values.
Unknown option names are ignored.
To get informations about the different mouse modes see mouse at "OPTIONS" in Term::Choose.
choose_a_directory
$chosen_directory = choose_a_directory( $dir, { layout => 1 } )With choose_a_directory the user can browse through the directory tree (as far as the granted rights permit it) and choose a directory which is returned.
The first argument is the starting point directory.
The second and optional argument is a reference to a hash. With this hash it can be set the different options:
show_hidden
If enabled, hidden directories are added to the available directories.
Values: 0,[1].
layout
See layout at "OPTIONS" 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.
Values: 0,[1].
clear_screen
If enabled, the screen is cleared before the output.
Values: 0,[1].
mouse
Set the mouse mode.
Values: [0],1,2,3,4.
choose_a_number
for ( 1 .. 5 ) {
$current = $new
$new = choose_a_number( 5, { current => $current, name => 'Testnumber' } );
}This function lets you choose/compose a number (unsigned integer) which is returned.
The fist argument - "digits" - is an integer and determines the range of the available numbers. For example setting the first argument to 6 would offer a range from 0 to 999999.
The second and optional argument is a reference to a hash with these keys (options):
current
The current value. If set two prompt lines are displayed - one for the current number and one for the new number.
name
Sets the name of the number seen in the prompt line.
Default: empty string ("");
thsd_sep
Sets the thousands separator.
Default: comma (,).
clear_screen
If enabled, the screen is cleared before the output.
Values: 0,[1].
mouse
Set the mouse mode.
Values: [0],1,2,3,4.
choose_a_subset
$subset = choose_a_subset( \@available_items, { current => \@current_subset } )choose_a_subset lets you choose a subset from a list.
As a first argument it is required a reference to an array which provides the available list.
The optional second argument is a hash reference. The following options are available:
current
This option expects as its value the current subset (a reference to an array). If set two prompt lines are displayed - one for the current subset and one for the new subset.
The subset is returned as an array reference.
layout
See layout at "OPTIONS" 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.
Values: 0,[1].
clear_screen
If enabled, the screen is cleared before the output.
Values: 0,[1].
mouse
Set the mouse mode.
Values: [0],1,2,3,4.
choose_multi
$tmp = choose_multi( $menu, $config, { in_place => 0 } )
if ( defined $tmp ) {
for my $key ( keys %$tmp ) {
$config->{$key} = $tmp->{$key};
}
}The first argument is a reference to an array of arrays. These arrays have three elements:
the key/option name
the prompt string
an array reference with the possible values related to the key/option.
The second argument is a hash reference:
the keys are the option names
the values are the indexes of the current value of the respective key.
$menu = [
[ 'enable_logging', "- Enable logging", [ 'NO', 'YES' ] ],
[ 'case_sensitive', "- Case sensitive", [ 'NO', 'YES' ] ],
...
];
$config = {
'enable_logging' => 0,
'case_sensitive' => 1,
...
};The optional third argument is a reference to a hash. The keys are
in_place
If enabled the configuration hash (passed as second argument) is edited in place.
Values: 0,[1].
clear_screen
If enabled, the screen is cleared before the output.
Values: 0,[1].
mouse
Set the mouse mode.
Values: [0],1,2,3,4.
When choose_multi 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. If the end of the list of the values is reached it begins from the beginning of the list.
choose_multi returns nothing if no changes are made. If the user has changed values and in_place is set to 1 choose_multi modifies the hash passed as the second argument in place and returns 1. With the option in_place set to 0 choose_multi does no in place modifications but modifies a copy of the configuration hash. A reference to that modified copy is then returned.
insert_sep
$integer = insert_sep( $integer, $separator );Inserts a thousands separator.
The following substitution is applied to the integer passed with the first argument:
$integer =~ s/(\d)(?=(?:\d{3})+\b)/$1$separator/g;After the substitution the number is returned.
If the first argument is not defined it is returned nothing immediately.
A thousands separator can be passed with a second argument.
The thousands separator defaults to a comma (,).
length_longest
length_longest expects as its argument a list of decoded strings passed a an array reference.
$longest = length_longest( \@elements );
( $longest, $length ) = length_longest( \@elements );In scalar context length_longest returns the length of the longest string - in list context it return a list where the the first item is the length of the longest string and the second is a reference to an array where the elements are the length of the corresponding elements from the array (reference) passed as the argument.
Length means here number of print columns as returned by the columns method from Unicode::GCString.
print_hash
Prints a simple hash to STDOUT (or STDERR if the output is redirected). Nested hashes are not supported. If the hash has more keys than the terminal rows the output is divided up on several pages. The user can scroll through the single lines of the hash. The output of the hash is closed, when the user presses Return.
The first argument is the hash to be printed passed as a reference.
The optional second argument is also a hash reference which allows to set the following options:
keys
The keys which should be printed in the given order. The keys are passed with an array reference. Keys which don't exist are ignored. If not set keys defaults to
[ sort keys %$hash ]len_key
The value sets the available print width for the keys. The default value is the length (of print columns) of the longest key.
If the available width for the values is less than one third of the total available width the keys are trimmed until the available width for the values is at least one third of the total available width.
maxcols
The maximum width of the output. If not set or set to 0 or set to a value higher than the terminal width the maximum terminal width is used instead.
left_margin
left_margin is added to len_key. It defaults to 1.
right_margin
The right_margin is subtracted from maxcols if maxcols is the maximum terminal width. The default value is 2.
clear_screen
If enabled, the screen is cleared before the output.
Values: 0,[1].
mouse
Set the mouse mode.
Values: [0],1,2,3,4.
term_size
term_size returns the current terminal width and the current terminal height.
( $width, $height ) = term_size()If the OS is MSWin32 Size from Win32::Console is used to get the terminal width and the terminal height else GetTerminalSize form Term::ReadKey is used.
On MSWin32 OS, if it is written to the last column on the screen the cursor goes to the first column of the next line. To prevent this newline when writing to a Windows terminal term_size subtracts 1 from the terminal width before returning the width if the OS is MSWin32.
unicode_sprintf
$unicode = unicode_sprintf( $unicode, $available_width, $rightpad );unicode_sprintf expects 2 or 3 arguments: the first argument is a decoded string, the second argument is the available width and the third and optional argument tells how to pad the string.
If the length of the string is greater than the available width it is truncated to the available width. If the string is equal to the available width nothing is done with the string. If the string length is less than the available width, unicode_sprintf adds spaces to the string until the string length is equal to the available width. If the third argument is set to a true value, the spaces are added at the beginning of the string else they are added at the end of the string.
Length or width means here number of print columns as returned by the columns method from Unicode::GCString.
unicode_trim
$unicode = unicode_trim( $unicode, $length )The first argument is a decoded string, the second argument is the length.
If the string is longer than passed length it is trimmed to that length at the right site and returned else the string is returned as it is.
Length means here number of print columns as returned by the columns method from Unicode::GCString.
util_readline
util_readline reads a line.
$string = util_readline( $prompt, { no_echo => 0 } )The fist argument is the prompt string. The optional second argument is a reference to a hash. The only key/option is
no_echo
Values: [0],1.
util_readline returns undef if Strg-D is pressed independently of whether the input buffer is empty or filled.
It is not required to chomp the returned string.
REQUIREMENTS
Perl version
Requires Perl version 5.10.1 or greater.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Term::TablePrintAUTHOR
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 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.