NAME
    Getopt::AutoConf -- use autoconf(1)-style options

SYNOPSIS
    Getopt::AutoConf provides command-line parameter parsing similar
    to that provided by GNU autoconf(1). Getopt::AutoConf simplifies
    parsing of arguments in the form --with, --without, --enable,
    and --disable.

SYNOPSIS
     ./configure.pl --with-foo=/usr/local/lib/libfoo.a --disable-bar \
            --enable-baz --without-quux

    called as:

      use Getopt::AutoConf;

      GetOptions(
            'foo'  => \@foo,
            'bar'  => \$bar,
            'baz'  => \$baz,
            'quux' => \&quux,
      ) or die $Getopt::AutoConf::ERROR;

      print @foo, $bar, $baz;
      # Prints: /usr/local/lib/libfoo.a 0 1

DESCRIPTION
    Getopt::AutoConf allows for autoconf-style parameters with no
    extra parsing on the part of the script writer.

    The module exports a single function, called GetOptions, which
    takes a hash describing what options should be parsed. Each key
    in this hash is a variable name, and each value is a reference
    to a variable into which the value should be placed, similar to
    Getopt::Long. GetOptions returns 1 on success or undef on
    failure. The variables referenced should already be defined,
    although in the absence of 'use strict' this is not required.

    Getopt::AutoConf::GetOptions is written in such a way that
    arguments not beginning with '--enable-', '--disable-', '--with-
    ', or '--without-' are passed through unmodified; another option
    processing module can then process the remaining arguments. For
    example:

      use Getopt::Long ();
      use Getopt::AutoConf ();

      my ($foo, $bar, $baz, $quux);
      Getopt::AutoConf::GetOptions('foo' => \$foo, 'bar' => \$bar);
      Getopt::Long::GetOptions('baz' => \$baz, 'quux' => \$quux);

    See t/03golngoa.t for another (working) example. Note that in
    this case, modules should be used with () as their argument
    list, and the functions' full name should be typed, to avoid the
    name clash.

    The keys to the hash passed into GetOptions can be references of
    one of three types: references to scalar variables, references
    to arrays, or code references. How each reference type is
    dereferenced depends on whether they were preceded by enable,
    disable, with, or without (each is detailed below).

    Options can be passed in the any of the following forms:

    --with-$var=$value, --enable-$var=$value
        This sets $var to $value. If a reference to a scalar is
        passed to GetOptions, then $value will be assigned to $var.
        If a reference to an array is passed, the $value will be
        pushed onto @{$var}. If a code ref is passed, then the code
        is executed, with ($var, $value) as parameters.

        If $val is attached to a scalar reference, and there are
        multiple occurances of $var on the command line, the last
        one passed overrides all earlier occurances.

    --without-$var(=$value)?, --disable-$var(=$value)?
        Both --without- and --disable- act identically. If a
        reference to a scalar variable is passed to GetOptions, the
        this value is set to 0 (regardless of what, if anything,
        comes after the "=" on the command line). If a reference to
        an array is passed in, and there is nothing after the "="
        (or no "="), the referent is set to the empty list. If there
        is data after the "=", then this data is spliced from the
        referenced array. Code references are invoked with ($var,
        $value) as paramters, or ($var, "") if $value is not present
        (in this way, enabled and disabled variables which are
        attached to code refs function identically).

EXAMPLES
    Here is some code with will upload the English and Spanish
    versions of the index page, along with the respective flag
    icons.

      # The code:
      GetOptions(
          "html"  => \@html,
          "image" => \@images,
      );

      for (@html, @images) {
          enqueue($_);
      }

      # The command line invocation:
      $ upload.pl --with-html=htdocs/index.en.html \
                  --with-html=htdocs/index.es.html \
                  --with-image=htdocs/images/flags/en.gif \
                  --with-image=htdocs/images/flags/es.gif

    A real(ish) example. A script designed to be invoked from a CVS
    commit might be invoked something like this (from the
    CVSROOT/loginfo file):

      # in CVSROOT/loginfo:
      DEFAULT /usr/local/bin/commit-fu \
                  --cvs=/usr/bin/cvs --cvsspec=%{sVv}  \
                  --cvsroot=/cvsroot --diffoptions="-uw" \
                  --recipient=commit-fu-users@lists.sf.net \
                  --recipient=cvs-dev@cvshome.com

      # And, in the body of /usr/local/bin/commit-fu:
      my ($cvs, $cvsroot, $cvsoptions, $cvsspec, @recipients);
      GetOptions("cvs"         => \$cvs,
                 "cvsspec"     => \$cvsspec,
                 "cvsroot"     => \$cvsroot,
                 "diffoptions" => \$diffoptions,
                 "recipient"   => \@recipients);

    A final example: the configure script for the sevenmail webmail
    software.

      # in configure.pl:
      my ($VERBOSE, $ap_src, %mysql, $defaultdomain);
      my @options = ('aliases', 'forwarding');
      GetOptions(
        "verbose"       => \$VERBOSE,
        "apache_src"    => \$ap_src,
        "mysql-user"    => \$mysql{'user'},
        "mysql-passwd"  => \$mysql{'passwd'},
        "mysql-host"    => \$mysql{'host'},
        "option"        => \@options,
        "defaultdomain" => \$defaultdomain,
      );

      # invocation:
      ./configure.pl --with-apache_src=/usr/local/src/apache_1.3.20/src \
                     --with-defaultdomain=sevenroot.org
                     --with-mysql-user=nobody   \
                     --with-mysql-passwd=l33t&s3kr3t   \
                     --wtih-mysql-host=dbhost     \
                     --enable-option=masquerading   \
                     --enable-option=mbox-limits \
                     --disable-option=aliases   \
                     --verbose

    This configuration has the effect of, along with setting all of
    the various scalars, removing the default "aliases" option
    defined in the script (because of the "--disable-
    option=aliases") but leaving the default "forwarding" option
    alone.

AUTHOR
    darren chamberlain <darren@cpan.org>

VERSION
    $Revision: 1.3 $

    Copyright 2001 darren chamberlain <darren@cpan.org>