parseopt - command line parsing library
=======================================

Marco Pantaleoni (panta@elasticworld.org)

1. SYNOPSIS
===========

 #include <parseopt.h>

 popt_return popt_parse(int argc, char * const argv[],
                        popt_specifier *specifiers,
                        int allow_collapsed,
                        popt_parameter parameter_cb);

 typedef struct
 {
     const char     *long_name;
     char            short_name;

     popt_argtype    argument_type;
     const char     *defval;

     popt_validate   validate_cb;

     const char    **argument;
     int            *value;
 };

 typedef enum
 {
     popt_argument_none,                                /* no argument expected                        */
     popt_argument_optional,                            /* argument is optional                        */
     popt_argument_optional_default,                    /* argument is optional, a default is supplied */
     popt_argument_required                             /* argument is required                        */
 } popt_argtype;

 typedef int (*popt_validate)(popt_specifier *spec,     /* callback called to validate an argument    */
                              const char *argument);

 typedef int (*popt_parameter)(const char *parameter);  /* callback called when a non-option is found */

 typedef enum
 {
     popt_ok,
     popt_error_unknown,                                /* unknown error           */
     popt_error_unknown_option,                         /* unknown option          */
     popt_error_unexpected_argument,                    /* argument was unexpected */
     popt_error_missing_argument,                       /* argument is missing     */
     popt_error_invalid                                 /* invalid option/argument */
 } popt_return;

2. DESCRIPTION
==============

The popt_parse() function parses the command line arguments. It
receives the program arguments through argc and argv. An element of
argv that starts with `-', and is not exactly `-' or `--' is an option
element. If the element starts with a single `-', then it is
considered a short option, otherwise if it starts with a `--' it is
considered a long option.

popt_parse() parses the command line, processing all options, in a
single pass. It features:

o    long and short options

o    the possibility to specify only a unique prefix to an option

o    the possibility to specify a callback to validate/convert
     arguments

o    predefined validation callbacks for integers, doubles, yes/no,
     and booleans

o    full reentrancy

Automatic help generation is possible through the popt_make_help()
function.

receives a specification of supported options in the specifiers array,
a boolean indicating if collapsed options (see below) are to be
supported in allow_collapsed, then a pointer to a function receiving
non-option parameters in parameter_cb.

3. OPTIONS
==========

none for the moment

4. RETURN VALUE
===============

5. EXAMPLES
===========

6. SEE ALSO
===========

the getopt(3) manpage: for an alternative

7. BUGS
=======

None known. Possibly millions.

8. AUTHOR
=========

Marco Pantaleoni (panta@elasticworld.org)

9. COPYRIGHT
============

Copyright (C) 2000 Marco Pantaleoni. All rights reserved.

The contents of this file are subject to the elastiC License version
1.0 (the "elastiC License"); you may not use this file except in
compliance with the elastiC License. You may obtain a copy of the
elastiC License at http://www.elasticworld.org/LICENSE

IN NO EVENT SHALL THE AUTHOR OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

THE AUTHOR AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND
THE AUTHOR AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE,
SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

See the elastiC License for the specific language governing rights and
limitations under the elastiC License.