Getopt::Long

Getopt::Long(3)        Perl Programmers Reference Guide        Getopt::Long(3)



NAME
       GetOptions - extended processing of command line options

SYNOPSIS
         use Getopt::Long;
         $result = GetOptions (...option-descriptions...);


DESCRIPTION
       The Getopt::Long module implements an extended getopt function called
       GetOptions(). This function adheres to the POSIX syntax for command
       line options, with GNU extensions. In general, this means that options
       have long names instead of single letters, and are introduced with a
       double dash "--". Support for bundling of command line options, as was
       the case with the more traditional single-letter approach, is provided
       but not enabled by default. For example, the UNIX "ps" command can be
       given the command line "option"

         -vax

       which means the combination of -v, -a and -x. With the new syntax --vax
       would be a single option, probably indicating a computer architecture.

       Command line options can be used to set values. These values can be
       specified in one of two ways:

         --size 24
         --size=24

       GetOptions is called with a list of option-descriptions, each of which
       consists of two elements: the option specifier and the option linkage.
       The option specifier defines the name of the option and, optionally,
       the value it can take. The option linkage is usually a reference to a
       variable that will be set when the option is used. For example, the
       following call to GetOptions:

         GetOptions("size=i" => \$offset);

       will accept a command line option "size" that must have an integer
       value. With a command line of "--size 24" this will cause the variable
       $offset to get the value 24.

       Alternatively, the first argument to GetOptions may be a reference to a
       HASH describing the linkage for the options, or an object whose class
       is based on a HASH. The following call is equivalent to the example
       above:

         %optctl = ("size" => \$offset);
         GetOptions(\%optctl, "size=i");

       Linkage may be specified using either of the above methods, or both.
       Linkage specified in the argument list takes precedence over the
       linkage specified in the HASH.

       The command line options are taken from array @ARGV. Upon completion of
       GetOptions, @ARGV will contain the rest (i.e. the non-options) of the
       command line.

       Each option specifier designates the name of the option, optionally
       followed by an argument specifier.

       Options that do not take arguments will have no argument specifier.
       The option variable will be set to 1 if the option is used.

       For the other options, the values for argument specifiers are:

       !       Option does not take an argument and may be negated, i.e.
               prefixed by "no". E.g. "foo!" will allow --foo (with value 1)
               and -nofoo (with value 0).  The option variable will be set to
               1, or 0 if negated.

       +       Option does not take an argument and will be incremented by 1
               every time it appears on the command line. E.g. "more+", when
               used with --more --more --more, will set the option variable to
               3 (provided it was 0 or undefined at first).

               The + specifier is ignored if the option destination is not a
               SCALAR.

       =s      Option takes a mandatory string argument.  This string will be
               assigned to the option variable.  Note that even if the string
               argument starts with - or --, it will not be considered an
               option on itself.

       :s      Option takes an optional string argument.  This string will be
               assigned to the option variable.  If omitted, it will be
               assigned "" (an empty string).  If the string argument starts
               with - or --, it will be considered an option on itself.

       =i      Option takes a mandatory integer argument.  This value will be
               assigned to the option variable.  Note that the value may start
               with - to indicate a negative value.

       :i      Option takes an optional integer argument.  This value will be
               assigned to the option variable.  If omitted, the value 0 will
               be assigned.  Note that the value may start with - to indicate
               a negative value.

       =f      Option takes a mandatory real number argument.  This value will
               be assigned to the option variable.  Note that the value may
               start with - to indicate a negative value.

       :f      Option takes an optional real number argument.  This value will
               be assigned to the option variable.  If omitted, the value 0
               will be assigned.

       A lone dash - is considered an option, the corresponding option name is
       the empty string.

       A double dash on itself -- signals end of the options list.

       Linkage specification

       The linkage specifier is optional. If no linkage is explicitly
       specified but a ref HASH is passed, GetOptions will place the value in
       the HASH. For example:

         %optctl = ();
         GetOptions (\%optctl, "size=i");

       will perform the equivalent of the assignment

         $optctl{"size"} = 24;

       For array options, a reference to an array is used, e.g.:

         %optctl = ();
         GetOptions (\%optctl, "sizes=i@");

       with command line "-sizes 24 -sizes 48" will perform the equivalent of
       the assignment

         $optctl{"sizes"} = [24, 48];

       For hash options (an option whose argument looks like "name=value"), a
       reference to a hash is used, e.g.:

         %optctl = ();
         GetOptions (\%optctl, "define=s%");

       with command line "--define foo=hello --define bar=world" will perform
       the equivalent of the assignment

         $optctl{"define"} = {foo=>'hello', bar=>'world')

       If no linkage is explicitly specified and no ref HASH is passed,
       GetOptions will put the value in a global variable named after the
       option, prefixed by "opt_". To yield a usable Perl variable, characters
       that are not part of the syntax for variables are translated to
       underscores. For example, "--fpp-struct-return" will set the variable
       $opt_fpp_struct_return. Note that this variable resides in the
       namespace of the calling program, not necessarily main.  For example:

         GetOptions ("size=i", "sizes=i@");

       with command line "-size 10 -sizes 24 -sizes 48" will perform the
       equivalent of the assignments

         $opt_size = 10;
         @opt_sizes = (24, 48);

       A lone dash - is considered an option, the corresponding Perl
       identifier is $opt_ .

       The linkage specifier can be a reference to a scalar, a reference to an
       array, a reference to a hash or a reference to a subroutine.

       Note that, if your code is running under the recommended use strict
       'vars' pragma, it may be helpful to declare these package variables via
       use vars perhaps something like this:

         use vars qw/ $opt_size @opt_sizes $opt_bar /;

       If a REF SCALAR is supplied, the new value is stored in the referenced
       variable. If the option occurs more than once, the previous value is
       overwritten.

       If a REF ARRAY is supplied, the new value is appended (pushed) to the
       referenced array.

       If a REF HASH is supplied, the option value should look like "key" or
       "key=value" (if the "=value" is omitted then a value of 1 is implied).
       In this case, the element of the referenced hash with the key "key" is
       assigned "value".

       If a REF CODE is supplied, the referenced subroutine is called with two
       arguments: the option name and the option value.  The option name is
       always the true name, not an abbreviation or alias.

       Aliases and abbreviations

       The option name may actually be a list of option names, separated by
       "⎪"s, e.g. "foo⎪bar⎪blech=s". In this example, "foo" is the true name
       of this option. If no linkage is specified, options "foo", "bar" and
       "blech" all will set $opt_foo. For convenience, the single character
       "?" is allowed as an alias, e.g. "help⎪?".

       Option names may be abbreviated to uniqueness, depending on
       configuration option auto_abbrev.

       Non-option call-back routine

       A special option specifier, <>, can be used to designate a subroutine
       to handle non-option arguments. GetOptions will immediately call this
       subroutine for every non-option it encounters in the options list.
       This subroutine gets the name of the non-option passed.  This feature
       requires configuration option permute, see section CONFIGURATION
       OPTIONS.

       See also the examples.

       Option starters

       On the command line, options can start with - (traditional), -- (POSIX)
       and + (GNU, now being phased out). The latter is not allowed if the
       environment variable POSIXLY_CORRECT has been defined.

       Options that start with "--" may have an argument appended, separated
       with an "=", e.g. "--foo=bar".

       Return values and Errors

       Configuration errors and errors in the option definitions are signalled
       using die() and will terminate the calling program unless the call to
       Getopt::Long::GetOptions() was embedded in eval { ... } or die() was
       trapped using $SIG{__DIE__}.

       A return value of 1 (true) indicates success.

       A return status of 0 (false) indicates that the function detected one
       or more errors during option parsing. These errors are signalled using
       warn() and can be trapped with $SIG{__WARN__}.

       Errors that can't happen are signalled using Carp::croak().

