.\" @(#)GetLongOpt.3 2.0 12/01/1993
.TH GETLONGOPT 3 "12 January 1993" "" "C++ LIBRARY CLASSES"
.UC 4
.SH NAME
GetLongOpt - C++ class for parsing command line and strings for options
.SH SYNOPSIS
.nf
.ft B
.ss 18
#include <GetLongOpt.h>

GetLongOpt::GetLongOpt(const char optmark = '-');
int GetLongOpt::parse(int argc, char * const *argv);
int GetLongOpt::parse(char * const str, char * const p);
int GetLongOpt::enroll(const char * const opt, const OptType t,
   const char * const desc, const char * const val);
const char * GetLongOpt::retrieve(const char * const opt) const;
void GetLongOpt::usage(ostream &outfile = cout) const;
void GetLongOpt::usage(const char *str);
.ft
.fi
.ss

.SH DESCRIPTION
GetLongOpt is a C++ class for getting options from the command line
and from strings. GetLongOpt supports long options. These options
may be flags or require optional or mandatory values.
If an option requires a value, then the value should be separated
from the option either by whitespace or by a "=". Long options
can be abbreviated. GetLongOpt can also be used to parse options given 
through environments.

The constructor for GetLongOpt takes an optional argument: the option
marker. If unspecified, this defaults to '-', the standard (?)
Unix option marker. For example, a DOS addict may want to 
specify '/' for the option marker!

.I GetLongOpt::enroll
adds option specifications to its internal
database. The first argument is the option sting. The second
is an enum saying if the option is a flag (GetLongOpt::NoValue),
if it requires a mandatory value (GetLongOpt::MandatoryValue) or
if it takes an optional value (GetLongOpt::OptionalValue).
The third argument is a string giving a brief description of
the option. This description will be used by 
.I GetLongOpt::usage.
GetLongOpt, for usage-printing, uses $val to represent values
needed by the options. <$val> is a mandatory value and [$val]
is an optional value. The final argument to 
.I GetLongOpt::enroll
is the default string to be returned if the option is not
specified. For flags (options with NoValue), use "" (empty
string, or in fact any arbitrary string) for specifying TRUE
and 0 (null pointer) to specify FALSE.

.I GetLongOpt::usage
is overloaded. If passed a string 
.I s,
it sets the
internal usage string to 
.I s.
Otherwise it simply prints the
command usage. The options and their
descriptions (as specified during enroll) are printed in the
order they are enrolled.

.I GetLongOpt::parse
is also overloaded. It can either parse a string of
options (typically given from the environment), or it can parse
the command line args (argc, argv). In either case a return
value < 1 represents a parse error. Appropriate error messages
are printed when errors are seen. GetLongOpt::parse, in its first
form, takes two strings: the first one is the string to be
parsed and the second one is a string to be prefixed to the
parse errors. In its second form, 
.I GetLongOpt::parse
takes in argc and argv and returns the
the optind (see getopt(3)) if parsing is successful.
Successful parsing, in either form of
.I GetLongOpt::parse,
updates the values of the options within the internal database.

The values of the options that are enrolled in the database
can be retrieved using 
.I GetLongOpt::retrieve.
This returns a string
and this string should be converted to whatever type you want.
See atoi(3), atof(3), atol(3) etc. I suppose you would do a 
.I GetLongOpt::parse
before
retrieving. Otherwise all you would get are the default values
you gave while enrolling!
Ambiguities while retrieving (may happen when options are
abbreviated) are resolved by taking the matching option that
was enrolled last.

If you try to retrieve something you did not enroll, you will
get a warning message. This means that you probably had made
a typo somewhere while enrolling or retrieving.

.SH BUGS
They should be there well-hidden. If you spot one report it.

.SH "SEE ALSO"
getopt(3),
getopts(1),
atoi(3), atof(3), atol(3).

.SH AUTHOR
.nf
S Manoharan
Advanced Computer Research Institute
1 Boulevard Marius Vivier-Merle
69443 Lyon Cedex 03 France

mano@acri.fr
.fi

.\" end of man page