NAME

Term::Choose::Util - CLI related functions.

VERSION

Version 0.054

SYNOPSIS

See "SUBROUTINES".

DESCRIPTION

This module provides some CLI related functions required by App::DBBrowser, App::YTDL and Term::TablePrint.

EXPORT

Nothing by default.

SUBROUTINES

Values in brackets are default values.

Unknown option names are ignored.

choose_a_dir

$chosen_directory = choose_a_dir( { layout => 1, ... } )

With choose_a_dir the user can browse through the directory tree (as far as the granted rights permit it) and choose a directory which is returned.

To move around in the directory tree:

- select a directory and press Return to enter in the selected directory.

- choose the "up"-menu-entry (" .. ") to move upwards.

To return the current working-directory as the chosen directory choose " = ".

The "back"-menu-entry (" < ") causes choose_a_dir to return nothing.

As an argument it can be passed a reference to a hash. With this hash the user can set the different options:

• clear_screen

  If enabled, the screen is cleared before the output.

  Values: 0,[1].

• current

  If set, choose_a_dir shows current as the current directory.

• decoded

  If enabled, the directory name is returned decoded with locale_fs form Encode::Locale.

• dir

  Set the starting point directory. Defaults to the home directory or the current working directory if the home directory cannot be found.

• enchanted

  If set to 1, the default cursor position is on the "up" 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.

  Values: 0,[1].

• justify

  Elements in columns are left justified if set to 0, right justified if set to 1 and centered if set to 2.

  Values: [0],1,2.

• layout

  See the option layout in Term::Choose

  Values: 0,[1],2,3.

• mouse

  See the option mouse in Term::Choose

  Values: [0],1,2,3,4.

• 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].

• show_hidden

  If enabled, hidden directories are added to the available directories.

  Values: 0,[1].

choose_a_file

$chosen_file = choose_a_file( { layout => 1, ... } )

Browse the directory tree the same way as described for choose_a_dir. Select ">F" to get the files of the current directory. To return the chosen file select "=".

The options are passed as a reference to a hash. See "choose_a_dir" for the different options. choose_a_file has no option current.

choose_dirs

$chosen_directories = choose_dirs( { layout => 1, ... } )

choose_dirs is similar to choose_a_dir but it is possible to return multiple directories.

Different to choose_a_dir:

" . " adds the current directory to the list of chosen directories.

To return the chosen list of directories (as an array reference) select the "confirm"-menu-entry " = ".

The "back"-menu-entry ( " < " ) resets the list of chosen directories if any. If the list of chosen directories is empty, " < " causes choose_dirs to return nothing.

choose_dirs uses the same option as choose_a_dir. The option current expects as its value a reference to an array (directories shown as the current directories).

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

• clear_screen

  If enabled, the screen is cleared before the output.

  Values: 0,[1].

• 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 ("");

• mouse

  See the option mouse in Term::Choose

  Values: [0],1,2,3,4.

• thsd_sep

  Sets the thousands separator.

  Default: comma (,).

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:

• clear_screen

  If enabled, the screen is cleared before the output.

  Values: 0,[1].

• current

  This option expects as its value the current subset of the available list (a reference to an array). If set, two prompt lines are displayed - one for the current subset and one for the new subset. Even if the option index is true the passed current subset is made of values and not of indexes.

  The subset is returned as an array reference.

• index

  If true, the index positions in the available list of the made choices is returned.

• justify

  Elements in columns are left justified if set to 0, right justified if set to 1 and centered if set to 2.

  Values: [0],1,2.

• layout

  See the option layout in Term::Choose.

  Values: 0,1,2,[3].

• mouse

  See the option mouse in Term::Choose

  Values: [0],1,2,3,4.

• 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].

• prefix

  prefix expects as its value a string. This string is put in front of the elements of the available list before printing. The chosen elements are returned without this prefix.

  The default value is "- " if the layout is 3 else the default is the empty string ("").

• prompt

  The prompt line before the choices.

  Defaults to "Choose:".

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 key/option name

• the prompt string

• an array reference with the available values of the key/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.

The optional third argument is a reference to a hash. The keys are

• clear_screen

  If enabled, the screen is cleared before the output.

  Values: 0,[1].

• in_place DEPRECATED

  This option will be removed and settings_menu will always do an in-place edit of the configuration hash (the second argument).

  If enabled, the configuration hash (second argument) is edited in place else a reference to the modified hash is returned.

  Values: 0,[1].

• mouse

  See the option mouse in Term::Choose

  Values: [0],1,2,3,4.

• prompt

  A prompt string used instead of the default prompt string.

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. If the end of the list of the values is reached, it begins from the beginning of the list.

settings_menu returns nothing if no changes are made. If the user has changed values and in_place is set to 1, settings_menu modifies the hash passed as the second argument in place and returns 1. With the option in_place set to 0 settings_menu 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( $number, $separator );

insert_sep inserts thousands separators into the number and returns the number.

If the first argument is not defined, it is returned nothing.

If the first argument contains one or more characters equal to the thousands separator, insert_sep returns the string unchanged.

As a second argument it can be passed a character which will be used as the thousands separator.

The thousands separator defaults to the 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 returns a list where 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 if called in void context. If not called in void context, print_hash returns the formatted hash as a string.

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. In void context the output of the hash is closed when the user presses Return.

Empty strings are used instead of undefined hash values.

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:

• clear_screen

  If enabled, the screen is cleared before the output.

  Values: 0,[1].

• 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 ]

• left_margin

  left_margin is added to len_key. It defaults to 1.

• len_key

  len_key sets the available print width for the keys. The default value is the length (of print columns) of the longest key.

  If the remaining 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.

  Default: undefined.

• mouse

  See the option mouse in Term::Choose

  Values: [0],1,2,3,4.

• preface

  With preface it can be passed a string which is printed above the hash.

  Default: undefined.

• prompt

  Sets the prompt string

  If preface is defined, prompt defaults to the empty string else the default is 'Close with ENTER'.

• right_margin

  The right_margin is subtracted from maxcols if maxcols is the maximum terminal width. The default value is 2.

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.

term_width

term_size returns the current terminal width. See "term_size" above.

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 the 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.

REQUIREMENTS

Perl version

Requires Perl version 5.8.3 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::TablePrint

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-2018 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.

cpanm Term::Choose::Util

perl -MCPAN -e shell
install Term::Choose::Util