SYNOPSIS
#include <vistaio.h>
VistaIOBoolean VistaIOParseCommand (noptions, options, argc, argv)
- int noptions, *argc; VistaIOOptionDescRec options[noptions]; char *argv;
ARGUMENTS
- noptions
- Specifies the number of entries in the table of option descriptors.
- options
- Specifies the location of the table of option descriptors.
- argc
- Specifies the number of command line arguments to be parsed, and returns the number of arguments that were not recognized as valid options.
- argv
- Specifies a vector of command line arguments to be parsed, and returns a vector of the arguments that were not recognized as valid options.
DESCRIPTION
VistaIOParseCommand parses command line arguments according to a table that describes valid command line options. The VistaIOoption(3) manual page describes this table's contents and specifies the forms that command line options may take. The noptions and options arguments specify the length and location of the table.The argc and argv arguments to VistaIOParseCommand are normally identical to the parameters of the program's main function. (Note, however, that the address of main's argc is passed rather than the actual value of argc.)
VistaIOParseCommand uses the first command line argument, argv[0], in a call to VistaIOSetProgramName(3) to record the program's name for future error messages.
The remaining command line arguments are then processed sequentially from argv[1] through argv[*argc - 1]. An argument is examined to determine whether it is an initial substring of any option keyword defined in the options table. If so, arguments following the keyword may be parsed as values associated with the option. The values are stored at locations specified by the options table. If a variable number of values are associated with the option, VistaIOParseCommand will allocate a vector of the appropriate length for them. Following the value arguments, VistaIOParseCommand expects either another option keyword or the end of the list of command line arguments.
If VistaIOParseCommand encounters an argument that could be an option keyword (based on its position among the command line arguments) but that isn't among the keywords defined in the table, it merely passes over it without complaint. Any such arguments that are not recognized are returned to the caller (see ``RETURN VALUES'', below).
VistaIOParseCommand checks that each required option appears once in the command line, and that each optional option appears at most once. If an option appears more than once, a message is printed and only values supplied with the last appearance of the option are retained. The options table entry for an optional option may specify the location of a VistaIOBoolean that is to be set to indicate whether the option was encountered. VistaIOParseCommand will set the VistaIOBoolean to TRUE if the option was encountered, and to FALSE otherwise.
In addition to the options specified by the options table, VistaIOParseCommand recognizes the option -help. When it encounters -help, VistaIOParseCommand ignores the remaining arguments on the command line, sets *argc to 1 to indicate that all arguments have been accounted for, and returns FALSE to indicate that the command line parse was not completed successfully. These returned indications normally cause the caller to print command usage information as shown in the code example below.
RETURN VALUES
VistaIOParseCommand returns FALSE if an option that appears among the command line arguments lacks the correct number of values of the appropriate form. It also returns FALSE if a required option is missing from the command line arguments. Finally, it returns FALSE if it encounters a -help option. Otherwise, VistaIOParseCommand returns TRUE. Thus, TRUE indicates that the command were parsed successfully by VistaIOParseCommand and that the program may continue on that basis.VistaIOParseCommand also returns a revised argv containing only the command line arguments that it did not recognize as valid options. In *argc it returns the number of such arguments. VistaIOParseCommand moves elements of the argv vector of strings so that all arguments that are not part of valid options are in the first *argc elements. At minimum, there will be one: the program's name. Others might be options that, for some reason, the programmer chooses not to handle with VistaIOParseCommand --- e.g., X Windows parameters that must be given to XtDisplayInitialize(3Xt) instead.
EXAMPLES
The following code fragment parses command line arguments using VistaIOParseCommand. Any arguments not recognized by VistaIOParseCommand are then parsed by some other means (e.g., by XtDisplayInitialize(3Xt)). Finally, if any arguments remain, having not been recognized during either parsing, they are printed along with information on the valid program options.
#include <vistaio.h>
static VistaIOOptionDescRec options[] = { /* option table entries */ };
int main (int argc, char *argv)
{
- if (! VistaIOParseCommand (VistaIONumber (options), options, & argc, argv))
- goto Usage;
/* Parse arguments remaining in argv[1] ... argv[argc - 1]. */
...
if (argc > 1) {
- VistaIOReportBadArgs (argc, argv);
Usage:
- VistaIOReportUsage (argv[0], VistaIONumber (options), options, NULL);
fprintf (stderr, " plus any X Windows options.\n\n");
exit (1);
}
...
}
DIAGNOSTICS
VistaIOParseCommand reports errors in command line options by printing directly to the standard error stream. Error reports include the program name obtained from argv[0]. The following messages may be produced:- ``Duplicate -option option; ignoring all but last.''
- The specified option was found more than once on the command line.
- ``Option -option has incorrect value arg.''
- One of the values associated with -option on the command line is arg, which is of the wrong form with respect to the type of value required.
- ``Option -option requires m value(s); found only n.''
- The option keyword -option must be followed by n values on the command line. Only m were present, however.
- ``Option -option must be specified.''
- The option -option is required but it was not present on the command line.
In addition, VistaIOParseCommand may invoke VistaIOError with the following message:
- ``Parsing of command options with type values is not implemented.''
- Options, as described in the options table, must take values that are of type VistaIOBit, VistaIOUByte, VistaIOSByte, VistaIOShort, VistaIOLong, VistaIOFloat, VistaIODouble, VistaIOBoolean, or VistaIOString. VistaIOParseCommand encountered a table entry describing an option of type type instead.