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))
                     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);
              }

              ...

       }

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  pro‐
       duced:

       ``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, Vis‐
              taIOUByte, 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>

VistaIO Version 1.2.14                            24 April 1993                           VistaIOParseCommand(3)