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 is a stand-alone - other CPAN modules are not needed for its implementation ( so it's easy to install! ;-) )
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:
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
(Type "quit" to quit)
PLEASE ENTER A CHOICE:
--< 2 >-<ENTER>----------------------------------
The user sees ==>
SELECTION = Second Item
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
93 Total Choices
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" 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
93 Total Choices
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" to quit)
PLEASE ENTER A CHOICE:
--< 14 >-<ENTER>----------------------------------
The user sees ==>
SELECTION = date
use Term::Menus;
my @list=`ls -1 /bin`;
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
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" 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
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" to quit)
PLEASE ENTER A CHOICE:
--< f >-<ENTER>----------------------------------
The user sees ==>
SELECTIONS = /bin Utility - awk /bin Utility - chgrp
use Term::Menus;
my %Menu_2=(
Label => 'Menu_2',
Item_1 => {
Text => "]Previous[ is a ]Convey[ Utility",
Convey => [ 'Good','Bad' ]
},
Select => 'One',
Banner => "\n Choose an Answer :"
);
my %Menu_1=(
Label => '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
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" to quit)
PLEASE ENTER A CHOICE:
--< 5 >-<ENTER>----------------------------------
Choose an Answer :
1. bash is a Good Utility
2. bash is a Bad Utility
(Type "quit" to quit)
PLEASE ENTER A CHOICE:
--< 1 >-<ENTER>----------------------------------
The user sees ==>
SELECTIONS = bash is a Good Utility
(Note: READ THE COMMENTS embedded in the Menu_2 sample following. The syntax is a bit tricky and MUST be created exactly as described - otherwise it will NOT work!)
package current_package_name; # Qualify subroutine calls with
# &main:: if not using
# a package architechture
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 @testlines;
## return value must NOT 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=(
Label => 'Menu_2',
Item_1 => {
Text => "]Convey[",
Convey => "¤t_package_name::create_items(\"]Previous[\")",
# IMPORTANT! '&' must be used to denote subroutine
# as the first character
# ¤t_package_name:: qualifier or &main::
# quaifiler MUST be used - otherwise
# Term::Menus cannot locate it
# embedded quote characters must be escaped
# enclosing double quotes MUST be used - this is
# a STRING being passed to Term::Menus that will
# then be internally eval-ed during runtime
# after the macro ]Previous[ is substituted
# other macros and values can be passed as
# arguments as follows:
# (\"]Previous[\",\"AnyString\")
},
Select => 'One',
Banner => "¤t_package_name::create_banner(\"]Previous[\")",
## or "&main::create_banner(\"]Previous[\")",
## if using in top level script (file does NOT
## have .pm extension)
);
my %Menu_1=(
Label => '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
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" 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
(Type "quit" to quit)
PLEASE ENTER A CHOICE:
--< 1 >-<ENTER>----------------------------------
The user sees ==>
SELECTIONS = bash is a Good Utility
More examples are in the EXAMPLES section below.
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
METHODS
pick - create a simple menu
$pick = &pick ($list|\@list|['list',...],[$Banner]);
Where $list is a variable containing a 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 a array or list reference of
the pick or picks.
@picks = &Menu ($Menu_1|\%Menu_1|{ Label => '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=(
Label => 'Menu_2',
Item_1 => {
Text => "]Previous[ is a ]Convey[ Utility",
Convey => [ 'Good','Bad' ]
},
Select => 'One',
Banner => "\n Choose an Answer :"
);
my %Menu_1=(
Label => '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:
*
Display => 15,
*
Label => 'Menu_1',
*
Item_1 => { Text => 'Item 1' },
Item_2 => { Text => 'Item 2' },
Items created via "]Convey[" macros have two drawbacks:
* They all have the same format.
* They all share the same "Result" element.
The syntax and usage of Item_<int> elements is important and
extensive enough warrant it's own section. See Item Configuration
Hash Structures below.
*
Select => 'Many',
*
Banner => "The following items are for selection,\n".
"\tEnjoy the Experience!",
NOTE: Macros (like "]Previous[" ) can be used in Banners! :-) (
See Item Configuration Macros below )
Item Congfiguration 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:
*
Text => 'This is Item_1',
*
Convey => [ `ls -1` ] ,
*
Default => 'base|chown',
Default => qr/base|chown/i,
The user sees ==>
Choose a /bin Utility :
93 Total Choices
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" to quit)
PLEASE ENTER A CHOICE:
*
Exclude => 'base|chown',
Exclude => qr/base|chown/i,
*
Include => 'base|chown',
Include => qr/base|chown/i,
*
Result => \%Menu_2,
--or--
*
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 Congfiguration 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:
*
use Term::Menus;
my %Menu_1=(
Label => '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
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" to quit)
PLEASE ENTER A CHOICE:
NOTE: "]C[" can be used as a shorthand for "]Convey[".
*
The "]Previous[" Macro can also be used in the Banner.
use Term::Menus;
my %Menu_2=(
Label => 'Menu_2',
Item_1 => {
Text => "]Previous[ is a ]Convey[ Utility",
Convey => [ 'Good','Bad' ]
},
Select => 'One',
Banner => "\n Choose an Answer :"
);
my %Menu_1=(
Label => '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
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" to quit)
PLEASE ENTER A CHOICE:
--< 5 >-<ENTER>----------------------------------
Choose an Answer :
1. bash is a Good Utility
2. bash is a Bad Utility
(Type "quit" 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[".
*
The "]Previous[{Menu_Label}" Macro can also be used in the Banner.
use Term::Menus;
my %Menu_3=(
Label => '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=(
Label => '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=(
Label => '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
PLEASE ENTER A CHOICE:
--< 5 >-<ENTER>----------------------------------
Is bash Good or Bad? :
1. bash is a Good Utility
2. bash is a Bad Utility
(Type "quit" 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!
(Type "quit" 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_Label}" can be used as a shorthand for
"]Previous[{Menu_Label}".
"]C[" can be used as a shorthand for "]Convey[".
*
use Term::Menus;
sub selected { print "\n SELECTED ITEM = $_[0]\n" }
my %Menu_1=(
Label => 'Menu_1',
Item_1 => {
Text => "/bin/Utility - ]Convey[",
Convey => [ `ls -1 /bin` ],
Result => "&selected(]Selected[)",
},
Select => 'One',
Banner => "\n Choose a /bin Utility :"
);
my @selections=&Menu(\%Menu_1);
print "SELECTIONS=@selections\n";
NOTE: "]S[" can be used as a shorthand for "]Selected[".
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] }
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 :
93 Total Choices
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" to quit)
PLEASE ENTER A CHOICE:
--< 5 >-<ENTER>----------------------------------
The user sees ==>
Choose an Answer :
(Type "quit" 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 :
(Type "quit" to quit)
PLEASE ENTER A CHOICE:
--< > >-<ENTER>-----------------------------
The user sees ==>
Choose a /bin Utility :
93 Total Choices
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" 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 :
93 Total Choices
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" 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 ==>
Please select all files for immediate transfer:
929 Total Choices
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" to quit)
PLEASE ENTER A CHOICE:
--< % >-<ENTER>----------------------------------
The user sees ==>
Please select all files for immediate transfer:
929 Total Choices
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" to quit)
PLEASE ENTER A CHOICE:
And if we choose to enter ' % ' again
--< % >-<ENTER>----------------------------------
The user sees ==>
Please select all files for immediate transfer:
929. znew has been transferred
928. zmore has been transferred
927. zless has been transferred
926. zipsplit.exe has been transferred
925. zipnote.exe has been transferred
924. zipinfo has been transferred
923. zipgrep has been transferred
922. zipcloak.exe has been transferred
921. zip.exe has been transferred
920. zgrep has been transferred
a. Select All. c. Clear All.
f. Finish.
929 Total Choices
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" to quit)
PLEASE ENTER A CHOICE:
This submenu of 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-or-if 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 above.
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 :
93 Total Choices
Press ENTER (or "d") to scroll downward
OR "u" to scroll upward (Type "quit" to quit)
PLEASE ENTER A CHOICE:
--< * >-<ENTER>----------------------------------
The user sees ==>
Choose a /bin Utility :
(Type "quit" to quit)
PLEASE ENTER A CHOICE:
This submenu of 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-or-if 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 above.
EXAMPLES
AUTHOR
Brian M. Kelly <Brian.Kelly@fullautosoftware.net>
COPYRIGHT
Copyright (C) 2000, 2001, 2002, 2003, 2004,
2005, 2006, 2007, 2008, 2010,
2011
by Brian M. Kelly.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License. (http://www.opensource.org/licenses/gpl-license.php).