head	1.1;
access;
symbols;
locks
	bsittler:1.1; strict;
comment	@# @;


1.1
date	2001.02.10.18.50.48;	author bsittler;	state Exp;
branches;
next	;


desc
@@


1.1
log
@Initial revision
@
text
@My getopt-compatible argument parser ----------------------------
$Id$
This document contains a brief description of my
re-implementation of getopt(), getopt_long(), and
getopt_long_only().                                        --BCWS
-----------------------------------------------------------------

NAME

getopt, getopt_long, getopt_long_only - Parse command line options

SYNOPSIS

#include "getopt.h"

extern int getopt(int argc, char * argv[], const char *opts);

extern int optind, opterr, optopt;

extern char *optarg;

extern int getopt_long(int argc, char * argv[], const char *shortopts,
                       const struct option *longopts, int *longind);

extern int getopt_long_only(int argc, char * argv[], const char *shortopts,
                            const struct option *longopts, int *longind);

OVERVIEW OF THE ARGUMENT PARSER

The getopt(), getopt_long() and getopt_long_only() functions parse
command line arguments. The argc and argv parameters passed to these
functions correspond to the argument count and argument list passed to
your program's main() function at program start-up. Element 0 of the
argument list conventionally contains the name of your program. Any
remaining arguments starting with "-" (except for "-" or "--" by
themselves) are option arguments, some of include option values. This
family of getopt() functions allows intermixed option and non-option
arguments anywhere in the argument list, except that "--" by itself
causes the remaining elements of the argument list to be treated as
non-option arguments.

CONFIGURABLE BEHAVIOR

If you'd like to recieve ':' instead of '?' for missing option values,
prefix the short option string with ':'.

If you'd like to disallow intermixing of options and non-option
arguments (thereby permitting options only at the beginning of the
argument list,) prefix the short option string with '+' or set the
environment variable "POSIXLY_CORRECT".

If you'd like to distinguish the precise order of option- and
non-option arguments in the argument list, and avoid argument
permution, prefix the short option string with '-'. For each
non-option argument, getopt() will return 1 and set optarg to point to
the non-option argument.

WHY RE-INVENT THE WHEEL?

I re-implemented getopt, getopt_long, and getopt_long_only because
there were noticable bugs in several versions of the GNU
implementations, and because the GNU versions aren't always
available on some systems (*BSD, for example.)

These should do all the expected Unix- and GNU-style argument
parsing, including permution, bunching, long options with single or
double dashes (double dashes are required if you use
my_getopt_long,) and optional arguments for both long and short
options. A word with double dashes all by themselves halts argument
parsing. A required long option argument can be in the same word as
the option name, separated by '=', or in the next word. An optional
long option argument must be in the same word as the option name,
separated by '='.

As with the GNU versions, a '+' prefix to the short option
specification (or the POSIXLY_CORRECT environment variable)
disables permution, a '-' prefix to the short option specification
returns 1 for non-options, ':' after a short option indicates a
required argument, and '::' after a short option specification
indicates an optional argument (which must appear in the same
word.)

The original intent was to re-implement the documented behavior of
the GNU versions, but I have found it necessary to emulate some of
the undocumented behavior as well. Some programs depend on it.

The GNU versions support POSIX-style -W "name=value" long
options. Currently, my_getopt does not support these, because I
don't have any documentation on them (other than the fact that they
are enabled by "W;" in the short option specification.) As a
temporary workaround, my_getopt treats "W;" in the short option
string identically to "W:".
@