COMPATIBILITY
       Getopt::Long::GetOptions() is the successor of newgetopt.pl that came
       with Perl 4. It is fully upward compatible.  In fact, the Perl 5
       version of newgetopt.pl is just a wrapper around the module.

       If an "@" sign is appended to the argument specifier, the option is
       treated as an array. Value(s) are not set, but pushed into array
       @opt_name. If explicit linkage is supplied, this must be a reference to
       an ARRAY.

       If an "%" sign is appended to the argument specifier, the option is
       treated as a hash. Value(s) of the form "name=value" are set by setting
       the element of the hash %opt_name with key "name" to "value" (if the
       "=value" portion is omitted it defaults to 1). If explicit linkage is
       supplied, this must be a reference to a HASH.

       If configuration option getopt_compat is set (see section CONFIGURATION
       OPTIONS), options that start with "+" or "-" may also include their
       arguments, e.g. "+foo=bar". This is for compatiblity with older
       implementations of the GNU "getopt" routine.

       If the first argument to GetOptions is a string consisting of only non-
       alphanumeric characters, it is taken to specify the option starter
       characters. Everything starting with one of these characters from the
       starter will be considered an option. Using a starter argument is
       strongly deprecated.

       For convenience, option specifiers may have a leading - or --, so it is
       possible to write:

          GetOptions qw(-foo=s --bar=i --ar=s);


