.ig
 Copyright (C) 1993,1994 by the author(s).
 
 This software is published in the hope that it will be useful, but
 WITHOUT ANY WARRANTY for any part of this software to work correctly
 or as described in the manuals. See the ShapeTools Public License
 for details.

 Permission is granted to use, copy, modify, or distribute any part of
 this software but only under the conditions described in the ShapeTools 
 Public License. A copy of this license is supposed to have been given
 to you along with ShapeTools in a file named LICENSE. Among other
 things, this copyright notice and the Public License must be
 preserved on all copies.


Author: Andreas Lampen (Andreas.Lampen@cs.tu-berlin.de)

$Header: stparseargs.3[4.0] Thu Jun 24 17:43:31 1993 andy@cs.tu-berlin.de frozen $
..
.TH stparseargs 3 "Thu Jun 24 17:43:31 1993" "sttk-1.7" "ShapeTools Toolkit Library"
.SH NAME
stParseArgs, stShortUsage \- parse command line arguments
.SH SYNOPSIS
#include <config.h>
.br
#include <sttk.h>
.sp
.ta 1c
int	stParseArgs (int argCount, char *argVector,
.br
	\h'\w'stParseArgs ('u'int newArgCount, char *(*newArgVector[]), OptDesc optionList[]);
.sp
void	stShortUsage (char *programName, OptDesc optionList[], char *extraText);
.sp
.SH DESCRIPTION
\fIstParseArgs\fP parses the command line for options previously
declared in an option desription list. The programs argument count and
argument vector are passed as \fIargCount\fP and \fPargVector\fP, and
the option description list as \fIoptionList\fP 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
\fInewArgVector\fP with \fInewArgCount\fP. 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.
.LP
The option list is an array of option definitions of the following form:
.nf
\fCtypedef struct {
  char *OptName;
  int  OptKind;
  int  (*OptFunc)();
  int  *OptVar;
  char *OptStr;
} StOptDesc;\fP
.fi
The array is finished by an option definition containing only null
entries. \fIOptName\fP is the name of the option how it appears on the
command line, without the leading minus sign. The \fIOptKind\fP is a
flag field defining the option type and the kind of action to be
performed. Valid option types are
.TP 2c
PSWITCH
The option is a switch and has no argument (default)
.TP
PARG
The option has an argument immediately following the option on the
command line.
.TP
POARG
The option has an optional argument.
.LP
The action to be prformed on occurence of an option on the command
line refers either to \fIOptFunc\fP, a function to be defined by the
application or to \fIOptVar\fP, an application variable, associated
with the option. The different kinds of action to be performed are
.TP 2c
PCALL
Call the function OptFunc (default).
.TP
PSET
Set the variable OptVar to 1 (TRUE).
.TP
PCLEAR
Set the variable OptVar to 0 (FALSE)
.TP
PTOGGLE
Toggle the value of the variable OptVar between 1 (TRUE) and 0 (FALSE).
.TP
PUSAGE
Call stShortUsage (see below).
.TP
PFAIL
Call stShortUsage (see below) and terminate program execution with
return code 1.
.LP
.ne 8
The following example shows some typical option definitions
.nf
\fCStOptDesc 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 },
};\fP
.fi
.LP
\fIstShortUsage\fP generates a short usage message from the given
\fIoptionList\fP. The message starts with the \fIprogramName\fP and
lists all option in the option list. At the end, \fIextraText\fP is
added, if given. The message is written to standard error.