


Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


NAME
       Getopt::Long - 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 exten-
       sions. In general, this means that options have long names
       instead of single letters, and are introduced with a dou-
       ble 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.

Command Line Options, an Introduction
       Command line operated programs traditionally take their
       arguments from the command line, for example filenames or
       other information that the program needs to know. Besides
       arguments, these programs often take command line options
       as well. Options are not necessary for the program to
       work, hence the name 'option', but are used to modify its
       default behaviour. For example, a program could do its job
       quietly, but with a suitable option it could provide ver-
       bose information about what it did.

       Command line options come in several flavours. Histori-
       cally, they are preceded by a single dash "-", and consist
       of a single letter.

           -l -a -c

       Usually, these single-character options can be bundled:

           -lac

       Options can have values, the value is placed after the
       option character. Sometimes with whitespace in between,
       sometimes not:

           -s 24 -s24

       Due to the very cryptic nature of these options, another
       style was developed that used long names. So instead of a
       cryptic "-l" one could use the more descriptive "--long".
       To distinguish between a bundle of single-character
       options and a long one, two dashes are used to precede the
       option name. Early implementations of long options used a
       plus "+" instead. Also, option values could be specified
       either like




2001-05-24                 perl v5.6.1                          1





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


           --size=24

       or

           --size 24

       The "+" form is now obsolete and strongly deprecated.

Getting Started with Getopt::Long
       Getopt::Long is the Perl5 successor of "newgetopt.pl".
       This was the first Perl module that provided support for
       handling the new style of command line options, hence the
       name Getopt::Long. This module also supports single-char-
       acter options and bundling. In this case, the options are
       restricted to alphabetic characters only, and the charac-
       ters "?" and "-".

       To use Getopt::Long from a Perl program, you must include
       the following line in your Perl program:

           use Getopt::Long;

       This will load the core of the Getopt::Long module and
       prepare your program for using it. Most of the actual
       Getopt::Long code is not loaded until you really call one
       of its functions.

       In the default configuration, options names may be abbre-
       viated to uniqueness, case does not matter, and a single
       dash is sufficient, even for long option names. Also,
       options may be placed between non-option arguments. See
       the Configuring Getopt::Long entry elsewhere in this docu-
       ment for more details on how to configure Getopt::Long.

       Simple options

       The most simple options are the ones that take no values.
       Their mere presence on the command line enables the
       option. Popular examples are:

           --all --verbose --quiet --debug

       Handling simple options is straightforward:

           my $verbose = '';   # option variable with default value (false)
           my $all = '';       # option variable with default value (false)
           GetOptions ('verbose' => \$verbose, 'all' => \$all);

       The call to GetOptions() parses the command line arguments
       that are present in "@ARGV" and sets the option variable
       to the value "1" if the option did occur on the command
       line. Otherwise, the option variable is not touched. Set-
       ting the option value to true is often called enabling the
       option.



2001-05-24                 perl v5.6.1                          2





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


       The option name as specified to the GetOptions() function
       is called the option specification. Later we'll see that
       this specification can contain more than just the option
       name. The reference to the variable is called the option
       destination.

       GetOptions() will return a true value if the command line
       could be processed successfully. Otherwise, it will write
       error messages to STDERR, and return a false result.

       A little bit less simple options

       Getopt::Long supports two useful variants of simple
       options: negatable options and incremental options.

       A negatable option is specified with a exclamation mark
       "!" after the option name:

           my $verbose = '';   # option variable with default value (false)
           GetOptions ('verbose!' => \$verbose);

       Now, using "--verbose" on the command line will enable
       "$verbose", as expected. But it is also allowed to use
       "--noverbose", which will disable "$verbose" by setting
       its value to "0". Using a suitable default value, the pro-
       gram can find out whether "$verbose" is false by default,
       or disabled by using "--noverbose".

       An incremental option is specified with a plus "+" after
       the option name:

           my $verbose = '';   # option variable with default value (false)
           GetOptions ('verbose+' => \$verbose);

       Using "--verbose" on the command line will increment the
       value of "$verbose". This way the program can keep track
       of how many times the option occurred on the command line.
       For example, each occurrence of "--verbose" could increase
       the verbosity level of the program.

       Mixing command line option with other arguments

       Usually programs take command line options as well as
       other arguments, for example, file names. It is good prac-
       tice to always specify the options first, and the other
       arguments last. Getopt::Long will, however, allow the
       options and arguments to be mixed and 'filter out' all the
       options before passing the rest of the arguments to the
       program. To stop Getopt::Long from processing further
       arguments, insert a double dash "--" on the command line:

           --size 24 -- --all

       In this example, "--all" will not be treated as an option,



