Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Term::Choose::Util(3) User Contributed Perl DocumentationTerm::Choose::Util(3)

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

VERSION
       Version 0.121

SYNOPSIS
       Functional interface:

	   use Term::Choose::Util qw( choose_a_directory );

	   my $chosen_directory	= choose_a_directory();

       Object-oriented interface:

	   use Term::Choose::Util;

	   my $ob = Term::Choose->new ();

	   my $chosen_directory	= $ob->choose_a_directory();

       See "SUBROUTINES".

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

EXPORT
       Nothing by default.

SUBROUTINES
       Values in brackets are default values.

       Options are passed as a hash reference. The options argument is the
       last (or	the only) argument.

       Options available for all subroutines

       o   clear_screen

	   If enabled, the screen is cleared before the	output.

	   Values: [0],1,2.

       o   color

	   Setting color to 1 enables the support for color and	text
	   formatting escape sequences except for the current selected
	   element. If set to 2, also for the current selected element the
	   color support is enabled (inverted colors).

	   Values: [0],1,2.

       o   hide_cursor

	   Hide	the cursor

	   Values: 0,[1].

       o   info

	   A string placed on top of of	the output.

	   Default: undef

       o   mouse

	   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.

       o   cs_label

	   The value of	cs_label (current selection label) is a	string which
	   is placed in	front of the current selection.

	   Defaults: "choose_directories": 'Dirs: ', "choose_a_directory":
	   'Dir: ', "choose_a_file": 'File: '. For "choose_a_number",
	   "choose_a_subset" and "settings_menu" the default is	undefined.

	   The current selection output	is placed between the info string and
	   the prompt string.

       o   prompt

	   A string placed on top of the available choices.

	   Default: undef

       o   back

	   Customize the string	of the menu entry "back".

	   Default: "BACK"

       o   confirm

	   Customize the string	of the menu entry "confirm".

	   Default: "CONFIRM".

   new
	   $ob = Term::Choose::Util->new( { mouse => 1,	... } );

       Returns a new Term::Choose::Util	object.

       Options:	all

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

       To move around in the directory tree:

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

       - choose	the "parent_dir" menu entry to move upwards.

       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.

       Options:

       o   alignment

	   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.

       o   decoded

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

	   Values: 0,[1].

       o   enchanted

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

       o   init_dir

	   Set the starting point directory. Defaults to the home directory.

	   If the option decoded is enabled (default), init_dir	expects	the
	   directory path as a decoded string.

       o   layout

	   See the option layout in Term::Choose

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

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

       o   show_hidden

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

	   Values: 0,[1].

       o   parent_dir

	   Customize the string	of the menu entry "parent_dir".

	   Default: ".."

   choose_a_file
	   $chosen_file	= choose_a_file( { show_hidden => 0, ... } )

       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

       o   filter

	   If set, the value of	this option is used as a glob pattern. Only
	   files matching this pattern will be displayed.

       o   show_files

	   Customize the string	of the menu entry "show_files".

	   Default: "[Show-Files]"

   choose_directories
	   $chosen_directories = choose_directories( { mouse =>	1, ... } )

       "choose_directories" is similar to "choose_a_directory" but it is
       possible	to return multiple directories.

       Selecting the  "add_dirs" menu entry opens the add-directories sub
       menu: one can add there directories from	the current working directory
       to the list of chosen directories.

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

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

       Options as in "choose_a_directory" plus

       o   add_dirs

	   Customize the string	of the menu entry "add_dirs".

	   Default: "[Choose-Dirs]"

   choose_a_number
	   $new	= choose_a_number( 5, {	cs_label => 'Number: ',	... }  );

       This function lets you choose/compose a number (unsigned	integer) which
       is 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.

       Options:

       o   small_first

	   Put the small number	ranges on top.

       o   thousands_separator

	   Sets	the thousands separator.

	   Default: ","

       The current-selection line is shown if cs_label is defined or as	soon
       as a number has been chosen.

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

       "choose_a_subset" lets you choose a subset from a list.

       The first argument is a reference to an array which provides the
       available list.

       Options:

       o   all_by_default

	   If enabled, all elements are	selected if CONFIRM is chosen without
	   any selected	elements.

	   Values: [0],1.

       o   alignment

	   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.

       o   index

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

	   Values: [0],1.

       o   keep_chosen

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

	   Values: [0],1;

       o   layout

	   See the option layout in Term::Choose.

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

       o   mark

	   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.

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

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

	   Default: empty string.

       o   cs_begin

	   Current selection: the cs_begin string is placed between the
	   cs_label string and the chosen elements as soon as an element has
	   been	chosen.

	   Default: empty string

       o   cs_separator

	   Current selection: the cs_separator is placed between the chosen
	   list	elements.

	   Default: " ,"

       o   cs_end

	   Current selection: as soon as elements have been chosen the cs_end
	   string is placed at the end of the chosen elements.

	   Default: empty string

       The current-selection line is shown if cs_label is defined or as	soon
       as elements have	been chosen.

       To return the chosen subset (as an array	reference) 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
	   $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:

       o   the unique name of the option

       o   the prompt string

       o   an array reference with the available values	of the option.

       The second argument is a	hash reference:

       o   the keys are	the option names

       o   the values (0 if not	defined) are the indexes of the	current	value
	   of the respective key/option.

       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. 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-reference (second argument) and returns the number
       of made changes.

       Setting the option cs_label to a	defined	value adds an info output
       line.

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::Choose::Util

AUTHOR
       MatthAxus Kiem <cuer2s@gmail.com>

CREDITS
       Thanks to the Perl-Community.de <http://www.perl-community.de> and the
       people form stackoverflow <http://stackoverflow.com> for	the help.

LICENSE	AND COPYRIGHT
       Copyright 2014-2020 MatthAxus 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.

perl v5.32.1			  2020-04-21		 Term::Choose::Util(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | EXPORT | SUBROUTINES | REQUIREMENTS | SUPPORT | AUTHOR | CREDITS | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Term::Choose::Util&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help