previous next top contents index framed top this page unframed
Figure 32–39. cmdMatch
| INTEGER PROCEDURE cmdMatch (STRING ARRAY(*) cmds; OPTIONAL STRING promptString; OPTIONAL BITS ctrlBits; PRODUCES OPTIONAL STRING s); |
cmdMatch is a standard means of presenting a menu of commands to the user and recognizing the user's choice or displaying the choices in response to a ? prompt.
cmdMatch matches a STRING (the “match STRING”) against the elements of cmds, and returns the index of the element that matches. The default case (in which ctrlBits is '0) is described first; it can be altered by setting various bits in ctrlBits.
32.38.1. The Default Case (No Bits Set in ctrlBits)
promptString is written to logFile.
A STRING is then read from cmdFile into s.
The match STRING is s.
A caseless comparison (see Section 4.8.2) is done between the match STRING and the elements of cmds (starting with the first) until either the match STRING is matched or all elements have been examined.
If the match STRING exactly (ignoring upper and lower case distinctions) matches a command, then that command is taken as the target command, and no further commands are examined.
If the match STRING matches an initial part of exactly one command, then that command is taken as the target command.
If the match STRING matches an initial part of more than one command, Ambiguous command is written to logFile and a new match STRING is read from cmdFile.
If the match STRING matches no command, Invalid command
is written to
logFile unless the first character of the match STRING is
?, in which
case the valid commands are written, one per line (the null
STRING is written as <eol>).
A new match STRING is read from cmdFile, and the matching
process begins again.
32.38.2. Non-Default Cases (ctrlBits is Non-Zero)
The valid
predefined bits for ctrlBits are as follows.
Setting these bits alters the default
behavior of cmdMatch:
| errorOK | If the match STRING is ambiguous or invalid, no message is written to logFile. An index one greater than the upper bound (if the match STRING is ambiguous) or one less than the lower bound (if the match STRING is invalid) of cmds is returned. |
| noResponse | Do not write promptString to logFile or read the match STRING from cmdFile; instead use promptString as the match STRING. If promptString is ambiguous or invalid, write the appropriate error message to logFile (unless errorOK is set), but do not prompt for another STRING, and return immediately with the same return value as if errorOK were set. |
| useKeyWord | The first word (sequence of non-whitespace
characters delimited by whitespace characters,
where a whitespace character is a blank, tab,
end-of-page, carriage return, or linefeed
character) is removed from the match STRING
and is used as the match STRING; the remainder
of the match STRING, leading whitespace
characters removed, is put into s. Matches
are attempted with the first word of each
element of cmds. If no match occurs and
errorOK (or noResponse) is set, the original
match STRING is produced in s. This bit might
be used, for example, for match STRINGs of the
form:
keyword blanks parameters for which keyword is used as the match STRING, and parameters is produced in s. |
| upperCase | The cases of letters in the commands in the cmds ARRAY are to be used to determine the minimum unambiguous abbreviations for commands. The part of the command sufficient to cause a STRING to match (if it would otherwise be ambiguous) should be uppercase, and the remainder of the command lowercase. |
When the noResponse bit is set,
cmdMatch normally uses promptString
as the match STRING, and does not write any information to
logFile
or read information from cmdFile,
except that an error message may be
written to logFile if the match STRING is ambiguous or invalid
(unless errorOK is set).
However, if promptString is "?",
the contents of the cmds ARRAY are
always written to logFile
as when noResponse is not set,
regardless of the setting of the errorOK bit,
and the value for “ambiguous” (one greater than the upper bound
of the cmds ARRAY) is returned.
Therefore, programs that want to suppress this behavior should
check to see if promptString is "?"
before calling cmdMatch with
noResponse set.
The above code behaves as follows:
The following code shows a use of the useKeyWord option:
If the user types the line pages 5, cmdIndex
is set to 1 and s is
"5". Thus the 5
does not take part in the matching process, but is
produced in the final argument.
32.38.3. Examples of cmdMatch
The following code shows how a comment may be put after the part of
the command that is to take part in the match:
STRING ARRAY(1 TO 3) commands;
...
IF NOT commands THENB
new(commands);
INIT commands
(
"NO HERALD do not put a herald on each page",
"NO PAGES do not print page numbers",
"COUNT do not print: just count pages",
);
END;
commandIndex := cmdMatch(commands,"command: ");
STRING ARRAY(1 TO 2) cmds;
INTEGER n;
STRING s;
...
new(cmds); INIT cmds ("PAGES","COPIES");
...
cmdIndex := cmdMatch(cmds,"command: ",useKeyWord,s);
n := cvi(s);
32.38.4. The upperCase Bit to cmdMatch
As an example of the use of the upperCase bit,
if two cmds elements are:
Closelibrary
CLOSEINTLIB
then C matches CLOSELIBRARY instead of being ambiguous, as it would be if upperCase were not set. The effect of following lowercase letters with uppercase letters in a command element (e.g., ClosELibRARY) is undefined.
In detail, the rules for upperCase are:
So, in the case of the cmds elements Closelibrary and CLOSEINTLIB, CL, CLO, CLOS, and CLOSE also all match CLOSELIBRARY. In the case of the cmds elements:
ABc
Abc
A matches Abc and AB matches ABc. In the case of the cmds elements:
CHeck
CHECKALL
C is ambiguous; CH, CHE, CHEC, and CHECK all match CHeck.
MAINSAIL Language Manual, Section 32.38