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

FreeBSD Manual Pages

  
 
  

home | help
Term::Menus(3)	      User Contributed Perl Documentation	Term::Menus(3)

NAME
       Term::Menus - Create Powerful Terminal, Console and CMD Enviroment
       Menus

SYNOPSIS
       "use Term::Menus;"

       see METHODS section below

DESCRIPTION
       Term::Menus allows you to create	powerful Terminal, Console and CMD
       environment menus. Any perl script used in a Terminal, Console or CMD
       environment can now include a menu facility that	includes sub-menus,
       forward and backward navigation,	single or multiple selection
       capabilities, dynamic item creation and customized banners. All this
       power is	simple to implement with a straight forward and	very intuitive
       configuration hash structure that mirrors the actual menu architechture
       needed by the application. A separate configuration file	is optional.
       Term::Menus is cross platform compatible.

       Term::Menus was initially conceived and designed	to work	seemlessly
       with the	perl based Network Process Automation Utility Module called
       Net::FullAuto (Available	in CPAN	:-) - however, it is not itself
       dependant on other Net::FullAuto	components, and	will work with *any*
       perl script/application.

       Reasons to use this module are:

       o You have a list (or array) of items, and wish to present the user a
	 simple	CMD enviroment menu to pick a single item and return that item
	 as a scalar (or simple	string). Example:

	    use	Term::Menus;

	    my @list=('First Item','Second Item','Third	Item');
	    my $banner="  Please Pick an Item:";
	    my $selection=&pick(\@list,$banner);
	    print "SELECTION = $selection\n";

	 The user sees ==>

	    Please Pick	an Item:

		1      First Item
		2      Second Item
		3      Third Item

	    (Press [F1]	for HELP)

	    ([ESC] to Quit)   PLEASE ENTER A CHOICE:

	 --< 2 >-<ENTER>----------------------------------

	 The user sees ==>

	    SELECTION =	Second Item

       o You have a large list of items	and need scrolling capability:

	    use	Term::Menus;

	    my @list=`ls -1 /bin`;
	    my $banner="   Please Pick an Item:";
	    my $selection=&pick(\@list,$banner);
	    print "SELECTION = $selection\n";

	 The user sees ==>

	    Please Pick	an Item:

		1      arch
		2      ash
		3      awk
		4      basename
		5      bash
		6      cat
		7      chgrp
		8      chmod
		9      chown
		10     cp

	    a.	Select All   f.	 FINISH
				___
	    93 Total Choices   |_v_| Scroll with ARROW keys   [F1] for HELP

	    ([ESC] to Quit)   PLEASE ENTER A CHOICE:

	 --<ENTER>--------------------------------------

	    Please Pick	an Item:

		11	cpio
		12	csh
		13	cut
		14	date
		15	dd
		16	df
		17	echo
		18	ed
		19	egrep
		20	env

	    a.	Select All   f.	 FINISH
				 ___
	    93	Total Choices	|_v_| Scroll with ARROW	keys   [F1] for	HELP

	    ([ESC] to Quit)   PLEASE ENTER A CHOICE:

	 --< 14	>-<ENTER>----------------------------------

	 The user sees ==>

	    SELECTION =	date

       o You need to select multiple items and return the selected list:

	    use	Term::Menus;

	    my %Menu_1=(

	       Item_1 => {

		  Text	  => "/bin Utility - ]Convey[",
		  Convey  => [ `ls -1 /bin` ],

	       },

	       Select => 'Many',
	       Banner => "\n   Choose a	/bin Utility :"
	    );

	    my @selections=&Menu(\%Menu_1);
	    print "SELECTIONS =	@selections\n";

	 The user sees ==>

	    Choose a /bin Utility :

		1      /bin Utility - arch
		2      /bin Utility - ash
		3      /bin Utility - awk
		4      /bin Utility - basename
		5      /bin Utility - bash
		6      /bin Utility - cat
		7      /bin Utility - chgrp
		8      /bin Utility - chmod
		9      /bin Utility - chown
		10     /bin Utility - cp

	    a.	Select All   c.	 Clear All   f.	 FINISH
				___
	    93 Total Choices   |_v_| Scroll with ARROW keys   [F1] for HELP

	    ([ESC] to Quit)   PLEASE ENTER A CHOICE:

	 --< 3 >-<ENTER>----------------------------------

	 --< 7 >-<ENTER>----------------------------------

	 The user sees ==>

	    Choose a /bin Utility :

		1      /bin Utility - arch
		2      /bin Utility - ash
	     *	3      /bin Utility - awk
		4      /bin Utility - basename
		5      /bin Utility - bash
		6      /bin Utility - cat
	     *	7      /bin Utility - chgrp
		8      /bin Utility - chmod
		9      /bin Utility - chown
		10     /bin Utility - cp

	    a.	Select All   c.	 Clear All   f.	 FINISH
				___
	    93 Total Choices   |_v_| Scroll with ARROW keys   [F1] for HELP

	    ([ESC] to Quit)   PLEASE ENTER A CHOICE:

	 --< f >-<ENTER>----------------------------------

	 The user sees ==>

	    SELECTIONS = /bin Utility -	awk /bin Utility - chgrp

       o You need sub-menus:

	    use	Term::Menus;

	    my %Menu_2=(

	       Name   => 'Menu_2',
	       Item_1 => {

		  Text	 => "]Previous[	is a ]Convey[ Utility",
		  Convey => [ 'Good','Bad' ]

	       },

	       Select => 'One',
	       Banner => "\n   Choose an Answer	:"
	    );

	    my %Menu_1=(

	       Name   => 'Menu_1',
	       Item_1 => {

		  Text	 => "/bin/Utility - ]Convey[",
		  Convey => [ `ls -1 /bin` ],
		  Result => \%Menu_2,

	       },

	       Select => 'One',
	       Banner => "\n   Choose a	/bin Utility :"
	    );

	    my $selection=&Menu(\%Menu_1);
	    print "\n	SELECTION=$selection\n";

	 The user sees ==>

	    Choose a /bin Utility :

	       1.	 /bin Utility -	arch
	       2.	 /bin Utility -	ash
	       3.	 /bin Utility -	awk
	       4.	 /bin Utility -	basename
	       5.	 /bin Utility -	bash
	       6.	 /bin Utility -	cat
	       7.	 /bin Utility -	chgrp
	       8.	 /bin Utility -	chmod
	       9.	 /bin Utility -	chown
	       10.	 /bin Utility -	cp

	    a.	Select All   c.	 Clear All   f.	  FINISH
				___
	    93 Total Choices   |_v_| Scroll with ARROW keys   [F1] for HELP

	    ([ESC] to Quit)   PLEASE ENTER A CHOICE:

	 --< 5 >-<ENTER>----------------------------------

	    Choose an Answer :

		1      bash is a Good Utility
		2      bash is a Bad Utility

	    (Press [F1]	for HELP)

	    ([ESC] to Quit)   PLEASE ENTER A CHOICE:

	 --< 1 >-<ENTER>----------------------------------

	 The user sees ==>

	    SELECTIONS = bash is a Good	Utility

       o You have a large amount of text, or instructional information,	and
	 want a	banner only screen that	displays the banner only (no
	 selections) and that moves to the next	screen/menu with just a	press
	 of the	ENTER key.  Yet, you want to preserve selections from earlier
	 menus,	and/or return to more menus after user completes reading the
	 banner	only screens.  You can also navigate backwards and forwards
	 through these screens.

	    use	Term::Menus:

	    my %Menu_1=(

	       Name   => 'Menu_1',
	       Banner => "\n   This is a BANNER	ONLY display."

	    );

	    &Menu(\%Menu_1);

	 The user sees ==>

	    This is a BANNER ONLY display.

	    ([ESC] to Quit)   Press ENTER to continue ...

       o You want to use perl subroutines to create the	text items and/or
	 banner:

	    use	Term::Menus;

	    sub	create_items {

	       my $previous=shift;
	       my @textlines=();
	       push @textlines,	"$previous is a	Good Utility";
	       push @textlines,	"$previous is a	Bad Utility";
	       return @textlines;
		      ## return	value must be an array
		      ## NOT an	array reference

	    }

	    sub	create_banner {

	       my $previous=shift;
	       return "\n   Choose an Answer for $previous :"
		      ## return	value MUST be a	string for banner

	    }

	    my %Menu_2=(

	       Name   => 'Menu_2',
	       Item_1 => {

		  Text	 => "]Convey[",
		  Convey => "create_items(]Previous[)",

	       },

	       Select => 'One',
	       Banner => "create_banner(]Previous[)",

	    );

	    my %Menu_1=(

	       Name   => 'Menu_1',
	       Item_1 => {

		  Text	 => "/bin/Utility - ]Convey[",
		  Convey => [ `ls -1 /bin` ],
		  Result => \%Menu_2,

	       },

	       Select => 'One',
	       Banner => "\n   Choose a	/bin Utility :"
	    );

	    my @selection=&Menu(\%Menu_1);
	    print "\n	SELECTION=@selection\n";

	 The user sees ==>

	    Choose a /bin Utility :

		1      /bin Utility - arch
		2      /bin Utility - ash
		3      /bin Utility - awk
		4      /bin Utility - basename
		5      /bin Utility - bash
		6      /bin Utility - cat
		7      /bin Utility - chgrp
		8      /bin Utility - chmod
		9      /bin Utility - chown
		10     /bin Utility - cp

	    a.	Select All   c.	 Clear All   f.	 FINISH
				___
	    93 Total Choices   |_v_| Scroll with ARROW keys   [F1] for HELP

	    ([ESC] to Quit)   PLEASE ENTER A CHOICE:

	 --< 5 >-<ENTER>----------------------------------

	    Choose an Answer for bash :

		1      bash is a Good Utility
		2      bash is a Bad Utility

	    (Press [F1]	for HELP)

	    ([ESC] to Quit)   PLEASE ENTER A CHOICE:

	 --< 1 >-<ENTER>----------------------------------

	 The user sees ==>

	    SELECTION =	bash is	a Good Utility

       o You want to use anonymous subroutines to create the text items	and/or
	 banner	(see the more detailed treatment of anonymous subroutines and
	 Term::Menus macros in a later section of this documentation):

	    use	Term::Menus;

	    my $create_items = sub {

	       my $previous=shift;
	       my @textlines=();
	       push @textlines,	"$previous is a	Good Utility";
	       push @textlines,	"$previous is a	Bad Utility";
	       return \@textlines;
		      ## return	value must an array reference

	    };

	    my $create_banner =	sub {

	       my $previous=shift;
	       return "\n   Choose an Answer for ]Previous[ :"
		      ## return	value MUST be a	string for banner

	    };

	    my %Menu_2=(

	       Name   => 'Menu_2',
	       Item_1 => {

		  Text	 => "]Convey[",
		  Convey => $create_items->(']Previous['), # Subroutine	executed
							   # at	runtime	by Perl
							   # and result	is passed
							   # to	Term::Menus.

							   # Do	not use	this argument
							   # construct with Result =>
							   # elements because only Menu
							   # blocks or subroutines can
							   # be	passed.	(Unless	the
							   # return item is itself
							   # a Menu configuration
							   # block [HASH] or an
							   # anonymous subroutine
							   # [CODE])

	       },

	       Select => 'One',
	       Banner => $create_banner, # Perl	passes sub itself at runtime and
					 # execution is	carried	out by Term::Menus.

	    );

	    my %Menu_1=(

	       Name   => 'Menu_1',
	       Item_1 => {

		  Text	 => "/bin/Utility - ]Convey[",
		  Convey => [ `ls -1 /bin` ],
		  Result => \%Menu_2,

	       },

	       Select => 'One',
	       Banner => "\n   Choose a	/bin Utility :"
	    );

	    my @selection=&Menu(\%Menu_1);
	    print "\n	SELECTION=@selection\n";

	 The user sees ==>

	    Choose a /bin Utility :

		1      /bin Utility - arch
		2      /bin Utility - ash
		3      /bin Utility - awk
		4      /bin Utility - basename
		5      /bin Utility - bash
		6      /bin Utility - cat
		7      /bin Utility - chgrp
		8      /bin Utility - chmod
		9      /bin Utility - chown
		10     /bin Utility - cp

	    a.	Select All   c.	 Clear All   f.	 FINISH
				___
	    93 Total Choices   |_v_| Scroll with ARROW keys   [F1] for HELP

	    ([ESC] to Quit)   PLEASE ENTER A CHOICE:

	 --< 5 >-<ENTER>----------------------------------

	    Choose an Answer for bash :

		1      bash is a Good Utility
		2      bash is a Bad Utility

	    (Press [F1]	for HELP)

	    ([ESC] to Quit)   PLEASE ENTER A CHOICE:

	 --< 1 >-<ENTER>----------------------------------

	 The user sees ==>

	    SELECTION =	bash is	a Good Utility

       Usage questions should be directed to the Usenet	newsgroup
       comp.lang.perl.modules.

       Contact me, Brian Kelly <Brian.Kelly@fullautosoftware.net>, if you find
       any bugs	or have	suggestions for	improvements.

   What	To Know	Before Using

       o There are two methods available with Term::Menus - &pick() and
	 &Menu().  "&Menu()" uses "&pick()" - you can get the same results
	 using only "&Menu()". However,	if you need to simply pick one item
	 from a	single list - use "&pick()". The syntax	is simpler, and	you'll
	 write less code.  ;-)

       o You'll	need to	be running at least Perl version 5.002 to use this
	 module.

