Menu info table management is performed by create_menu( ) and find_menu( ). Because MENU structures are stored directly, there is no need to worry about memory allocation when creating a new MINFO entry. create_menu( ) defines a local MINFO structure, initializes it appropriately, and returns it by value to the calling routine. To find a given MINFO entry, find_menu () iterates through the MInfo array, comparing the name of each registered entry with the name string supplied. When a match occurs, a pointer to the structure having the matching name is returned.

The item info table is managed by create_item( ) and find_item( ). find_item( ) works like find_menu( ). Because IINFO structures are stored by reference (to reduce memory requirements), create_item( ) must allocate a memory block for the new IINFO structure and return a pointer to that block. Provided there wasn't any problem with obtaining the memory, both the IINFO structure and its member INFO structure get initialized with all the default values appropriate to an unprocessed item entry.

The itemcheck( ) function is called from a few places in cmenu to make sure both required portions of an item definition, the text and an action clause, have been specified.

When a menu specification file has been completely processed and no fatal errors occurred, the write_file( ) function is called to create the output file on disk. After creating the output filename and opening the file for writing (in binary mode), the first thing write_file( ) actually writes is the value of the global menu count, n_menus. Each menu is then written to the file in a format consisting of the MENU structure first, then each associated ITEM structure. There is no need to write an explicit item count for each menu because that information is already part of the MENU structure, and rmenu can obtain that value dynamically when the .mnc file is loading for execution. To insure portability across machines with different storage requirements for various variable types, all reads and writes involving the .mnc file are performed using the sizeof operator to determine how many bytes to transfer. Even writing a simple integer value, such as the menu count (line 273), should employ sizeof rather than a constant byte count value such as 2 or 4.

After each item is written to disk, its memory block is freed (line 299). If there are many menu definitions in a single menu specification file, then many blocks of item memory will end up having been allocated and freed repetitively. Since, however, cmenu is only run occasionally, the extra overhead this repetition entails isn't enough to have a noticeable effect on performance.

In rmenu, realtime efficiency is far more critical because many processes may be active simultaneously. (I often see between ten and fifteen rmenu processes running concurrently at the office.) Later we'll see how rmenu employs a slightly more complex allocation strategy to avoid the memory thrashing problem.

ANSI C function headers allow the specification of ellipses (...) to indicate a variable number of arguments in a function header or prototype. The macros va_list and va_start, used in the processing of the variable length argument list, are taken from the <stdarg.h> standard header file (see line 16).

Pre-ANSI C, on the other hand, cannot handle ellipses in function definitions. Before the existence of ellipses and <stdarg.h>, functions taking a variable number of arguments were processed with the macros defined in <stdarg.h>'s predecessor, <varargs.h>. <varargs.h> contains alternate versions of the macros va_list and va_start, plus an additional macro named va_alist that is used in function headers as the placeholder for optional arguments.

The usages of <varargs.h> and <stdarg.h> differ only up to (and including) the appearance of the va_start macro. After that, the methods are equivalent, so the conditional portions of the three error reporting functions end at that point.

Each diagnostic function calls fprintf( ) to send the name and current line number of the source file involved to the standard error stream. Then they call vfprintf( ) to send the specific error information suppled in the call to the standard error stream. The only difference between the three functions is in the way they affect the global error flags. warning( ) sets no flags. error( ) sets only err_flag. fatalerr( ) sets both err_flag and fatal. Setting the fatal flag causes processing of the current source file to be terminated immediately upon return to the main processing loop, while err_flag is sampled only after the current source file has been completely processed (without fatal errors) to determine if an object file should be written.

The strstr( ) function tests if one given string is a subset of a second given string. strstr( ) is supplied in case your library does not already include it. Compilation of strstr( ) is conditionally controlled by the NEEDSTR symbolic constant defined in the makefile.

Tokens are the basic syntactic objects manipulated by cmenu. Each token is represented by an integer value, sometimes in conjunction with the value of an auxiliary variable. If the token represents a keyword or special condition, then the integer value alone is sufficient to qualify it. If the token represents a string or a numeric value, then the token value T_STRING or T_VALUE in conjunction with the text in global array tparam (for strings), or the integer value of the global vparam (for values) is needed to fully qualify the token. You'll find definitions for tparam and vparam in ccmenu.h (see CUJ, January, 1992). The token values are defined in lines 41-99.

When gettok( ) is called it first checks for an active ungotten token. If found, all the saved static token detail variables are copied into th eir global counterparts and gettok( ) returns the saved token value.

If there wasn't an active ungotten token, it is time to get a new one. The global detail variables tparam and vparam are cleared, and getword( ) is called to fetch the next syntactic object from the input stream. Lines 85-98 handle the easy kinds of tokens: EOF, quoted string, colon, or simple reserved word. (In the case of quoted text, the text needs to be copied into tparam.) Lines 100-104 process integer values by setting vparam if a leading digit is detected and returning T_VALUE. If we reach line 105, the token is treated as an unquoted string: the text is copied into tparam, and T_STRING is returned.

The ungettok( ) function (lines 29-49) first checks to make sure there isn't already a token pushed back. (There shouldn't ever be if the program is working correctly; this test was put here only to catch possible development bugs.) Then all the token detail values are saved in the static variables.

