/ 
Term-Choose-Util-0.071
River stage one • 3 direct dependents • 3 total dependents
/ Term::Choose::Util

NAME

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

VERSION

Version 0.071

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.

Options available for all functions:

  • clear_screen

    If enabled, the screen is cleared before the output.

    Values: [0],1.

  • info

    A string placed on top of of the output.

  • mouse

    See the option mouse in Term::Choose

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

  • hide_cursor

    Hide the cursor

    Values: 0,[1].

  • prompt

    A string placed on top of the available choices.

    back

    Allows to overwrite the default string of the menu entry "back".

  • confirm

    Allows to overwrite the default string of the menu entry "confirm".

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

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:

  • decoded

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

    Values: 0,[1].

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

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

  • up

    Overwrite the default string ( .. ) of the menu entry "up".

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 (string can be changed with the option choose_file) to get the files of the current directory. To return the chosen file select OK .

The options are passed as a reference to a hash. See "choose_a_dir" for the different options

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:

++ (change with option add_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 OK .

The "back"-menu-entry ( << ) removes the last added directory. 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 prompt can used to put empty lines between the header row and the menu (prompt set to a single space means one empty line).

choose_a_number

$new = choose_a_number( 5, { 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):

  • name

    The value of name is put in front of the composed number in the info-output.

    Default: "> ";

  • small_on_top DEPRECATED

    Renamed to small_first.

  • small_first

    Put the small number ranges on top.

  • thsd_sep

    Sets the thousands separator.

    Default: comma (,).

choose_a_subset

$subset = choose_a_subset( \@available_items, { name => 'new> ' } )

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:

  • fmt_chosen DEPRECATED

    The option fmt_chosen is deprecated; use the options sofar_begin, sofar_separator and sofar_end to format the info-output.

    If fmt_chosen is set to 1, each chosen item gets its own line in the output on the screen.

    Values: [0],1;

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

  • 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,[3].

  • mark

    Expects as its value a reference to an array with indexes. Elements corresponding to these indexes are preselected when choose_a_subset is called.

  • name

    The value of name is a string. It is placed in front of the subset-info-output.

  • 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 in the menu. The chosen elements are returned without this prefix.

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

  • remove_chosen DEPRECATED

    Use keep_chosen instead.

    If enabled, the chosen items are remove from the available choices.

    Values: 0,[1];

  • sofar_begin

    The value of sofar_begin is a string.

    Subset-info-output: sofar_begin is placed between the name string and the chosen elements as soon as an element has been chosen.

    Default: empty

  • sofar_separator

    The value of sofar_separator is a string.

    Subset-info-output: sofar_separator is placed between the chosen list elements.

    Default: ,

  • sofar_end

    The value of sofar_end is a string.

    Subset-info-output: as soon as elements have been chosen sofar_end if placed at the end of the chosen elements.

    Default: empty

To return the chosen subset (as an array reference) select the "confirm"-menu-entry -OK-.

The "back"-menu-entry ( << ) removes the last added chosen items. If the list of chosen items is empty, " << " 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 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.

With the optional third argument can be passed the options.

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.

If the "back"-menu-entry (BACK) is chosen, settings_menu does not apply the made changes and returns nothing. If the "confirm"-menu-entry (CONFIRM) is chosen, settings_menu applies the made changes and returns the number of made changes.

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