|
Copyright (C) 1999-2004 by Steve Litt
Current Dir --. Location of config file |
The UMENU configuration file defines menu system wide configurations, including the following:
The directory containing all menu definition files (at least for the user, if menudir= contains a $HOME string), contains a menu definition file for each submenu. The filename will contain only lower case alpha letters, with an exteonly lower case alpha letters, with an extension of .mnu. The first letter of the filename corresponds to the main menu to use. Therefore, the directory may contain up to 25 main menus (q is a reserved letter). The choice of main menu is made on the command line when invoking umenu. The remaining letters of the filename, up to but excluding the dot and extension, correspond to the keystroke sequence the user pressed to navigate to the submenu.
Thus, if the user accessed the "c" menu system, then pressed (in sequence) keys d, o and g to navigate to a submenu, the Menu Definition File defining that submenu would be cdog.mnu.
As of version 0.7.0, UMENU uses
a much simpler object architecture to make the program more robust and
maintainable:
|
|
Older versions used a much more
complex and hard to maintain object architecture:
|
However, the location (in any operating system) can be changed via the UMENU_CONFIG environment variable. This provides a great way to standardize menu configuration across a network, without client configuration.
nodedir= |
The Node directory. Location of
the Node.pm file and the EMDL to UMENU parser/converter. |
menudir= | The directory containing the menu files. Typically
$HOME/.umenu/menudir. |
scriptdir= | A directory into which the user can write script files to
execute.
Note that this can be achieved with environment variables to point to
the
user's home directory. Scripts are erased right after they're executed,
so this will not result in file buildup.
Scripts have filenames designed to make them unique. Otherwise multitasking and multiuser use of the menu program would fail, as commands and script files become switched. To accommodate this, script filenames start with the menu string of the invoked command, followed by the Unix date/time as the number of seconds since the epoch. To accommodate large number of users and processes, it's anticipated that later script filenames will also include the username, and possibly a terminal or process id. |
os= |
Valid values are unix and windows. Note that to get UMENU
to work you must use unix,
because at present UMENU does not work with Windows. Version 0.7.0
replaced the earlier error prone "OS autodetection" code with code that
looks to the configuration file to derive the operating system. The new
way is much more robust. |
getch_style= |
The distribution umenu.cnf file
sets this to 1, and hopefully you won't need to change it. Valid values
are 1 and 0, each of which cause the keystroke acquisition routine to
be configured slightly differently. If UMENU appears to fail just
before or during keystroke acquisition, you can try changing this
value. Modern Linuces and FreeBSD 5.1 work well with a value of 1, but
for other Unices or several year old Linuces, you might need to change
this setting. |
perl umenu.pl aNote that it's quite easy to create a script, in a directory on the executable path, to change directories and run this command for you. Note also that as other UMENU system implementations are developed, the command may change but the menu system letter will always appear on the command line.
The above mentioned command will bring up the main menu, whose information is contained in a file called a.mnu. Now let's say that the main menu, whose data is contained in a.mnu, contains a choice called "Editors", meant to bring up a submenu of all the possible editors. Let's further say that menu choice is invoked when the user presses the E key. In such a case, the data for the Editors submenu would be contained in ae.mnu. If the Editors menu had a choice L for Linux editors submenu, the had a choice L for Linux editors submenu, the Linux editors submenu would be contained in ael.mnu. Naturally, in DOS systems, this scheme would confine us to seven levels of submenu -- not a particularly confining restriction. In modern operating systems, it wouldn't constrain us at all.
It is an absolute specification of this system that all letters in the filename must be lower case. This makes life much easier in case sensitive operating systems, and allows easy transfer of a menu between operating systems.
A fundimental design criteria is that this menu system can easily be maintained by any text editor, such as DOS edit, Windows Notepad, or Linux vi. While we would expect programmers to add automated configuration tools, we want to be sure that the user's menu system is never "held captive" by such a tool. To accomplish that, we have created a simple convention within each file that does not require fixed length lines, allows for future expansion, and is easy to understand and edit.
NOTE
In earlier versions (before 0.7.0), Q was a reserved letter that automatically returned to the previous menu, or to the operating system if you were at the top level menu. These previous versions did not require a C (command) parameter line for any choice whose letter was Q. If you have menu definition files created for those earlier versions, and those definition files don't have C parameters on choices whose letters are Q, in version 0.7.0 and later you will see a string saying nop, standing for No OPeration, in front of such choices. Those choices do nothing in version 0.7.0 and later. |
Each line describes one and only one property of a menu choice. Each
line is ended by the newline native to the OS. Each line is composed
only
of printable characters. The first character of each line is a flag
indicating
the purpose of the line.
Version 0.7.0 allows multiple C lines, which concatinate in order separated by a space. If you want each of these to be a separate command, end each with a semicolon.
To reduce the likelihood of corruption, the file is absolutely NOT fixed record length.
T_Networking Menu
L_S
T_Shutdown now
C_/sbin/shutdown -h now
L_O
D_/etc
C_find -type f | xargs grep -l 192.168.1.2 | less
T_Search /etc/*.conf tree for old ip
Col
1 Ltr |
Data
Type |
Description | Handling multiples | |||
L | Menu Letter | The letter the user must press to invoke this menu choice. All lines under a letter line describe that menu choice, until another letter line or EOF is encountered. | Since Letter lines delineate menu choices, by definition it's impossible to have two per menu choice. If two choices on a menu have the same letter, it's up to the menu program to decide how to handle it, either by always running the first, always running the last, or giving the user a choice. | |||
T | Text | The text to be placed on the menu. Menu programs will truncate as necessary for screen considerations. If this line appears above all Letter lines, it's the submenu's title. | Having two text lines in a menu choice is an error, but it should not terminate the menu system. It shall be handled by ignoring all but the first. Optionally, the program may issue a message, then return to normal operation. | |||
C | Command | The exact command to be issued, or the exact command combined
with
prompted user-input substitutions, or a special character telling the
menu
program where to go next.
The next section of this document contains a detailed discussion of Menu Definition File Command Line Syntax. |
As of version 0.7.0, multiple command lines for a given
choice are concatenated separated by spaces. If these commands are
intended to be separate Bash commands, each should end in a semicolon. In versions before 0.7.0, having two command lines in a menu choice was an error. |
|
||
D | Directory | The directory to switch to before issuing the command. This directory should appear exactly as it would in a cd command. | Having two directory lines in a menu choice is an error, but it should not terminate the menu system. It shall be handled by ignoring all but the first. Optionally, the program may issue a message, then return to normal operation. | |||
V | driVe | For DOS compatibility, the menu program will switch to this drive before executing the cd command to the directory. If accidentally used in a UNIX type system, it will be ignored. | Having two drive lines in a menu choice is an error, but it should not terminate the menu system. It shall be handled by ignoring all but the first. Optionally, the program may issue a message, then return to normal operation. | |||
P | Prepath | One or more directories that should be added to the existing
path,
at the beginning of the existing path, in order to successfully run the
command. The menu program will prepend this exact data to the existing path, so this data must end with the path separator for the OS in question. It is the responsibility of the menu program to remove these directories from the path at the conclusion of the command. |
Having two prepath lines in a menu choice is an error, but it should not terminate the menu system. It shall be handled by ignoring all but the first. Optionally, the program may issue a message, then return to normal operation. | |||
# | Comment | Ignore this line completely. Note that this ONLY works in column 1, nowhere else. | Multiples are fine. These are just comments. | |||
E | Environment Var | A command to set an enviro | E | Environment Var | A command to set an environment variable. The menu program
will execute
the command, and must reset or remove this set at the conclusion of the
command (so it must know prior state). Unlike most other lines, it is
perfectly
OK to have multiple E lines.
Because of the difficulty of implementing this across
different operating
systems, handling E lines is optional for a menu program, but it works
for UMENU. |
It is perfectly permissible to have multiple environment lines, in which case each one will be set. |
S | Stop | Stop after running the program so the user can see the
screen. Without
this, the menu program would appear over the concluded program's
output,
eraseing it.
The data portion of the line will be a prompt. If there's no data, the menu program will print "Press Enter to continue==>" |
Having two stop lines in a menu choice is an error, but it should not terminate the menu system. It shall be handled by ignoring all but the first. Optionally, the program may issue a message, then return to normal operation. | |||
= | Special
Config Program Use |
Originally,
lines starting with an equal sign hold temporary info, such as the
original and new menu files and choice letters and location in the
menu,
during execution of lint or config programs. These should be deleted at
the conclusion of such programs, and never thought of as permanent
data.
Menu programs should ignore these lines, and Lint programs should issue
stern warnings upon finding such lines in menu definition files (unless
that lint program put it in). Because EMDL is a much better way to configure a UMENU menu system than were the old scripts, modern versions of UMENU no longer have scripts that use the equal sign in this way, but it's still reserved for that purpose. |
In config and lint programs, there are typically several equal sign lines. The following characters determine their use. The existance of such lines during execution of a menu pance of such lines during execution of a menu program is considered a non-important error, and should be ignored. |
NOTE
Before version 0.7.0, it was an error to have multiple command lines. Also, before 0.7.0 it was permissible to leave the command line off any choice whose menu letter was Q, because any such choice defaulted to exit. As of 0.7.0, the Q letter does not cause the choice to exit, and as a warning prints the string nop, standing for No OPeration, before the menu letter on the menu. |
Command lines can be either pseudo command lines, which define menu system navigation, or real command lines, which trigger the operating system to perform the command. Real command lines can be configured to prompt the user for arguments.
^ | Go up one menu level, or exit the menu program if already at
the top.
Note that the ^ command can be considered the inverse of the ~ command explained below. |
~ | Go down one level. Execute the submenu defined by the present
menu's
definition file filename, with this Letter choice tacked on to the end.
In other words, if from menu ab.mnu, the user pressed the c key, and
letter
c has a command of ~, the menu program would execute the menu defined
by
file abc.mnu.
If no menu definition file exists for the new submenu (abc.mnu in the example above), the program will issue an error message, prompt the user to hit a key signifying he's seen the error message, then return the user to the original menu (ab.mnu in the example above). |
L_DThe D choice illustrated above would run the command, giving a directory listing of the current directory, showing a single column with details, in reverse time order.
T_Files current dir
C_ls -ltr
These modifications to the command environment are accomplished by placing other kinds of lines after the Choice Letter Line. Such lines include the Prepath line (P), the Directory line (D), the drive line (V, dos/win only), and the Stop line (S).
L_SAfter the user presses S, the menu program will pause with the following prompt:
T_Search a directory
C_ls -ltr %1%Directory to be searched%%
S_1
Directory to be searched==>The user will then type in the directory, for instance, /etc. The program will replace the %1%Directory to be searched%% token with the user-input string /etc, and run the command ls -ltr /etc. A replacement token is defined by a percent sign, followed by a single character, followed by another percent sign, followed by a string, followed by two consecutive percent signs.
But using UMENUs argument replacement feature, it can be set up in
one
minute, as follows:
C_find %1%Tree to search%% -type f | xargs grep -l %2%Search string%% | sort %4| xargs grep -l %2%Search string%% | sort %4%Type -r for reverse, otherwise type nothing%% -o %3%Output file%% |
Note that this would be entirely one line in the file, even though it word wraps in this HTML document. When the user chooses this item, he'd respond to the following four prompts in following order. Let's imagine the user responded to the prompts as indicated by the bolded text in the example below:
Tree to search==>/etcThis would create file junk.jnk, containing a list of all files in directory /etc and below containing string 192.168.102. This file would be sorted in non-reverse order.
Search string==>192.168.103
Output file==>junk.jnk
Type -r for reverse, otherwise type nothing==>
The order of the prompts is determined by the character between each replacible argument's initial percent signs. If two arguments contained the same char between their initial percent signs, their order would be determined by the sort order of the entire replacement prompts.
Note that the above example was meant to be very complex. Most are
simpler.
Check out this interface to the locate command:
C_locate %1%Search text%% |
|