METHODS
       pick - create a simple menu
	       $pick = &pick ($list|\@list|['list',...],[$Banner]);

	   Where $list is a variable containing	an array or list reference.
	   This	argument can also be a escaped array (sending a	reference) or
	   an anonymous	array (which also sends	a reference).

	   $Banner is an optional argument sending a customized	Banner to top
	   the simple menu - giving instructions, descriptions,	etc.  The
	   default is "Please Pick an Item:"

       Menu - create a complex Menu
	       $pick  =	&Menu ($list|\@list|['list',...],[$Banner]);

	   Where $pick is a variable containing	an array or list reference of
	   the pick or picks.

	       @picks =	&Menu ($Menu_1|\%Menu_1|{ Name => 'Menu_1' });

	   Where $Menu_1 is a hash reference to	the top	level Menu
	   Configuration Hash Structure.

   Menu	Configuration Hash Structures

	   These are the building blocks of the	overall	Menu architecture.
	   Each	hash structure represents a menu screen. A single menu layer,
	   has only one	hash structure defining	it. A menu with	a single sub-
	   menu	will have two hash structures. The menus connect via the
	   "Result" element of an Item - "Item_1" - hash structure in parent
	   menu	%Menu_1:

	      my %Menu_2=(

		 Name	=> 'Menu_2',
		 Item_1	=> {

		    Text   => "]Previous[ is a ]Convey[	Utility",
		    Convey => [	'Good','Bad' ]
		 },

		 Select	=> 'One',
		 Banner	=> "\n	 Choose	an Answer :"
	      );

	      my %Menu_1=(

		 Name	=> 'Menu_1',
		 Item_1	=> {

		    Text   => "/bin/Utility - ]Convey[",
		    Convey => [	`ls -1 /bin` ],
		    Result => \%Menu_2,

		 },

		 Select	=> 'One',
		 Banner	=> "\n	 Choose	a /bin Utility :"
	      );

       Menu Component Elements

       Each Menu Configuration Hash Structure consists of elements that	define
       and control it's	behavior, appearance, constitution and purpose.	An
       element's syntax	is as you would	expect it to be	in perl	- a key	string
       pointing	to an assocaited value:	"key =>	value".	The following items
       list supported key names	and ther associated value types:

       o   Display => 'Integer'

	     The Display key is	an optional key	that determines	the number of
	     Menu Items	that will be displayed on each screen. This is useful
	     when the items are	multi-lined, or	the screen size	is bigger or
	     smaller than the default number utilizes in the most practical
	     fashion. The default number is 10.

		Display	=> 15,

       o   Name	=> 'Char String	consisting of ASCII Characters'

	     The Name key provides a unique identifier to each Menu Structure.
	     This element is not "strictly" required for most Menu construts
	     to	function properly. Term::Menus goes to great lengths to
	     discover and utilize the Menu's name provided on the left side of
	     the equals	character of a Menu block using	the following
	     construct:

		my %MenuName=(

		   [ Menu Contents Here	]

		);

	     In	the above example, the Menu name is "MenuName".	Most of	the
	     time Term::Menus will discover this name successfully, affording
	     the user or Menu developer	one less requirement to	worry about.
	     Allowing Term::Menus to discover this name	will cut down on
	     opportunities for coding errors (and we all have enough of	those
	     already). HOWEVER,	there are "edge	cases" and more	complex	Menu
	     constructs	that will prevent Term::Menus from accurately
	     discovering this name. Therefore, it is recommended and is
	     considered	a "best	practice" to always explicitly "Name" Menu
	     blocks as follows:

		my %MenuName=(

		   Name	=> 'MenuName',

		   [ Menu Contents Here	]

		);

	     Be	careful	to always use the SAME NAME for	the Name element as
	     for the Menu block	itself.	This can be a source of	error,
	     especially	when one is using Macros that reference	Menu Names
	     explicitly	(So be CAREFUL!) One case where	the Name element must
	     ALWAYS be used (if	one wishes to reference	that Menu with an
	     explicit Named Macro) is when creating anonymous Menu blocks to
	     feed directly to Result elements:

		my %ContainingMenu=(

		   Name	  => 'ContainingMenu',
		   Item_1 => {

		       Text => "Some Text",
		       Result => {

			  Name => "Anonymous_Menu", # MUST use "Name" element
						    # if planning to use
						    # explicit Macros

			  [ Menu Contents Here ]

		       },
		   },

		);

       o   Item_<int> => { Item	Configuration Hash Structure }

	     The Item__int_ elements define customized menu items.  There are
	     essentially two methods for creating menu items: The Item__int_
	     elements, and the "]Convey[" macro	(described later). The
	     difference	being that the "]Convey[" macro	turns an Item
	     Configuration Hash	into an	Item Template -> a powerful way	to
	     Item-ize large lists or quantities	of data	that would otherwise
	     be	difficult - even impossible - to anticipate and	cope with
	     manually.

		Item_1 => { Text => 'Item 1' },
		Item_2 => { Text => 'Item 2' },

	     Items created via "]Convey[" macros have two drawbacks:

	     o They all	have the same format.

	     o They all	share the same "Result"	element.

	     The syntax	and usage of Item__int_	elements is important and
	     extensive enough to warrant it's own section. See Item
	     Configuration Hash	Structures below.

       o   Select => 'One' --or-- 'Many'

	     The MENU LEVEL Select element determines whether this particular
	     menu layer	allows the selection of	multiple items - or a single
	     item. The default is 'One'.

		Select => 'Many',

       o   Banner => 'Char String consisting of	ASCII Characters' or anonymous
	   subroutine or subroutine reference for generating dynamic banners.

	     The Banner	element	provides a customized descriptive header to
	     the menu.	$Banner	is an optional element - giving	instructions,
	     descriptions, etc.	 The default is	"Please	Pick an	Item:"

		Banner => "The following items are for selection,\n".
			  "\tEnjoy the Experience!",

	     --or--

		Banner => sub {	<generate dynamic banner content here> },

	     --or--

		my $create_banner = sub	{ <generate dynamic banner content here> },

		Banner => $create_banner,

	     Creating a	reference to a Banner subroutine enables the sharing
	     of	Banner generation code between multiple	Menus.

	     NOTE:   Macros (like  "]Previous["	)  can be used in Banners!
	     :-)   ( See Item Configuration Macros below )

       Item Configuration Hash Structures

       Each Menu Item can have an independant configurtion. Each Menu
       Configuration Hash Structure consists of	elements that define and
       control it's behavior, appearance, constitution and purpose. An
       element's syntax	is as you would	expect it to be	in perl	- a key	string
       pointing	to an assocaited value:	key => value. The following items list
       supported key names and ther associated value types:

       o   Text	=> 'Char String	consisting of ASCII Characters'

	     The Text element provides a customized descriptive	string for the
	     Item.  It is the text the user will see displayed,	describing the
	     selection.

		Text =>	'This is Item_1',

       o   Convey => [ List ] --or-- @List --or-- $Scalar --or-- 'ASCII
	   String' --or-- Anonymous Subroutine --or-- Subroutine Reference
	   --or-- Ordinary Subroutine (*Ordinary* subroutine calls need	to be
	   surrounded by quotes. DO NOT	use quotes with	anonymous subroutine
	   calls or ones called	with a reference!)

	     The Convey	element	has a twofold purpose; it provides for the
	     contents of the "]Convey["	macro, and defines or contains the
	     string or result that is passed on	to child menus - if any. Use
	     of	this configuration element is optional.	If "Convey" is not a
	     list, then	it's value is passed onto child	menus. If "Convey" is
	     a list, then the Item selected is passed onto the children	- if
	     any. It is	important to note, when	used, that only	the resulting
	     Convey string - NOT the the Item "Text" value or string, is
	     conveyed to child menus. When the "Convey"	element	is not used,
	     the full Item "Text" value	is conveyed to the children - if any.
	     However, the full contents	of the "Text" element is returned as
	     the Result	of the operation when the user completes all menu
	     activity. See the Macro section below for more information.

		Convey => [ `ls	-1` ],

	     NOTE:     When using anonymous subroutines	or subroutine
	     references, there may be situations where code populating the
	     Convey item encounters an error or	gets data that is empty	or
	     unsatisfactory for	some reason, and there is a need to print a
	     message or	write to a log or send an alert, and then return from
	     this routine to an	earlier	menu. To force a return	to a parent
	     menu (assuming there is one) from a subroutine assigned to	a
	     Convey element, just return '<' from the subroutine. To return to
	     any ancestor Menu in the stack, return this macro from the
	     subroutine: "{Menu_Name}<"	:-)

       o   Default => 'Char String' --or-- Perl	regular	expression - qr/.../

	     The Default element provides a means to pre-select	certain
	     elements, as if the items were selected by	the user. This can be
	     done with two constructs -	simple string or pre-compiled regular
	     expression.  Note:	The "Default" element is available only	when
	     the "Select" element is set to 'Many' - "Select ="	'Many',>

		Default	=> 'base|chown',

		Default	=> qr/base|chown/i,

	     The user sees ==>

		Choose a /bin Utility :

		    1	   /bin	Utility	- arch
		    2	   /bin	Utility	- ash
		    3	   /bin	Utility	- awk
		 *  4	   /bin	Utility	- basename
		    5	   /bin	Utility	- bash
		    6	   /bin	Utility	- cat
		    7	   /bin	Utility	- chgrp
		    8	   /bin	Utility	- chmod
		 *  9	   /bin	Utility	- chown
		    10	   /bin	Utility	- cp

		a.  Select All	 c.  Clear All	 f.  FINISH
				    ___
		93 Total Choices   |_v_| Scroll	with ARROW keys	  [F1] for HELP

		([ESC] to Quit)	  PLEASE ENTER A CHOICE:

       o   Select => 'One' --or-- 'Many'

	     The ITEM LEVEL Select element provides a means to inform
	     Term::Menus that the specific items of a single ITEM BLOCK	(as
	     opposed to	full menu) are subject to multiple selecting - or just
	     single selection. This is useful in particular for	Directory Tree
	     navigation	- where	files can be multi-selected (or	tagged), yet
	     when a directory is selectedi, it forces an immediate navigation
	     and new menu - showing the	contents of the	just selected
	     directory.

	     NOTE: See the RECURSIVELY CALLED MENUS section for	more
	     information.

		Select => 'More',

	     The user sees ==>

		 d  1	   bin
		 d  2	   blib
		 d  3	   dist
		 d  4	   inc
		 d  5	   lib
		 d  6	   Module
		 d  7	   t
		    8	   briangreat2.txt
		 *  9	   ChangeLog
		    10	   close.perl

		a.  Select All	 f.  FINISH
				    ___
		49 Total Choices   |_v_| Scroll	with ARROW keys	  [F1] for HELP

		([ESC] to Quit)	  PLEASE ENTER A CHOICE:

       o   Exclude => 'Char String' --or-- Perl	regular	expression - qr/.../

	     The Exclude element provides a means to remove matching elements
	     from the Menu seen	by the user. This element is useful only when
	     the "]Convey[" macro is used to populate items. This can be done
	     with two constructs - simple string or pre-compiled regular
	     expression.

		Exclude	=> 'base|chown',

		Exclude	=> qr/base|chown/i,

       o   Include => 'Char String' --or-- Perl	regular	expression - qr/.../

	     The Include element provides a means to create items filtered
	     from a larger list	of potential items available via the
	     "]Convey["	macro. This element is useful only when	the "]Convey["
	     macro is used to populate items. The "Exclude" element can	be
	     used in conjunction with "Include"	to further refine the final
	     list of items used	to construct the menu. The "Include" element -
	     when used - always	takes presidence, and the "Exclude" will be
	     used only on the "Include"	filtered results. This element can be
	     used with two value constructs - simple string or pre-compiled
	     regular expression.

		Include	=> 'base|chown',

		Include	=> qr/base|chown/i,

       o   Result => \%Menu_2  --or --	"&any_method()",

	   o Result is an optional element that	also has two important uses:

	   o For selecting the child menu next in the chain of operation and
	     conveyance,

		Result => \%Menu_2,

	     --or--

	   o For building customized method arguements using "&Menu()"'s
	     built-in macros.

	   o

		Result => "&any_method($arg1,\"]Selected[\",\"]Previous[\")",

	     NOTE: ALWAYS be sure to surround the subroutine or	method calling
	     syntax with DOUBLE	QUOTES.	(You can use single quotes if you
	     don't want	interpolation).	Quotes are necessary because you're
	     telling "&Menu()" - not Perl - what method	you want invoked.
	     "&Menu()" won't invoke the	method until after all other
	     processing	- where	Perl will try to invoke	it the first time it
	     encounters	the line during	runtime	- lo----ng before a user gets
	     a chance to see or	do anything. BUT - be sure NOT to use quotes
	     when assigning a child menu reference to the "Result" value.

	     Again, Result is an optional element. The default behavior	when
	     "Result" is omitted from the Item Configuration element, is for
	     the selection to be returned to the "&Menu()"'s calling
	     script/module/app.	If the "Select"	element	was set	to 'One', then
	     that item is returned regardless of whether the Perl structure
	     receiving the output is an	array or scalar. If there were
	     multiple selections - i.e., "Select" is set to 'Many' - then,
	     depending on what structure is set	for receiving the output, will
	     determine whether "&Menu()" returns a list	(i.e. -	array),	or
	     reference to an array.

       Item Configuration Macros

       Each Menu Item can utilize a very powerful set of configuration Macros.
       These constructs	principally act	as purveyors of	information - from one
       menu to another,	from one element to another. There are currently three
       available Macros:

       o   ]Convey[

	     "]Convey["	is used	in conjunction with the	Convey element
	     (described) earlier. It's purpose to "convey" or transport	or
	     carry a list item associated with the "Convey" element - and
	     replace the "]Convey[" Macro in the "Text"	element	value with
	     that list item. The Convey	mechanism utilizing the	"Convey" Macro
	     is	essentially an Item multiplier.	The entire contents of the
	     list associated with the Convey element will be turned into it's
	     own "Item"	when the menu is displayed. Both ordinary and
	     anonymous subroutines can be use to dynamically generate Convey
	     lists. (With ]Convey[, macros can be used only as subroutine
	     arguments or in the body of anonymous subroutines - see other
	     examples.)

		use Term::Menus;

		my %Menu_1=(

		   Name	  => 'Menu_1',
		   Item_1 => {

		      Text   =>	"/bin/Utility -	]Convey[",
		      Convey =>	[ `ls -1 /bin` ],
		      Result =>	\%Menu_2,

		   },

		   Select => 'One',
		   Banner => "\n   Choose a /bin Utility :"
		);

		my @selections=&Menu(\%Menu_1);
		print "SELECTIONS=@selections\n";

	     The user sees ==>

		Choose a /bin Utility :

		    1	   /bin	Utility	- arch
		    2	   /bin	Utility	- ash
		    3	   /bin	Utility	- awk
		    4	   /bin	Utility	- basename
		    5	   /bin	Utility	- bash
		    6	   /bin	Utility	- cat
		    7	   /bin	Utility	- chgrp
		    8	   /bin	Utility	- chmod
		    9	   /bin	Utility	- chown
		    10	   /bin	Utility	- cp

		a.  Select All	 c.  Clear All	 f.  FINISH
				    ___
		93 Total Choices   |_v_| Scroll	with ARROW keys	  [F1] for HELP

		([ESC] to Quit)	  PLEASE ENTER A CHOICE:

	     NOTE:     "]C["  can be used as a shorthand for  "]Convey[".

       o   ]Previous[

	     "]Previous[" can be used in child menus. The "]Previous[" Macro
	     contains the Selection of the parent menu.	Unlike the "]Convey["
	     Macro, the	"]Previous[" Macro can be used in both the "Text"
	     element value, and	the "Result" element values (when constructing
	     method calls):

	     The "]Previous[" Macro can	also be	used in	the Banner.

		use Term::Menus;

		my %Menu_2=(

		   Name	  => 'Menu_2',
		   Item_1 => {

		      Text   =>	"]Previous[ is a ]Convey[ Utility",
		      Convey =>	[ 'Good','Bad' ]
		   },

		   Select => 'One',
		   Banner => "\n   Choose an Answer :"
		);

		my %Menu_1=(

		   Name	  => 'Menu_1',
		   Item_1 => {

		      Text   =>	"/bin/Utility -	]Convey[",
		      Convey =>	[ `ls -1 /bin` ],
		      Result =>	\%Menu_2,

		   },

		   Select => 'One',
		   Banner => "\n   Choose a /bin Utility :"
		);

		my @selections=&Menu(\%Menu_1);
		print "SELECTIONS=@selections\n";

	     The user sees ==>

		Choose a /bin Utility :

		    1	   /bin	Utility	- arch
		    2	   /bin	Utility	- ash
		    3	   /bin	Utility	- awk
		    4	   /bin	Utility	- basename
		    5	   /bin	Utility	- bash
		    6	   /bin	Utility	- cat
		    7	   /bin	Utility	- chgrp
		    8	   /bin	Utility	- chmod
		    9	   /bin	Utility	- chown
		    10	   /bin	Utility	- cp

		a.  Select All	 c.  Clear All	 f.  FINISH

		93 Total Choices   |_v_| Scroll	with ARROW keys	  [F1] for HELP

		([ESC] to Quit)	  PLEASE ENTER A CHOICE:

	     --< 5 >-<ENTER>----------------------------------

		Choose an Answer :

		    1	   bash	is a Good Utility
		    2	   bash	is a Bad Utility

		(Press [F1] for	HELP)

		([ESC] to Quit)	  PLEASE ENTER A CHOICE:

	     --< 1 >-<ENTER>----------------------------------

	     The user sees ==>

		SELECTIONS = bash is a Good Utility

	     NOTE:     "]P["  can be used as a shorthand for  "]Previous[".

       o   ]Previous[{ <Menu_Name> }  i.e. Explicit Named Macro

	     "]Previous[{Menu_Name}" (i.e. Explicit Named Macros) can be used
	     in	child menus.  The "]Previous[{Menu_Name}" Macro	contains the
	     Selection of any preceding	menu specified with the	"Menu_Name"
	     string. The "]Previous[{Menu_Name}" follows the same conventions
	     as	the "]Previous[" Macro - but enables access to the selection
	     of	i<any> preceding menu. This is very useful for Menu trees more
	     than two levels deep.

	     The "]Previous[{Menu_Name}" Macro can also	be used	in the Banner.

		use Term::Menus;

		my %Menu_3=(

		   Name	  => 'Menu_3',
		   Item_1 => {

		      Text   =>	"]Convey[ said ]P[{Menu_1} is a	]Previous[ Utility!",
		      Convey =>	[ 'Bob','Mary' ]
		   },

		   Select => 'One',
		   Banner => "\n   Who commented on ]Previous[{Menu_1}?	:"
		);

		my %Menu_2=(

		   Name	  => 'Menu_2',
		   Item_1 => {

		      Text   =>	"]Previous[ is a ]C[ Utility",
		      Convey =>	[ 'Good','Bad' ],
		      Result =>	\%Menu_3,
		   },

		   Select => 'One',
		   Banner => "\n   Is ]P[ Good or Bad? :"
		);

		my %Menu_1=(

		   Name	  => 'Menu_1',
		   Item_1 => {

		      Text   =>	"/bin/Utility -	]Convey[",
		      Convey =>	[ `ls -1 /bin` ],
		      Result =>	\%Menu_2,

		   },

		   Select => 'One',
		   Banner => "\n   Choose a /bin Utility :"
		);

		my @selections=&Menu(\%Menu_1);
		print "SELECTIONS=@selections\n";

	     The user sees ==>

		Choose a /bin Utility :

		    1	   /bin	Utility	- arch
		    2	   /bin	Utility	- ash
		    3	   /bin	Utility	- awk
		    4	   /bin	Utility	- basename
		    5	   /bin	Utility	- bash
		    6	   /bin	Utility	- cat
		    7	   /bin	Utility	- chgrp
		    8	   /bin	Utility	- chmod
		    9	   /bin	Utility	- chown
		    10	   /bin	Utility	- cp

		([ESC] to Quit)	  PLEASE ENTER A CHOICE:

	     --< 5 >-<ENTER>----------------------------------

		Is bash	Good or	Bad? :

		    1	   bash	is a Good Utility
		    2	   bash	is a Bad Utility

		(Press [F1] for	HELP)

		([ESC] to Quit)	  PLEASE ENTER A CHOICE:

	     --< 1 >-<ENTER>----------------------------------

		Who commented on bash? :

		    1	   Bob said bash is a Good Utility!
		    2	   Mary	said bash is a Good Utility!

		(Press [F1] for	HELP)

		([ESC] to Quit)	  PLEASE ENTER A CHOICE:

	     --< 2 >-<ENTER>----------------------------------

	     The user sees ==>

		SELECTIONS = Mary said bash is a Good Utility!

	     NOTE:     "]P["  can be used as a shorthand for  "]Previous[".

	     "]P[{Menu_Name}"  can be used as a	shorthand for
	     "]Previous[{Menu_Name}".

	     "]C[" can be used as a shorthand for "]Convey[".

       o   ]Selected[

	     "]Selected[" can only be used in a	terminal menu. ( A terminal
	     menu is the last menu in the chain, or the	last menu the user
	     sees. It is the menu that defines the "Result" element with a
	     method "Result => &any_method()", or does not have	a "Result"
	     element included or defined. ) "]Selected[" is used to pass the
	     selection of the current menu to the "Result" element method of
	     the current menu:

		use Term::Menus;

		sub selected { print "\n   SELECTED ITEM = $_[0]\n" }

		my %Menu_1=(

		   Name	  => 'Menu_1',
		   Item_1 => {

		      Text   =>	"/bin/Utility -	]Convey[",
		      Convey =>	[ `ls -1 /bin` ],
		      Result =>	"&selected(]Selected[)", # ]Selected[ macro passed to
							 # ordinary perl subroutine.
							 # The '&' characater is optional
							 # but the quotes are NOT. Ordinary
							 # subroutine calls MUST be
							 # surrounded by either	double or
							 # single quotes. (DO NOT use
							 # quotes around anonymous
							 # subroutine calls, however!)

		   },

		   Select => 'One',
		   Banner => "\n   Choose a /bin Utility :"
		);

		my $selection=&Menu(\%Menu_1);
		print "\n   SELECTION=$selection\n";

	     NOTE:     "]S["  can be used as a shorthand for  "]Selected[".

	     NOTE:     It is possible to use the same Result subroutine	in
			  different Item_<int> blocks, and even	in
			  other	Menu blocks within the same script.
	     Furthermore,
			  when complex Menu structures are created using lots
			  of anonymous subroutines with	generous subroutine
			  reuse, it can	be difficult to	prevent	early
	     substitution
			  of this Macro	by a parent Menu. To prevent this, use
			  the Explicit Named Macro construct with this Macro
	     as
			  well - "]Selected[{Menu_Name}"

			  Also,	if the same Result subroutine is to be used by
			  multiple nested menus, all the Menu_Names of those Menu
			  blocks should	be included in the Named section
			  separated by the vertical bar	symbol - C<]S[{Menu1_Name|Menu2_Name}>

	     NOTE:     Stepchild and Grandchild	Menus -	While on the topic
			  of multiple nested menus, one	of the more
	     challenging
			  aspects is preventing	child menus from having	their
			  macros expanded or populated too "early" during
	     runtime.
			  Using	the "Explict Name" convention
	     ("]Selected[{Menu_Name}")
			  helps, but there is another issue to be aware	of. It
	     is
			  extremely useful (and	powerful!) to use previous
	     menu
			  selections to	dynamically build and return child
	     menus
			  for some results, but	not for	others.	Code to
	     reflect
			  this goal would ordinarly look like this:

			  $result_code = sub {

			     my	$selection=']S[{current_menu_name}';
			     if	($selection eq 'Return to Main Menu')  {

				return '{main}<';

			     } else {

				my %next_menu=(

				   Name	=> 'next_menu',
				   Item_1 => {

				      Text => ']C[',
				      Convey =>	[ ... ],

				   },
				   Item_2 => { ... },

				);

			     }

			  };

			  But this may not work	correctly. The reason is that
			  Term::Menus identifies menus in result blocks	by
			  explicitly looking for the 'Item_' (Item underscore)
			  string in the	block. If it finds one it will treat
			  the result as	a child	menu to	be I<immediately>
			  created - not	a routine to be	evaluated first! So,
			  in this scenario, the	routine	is acting as a kind
			  of surrogate or "step" parent, since it is not a
			  "real" parent	menu. Hence, the "stepchild" menu. In
			  this situation it may	be necessary to	"trick"
			  Term::Menus into not recognizing the embedded	menu
			  (yet)	that is	part of	a conditional structure	that
			  will be returned, only if the	conditional is true.
			  To do	that, you can code this	scenario like this:

			  $result_code = sub {

			     my	$selection=']S[{current_menu_name}';
			     if	($selection eq 'Return to Main Menu')  {

				return '{main}<';

			     } else {

				my %next_menu=(	 # This	is a "stepchild" menu

				   Name	=> 'next_menu',

				);
				my $key	= 'Item'.'_1';
				$next_menu{$key}={

				    Text => ']C[',
				    Convey => [	... ],

				};
				$key = 'Item'.'_2';
				$next_menu{$key}={

				    Text => '. . .',

				};
				return \%next_menu;

			     }

			  };

			  While	that works, it is not very elegant (and	not
			  Best Practice!). It is better	in these situations
			  to substitute	the Select (C<]Select[>) or Previous
			  (C<]Previous[>) Macros with a	TEST Macro (C<]Test[>
			  or C<]T[> is shorthand):

			  $result_code = sub {

			     my	$selection=']T[{current_menu_name}'; # <-- Note	the ]T[
			     if	($selection eq 'Return to Main Menu')  {

				return '{main}<';

			     } else {

				my %next_menu=(	 # "stepchild" menu

				   Name	=> 'next_menu',
				   Item_1 => {

				      Text => ']C[',
				      Convey =>	[ ... ],

				   },
				   Item_2 => { ... },

				);

			     }

			  };

			  The presence of the C<]Test[>	macro tells
			  Term::Menus that it's	dealing	with stepchild menus,
			  and not to evaluate them early.

			  However, there are scenario's	where you want to
			  evaluate on a	condition that does not	involve	a
			  child	or even	a step child menu - but	a grandchild
			  or great grandchild menu, etc. (This can certainly
			  happen when there is menu re-use or recursion). In
			  these	situations Term::Menus will invariably
			  determine there is an	error condition	(due to	the
			  explicitly named menu	missing	in the history stack)
			  when there isn't - because there is no "obvious"
			  way for Term::Menus to know that an explicitly named
			  menu is not yet "supposed" to	exist. In these
			  scenarios the	only option will be to suppress	the
			  error	message	and allow macro	expansion to otherwise
			  continue unabated. To	do that, and allow processing
			  to continue, use a "bang" (or	exclamation point)
			  character in the macro syntax	after the starting
			  bracket:

			  C<my $selection=']!S[{menu_name}';>

			  --OR--

			  C<my $selection=']!T[{menu_name}';>

			  Hopefully, one or more of these approaches or
			  "tricks" will	deliver	the results you're after.
			  Whatever works!

	     NOTE:     if you want to return output from the Result
	     subroutine,
			  you must include a 'return' statement. So the	sub
	     above:

			     sub selected { print "\n	SELECTED ITEM =	$_[0]\n" }

			  Becomes:

			     sub selected { print "\n	SELECTED ITEM =	$_[0]\n";return	$_[0] }

ANONYMOUS SUBROUTINES AND MACROS
       Term::Menus macros can be used directly in the body of anonymous
       subroutines! Ordinary subroutines can be	used as	illustrated above of
       course, but the macro values can	only be	passed as arguments to
       ordinary	subroutines. This is much more complicated and less intuitive
       than using macros directly in the code itself. Below is an example of
       their usage. The	author received	a request a while back from a user,
       asking if it was	possible to return the item number rather than it's
       text value. The answer of course	is YES!	The code below illustrates
       this:

	  use Term::Menus;

	  my @list=('One','Two','Three');

	  my %Menu_1=(

	     Item_1 => {

		Text	=> "NUMBER - ]Convey[",
		Convey	=> \@list,
		Result	=> sub {
				  my $cnt=-1;my	$selection=']Selected[';
				  foreach my $item (@list) {
				     $cnt++;
				     chomp($item);
				     last if -1<index $selection, $item;
				  } return "$cnt";
			       }
			       # Note use of ]Selected[	macro in
			       # anonymous subroutine body

	     },

	     Select => 'One',
	     Banner => "\n   Choose a /bin Utility :"
	  );

	  my $selection=Menu(\%Menu_1);
	  print	"   \nSELECTION	= $selection\n";

       Anonymous subroutines can be assigned directly to "Item_1" (or Item_2,
       etc.) elements 'Convey' and 'Result' as well as to the Menu "Banner"
       element.	Use of the these constructs over more traditional subroutines
       is encouraged because it	means writing less code, while enabling	the
       code that is written to be less complex,	more intuitive and readable,
       and certainly easier to maintain. The same anonymous routine can	be use
       in multipe Menus	or Items of a single Menu by assigning that routine to
       a variable, and then assigning the variable instead.

       NOTE:   To force	a return to a parent menu (assuming there is one) from
       a subroutine assigned to	a Result element, just return '<' from the
       subroutine. This	is extremely useful when there is a desire to process
       a selection, and	then return to the parent menu when processing is
       complete. To return to any ancestor Menu	in the stack, return this
       macro from the subroutine: "{Menu_Name}<" :-)

	  use Term::Menus;

	  my @list=('One','Two','Three');

	  my $result = sub {
			      my $cnt=-1;my $selection=']Selected[';
			      foreach my $item (@list) {
				 $cnt++;
				 chomp($item);
				 last if -1<index $selection, $item;
			      }	return "$cnt";
			   };
			   # Anonymous subroutine assigned to "$result"	variable

	  my %Menu_1=(

	     Item_1 => {

		Text	=> "NUMBER - ]Convey[",
		Convey	=> \@list,
		Result	=> $result, # Anonymous	subroutine assisned via
				    # "$result"	variable

	     },

	     Select => 'One',
	     Banner => "\n   Choose a /bin Utility :"
	  );

	  my $selection=Menu(\%Menu_1);
	  print	"   \nSELECTION	= $selection\n";