2001-05-24                 perl v5.6.1                          3





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


       but passed to the program unharmed, in "@ARGV".

       Options with values

       For options that take values it must be specified whether
       the option value is required or not, and what kind of
       value the option expects.

       Three kinds of values are supported: integer numbers,
       floating point numbers, and strings.

       If the option value is required, Getopt::Long will take
       the command line argument that follows the option and
       assign this to the option variable. If, however, the
       option value is specified as optional, this will only be
       done if that value does not look like a valid command line
       option itself.

           my $tag = '';       # option variable with default value
           GetOptions ('tag=s' => \$tag);

       In the option specification, the option name is followed
       by an equals sign "=" and the letter "s". The equals sign
       indicates that this option requires a value. The letter
       "s" indicates that this value is an arbitrary string.
       Other possible value types are "i" for integer values, and
       "f" for floating point values. Using a colon ":" instead
       of the equals sign indicates that the option value is
       optional. In this case, if no suitable value is supplied,
       string valued options get an empty string "''" assigned,
       while numeric options are set to "0".

       Options with multiple values

       Options sometimes take several values. For example, a pro-
       gram could use multiple directories to search for library
       files:

           --library lib/stdlib --library lib/extlib

       To accomplish this behaviour, simply specify an array ref-
       erence as the destination for the option:

           my @libfiles = ();
           GetOptions ("library=s" => \@libfiles);

       Used with the example above, "@libfiles" would contain two
       strings upon completion: ""lib/srdlib"" and
       ""lib/extlib"", in that order.  It is also possible to
       specify that only integer or floating point numbers are
       acceptible values.

       Often it is useful to allow comma-separated lists of val-
       ues as well as multiple occurrences of the options. This



2001-05-24                 perl v5.6.1                          4





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


       is easy using Perl's split() and join() operators:

           my @libfiles = ();
           GetOptions ("library=s" => \@libfiles);
           @libfiles = split(/,/,join(',',@libfiles));

       Of course, it is important to choose the right separator
       string for each purpose.

       Options with hash values

       If the option destination is a reference to a hash, the
       option will take, as value, strings of the form
       key"="value. The value will be stored with the specified
       key in the hash.

           my %defines = ();
           GetOptions ("define=s" => \%defines);

       When used with command line options:

           --define os=linux --define vendor=redhat

       the hash "%defines" will contain two keys, ""os"" with
       value ""linux" and ""vendor"" with value ""redhat"".  It
       is also possible to specify that only integer or floating
       point numbers are acceptible values. The keys are always
       taken to be strings.

       User-defined subroutines to handle options

       Ultimate control over what should be done when (actually:
       each time) an option is encountered on the command line
       can be achieved by designating a reference to a subroutine
       (or an anonymous subroutine) as the option destination.
       When GetOptions() encounters the option, it will call the
       subroutine with two arguments: the name of the option, and
       the value to be assigned. It is up to the subroutine to
       store the value, or do whatever it thinks is appropriate.

       A trivial application of this mechanism is to implement
       options that are related to each other. For example:

           my $verbose = '';   # option variable with default value (false)
           GetOptions ('verbose' => \$verbose,
                       'quiet'   => sub { $verbose = 0 });

       Here "--verbose" and "--quiet" control the same variable
       "$verbose", but with opposite values.

       If the subroutine needs to signal an error, it should call
       die() with the desired error message as its argument.
       GetOptions() will catch the die(), issue the error mes-
       sage, and record that an error result must be returned



