 | Chapter 7 The Standard Perl Library |  |
use Getopt::Long;
$result = GetOptions(option-descriptions);The Getopt::Long module implements an extended function called
GetOptions(). This function retrieves and processes the
command-line options with which your Perl program was invoked, based on the
description of valid options that you provide.
GetOptions() 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 hyphen
--. (A single hyphen can also be used,
but implies restrictions on functionality. See later in the chapter.) There is
no bundling of command-line options, as was the case with the more traditional
single-letter approach. For example, the UNIX
ps(1) command can be given the command-line
argument:
-vax
which means the combination of -v, -a and -x.
With the Getopt::Long syntax, -vax would be a single option.
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 be
assigned the value 24.
Alternatively, the first argument to GetOptions may be a reference to a hash describing the linkage for the options. 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. The linkage specified in the argument list takes precedence over the linkage specified in the hash.
The command-line options are implicitly taken from array @ARGV. Upon completion
of GetOptions(), @ARGV will contain only the command-line
arguments that were not options. (But see below for a way to process
non-option arguments.) Each option specifier handed to
GetOptions() designates the name of an option, possibly
followed by an argument specifier. Values for argument specifiers are:
<none>Option does not take an argument. If the user invokes the option, the option variable will be set to 1.
! Option does not take an argument and may be negated, that is, prefixed by
"no". For example, foo! will allow --foo (with value 1
being assigned to the option variable) and
-nofoo
(with value 0).
=s Option takes a mandatory string argument.
This string will be assigned to the option variable.
Even if the string argument starts with - or --, it
will be assigned to the option variable rather than taken as a separate
option.
:s Option takes an optional string argument.
This string will be assigned to the option variable. If the string is
omitted from the command invocation, "" (an empty string) will be
assigned to the option variable.
If the string argument starts with - or --, it
will be taken as another option rather than assigned to the option variable.
=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 integer value will be assigned to the option variable.
If the optional argument is omitted, the value 0 will be assigned to the
option variable. The value may start with - to indicate a negative
value.
=f Option takes a mandatory floating-point 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 floating-point argument.
This value will be assigned to the option variable.
If the optional argument is omitted, the value 0 will be assigned to the
option variable.
The value may start with - to indicate a negative value.
A lone hyphen - is considered an option; the corresponding option
name is the empty string.
A lone double hyphen -- terminates the
processing of options and arguments. Any options following the double hyphen
will remain in @ARGV when GetOptions()
returns.
If an argument specifier concludes with @ (as in =s@),
then the option is treated as an array. That is, multiple invocations of
the same option, each with a particular value, will result in the list of
values being assigned to the option variable, which is an array. See the
following section for an example.
The linkage specifier is optional. If no linkage is explicitly
specified but a hash reference 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 anonymous array is generated. For example:
%optctl = (); &GetOptions (\%optctl, "sizes=i@");
with command-line arguments:
-sizes 24 -sizes 48
will perform the equivalent of the assignment:
$optctl{"sizes"} = [24, 48];If no linkage is explicitly specified and no hash reference 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 hyphen (-) is considered an option; the corresponding
identifier is $opt_ .
The linkage specifier can be a reference to a scalar, a reference to an array, or a reference to a subroutine:
If a scalar reference is supplied, the new value is stored in the referenced variable. If the option occurs more than once, the previous value is overwritten.
If an array reference is supplied, the new value is appended (pushed) to the referenced array.
If a code reference 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.
The option specifier may actually include a "|"-separated list of option names:
foo|bar|blech=s
In this example, foo is the true name of the option. If no
linkage is specified, options -foo, -bar and
-blech all will set $opt_foo.
Options may be invoked as unique abbreviations, depending on
configuration variable $Getopt::Long::autoabbrev.
A special option specifier <> can be used to designate a subroutine
to handle non-option arguments. For example:
&GetOptions(..."<>", \&mysub...);
In this case GetOptions() will immediately call
&mysub for every non-option it encounters in the options
list. This subroutine gets the name of the non-option passed. This feature
requires $Getopt::Long::order to have the value of the
predefined and exported variable, $PERMUTE. See also the
examples.
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, following an equals sign (=). For
example: --foo=bar.
A return status of 0 (false) indicates that the function detected
one or more errors.
The following variables can be set to change the default behavior of
GetOptions():
$Getopt::Long::autoabbrevIf true, then allow option names to be invoked with unique abbreviations.
Default is 1 unless environment variable
POSIXLY_CORRECT has been set.
$Getopt::Long::getopt_compatIf true, then allow "+" to start options.
Default is 1 unless environment variable
POSIXLY_CORRECT has been set.
$Getopt::Long::orderIf set to $PERMUTE, then non-options are allowed to be mixed with
options on the command line. If set to $REQUIRE_ORDER, then
mixing is not allowed. Default is $REQUIRE_ORDER if environment
variable POSIXLY_CORRECT has been set, $PERMUTE otherwise.
Both $PERMUTE and $REQUIRE_ORDER are defined in the library
module and automatically exported.
$PERMUTE means that:
-foo arg1 -bar arg2 arg3
is equivalent to:
-foo -bar arg1 arg2 arg3
If a non-option callback routine is specified, @ARGV will always be
empty upon successful return of GetOptions() since all options have been
processed, except when -- is used. So, for example:
-foo arg1 -bar arg2 -- arg3
will call the callback routine for arg1 and
arg2, and then terminate, leaving arg3 in
@ARGV. If $Getopt::Long::order is
$REQUIRE_ORDER, option processing terminates when the first
non-option is encountered.
-foo arg1 -bar arg2 arg3
is equivalent to:
-foo -- arg1 -bar arg2 arg3
$Getopt::Long::ignorecaseIf true, then ignore case when matching options. Default is 1.
$Getopt::Long::VERSIONThe version number of this Getopt::Long implementation is in the format
major.minor. This can be used to have Exporter check the
version. Example:
use Getopt::Long 2.00;
$Getopt::Long::major_version and
$Getopt::Long::minor_version may be inspected for the
individual components.
$Getopt::Long::errorInternal error flag. May be incremented from a callback routine to cause options parsing to fail.
$Getopt::Long::debugEnable copious debugging output. Default is 0.
If the option specifier is one:i (which 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 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:
$opt_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 becomes 2 @ARGV becomes qw(bar blech)
If you're using the use strict pragma, which requires you to employ
only lexical variables or else globals that are fully declared, you
will have to use the double-colon package delimiter or else the
use vars pragma. For example:
use strict; use vars qw($opt_rows $opt_cols); use Getopt::Long;
|  | |
| 7.2.34 GDBM_File - Tied Access to GDBM Library |  | 7.2.36 Getopt::Std - Process Single-Character Options with Option Clustering |