GetOptions

$result = GetOptions(option-descriptions)

Uses descriptions from option-descriptions to retrieve and process the command-line options with which your Perl program was invoked. The options are taken from @ARGV. After GetOptions has processed the options, @ARGV contains only command-line arguments that were not options. Returns 0 if errors are detected. Each option description consists of two elements:

Option specifier

Defines the option name and optionally a value as an argument specifier.

Option linkage

A reference to a variable that is set when the option is present.

GetOptions can also take as a first argument a reference to a hash that describes the linkage for the options. The linkage specified in the argument list takes precedence over the one specified in the hash. Thus the following are equivalent:

%optctl = (size => \$offset);
&GetOptions(\%optctl, "size=i");

and:

&GetOptions("size=i" => \$offset);

Option specifiers

Each option specifier consists of an option name and possibly an argument specifier. The name can be a name, or a list of names separated by |; the first name in the list is the true name of the option and the others are treated as aliases. Option names may be invoked with the shortest unique abbreviation. Values for argument specifiers are:

<none>

Option takes no argument. The option variable is set to 1.

!   

Option does not take an argument and may be negated, that is, prefixed by "no".

=s   

Option takes a mandatory argument that is a string to be assigned to the option variable. Even if the argument starts with - or --, it is assigned to the option variable rather than treated as another option.

:s   

Option takes an optional string argument. If the option is invoked with no argument, an empty string ("") is assigned to the option variable. If the argument starts with - or --, it is treated as another option rather than assigned to the option variable.

=i   

Option takes a mandatory integer argument, which may start with - to indicate a negative value.

:i   

Option takes an optional integer argument that may start with - to indicate a negative value. With no argument, the value 0 is assigned to the option variable.

=f   

Option takes a mandatory floating-point argument that may start with - to indicate a negative value.

:f   

Option takes an optional floating-point argument that may start with - to indicate a negative value. With no argument, the value 0 is assigned to the option variable.

A hyphen (-) by itself is considered an option whose name is the empty string. A double hyphen (--) by itself terminates option processing. Any options following the double hyphen remain in @ARGV when GetOptions returns. If an argument specifier ends with @ (e.g., =s@), then the option is treated as an array.

The special option specifier <> can be used to designate a subroutine to handle non-option arguments. For this specifier to be used, the variable $Getopt::Long::order must have the value of the predefined and exported variable, $PERMUTE. See the description of Getopt::Long::config below.

Linkage specification

The linkage specifier can be a reference to a:

Scalar

The new value is stored in the referenced variable. If the option occurs more than once, the previous value is overwritten.

Array

The new value is appended (pushed) onto the referenced array.

Subroutine

The referenced subroutine is called with two arguments: the option name, which is always the true name, and the option value.

If no linkage is explicitly specified, but a hash reference is passed, GetOptions puts the value in the hash. For array options, a reference to an anonymous array is generated.

If no linkage is explicitly specified and no hash reference is passed, GetOptions puts the value into a global variable named after the option, prefixed by opt_. Characters that are not part of the variable syntax are translated to underscores. For example, --fpp-struct-return sets the variable $opt_fpp_struct_return.