[Chapter 7] 7.2.35 Getopt::Long - Extended Processing of Command-Line Options

7.2.35 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:

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

7.2.35.1 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:

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.

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

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

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

7.2.35.5 Return value

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

7.2.35.6 Configuration variables

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 .

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