unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-3.6)
Page:
Section:
Apropos / Subsearch:
optional field



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


NAME
       Getopt::Long - Extended processing of command line options

SYNOPSIS
         use Getopt::Long;
         my $data   = "file.dat";
         my $length = 24;
         my $verbose;
         $result = GetOptions ("length=i" => \$length,    # numeric
                               "file=s"   => \$data,      # string
                               "verbose"  => \$verbose);  # flag

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



perl v5.8.5                 2002-11-06                          1





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


       option name. Early implementations of long options used a
       plus "+" instead. Also, option values could be specified
       either like

           --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
       "Configuring Getopt::Long" for more details on how to con-
       figure 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



perl v5.8.5                 2002-11-06                          2





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


       the value 1 if the option did occur on the command line.
       Otherwise, the option variable is not touched. Setting the
       option value to true is often called enabling the option.

       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 an 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 program
       can find out whether $verbose is false by default, or dis-
       abled 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:



perl v5.8.5                 2002-11-06                          3





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


           --size 24 -- --all

       In this example, "--all" will not be treated as an option,
       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:

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

       Alternatively, you can specify that the option can have
       multiple values by adding a "@", and pass a scalar refer-
       ence as the destination:

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




perl v5.8.5                 2002-11-06                          4





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


       Used with the example above, @libfiles (or @$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
       is easy using Perl's split() and join() operators:

           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.

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

       Alternatively you can use:

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

       When used with command line options:

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

       the hash %defines (or %$defines) will contain two keys,
       "os" with value ""linux" and "vendor" with value "redhat".
       It is also possible to specify that only integer or float-
       ing 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 or three arguments. The first argument
       is the name of the option. For a scalar or array destina-
       tion, the second argument is the value to be stored. For a
       hash destination, the second arguments is the key to the
       hash, and the third argument the value to be stored. It is
       up to the subroutine to store the value, or do whatever it
       thinks is appropriate.




perl v5.8.5                 2002-11-06                          5





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


       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
       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.



perl v5.8.5                 2002-11-06                          6





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


       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

       !   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"
           and "--no-foo" (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.

           o   Extended integer, Perl style. This can be either
               an optional leading plus or minus sign, followed
               by a sequence of digits, or an octal string (a
               zero, optionally followed by '0', '1', .. '7'), or
               a hexadecimal string ("0x" followed by '0' .. '9',
               'a' .. 'f', case insensitive), or a binary string
               ("0b" followed by a series of '0' and '1').

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



perl v5.8.5                 2002-11-06                          7





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


           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.

       : number [ desttype ]
           Like ":i", but if the value is omitted, the number
           will be assigned.

       : + [ desttype ]
           Like ":i", but if the value is omitted, the current
           value for the option will be incremented.

Advanced Possibilities
       Object oriented interface

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

           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...];

       Thread Safety

       Getopt::Long is thread safe when using ithreads as of Perl
       5.8.  It is not thread safe when using the older (experi-
       mental and now obsolete) threads implementation that was
       added to Perl 5.005.

       Documentation and help texts

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

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





perl v5.8.5                 2002-11-06                          8





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


           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.

           =back

           =head1 DESCRIPTION

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

           =cut

       See Pod::Usage 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



perl v5.8.5                 2002-11-06                          9





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


       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 test-
       ing 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:

           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:



perl v5.8.5                 2002-11-06                         10





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


           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

       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);




perl v5.8.5                 2002-11-06                         11





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


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

       Argument callback

       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 one parameter: the argument name.

       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, "pro-
       cess("arg2")" while $width is 72, and "process("arg3")"
       while $width is 60.

       This feature requires configuration option permute, see
       section "Configuring Getopt::Long".

Configuring Getopt::Long
       Getopt::Long can be configured by calling subroutine
       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



perl v5.8.5                 2002-11-06                         12





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


                   environment 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".

       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 callback 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




perl v5.8.5                 2002-11-06                         13





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


                   This will call the callback routine for arg1
                   and arg2, and then 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 bun-
                   dles from long option names, long options must
                   be introduced with "--" and bundles with "-".

                   Note that, if you have options "a", "l" and
                   "all", and auto_abbrev enabled, possible argu-
                   ments and option settings are:

                       using argument               sets option(s)
                       ------------------------------------------
                       -a, --a                      a
                       -l, --l                      l
                       -al, -la, -ala, -all,...     a, l
                       --al, --all                  all

                   The suprising part is that "--a" sets option
                   "a" (due to auto completion), not "all".

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

       bundling_override (default: disabled)
                   If "bundling_override" is enabled, bundling is
                   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.




