Help language development. Donate to The Perl Foundation

Term::Choose::Util cpan:KUERBIS last updated on 2019-10-30

Term-Choose-Util-p6-1.3.0/

Build Status

NAME

Term::Choose::Util - TUI-related functions for selecting directories, files, numbers and subsets of lists.

DESCRIPTION

This module provides TUI-related functions for selecting directories, files, numbers and subsets of lists.

CONSTRUCTOR

The constructor method new can be called with optional named arguments:

    my $new = Term::Choose::Util.new( :mouse(1), ... )

DEPRECATIONS

The use of choose-dirs is deprecated - use choose-directories instead.

The use of choose-a-dir is deprecated - use choose-a-directory instead.

The deprecated routine names will be removed.

RENAMED OPTIONS

<Old names>:        <New names>:

justify             alignment

dir                 init-dir

up                  parent-dir

name                current-selection-label

sofar-begin         current-selection-begin

sofar-separator     current-selection-separator

sofar-end           current-selection-end

thsd-sep            thousands-separator

Only the new option names work.

ROUTINES

Values in brackets are default values.

Options available for all subroutines

If enabled, the screen is cleared before the output.

Values: [0],1.

Enables the support for color and text formatting escape sequences.

Values: [0],1.

Hide the cursor

Values: 0,[1].

A string placed on top of of the output.

Default: undef

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.

The value of current-selection-label is a string which is placed in front of the "chosen so far" info output.

With settings-menu the "chosen so far" info output is only shown if current-selection-label is defined.

Defaults: choose-directories: 'Dirs: ', choose-a-directory: 'Dir: ', choose-a-file: 'File: ', choose-a-number: ' >', choose-a-subset: '', settings-menu: undef

The "chosen so far" info output is placed between the info string and the prompt string.

A string placed on top of the available choices.

Default: undef

Customize the string of the menu entry "back".

Default: BACK

Customize the string of the menu entry "confirm".

Default: CONFIRM.

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

To move around in the directory tree:

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.

Following options can be set:

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

Values: [0],1,2.

Set the starting point directory. Defaults to the home directory ($*HOME).

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

See the option layout in Term::Choose

Values: 0,[1],2.

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

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

Values: 0,[1].

Customize the string of the menu entry "parent-dir".

Default: PARENT-DIR

choose-a-file

    $chosen-file = choose-a-file( :layout(1), ... )

Browse the directory tree the same way as described for choose-a-directory. Select the "show-files" menu entry to get the files of the current directory. To return the chosen file select the "confirm" menu entry.

Options as in choose-a-directory plus

Customize the string of the menu entry "show-files".

Default: SHOW-FILES

choose-directories

    @chosen-directories = choose-directories( :layout(1), ... )

choose-directories is similar to choose-a-directory but it is possible to return multiple directories.

Use the "add-dir" menu entry to add the current directory to the list of chosen directories.

To return the list of chosen directories select the "confirm" menu entry.

The "back" menu entry removes the last added directory. If the list of chosen directories is empty, "back" causes choose-directories to return nothing.

Options as in choose-a-directory plus

Customize the string of the menu entry "add-dir".

Default: ADD-DIR

choose-a-number

    my $number = choose-a-number( 5, :name<Testnumber>, ... );

This function lets you choose/compose a number (unsigned integer) which is then 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. If not set, it defaults to 7.

Options:

Put the small number ranges on top.

Sets the thousands separator.

Default: ,

choose-a-subset

    $subset = choose-a-subset( @available-items, :layout( 1 ), ... )

choose-a-subset lets you choose a subset from a list.

The subset is returned as an array.

The first argument is the list of choices.

Options:

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

Values: [0],1,2.

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

Values: [0],1.

If enabled, the chosen items are not removed from the available choices.

Values: [0],1;

See the option layout in Term::Choose.

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

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.

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

Info output: the current-selection-begin string is placed between the current-selection-label string and the chosen elements as soon as an element has been chosen.

Default: empty string

Info output: current-selection-separator is placed between the chosen list elements.

Default: ,

Info output: as soon as elements have been chosen the current-selection-end string is placed at the end of the chosen elements.

Default: empty string

To return the chosen subset 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

    my @menu = (
        ( 'enable-logging', "- Enable logging", ( 'NO', 'YES' )   ),
        ( 'case-sensitive', "- Case sensitive", ( 'NO', 'YES' )   ),
        ( 'attempts',       "- Attempts"      , ( '1', '2', '3' ) )
    );

    my %config = (
        'enable-logging' => 0,
        'case-sensitive' => 1,
        'attempts'       => 2
    );

    settings-menu( @menu, %config, :1mouse, ... );

The first argument is a list of lists. Each of the lists have three elements:

the option name

the prompt string

a list of the available values for the option

The second argument is a hash:

the hash key is the option name

the hash value (zero based index) sets the current value for the option.

This hash is edited in place: the changes made by the user are saved in this hash.

Options: see Options available for all subroutines(#Options available for all subroutines).

When settings-menu is called, it displays for each list 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.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 (second argument) and returns the number of made changes.

Setting the option current-selection-label to a defined value adds an info output line.

AUTHOR

Matthäus Kiem [email protected]

CREDITS

Thanks to the people from Perl-Community.de, from stackoverflow and from #perl6 on irc.freenode.net for the help.

LICENSE AND COPYRIGHT

Copyright 2016-2019 Matthäus Kiem.

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.