2001-05-24                 perl v5.6.1                          5





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


       upon completion.

       If the text of the error message starts with an exclaman-
       tion mark "!"  it is interpreted specially by GetOp-
       tions(). There is currently one special command imple-
       mented: "die("!FINISH")" will cause GetOptions() to stop
       processing options, as if it encountered a double dash
       "--".

       Options with multiple names

       Often it is user friendly to supply alternate mnemonic
       names for options. For example "--height" could be an
       alternate name for "--length". Alternate names can be
       included in the option specification, separated by verti-
       cal bar "|" characters. To implement the above example:

           GetOptions ('length|height=f' => \$length);

       The first name is called the primary name, the other names
       are called aliases.

       Multiple alternate names are possible.

       Case and abbreviations

       Without additional configuration, GetOptions() will ignore
       the case of option names, and allow the options to be
       abbreviated to uniqueness.

           GetOptions ('length|height=f' => \$length, "head" => \$head);

       This call will allow "--l" and "--L" for the length
       option, but requires a least "--hea" and "--hei" for the
       head and height options.

       Summary of Option Specifications

       Each option specifier consists of two parts: the name
       specification and the argument specification.

       The name specification contains the name of the option,
       optionally followed by a list of alternative names sepa-
       rated by vertical bar characters.

           length            option name is "length"
           length|size|l     name is "length", aliases are "size" and "l"

       The argument specification is optional. If omitted, the
       option is considered boolean, a value of 1 will be
       assigned when the option is used on the command line.

       The argument specification can be




2001-05-24                 perl v5.6.1                          6





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


       !   The option does not take an argument and may be
           negated, i.e. prefixed by "no". E.g. ""foo!"" will
           allow "--foo" (a value of 1 will be assigned) and
           "--nofoo" (a value of 0 will be assigned). If the
           option has aliases, this applies to the aliases as
           well.

           Using negation on a single letter option when bundling
           is in effect is pointless and will result in a warn-
           ing.

       +   The 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 increment the value three times, result-
           ing in a value of 3 (provided it was 0 or undefined at
           first).

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

       = type [ desttype ]
           The option requires an argument of the given type.
           Supported types are:

           s   String. An arbitrary sequence of characters. It is
               valid for the argument to start with "-" or "--".

           i   Integer. An optional leading plus or minus sign,
               followed by a sequence of digits.

           f   Real number. For example "3.14", "-6.23E24" and so
               on.

           The desttype can be "@" or "%" to specify that the
           option is list or a hash valued. This is only needed
           when the destination for the option value is not oth-
           erwise specified. It should be omitted when not
           needed.

       : type [ desttype ]
           Like "=", but designates the argument as optional.  If
           omitted, an empty string will be assigned to string
           values options, and the value zero to numeric options.

           Note that if a string argument starts with "-" or
           "--", it will be considered an option on itself.

Advanced Possibilities
       Object oriented interface

       Getopt::Long can be used in an object oriented way as
       well:




2001-05-24                 perl v5.6.1                          7





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


           use Getopt::Long;
           $p = new Getopt::Long::Parser;
           $p->configure(...configuration options...);
           if ($p->getoptions(...options descriptions...)) ...

       Configuration options can be passed to the constructor:

           $p = new Getopt::Long::Parser
                    config => [...configuration options...];

       For thread safety, each method call will acquire an exclu-
       sive lock to the Getopt::Long module. So don't call these
       methods from a callback routine!

       Documentation and help texts

       Getopt::Long encourages the use of Pod::Usage to produce
       help messages. For example:

           use Getopt::Long;
           use Pod::Usage;

           my $man = 0;
           my $help = 0;

           GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
           pod2usage(1) if $help;
           pod2usage(-exitstatus => 0, -verbose => 2) if $man;

           __END__

           =head1 NAME

           sample - Using GetOpt::Long and Pod::Usage

           =head1 SYNOPSIS

           sample [options] [file ...]

            Options:
              -help            brief help message
              -man             full documentation

           =head1 OPTIONS

           =over 8

           =item B<-help>

           Print a brief help message and exits.

           =item B<-man>

           Prints the manual page and exits.



