Sub-menus in the User Menu are produced by a type of library file, ``script menus'', which (at the top level) are found in the directories in the script search path. The script menus must have an extension ``.scm'' (``script menu''). The format is similar to library files:
(Library libname);
# any comments
# optional keywords to implement conditional flow
Define [eval] name [value]
If expression
IfDef name
IfnDef name
Else
Endif
[ nosort]
name1 path_to_script
...
[ name2] path_to_menu
...
The first line must be a CIF comment line in the same format as other library files. The libname contains the text which will appear in the menu button which will pop up the menu. This text may contain white space and/or punctuation, though some special characters, such as `/', may be stripped or replaced internally. The text can be quoted, though this is optional. The text can also not appear at all, in which case the label used will be the base name (the file name, stripped of the .scm extension) of the menu file.
Blank lines and lines starting with `#' are ignored. If a line containing the single word ``nosort'' is found, then the menu entries will be in the same order as in the file, otherwise they will be alphabetically sorted. The User Menu itself is always sorted.
All library files (including the device library) support a limited macro capability. The macro capability makes use of the generic macro preprocessor provided in Xic, which is described in 18.1. The reader should refer to this section for a full description of the preprocessor capabilities. The preprocessor provides a few predefined macros used for testing (and customizing for) release number, operating system, etc. The keyword names, which correspond to the generic names as described for the macro preprocessor, are case-insensitive and listed in the following table.
| Keyword | Function |
|---|---|
| Define | Define a macro. |
| If | Conditional evaluated test. |
| IfDef | Conditional definition test. |
| IfnDef | Conditional non-definition test. |
| Else | Conditional else clause. |
| Endif | Conditional end clause. |
These can be used to conditionally determine which parts of the file are actually loaded when the library is read. The paths (but not the names) are macro expanded, and the conditional keywords can be used to implement flow control as the file is read. They work the same as similar keywords in the technology file (see A.2) and in scripts (see 18.8), and are reminiscent of the preprocessor directives in the C/C++ programming language.
The Define eval construct can access functions found in a script library file (see 17.3) found in the same script search path component directory as the menu file file, or from library files found earlier in the search path. When traversing the script search path, the library file, if any, is loaded before the script files and menu files are read.
The remaining lines in the file are name/path pairs, where the name is the label that will appear on the button in the pop-up menu, and the path is a full path to a script file (with ``.scr'' extension) or another script menu file (with ``.scm'' extension) for a sub-menu. If the path is to a menu file, the pop-up menu will contain a button which will produce another pop-up menu containing the referenced menu file's entries. There is no limit on the depth of the references. In this case, the name can be omitted, in which case the referenced menu file will supply the button text. If a name is given, it will supersede the button text defined in the referenced menu file.
A name must always be given for a path to a script file. If the label text in name contains white space, it must be quoted. Punctuation is allowed, though some characters may be stripped or replaced internally. Each name text should be unique in the menu, duplicates are ignored.
Scripts referenced through a menu file should not be kept in the script search path directories, as they would be added to the main User Menu as well as the pop-up menu. They can be placed, for example, in a subdirectory of the directory containing the menu file, which is not itself in the script path.
Only scripts which are defined in separate files can be referenced through a script library, not those defined in the technology file. Scripts defined in the technology file, and those added with the !script command, will appear in the main User Menu.
Example:
Suppose that you have a submenu.scm file, and you want to be able to set the command paths at program startup, depending on some factors. One way to do this is to white a function and place it in the script library file, that will return a path to a directory containing the menu functions, e.g.,
function func_loc()
if (something)
return ("/home/bob/commands")
else
return ("/home/joe/commands")
end
endfunc
In the submenu.scm file, one has lines like
define eval FUNC_LOC func_loc()
cmd1 FUNC_LOC/cmd1.scr
cmd2 FUNC_LOC/cmd2.scr
...
In this example, the menu appearance is always the same, however the functions executed when a button is pressed depend on the func_loc() return.