RECURSIVELY CALLED MENUS
       There are occasions where it is desirable to re-use the same Menu
       template/hash configuration with	dynamically discovered data. One
       obvious example of this is navigating directory trees. Each subsequent
       directory selection could potentially contain deeper levels of
       directories. Essentially, any data structured in	any kind of relational
       tree layout is subject to this kind of navigation approach. Be warned
       however,	unlike most other functionality	that is	handled	almost
       entirely	by the Term::Menus module, the code for	doing recursive
       templating is mostly contained in the template/hash configuration
       itself. There is	a "helper routine" (&get_Menu_map) that	Term::Menus
       provides	to assist with the creation of recursively-friendly
       configurations, but given the highly data-centric characteristics of
       such functionality, most	of the working code must be left to the
       authoring and management	of the user.

       _get_Menu_map()

       This is a helper	routine	that returns a list of ancestor	menu results.
       This is needed when wanting to navigate a directory tree	for instance.
       Imagine a directory path	that looks like	this: /one/two/three. A	call
       to &get_Menu_map() when processing directory three with return this
       list: ('one','two').

	   The following code is an example of how to use recursion for
	   navigating a	directory tree.

	      use Term::Menus;

	      my %dir_menu=(

		 Name	=> 'dir_menu',
		 Item_1	=> {

		    Text => "]C[",
		    Mark => "d",
		    Convey => sub {

		       if ("]P[") {

			  my $dir="]P[";
			  if ($^O eq 'cygwin') {
			     $dir='/cygdrive/c/';
			  } else {
			     $dir='/';
			  }
			  my @xfiles=();
			  my @return=();
			  my @map=get_Menu_map;
			  my $path=join	"/", @map;
			  opendir(DIR,"$dir$path") || die $!;
			  @xfiles = readdir(DIR);
			  closedir(DIR);
			  foreach my $entry (sort @xfiles) {
			     next if $entry eq '.';
			     next if $entry eq '..';
			     if	(-1<$#map) {
				next unless -d "$dir$path/$entry";
			     } else {
				next unless -d "$dir/$entry";
			     }
			     push @return, "$entry";
			  }
			  return @return;

		       }
		       my @xfiles=();
		       my @return=();
		       if ($^O eq 'cygwin') {
			  opendir(DIR,'/cygdrive/c/') || die $!;
		       } else {
			  opendir(DIR,'/') || die $!;
		       }
		       @xfiles = readdir(DIR);
		       closedir(DIR);
		       foreach my $entry (@xfiles) {
			  next if $entry eq '.';
			  next if $entry eq '..';
			  next unless -d "$entry";
			  push @return,	"$entry";
		       }
		       return @return;

		    },
		    Result => {	'dir_menu'=>'recurse' },

		 },
		 Item_2	=> {

		    Text => "]C[",
		    Select => 'Many',
		    Convey => sub {

		       if ("]P[") {

			  my $dir="]P[";
			  if ($^O eq 'cygwin') {
			     $dir='/cygdrive/c/';
			  } else {
			     $dir='/';
			  }

			  my @xfiles=();
			  my @return=();
			  my @map=get_Menu_map;
			  my $path=join	"/", @map;
			  opendir(DIR,"$dir/$path") || die $!;
			  @xfiles = readdir(DIR);
			  closedir(DIR);
			  foreach my $entry (sort @xfiles) {
			     next if $entry eq '.';
			     next if $entry eq '..';
			     if	(-1<$#map) {
				next if	-d "$dir/$path/$entry";
			     } else {
				next if	-d "$dir/$entry";
			     }
			     push @return, "$entry";
			  }
			  return @return;

		       }
		       my @xfiles=();
		       my @return=();
		       if ($^O eq 'cygwin') {
			  opendir(DIR,'/cygdrive/c/') || die $!;
		       } else {
			  opendir(DIR,'/') || die $!;
		       }
		       @xfiles = readdir(DIR);
		       closedir(DIR);
		       foreach my $entry (@xfiles) {
			  next if $entry eq '.';
			  next if $entry eq '..';
			  next if -d "$entry";
			  push @return,	"$entry";
		       }
		       return @return;

		    },
		 },
		 Banner	=> "   Current Directory: ]P[\n",

	      );

	      my $selection=Menu(\%dir_menu);

	      if (ref $selection eq 'ARRAY') {
		 print "\nSELECTION=",(join " ",@{$selection}),"\n";
	      }	else {
		 print "\nSELECTION=$selection\n";
	      }