2001-05-24                 perl v5.6.1                          8





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


           =back

           =head1 DESCRIPTION

           B<This program> will read the given input file(s) and do someting
           useful with the contents thereof.

           =cut

       See the Pod::Usage manpage for details.

       Storing options in a hash

       Sometimes, for example when there are a lot of options,
       having a separate variable for each of them can be cumber-
       some. GetOptions() supports, as an alternative mechanism,
       storing options in a hash.

       To obtain this, a reference to a hash must be passed as
       the first argument to GetOptions(). For each option that
       is specified on the command line, the option value will be
       stored in the hash with the option name as key. Options
       that are not actually used on the command line will not be
       put in the hash, on other words, "exists($h{option})" (or
       defined()) can be used to test if an option was used. The
       drawback is that warnings will be issued if the program
       runs under "use strict" and uses "$h{option}" without
       testing with exists() or defined() first.

           my %h = ();
           GetOptions (\%h, 'length=i');       # will store in $h{length}

       For options that take list or hash values, it is necessary
       to indicate this by appending an "@" or "%" sign after the
       type:

           GetOptions (\%h, 'colours=s@');     # will push to @{$h{colours}}

       To make things more complicated, the hash may contain ref-
       erences to the actual destinations, for example:

           my $len = 0;
           my %h = ('length' => \$len);
           GetOptions (\%h, 'length=i');       # will store in $len

       This example is fully equivalent with:

           my $len = 0;
           GetOptions ('length=i' => \$len);   # will store in $len

       Any mixture is possible. For example, the most frequently
       used options could be stored in variables while all other
       options get stored in the hash:




2001-05-24                 perl v5.6.1                          9





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


           my $verbose = 0;                    # frequently referred
           my $debug = 0;                      # frequently referred
           my %h = ('verbose' => \$verbose, 'debug' => \$debug);
           GetOptions (\%h, 'verbose', 'debug', 'filter', 'size=i');
           if ( $verbose ) { ... }
           if ( exists $h{filter} ) { ... option 'filter' was specified ... }


       Bundling

       With bundling it is possible to set several single-charac-
       ter options at once. For example if "a", "v" and "x" are
       all valid options,

           -vax

       would set all three.

       Getopt::Long supports two levels of bundling. To enable
       bundling, a call to Getopt::Long::Configure is required.

       The first level of bundling can be enabled with:

           Getopt::Long::Configure ("bundling");

       Configured this way, single-character options can be bun-
       dled but long options must always start with a double dash
       "--" to avoid abiguity. For example, when "vax", "a", "v"
       and "x" are all valid options,

           -vax

       would set "a", "v" and "x", but

           --vax

       would set "vax".

       The second level of bundling lifts this restriction. It
       can be enabled with:

           Getopt::Long::Configure ("bundling_override");

       Now, "-vax" would set the option "vax".

       When any level of bundling is enabled, option values may
       be inserted in the bundle. For example:

           -h24w80

       is equivalent to

           -h 24 -w 80




2001-05-24                 perl v5.6.1                         10





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


       When configured for bundling, single-character options are
       matched case sensitive while long options are matched case
       insensitive. To have the single-character options matched
       case insensitive as well, use:

           Getopt::Long::Configure ("bundling", "ignorecase_always");

       It goes without saying that bundling can be quite confus-
       ing.

       The lonesome dash

       Normally, a lone dash "-" on the command line will not be
       considered an option. Option processing will terminate
       (unless "permute" is configured) and the dash will be left
       in "@ARGV".

       It is possible to get special treatment for a lone dash.
       This can be achieved by adding an option specification
       with an empty name, for example:

           GetOptions ('' => \$stdio);

       A lone dash on the command line will now be a legal
       option, and using it will set variable "$stdio".

       Argument call-back

       A special option 'name' "<"> can be used to designate a
       subroutine to handle non-option arguments. When GetOp-
       tions() encounters an argument that does not look like an
       option, it will immediately call this subroutine and
       passes it the argument as a parameter.

       For example:

           my $width = 80;
           sub process { ... }
           GetOptions ('width=i' => \$width, '<>' => \&process);

       When applied to the following command line:

           arg1 --width=72 arg2 --width=60 arg3

       This will call "process("arg1")" while "$width" is "80",
       "process("arg2")" while "$width" is "72", and "pro-
       cess("arg3")" while "$width" is "60".

       This feature requires configuration option permute, see
       section the Configuring Getopt::Long entry elsewhere in
       this document.

