NAME

       stParseArgs, stShortUsage - parse command line arguments

SYNOPSIS

       #include <config.h>
       #include <sttk.h>

       int stParseArgs (int argCount, char *argVector,
                        int newArgCount, char *(*newArgVector[]), OptDesc optionList[]);

       voidstShortUsage (char *programName, OptDesc optionList[], char *extraText);

DESCRIPTION

       stParseArgs  parses  the  command  line  for  options  previously  declared  in  an option
       desription list. The programs argument count and argument vector are  passed  as  argCount
       and  argVector, and the option description list as optionList to stParseArgs. This filters
       out all known (from the option list) options and their arguments and returns the remaining
       tokens from the command line in newArgVector with newArgCount. Options on the command line
       must be preceded by a minus sign, otherwise they will not be recognized. The  first  entry
       in  the  argument  vector,  the  program  name,  passes  the  function without any damage.
       stParseArgs may be invoked multiple times with different option lists.

       The option list is an array of option definitions of the following form:
       typedef struct {
         char *OptName;
         int  OptKind;
         int  (*OptFunc)();
         int  *OptVar;
         char *OptStr;
       } StOptDesc;
       The array is finished by an option definition containing only null entries. OptName is the
       name of the option how it appears on the command line, without the leading minus sign. The
       OptKind is a flag field defining the option type and the kind of action to  be  performed.
       Valid option types are

       PSWITCH
               The option is a switch and has no argument (default)

       PARG    The option has an argument immediately following the option on the command line.

       POARG   The option has an optional argument.

       The  action  to be prformed on occurence of an option on the command line refers either to
       OptFunc, a function to be  defined  by  the  application  or  to  OptVar,  an  application
       variable, associated with the option. The different kinds of action to be performed are

       PCALL   Call the function OptFunc (default).

       PSET    Set the variable OptVar to 1 (TRUE).

       PCLEAR  Set the variable OptVar to 0 (FALSE)

       PTOGGLE
               Toggle the value of the variable OptVar between 1 (TRUE) and 0 (FALSE).

       PUSAGE  Call stShortUsage (see below).

       PFAIL   Call stShortUsage (see below) and terminate program execution with return code 1.

       The following example shows some typical option definitions
       StOptDesc bindOptions[] = {
         { "help",    PFAIL,        NULL,           NULL,         NULL },
         { "trace",   PSWITCH|PSET, NULL,           &atBindTrace, NULL },
         { "since",   PCALL|PARG,   handleBaseline, NULL,         NULL },
         { "version", PCALL,        printVersion,   NULL,         NULL },
         { NULL,      NULL,         NULL,           NULL,         NULL },
       };

       stShortUsage generates a short usage message from the given optionList. The message starts
       with the programName and lists all option in the option list. At  the  end,  extraText  is
       added, if given. The message is written to standard error.