EXAMPLES
       If the option specifier is "one:i" (i.e. takes an optional integer
       argument), then the following situations are handled:

          -one -two            -> $opt_one = '', -two is next option
          -one -2              -> $opt_one = -2

       Also, assume specifiers "foo=s" and "bar:s" :

          -bar -xxx            -> $opt_bar = '', '-xxx' is next option
          -foo -bar            -> $opt_foo = '-bar'
          -foo --              -> $opt_foo = '--'

       In GNU or POSIX format, option names and values can be combined:

          +foo=blech           -> $opt_foo = 'blech'
          --bar=               -> $opt_bar = ''
          --bar=--             -> $opt_bar = '--'

       Example of using variable references:

          $ret = GetOptions ('foo=s', \$foo, 'bar=i', 'ar=s', \@ar);

       With command line options "-foo blech -bar 24 -ar xx -ar yy" this will
       result in:

          $foo = 'blech'
          $opt_bar = 24
          @ar = ('xx','yy')

       Example of using the <> option specifier:

          @ARGV = qw(-foo 1 bar -foo 2 blech);
          GetOptions("foo=i", \$myfoo, "<>", \&mysub);

       Results:

          mysub("bar") will be called (with $myfoo being 1)
          mysub("blech") will be called (with $myfoo being 2)

       Compare this with:

          @ARGV = qw(-foo 1 bar -foo 2 blech);
          GetOptions("foo=i", \$myfoo);

       This will leave the non-options in @ARGV:

          $myfoo -> 2
          @ARGV -> qw(bar blech)