Configuring Getopt::Long
       Getopt::Long can be configured by calling subroutine



2001-05-24                 perl v5.6.1                         11





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


       Getopt::Long::Configure(). This subroutine takes a list of
       quoted strings, each specifying a configuration option to
       be enabled, e.g.  "ignore_case", or disabled, e.g.
       "no_ignore_case". Case does not matter. Multiple calls to
       Configure() are possible.

       Alternatively, as of version 2.24, the configuration
       options may be passed together with the "use" statement:

           use Getopt::Long qw(:config no_ignore_case bundling);

       The following options are available:

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

       posix_default
                   This option causes all configuration options
                   to be reset to their default values as if the
                   environment variable POSIXLY_CORRECT had been
                   set.

       auto_abbrev Allow option names to be abbreviated to
                   uniqueness.  Default is enabled unless envi-
                   ronment variable POSIXLY_CORRECT has been set,
                   in which case "auto_abbrev" is disabled.

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

       gnu_compat  "gnu_compat" controls whether "--opt=" is
                   allowed, and what it should do. Without
                   "gnu_compat", "--opt=" gives an error. With
                   "gnu_compat", "--opt=" will give option "opt"
                   and empty value.  This is the way GNU
                   getopt_long() does it.

       gnu_getopt  This is a short way of setting "gnu_compat"
                   "bundling" "permute" "no_getopt_compat". With
                   "gnu_getopt", command line handling should be
                   fully compatible with GNU getopt_long().

       require_order
                   Whether command line arguments are allowed to
                   be mixed with options.  Default is disabled
                   unless environment variable POSIXLY_CORRECT
                   has been set, in which case "require_order" is
                   enabled.

                   See also "permute", which is the opposite of
                   "require_order".



2001-05-24                 perl v5.6.1                         12





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


       permute     Whether command line arguments are allowed to
                   be mixed with options.  Default is enabled
                   unless environment variable POSIXLY_CORRECT
                   has been set, in which case "permute" is dis-
                   abled.  Note that "permute" is the opposite of
                   "require_order".

                   If "permute" is enabled, this means that

                       --foo arg1 --bar arg2 arg3

                   is equivalent to

                       --foo --bar arg1 arg2 arg3

                   If an argument call-back routine is specified,
                   "@ARGV" will always be empty upon succesful
                   return of GetOptions() since all options have
                   been processed. The only exception is when
                   "--" is used:

                       --foo arg1 --bar arg2 -- arg3

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

                   If "require_order" is enabled, options pro-
                   cessing terminates when the first non-option
                   is encountered.

                       --foo arg1 --bar arg2 arg3

                   is equivalent to

                       --foo -- arg1 --bar arg2 arg3

                   If "pass_through" is also enabled, options
                   processing will terminate at the first unrec-
                   ognized option, or non-option, whichever comes
                   first.

       bundling (default: disabled)
                   Enabling this option will allow single-charac-
                   ter options to be bundled.  To distinguish
                   bundles from long option names, long options
                   must be introduced with "--" and single-char-
                   acter options (and bundles) with "-".

                   Note: disabling "bundling" also disables
                   "bundling_override".

       bundling_override (default: disabled)
                   If "bundling_override" is enabled, bundling is



