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 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>