CONFIGURATION OPTIONS
       GetOptions can be configured by calling subroutine
       Getopt::Long::Configure. This subroutine takes a list of quoted
       strings, each specifying a configuration option to be set, e.g.
       ignore_case. Options can be reset by prefixing with no_, e.g.
       no_ignore_case. Case does not matter. Multiple calls to config are
       possible.

       Previous versions of Getopt::Long used variables for the purpose of
       configuring. Although manipulating these variables still work, it is
       strongly encouraged to use the new config routine. Besides, it is much
       easier.

       The following options are available:

       default     This option causes all configuration options to be reset to
                   their default values.

       auto_abbrev Allow option names to be abbreviated to uniqueness.
                   Default is set unless environment variable POSIXLY_CORRECT
                   has been set, in which case auto_abbrev is reset.

       getopt_compat
                   Allow '+' to start options.  Default is set unless
                   environment variable POSIXLY_CORRECT has been set, in which
                   case getopt_compat is reset.

       require_order
                   Whether non-options are allowed to be mixed with options.
                   Default is set unless environment variable POSIXLY_CORRECT
                   has been set, in which case b<require_order> is reset.

                   See also permute, which is the opposite of require_order.

       permute     Whether non-options are allowed to be mixed with options.
                   Default is set unless environment variable POSIXLY_CORRECT
                   has been set, in which case permute is reset.  Note that
                   permute is the opposite of require_order.

                   If permute is set, this means that

                       -foo arg1 -bar arg2 arg3

                   is equivalent to

                       -foo -bar arg1 arg2 arg3

                   If a non-option call-back routine is specified, @ARGV will
                   always be empty upon succesful return of GetOptions since
                   all options have been processed, except when -- is used:

                       -foo arg1 -bar arg2 -- arg3

                   will call the call-back routine for arg1 and arg2, and
                   terminate leaving arg2 in @ARGV.

                   If require_order is set, options processing terminates when
                   the first non-option is encountered.

                       -foo arg1 -bar arg2 arg3

                   is equivalent to

                       -foo -- arg1 -bar arg2 arg3


       bundling (default: reset)
                   Setting this variable to a non-zero value will allow
                   single-character options to be bundled. To distinguish
                   bundles from long option names, long options must be
                   introduced with -- and single-character options (and
                   bundles) with -. For example,

                       ps -vax --vax

                   would be equivalent to

                       ps -v -a -x --vax

                   provided "vax", "v", "a" and "x" have been defined to be
                   valid options.

                   Bundled options can also include a value in the bundle; for
                   strings this value is the rest of the bundle, but integer
                   and floating values may be combined in the bundle, e.g.

                       scale -h24w80

                   is equivalent to

                       scale -h 24 -w 80

                   Note: resetting bundling also resets bundling_override.

       bundling_override (default: reset)
                   If bundling_override is set, bundling is enabled as with
                   bundling but now long option names override option bundles.
                   In the above example, -vax would be interpreted as the
                   option "vax", not the bundle "v", "a", "x".

                   Note: resetting bundling_override also resets bundling.

                   Note: Using option bundling can easily lead to unexpected
                   results, especially when mixing long options and bundles.
                   Caveat emptor.

       ignore_case  (default: set)
                   If set, case is ignored when matching options.

                   Note: resetting ignore_case also resets ignore_case_always.

       ignore_case_always (default: reset)
                   When bundling is in effect, case is ignored on single-
                   character options also.

                   Note: resetting ignore_case_always also resets ignore_case.

       pass_through (default: reset)
                   Unknown options are passed through in @ARGV instead of
                   being flagged as errors. This makes it possible to write
                   wrapper scripts that process only part of the user supplied
                   options, and passes the remaining options to some other
                   program.

                   This can be very confusing, especially when permute is also
                   set.

       prefix      The string that starts options. See also prefix_pattern.

       prefix_pattern
                   A Perl pattern that identifies the strings that introduce
                   options.  Default is (--⎪-⎪\+) unless environment variable
                   POSIXLY_CORRECT has been set, in which case it is (--⎪-).

       debug (default: reset)
                   Enable copious debugging output.

OTHER USEFUL VARIABLES
       $Getopt::Long::VERSION
                   The version number of this Getopt::Long implementation in
                   the format major.minor. This can be used to have Exporter
                   check the version, e.g.

                       use Getopt::Long 3.00;

                   You can inspect $Getopt::Long::major_version and
                   $Getopt::Long::minor_version for the individual components.

       $Getopt::Long::error
                   Internal error flag. May be incremented from a call-back
                   routine to cause options parsing to fail.

AUTHOR
       Johan Vromans <jvromans@squirrel.nl>

COPYRIGHT AND DISCLAIMER
       This program is Copyright 1990,1998 by Johan Vromans.  This program is
       free software; you can redistribute it and/or modify it under the terms
       of the GNU General Public License as published by the Free Software
       Foundation; either version 2 of the License, or (at your option) any
       later version.

       This program is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
       General Public License for more details.

       If you do not have a copy of the GNU General Public License write to
       the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
       USA.










































3rd Berkeley Distribution    perl 5.005, patch 02              Getopt::Long(3)