USAGE and NAVIGATION
       Usage of	"&pick()" and/or "&Menu()" during the runtime of a script in
       which one or both are included, is simple and intuitive.	Nearly
       everything the end user needs in	terms of instruction is	included on-
       screen. The script-writer/developer/programmer can also include
       whatever	instructions s/he deems	necessary and/or helpful in the
       customizable "Banner" (as described above). There is however, one
       important feature about using "&Menu()" with sub-menus that's important
       to know about.

       Forward	' _ ' and  Backward  ' _ ' Navigation

       When working with more than one "&Menu()" screen, it's valuable to know
       how to navigate back and	forth between the different "&Menu()"
       levels/layers.  For example, above was illustrated the output for two
       layers of menus - a parent and a	child:

	   The user sees ==>

	      Choose a /bin Utility :

		 1.	   /bin	Utility	- arch
		 2.	   /bin	Utility	- ash
		 3.	   /bin	Utility	- awk
		 4.	   /bin	Utility	- basename
		 5.	   /bin	Utility	- bash
		 6.	   /bin	Utility	- cat
		 7.	   /bin	Utility	- chgrp
		 8.	   /bin	Utility	- chmod
		 9.	   /bin	Utility	- chown
		 10.	   /bin	Utility	- cp

	      a.  Select All   c.  Clear All   f.  FINISH
				  ___
	      93 Total Choices	 |_v_| Scroll with ARROW keys	[F1] for HELP

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

	   --< 5 >-<ENTER>----------------------------------

	   The user sees ==>

	      Choose an	Answer :

		  1	 bash is a Good	Utility
		  2	 bash is a Bad Utility

	      (Press [F1] for HELP)

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

	   In the above	example, suppose that the user "fat-fingered" his/her
	   choice, and really didn't want to "bash" bash, but wanted to	bash
	   awk instead.	Is restarting the whole	script/application now
	   necessary?  Suppose it was a	process	that had run overnight,	and
	   the user is seeing this menu	through	fogged glasses from the	steam
	   rising out of their morning coffee? Having to run the whole job
	   again would not be welcome news for the BOSS. THANKFULLY,
	   navigation makes this situation avoidable.  All the user would have
	   to do is type ' < ' to go backward to the previous menu, and	' > '
	   to go forward to the	next menu (assuming there is one in each
	   case):

	   The user sees ==>

	      Choose an	Answer :

		  1	 bash is a Good	Utility
		  2	 bash is a Bad Utility

	      (Press [F1] for HELP)

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

	    --<	 >  >-<ENTER>-----------------------------

	   The user sees ==>

	      Choose a /bin Utility :

		  1	 /bin Utility -	arch
		  2	 /bin Utility -	ash
		  3	 /bin Utility -	awk
		  4	 /bin Utility -	basename
	       -  5	 /bin Utility -	bash
		  6	 /bin Utility -	cat
		  7	 /bin Utility -	chgrp
		  8	 /bin Utility -	chmod
		  9	 /bin Utility -	chown
		  10	 /bin Utility -	cp

	      a.  Select All   c.  Clear All   f.  FINISH
				  ___
	      93 Total Choices	 |_v_| Scroll with ARROW keys	[F1] for HELP

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

	   Note	in the above example the Dash '	- ' in front of	item 5.	This
	   informs the user that s/he had previously selected this item. To
	   clear the selection,	the user would simply choose item 5 again.
	   This	effectively deletes the	previous choice	and restores the menu
	   for a new selection.	If the user was	satisfied with the choice, and
	   was simply double checking thier selection, they simply repeat the
	   navigation process by typing	' > ' -	then <ENTER> - and returning
	   to the child	menu they left.

	   If the child	menu was a multiple-selection menu, and	the user had
	   made	some selections	before navigating back to the parent menu, the
	   user	would see a ' +	' rather than a	' - '. This informs the	user
	   that	selections were	made in	the child menu.

	      Choose a /bin Utility :

		 1.	   /bin	Utility	- arch
		 2.	   /bin	Utility	- ash
		 3.	   /bin	Utility	- awk
		 4.	   /bin	Utility	- basename
	      +	 5.	   /bin	Utility	- bash
		 6.	   /bin	Utility	- cat
		 7.	   /bin	Utility	- chgrp
		 8.	   /bin	Utility	- chmod
		 9.	   /bin	Utility	- chown
		 10.	   /bin	Utility	- cp

	      a.  Select All   c.  Clear All   f.  FINISH
				  ___
	      93 Total Choices	 |_v_| Scroll with ARROW keys	[F1] for HELP

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

       View Sorted Items ' % '

       When working with numerous items	in a single menu, it may be desirable
       to see the set of choices organized in either descending	or reverse
       acscii order.  Term::Menus provides this	feature	with the Percent ' % '
       key.  Simply type ' % ' and the items will be sorted in descending
       ascii order. Type ' % ' again, and you will see the items reverse
       sorted. Assume that we have the following menus.

	   The user sees ==>

	      Choose a /bin Utility :

	       *  1	 [.exe
	       *  2	 2to3
		  3	 2to3-3.2
	       *  4	 411toppm.exe
		  5	 a2p.exe
		  6	 aaflip.exe
		  7	 aclocal
	       *  8	 aclocal-1.10
		  9	 aclocal-1.11
	       *  10	 aclocal-1.12

	      a.  Select All   c.  Clear All   f.  FINISH
				    ___
	      1925 Total Choices   |_v_| Scroll	with ARROW keys	  [F1] for HELP

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

	   --< % >-<ENTER>----------------------------------

	   The user sees ==>

	      Choose a /bin Utility :

	      *	 2.	   2to3
		 3.	   2to3-3.2
	      *	 4.	   411toppm.exe
		 759.	   FvwmCommand.exe
		 1650.	   Ted.exe
		 1782.	   WPrefs.exe
		 1785.	   X
		 1889.	   XWin.exe
		 1808.	   Xdmx.exe
		 1815.	   Xephyr.exe

	      a.  Select All   c.  Clear All   f.  FINISH

	      (Type '<'	to return to previous Menu)
				     ___
	      1925  Total Choices   |_v_| Scroll with ARROW keys   [F1]	for HELP

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

	   And if we choose to enter ' % ' again

	   --< % >-<ENTER>----------------------------------

	   The user sees ==>

	      Choose a /bin Utility :

		  1925	   znew
		  1924	   zmore
		  1923	   zless
		  1922	   zipsplit.exe
		  1921	   zipnote.exe
		  1920	   zipinfo.exe
		  1919	   zipgrep
		  1918	   zipcloak.exe
		  1917	   zip.exe
		  1916	   zgrep

	      a.  Select All   c.  Clear All   f.  FINISH

	      (Type '<'	to return to previous Menu)
				    ___
	      1925 Total Choices   |_v_| Scroll	with ARROW keys	  [F1] for HELP

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

	   This	submenu	of sorted selections works just	like any other menu.
	   The user can	deselect an item, clear	all items, re-choose all
	   items, etc. The choices made	here are preserved when	the user
	   navigates back to the original (parent) menu. In other words, if
	   Item	1. is deselected in the	sorted menu, Item 1.  will also	be
	   deselected in the parent menu. Navigating back to the parent	is
	   necessary - the menu	will not generate results from a sort menu.
	   Use either the LEFTARROW ' <	' key or FINISH	key ' F	or f ' to
	   return to the parent	menu, and then continue	your menu activities
	   there.

       View Summary of Selected	Items '	* '

       When working with numerous items	in a single menu, it is	desirable to
       see the set of choices made before leaving the menu and committing to a
       non-returnable forward (perhaps even critical) process. Term::Menus
       provides	this feature with the Star ' * ' key. Assume we	have the
       following menu with 93 Total Choices. Assume further that we have
       selected	items 1,3,9 & 11. Note that we cannot see Item 11 on the first
       screen since this menu is configured to show only 10 Items at a time.

	   The user sees ==>

	      Choose a /bin Utility :

	       *  1	 [.exe
		  2	 2to3
	       *  3	 2to3-3.2
		  4	 411toppm.exe
		  5	 a2p.exe
		  6	 aaflip.exe
		  7	 aclocal
		  8	 aclocal-1.10
	       *  9	 aclocal-1.11
		  10	 aclocal-1.12

	      a.  Select All   c.  Clear All   f.  FINISH
				    ___
	      1925 Total Choices   |_v_| Scroll	with ARROW keys	  [F1] for HELP

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

	   --< * >-<ENTER>----------------------------------

	   The user sees ==>

	      Choose a /bin Utility :

	       *  1	 [.exe
	       *  3	 2to3-3.2
	       *  9	 aclocal-1.11
	       *  11	 aclocal-1.13

	      a.  Select All   c.  Clear All   f.  FINISH

	      (Type '<'	to return to previous Menu)

	      ([F1] for	HELP)

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

	   This	submenu	of summary selections works just like any other	menu.
	   The user can	deselect an item, clear	all items, re-choose all
	   items, etc. The choices made	here are preserved when	the user
	   navigates back to the original (parent) menu. In other words, if
	   Item	1. is deselected in the	summary	menu, Item 1.  will also be
	   deselected in the parent menu. Navigating back to the parent	is
	   necessary - the menu	will not generate results from a summary menu.
	   Use either the LEFTARROW ' <	' key or FINISH	key ' F	or f ' to
	   return to the parent	menu, and then continue	your menu activities
	   there.

       Shell Out to Command Environment	' !command '

       Borrowed	from the editor	vi, users can run any command environment
       command (typically a shell command) without leaving their Term::Menus
       session or even context.	At anytime, a user can type an exclamation
       point ' ! ' followed by the command they	wish to	run, and that command
       will be run and the results returned for	viewing.

	   The user sees ==>

	      Choose a /bin Utility :

	       *  1	 [.exe
		  2	 2to3
	       *  3	 2to3-3.2
		  4	 411toppm.exe
		  5	 a2p.exe
		  6	 aaflip.exe
		  7	 aclocal
		  8	 aclocal-1.10
	       *  9	 aclocal-1.11
		  10	 aclocal-1.12

	      a.  Select All   c.  Clear All   f.  FINISH
				    ___
	      1925 Total Choices   |_v_| Scroll	with ARROW keys	  [F1] for HELP

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

	   --< !hostname >-<ENTER>----------------------------------

	   The user sees ==>

	      Choose a /bin Utility :

	       *  1	 [.exe
		  2	 2to3
	       *  3	 2to3-3.2
		  4	 411toppm.exe
		  5	 a2p.exe
		  6	 aaflip.exe
		  7	 aclocal
		  8	 aclocal-1.10
	       *  9	 aclocal-1.11
		  10	 aclocal-1.12

	      a.  Select All   c.  Clear All   f.  FINISH
				    ___
	      1925 Total Choices   |_v_| Scroll	with ARROW keys	  [F1] for HELP

	      ([ESC] to	Quit)	PLEASE ENTER A CHOICE:

	   central_server

	   Press ENTER to continue

AUTHOR
       Brian M.	Kelly <Brian.Kelly@fullautosoftware.net>

COPYRIGHT
       Copyright (C) 2000-2015 by Brian	M. Kelly.

       This program is free software; you can redistribute it and/or modify it
       under the terms of the GNU Affero General Public	License.
       (http://www.gnu.org/licenses/agpl.html).

perl v5.24.1			  2016-01-09			Term::Menus(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | ANONYMOUS SUBROUTINES AND MACROS | RECURSIVELY CALLED MENUS | USAGE and NAVIGATION | AUTHOR | COPYRIGHT

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

home | help