Getopt::Long - Extended Processing of Command-Line Options

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:

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.

Linkage specification

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:

Aliases and abbreviations

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.

Non-option callback routine

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.

Option starters

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

Options that start with -- may have an argument appended, following an equals sign (=). For example: --foo=bar.

Return value

A return status of (false) indicates that the function detected one or more errors.

Configuration variables

The following variables can be set to change the default behavior of GetOptions():

Examples

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;