2001-05-24                 perl v5.6.1                         13





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


                   enabled as with "bundling" but now long option
                   names override option bundles.

                   Note: disabling "bundling_override" also dis-
                   ables "bundling".

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

       ignore_case  (default: enabled)
                   If enabled, case is ignored when matching long
                   option names. Single character options will be
                   treated case-sensitive.

                   Note: disabling "ignore_case" also disables
                   "ignore_case_always".

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

                   Note: disabling "ignore_case_always" also dis-
                   ables "ignore_case".

       pass_through (default: disabled)
                   Options that are unknown, ambiguous or sup-
                   plied with an invalid option value are passed
                   through in "@ARGV" instead of being flagged as
                   errors. This makes it possible to write wrap-
                   per scripts that process only part of the user
                   supplied command line arguments, and pass the
                   remaining options to some other program.

                   If "require_order" is enabled, options pro-
                   cessing will terminate at the first unrecog-
                   nized option, or non-option, whichever comes
                   first.  However, if "permute" is enabled
                   instead, results can become confusing.

       prefix      The string that starts options. If a constant
                   string is not sufficient, see "prefix_pat-
                   tern".

       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: disabled)
                   Enable debugging output.




2001-05-24                 perl v5.6.1                         14





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


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__}".

       GetOptions returns true to indicate success.  It returns
       false when 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().

Legacy
       The earliest development of "newgetopt.pl" started in
       1990, with Perl version 4. As a result, its development,
       and the development of Getopt::Long, has gone through sev-
       eral stages. Since backward compatibility has always been
       extremely important, the current version of Getopt::Long
       still supports a lot of constructs that nowadays are no
       longer necessary or otherwise unwanted. This section
       describes briefly some of these 'features'.

       Default destinations

       When no destination is specified for an option, GetOptions
       will store the resultant value in a global variable named
       "opt_"XXX, where XXX is the primary name of this option.
       When a progam executes under "use strict" (recommended),
       these variables must be pre-declared with our() or "use
       vars".

           our $opt_length = 0;
           GetOptions ('length=i');    # will store in $opt_length

       To yield a usable Perl variable, characters that are not
       part of the syntax for variables are translated to under-
       scores. 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 nec-
       essarily "main". For example:

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

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

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






2001-05-24                 perl v5.6.1                         15





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


       Alternative option starters

       A string of alternative option starter characters may be
       passed as the first argument (or the first argument after
       a leading hash reference argument).

           my $len = 0;
           GetOptions ('/', 'length=i' => $len);

       Now the command line may look like:

           /length 24 -- arg

       Note that to terminate options processing still requires a
       double dash "--".

       GetOptions() will not interpret a leading ""<>"" as option
       starters if the next argument is a reference. To force
       ""<"" and "">"" as option starters, use ""><"". Confusing?
       Well, using a starter argument is strongly deprecated any-
       way.

       Configuration variables

       Previous versions of Getopt::Long used variables for the
       purpose of configuring. Although manipulating these vari-
       ables still work, it is strongly encouraged to use the
       "Configure" routine that was introduced in version 2.17.
       Besides, it is much easier.

Trouble Shooting
       Warning: Ignoring '!' modifier for short option

       This warning is issued when the '!' modifier is applied to
       a short (one-character) option and bundling is in effect.
       E.g.,

           Getopt::Long::Configure("bundling");
           GetOptions("foo|f!" => \$foo);

       Note that older Getopt::Long versions did not issue a
       warning, because the '!' modifier was applied to the first
       name only. This bug was fixed in 2.22.

       Solution: separate the long and short names and apply the
       '!' to the long names only, e.g.,

           GetOptions("foo!" => \$foo, "f" => \$foo);


       GetOptions does not return a false result when an option
       is not supplied

       That's why they're called 'options'.



2001-05-24                 perl v5.6.1                         16





Getopt::Long(3p) Perl Programmers Reference GuideGetopt::Long(3p)


AUTHOR
       Johan Vromans <jvromans@squirrel.nl>

COPYRIGHT AND DISCLAIMER
       This program is Copyright 2000,1990 by Johan Vromans.
       This program is free software; you can redistribute it
       and/or modify it under the terms of the Perl Artistic
       License or 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.





































2001-05-24                 perl v5.6.1                         17


