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>