|
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::autoabbrev
If 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_compat
If true, then allow "
+
" to start options. Default is 1 unless environment variable
POSIXLY_CORRECT
has been set.
$Getopt::Long::order
If 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::ignorecase
If true, then ignore case when matching options. Default is
1
.
$Getopt::Long::VERSION
The 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::error
Internal error flag. May be incremented from a callback routine to cause options parsing to fail.
$Getopt::Long::debug
Enable 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 |