NAME¶
VistaIOParseCommand - parse command line arguments
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))
/* 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);
}
...
}
SEE ALSO¶
VistaIOReportBadArgs(3),
VistaIOReportUsage(3),
VistaIOIdentifyFiles(3),
VistaIOoption(3),
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.
AUTHOR¶
Art Pope <pope@cs.ubc.ca>
Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>