NAME
Term::Choose::Util - CLI related functions.
VERSION
Version 0.000_01
SYNOPSIS
See "SUBROUTINES".
DESCRIPTION
This module provides some CLI related functions required by App::DBBrowser, Term::TablePrint and App::YTDL.
EXPORT
Nothing by default.
SUBROUTINES
term_size
term_size returns the current terminal width and the current terminal heigth.
( $width, $heigth ) = term_size()If the OS is MSWin32 chars from Term::Size::Win32 is used to get the terminal width and the terminal heigth else GetTerminalSize form Term::ReadKey is used.
On windows, 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 term_size subtracts 1 from the terminal width before returning the width if the OS is MSWin32.
As an argument it can be passed an filehandle. With no argument the filehandle defaults to STDOUT.
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 which can be set to 0 or 1. It defaults to 0.
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.
choose_a_number
$chosen_number = choose_a_number( $digits, { thsd_sep => ',', name => 'Rows' } );This function lets you choose/compose a number (unsigned integer) which is returned.
The fist argument is an integer and determines the range of numbers that can be chosen. 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:
thsd_sep
Sets the thousands separator.
Defaults to the comma (",").
name
Sets the name of the number seen in the prompt line.
Defaults to the empty string ("");
choose_a_subset
$subset = choose_a_subset( \@available_items )choose_a_subset lets you choose a subset from a list.
As an argument it is required a reference to an array which provides the available list.
The subset is returned as an array reference.
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 which 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 third argument is a reference to a hash. The only key of this hash is in_place. It defaults to 1.
When choose_multi is called it displays for each array entry as a line 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 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 returns the modified "key => value" pairs as a hash reference.
choose_a_directory
$chosen_directory = choose_a_directory( $dir )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.
insert_sep
$number = insert_sep( $number, $separator );Inserts a thousands separator.
The following substitution is applied to the number passed with the first argument.
$number =~ 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 (",").
unicode_trim
$unicode = unicode_trim( $unicode, $length )The first argument is a correctly decoded string, the second argument is the length.
If the string is longer than passed length it is trimmed to that length 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.
unicode_sprintf
$unicode = unicode_sprintf( $unicode, $available_width, $right_justify );unicode_sprintf expects 2 or 3 arguments: the first argument is a decoded string, the second the available width and the third and optional argument tells how to justify 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 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.
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.