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" \
                 [email protected] \
                 [email protected]

     # 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 <[email protected]>

VERSION
   $Revision: 1.3 $

   Copyright 2001 darren chamberlain <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.