As each token processing function receives control, it can count on the availability of certain information through global variables. We've already seen how most of these global variables are managed. There's one more, named token, that contains the most recently scanned token value (responsible for arrival at a particular function in cmenu2). This variable is assigned in the main processing loop, immediately before the dispatch is performed. We need to know this value, because some token processing functions can handle more than one token, and they examine the value of token to determine which token they have been called to process.

do_title( ) and do_path( ) are very similar, each verifying the existence of its required text string parameter, making sure the option hasn't appeared before, and stuffing the string into the appropriate element of the current Menu structure. (Mp comes in handy here.)

do_path( ) performs all the steps above, plus one more: it deletes any trailing path delimiter character (slash or backslash) found at the end of the path text. This prevents two consecutive path delimiter characters from appearing in a path string when incremental paths are glued together.

The do_align( ) function was originally intended to support alternative ways of aligning the item text on the screen. I later changed my mind about the usefulness that option and never taught rmenu how to recognize it. The cmenu code for processing the option remains, if someone thinks of a reason for rmenu to use it.

do_spacing( ) and do_columns( ) are similar to do_title( ) and do_path( ), but they take an integer instead of a text string for their parameter. I don't think they require any further annotation.

The do_escape( ) function handles both the escape and noescape options, checking for the usual error conditions and then setting the escape flag in the Menu structure to either YES or NO. If this option does not appear, the default value for the escape flag ends up being DEFAULT, which has a very different meaning from both YES and NO.

The do_endmenu( ) function pulls clean-up duty after a menu definition. If no items were found, that merits an error message. The forward reference table is then checked to make sure all references have been resolved. If an unresolved reference is found, then a little shuffle-play is performed involving the global line number variable, lineno. This forces the error message function to report the line number where the unresolved reference was made, instead of the current line number.

Finally, global modes are reset in lines 284-287 with values indicating a "not in menu" status. The Processed flag is set to show that the menu has now been defined, and the number of items found is stashed away in the Menu structure (squeezing some final mileage out of old venerable Mp).

There is no explicit keyword to mark the end of an item definition. The first thing, therefore, the do_item( ) function (lines 291-357) must do is check that the last item, if any, defined in the current menu included its required clauses. The call to itemcheck( ) in line 303 does this.

Next, we test if a label is attached to the item definition. If not, a dummy name is constructed; if so, the identifier name used is checked for legality in lines 311-326.

Lines 328-329 make sure that the label name has not been used before in the current menu. Even if a forward reference has been made to this label, it will not show up in a call to find_item( ) because the forward reference information has all been segregated into the fwd_refs table (to be examined shortly).

The do_opts( ) function handles a whole slew of trivial binary options by setting Item flags to values triggered directly by the option tokens. There are three functional categories processed by do_opts( ): prompting, pre-clearing and post-clearing. Only one option from each of those three categories is permitted to appear within any one item definition. The flag associated with each category is initialized to the value DEFAULT. It keeps that value until the appropriate statement forces the value to either YES or NO.

The do_nextitem( ) function processes the nextitem clause, so the user may alter the menu system's flow of control. One of four variations must be used. The last is to supply a label for the next item to be highlighted. If the next token after nextitem is a string, then find_item( ) is called to see if the item has been defined. If it has, its index is inserted into the nextitem element of the Item structure and no forward referencing is involved. If find_item( ) couldn't find it, lines 432-437 install the item reference into the forward reference table, for resolution when the item definition with the given label finally appears. If you missed it, see "The Item Clause" section above for related details.

If the screen text for the menu item was not specified in the item clause, it must appear in a subsequent text clause. The do_text( ) and do_text2( ) functions process this option. After do_text( ) has checked the basics, do_text2( ) tests whether the string is too long to store in the available space. If it's too long, a message is printed and no attempt is made to copy the string into the ITEM structure.

After copying a reasonable length string in through the Ip pointer, the flag named widest (in the MENU structure) is updated to reflect the length of the longest item text seen so far. This value will be used by rmenu when it comes time to decide how all the menu items will be arranged on the screen.

The exit action may be specified either with or without the action keyword preceding it. Both forms are valid.

The basic action clause is specified by the action keyword and a text string. The string represents an operating system command (or sequence of commands separated by semicolons). All do_action( ) does is copy the string (through Ip) into the action element of the current ITEM structure (line 527). The emenu action, which calls an external menu, is processed in the same way, except that the acttyp element of the ITEM structure is set to identify the action string as an external menu name rather than a command to be passed to the system's command interpreter.

The fourth type of action is the lmenu clause, specifying a local menu to run. If no menu by the given name is found in the file, a menu structure is created and added to the MInfo array, and the index number of the new menu entry is plugged into lmenunum element of the item being processed.

There is nothing new to say about the do_help( ) function, so I won't.

The final function in the module, do_err( ), gets called whenever a keyword is encountered unexpectedly (for example when the first keyword is seen without a leading nextitem). In the keywords table array, any keyword that does not represent the beginning of a legitimate option sequence is assigned do_err( ) as its processing function. By calling the fatalerr( ) function to print its error message, do_err( ) forces compilation to be terminated immediately after the error message is printed, allowing the user to fix the syntax without having to deal with additional spurious error messages.