perl v5.8.5                 2002-11-06                         14





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


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

                   With "ignore_case", option specifications for
                   options that only differ in case, e.g., "foo"
                   and "Foo", will be flagged as duplicates.

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

       auto_version (default:disabled)
                   Automatically provide support for the --ver-
                   sion option if the application did not specify
                   a handler for this option itself.

                   Getopt::Long will provide a standard version
                   message that includes the program name, its
                   version (if $main::VERSION is defined), and
                   the versions of Getopt::Long and Perl. The
                   message will be written to standard output and
                   processing will terminate.

                   "auto_version" will be enabled if the calling
                   program explicitly specified a version number
                   higher than 2.32 in the "use" or "require"
                   statement.

       auto_help (default:disabled)
                   Automatically provide support for the --help
                   and -? options if the application did not
                   specify a handler for this option itself.

                   Getopt::Long will provide a help message using
                   module Pod::Usage. The message, derived from
                   the SYNOPSIS POD section, will be written to
                   standard output and processing will terminate.

                   "auto_help" will be enabled if the calling
                   program explicitly specified a version number
                   higher than 2.32 in the "use" or "require"
                   statement.

       pass_through (default: disabled)
                   Options that are unknown, ambiguous or



perl v5.8.5                 2002-11-06                         15





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


                   supplied with an invalid option value 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 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.

                   Note that the options terminator (default
                   "--"), if present, will also be passed through
                   in @ARGV.

       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.

Exportable Methods
       VersionMessage
           This subroutine provides a standard version message.
           Its argument can be:

           *   A string containing the text of a message to print
               before printing the standard message.

           *   A numeric value corresponding to the desired exit
               status.

           *   A reference to a hash.

           If more than one argument is given then the entire
           argument list is assumed to be a hash.  If a hash is
           supplied (either as a reference or as a list) it
           should contain one or more elements with the following
           keys:

           "-message"
           "-msg"
               The text of a message to print immediately prior



perl v5.8.5                 2002-11-06                         16





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


               to printing the program's usage message.

           "-exitval"
               The desired exit status to pass to the exit()
               function.  This should be an integer, or else the
               string "NOEXIT" to indicate that control should
               simply be returned without terminating the invok-
               ing process.

           "-output"
               A reference to a filehandle, or the pathname of a
               file to which the usage message should be written.
               The default is "\*STDERR" unless the exit value is
               less than 2 (in which case the default is "\*STD-
               OUT").

           You cannot tie this routine directly to an option,
           e.g.:

               GetOptions("version" => \&VersionMessage);

           Use this instead:

               GetOptions("version" => sub { VersionMessage() });

       HelpMessage
           This subroutine produces a standard help message,
           derived from the program's POD section SYNOPSIS using
           Pod::Usage. It takes the same arguments as VersionMes-
           sage(). In particular, you cannot tie it directly to
           an option, e.g.:

               GetOptions("help" => \&HelpMessage);

           Use this instead:

               GetOptions("help" => sub { HelpMessage() });

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

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



perl v5.8.5                 2002-11-06                         17





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


       several stages. Since backward compatibility has always
       been extremely important, the current version of
       Getopt::Long still supports a lot of constructs that nowa-
       days 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);

       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 anyway.




perl v5.8.5                 2002-11-06                         18





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


       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
       GetOptions does not return a false result when an option
       is not supplied

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

       GetOptions does not split the command line correctly

       The command line is not split by GetOptions, but by the
       command line interpreter (CLI). On Unix, this is the
       shell. On Windows, it is COMMAND.COM or CMD.EXE. Other
       operating systems have other CLIs.

       It is important to know that these CLIs may behave differ-
       ent when the command line contains special characters, in
       particular quotes or backslashes. For example, with Unix
       shells you can use single quotes ("'") and double quotes
       (""") to group words together. The following alternatives
       are equivalent on Unix:

           "two words"
           'two words'
           two\ words

       In case of doubt, insert the following statement in front
       of your Perl program:

           print STDERR (join("|",@ARGV),"\n");

       to verify how your CLI passes the arguments to the pro-
       gram.

       Undefined subroutine &&amp;main::GetOptions called

       Are you running Windows, and did you write

           use GetOpt::Long;

       (note the capital 'O')?

       How do I put a "-?" option into a Getopt::Long?

       You can only obtain this using an alias, and Getopt::Long
       of at least version 2.13.





perl v5.8.5                 2002-11-06                         19





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


           use Getopt::Long;
           GetOptions ("help|?");    # -help and -? will both set $opt_help

AUTHOR
       Johan Vromans <jvromansATsquirrel.nl>

COPYRIGHT AND DISCLAIMER
       This program is Copyright 2003,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.


































perl v5.8.5                 2002-11-06                         20