Getopt::Long(3) Getopt::Long(3)
NAME
GetOptions - extended processing of command line options
SYNOPSIS
use Getopt::Long;
$result = GetOptions (...option-descriptions...);
DESCRIPTION
The Getopt::Long module implements an extended getopt function called
GetOptions(). This function 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
dash "--". Support for bundling of command line options, as was the case
with the more traditional single-letter approach, is provided but not
enabled by default. For example, the UNIX "ps" command can be given the
command line "option"
-vax
which means the combination of -v, -a and -x. With the new syntax --vax
would be a single option, probably indicating a computer architecture.
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 get the value 24.
Alternatively, the first argument to GetOptions may be a reference to a
HASH describing the linkage for the options, or an object whose class is
based on a HASH. 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.
Linkage specified in the argument list takes precedence over the linkage
specified in the HASH.
Page 1
Getopt::Long(3) Getopt::Long(3)
The command line options are taken from array @ARGV. Upon completion of
GetOptions, @ARGV will contain the rest (i.e. the non-options) of the
command line.
Each option specifier designates the name of the option, optionally
followed by an argument specifier. Values for argument specifiers are:
<none> Option does not take an argument. The option variable will be set
to 1.
! Option does not take an argument and may be negated, i.e.
prefixed by "no". E.g. "foo!" will allow --foo (with value 1) and
-nofoo (with value 0). The option variable will be set to 1, or
0 if negated.
=s Option takes a mandatory string argument. This string will be
assigned to the option variable. Note that even if the string
argument starts with - or --, it will not be considered an option
on itself.
:s Option takes an optional string argument. This string will be
assigned to the option variable. If omitted, it will be assigned
"" (an empty string). If the string argument starts with - or
--, it will be considered an option on itself.
=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 value will be
assigned to the option variable. If omitted, the value 0 will be
assigned. Note that the value may start with - to indicate a
negative value.
=f Option takes a mandatory real number 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 real number argument. This value will
be assigned to the option variable. If omitted, the value 0 will
be assigned.
A lone dash - is considered an option, the corresponding option name is
the empty string.
A double dash on itself -- signals end of the options list.
Linkage specification
The linkage specifier is optional. If no linkage is explicitly specified
but a ref HASH is passed, GetOptions will place the value in the HASH.
For example:
Page 2
Getopt::Long(3) Getopt::Long(3)
%optctl = ();
GetOptions (\%optctl, "size=i");
will perform the equivalent of the assignment
$optctl{"size"} = 24;
For array options, a reference to an array is used, e.g.:
%optctl = ();
GetOptions (\%optctl, "sizes=i@");
with command line "-sizes 24 -sizes 48" will perform the equivalent of
the assignment
$optctl{"sizes"} = [24, 48];
For hash options (an option whose argument looks like "name=value"), a
reference to a hash is used, e.g.:
%optctl = ();
GetOptions (\%optctl, "define=s%");
with command line "--define foo=hello --define bar=world" will perform
the equivalent of the assignment
$optctl{"define"} = {foo=>'hello', bar=>'world')
If no linkage is explicitly specified and no ref HASH 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 dash - is considered an option, the corresponding Perl identifier
is $opt_ .
The linkage specifier can be a reference to a scalar, a reference to an
array, a reference to a hash or a reference to a subroutine.
Page 3
Getopt::Long(3) Getopt::Long(3)
If a REF SCALAR is supplied, the new value is stored in the referenced
variable. If the option occurs more than once, the previous value is
overwritten.
If a REF ARRAY is supplied, the new value is appended (pushed) to the
referenced array.
If a REF HASH is supplied, the option value should look like "key" or
"key=value" (if the "=value" is omitted then a value of 1 is implied).
In this case, the element of the referenced hash with the key "key" is
assigned "value".
If a REF CODE 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.
Aliases and abbreviations
The option name may actually be a list of option names, separated by
"|"s, e.g. "foo|bar|blech=s". In this example, "foo" is the true name of
this option. If no linkage is specified, options "foo", "bar" and "blech"
all will set $opt_foo.
Option names may be abbreviated to uniqueness, depending on configuration
option autoabbrev.
Non-option call-back routine
A special option specifier, <>, can be used to designate a subroutine to
handle non-option arguments. GetOptions will immediately call this
subroutine for every non-option it encounters in the options list. This
subroutine gets the name of the non-option passed. This feature requires
configuration option permute, see section CONFIGURATION OPTIONS.
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 POSIXLYCORRECT has been defined.
Options that start with "--" may have an argument appended, separated
with an "=", e.g. "--foo=bar".
Return value
A return status of 0 (false) indicates that the function detected one or
more errors.
Page 4
Getopt::Long(3) Getopt::Long(3)
COMPATIBILITY
Getopt::Long::GetOptions() is the successor of newgetopt.pl that came
with Perl 4. It is fully upward compatible. In fact, the Perl 5 version
of newgetopt.pl is just a wrapper around the module.
If an "@" sign is appended to the argument specifier, the option is
treated as an array. Value(s) are not set, but pushed into array
@opt_name. If explicit linkage is supplied, this must be a reference to
an ARRAY.
If an "%" sign is appended to the argument specifier, the option is
treated as a hash. Value(s) of the form "name=value" are set by setting
the element of the hash %opt_name with key "name" to "value" (if the
"=value" portion is omitted it defaults to 1). If explicit linkage is
supplied, this must be a reference to a HASH.
If configuration option getoptcompat is set (see section CONFIGURATION
OPTIONS), options that start with "+" or "-" may also include their
arguments, e.g. "+foo=bar". This is for compatiblity with older
implementations of the GNU "getopt" routine.
If the first argument to GetOptions is a string consisting of only non-
alphanumeric characters, it is taken to specify the option starter
characters. Everything starting with one of these characters from the
starter will be considered an option. Using a starter argument is
strongly deprecated.
For convenience, option specifiers may have a leading - or --, so it is
possible to write:
GetOptions qw(-foo=s --bar=i --ar=s);
EXAMPLES
If the option specifier is "one:i" (i.e. 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 = '--'
Page 5
Getopt::Long(3) Getopt::Long(3)
Example of 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:
$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 -> 2
@ARGV -> qw(bar blech)
CONFIGURATION OPTIONS
GetOptions can be configured by calling subroutine Getopt::Long::config.
This subroutine takes a list of quoted strings, each specifying a
configuration option to be set, e.g. ignorecase. Options can be reset
by prefixing with no, e.g. noignorecase. Case does not matter.
Multiple calls to config are possible.
Previous versions of Getopt::Long used variables for the purpose of
configuring. Although manipulating these variables still work, it is
strongly encouraged to use the new config routine. Besides, it is much
easier.
The following options are available:
default This option causes all configuration options to be reset to
their default values.
auto_abbrev Allow option names to be abbreviated to uniqueness. Default
is set unless environment variable POSIXLY_CORRECT has been
set, in which case autoabbrev is reset.
Page 6
Getopt::Long(3) Getopt::Long(3)
getopt_compat
Allow '+' to start options. Default is set unless
environment variable POSIXLY_CORRECT has been set, in which
case getoptcompat is reset.
require_order
Whether non-options are allowed to be mixed with options.
Default is set unless environment variable POSIXLY_CORRECT
has been set, in which case b<require_order> is reset.
See also permute, which is the opposite of requireorder.
permute Whether non-options are allowed to be mixed with options.
Default is set unless environment variable POSIXLY_CORRECT
has been set, in which case permute is reset. Note that
permute is the opposite of requireorder.
If permute is set, this means that
-foo arg1 -bar arg2 arg3
is equivalent to
-foo -bar arg1 arg2 arg3
If a non-option call-back routine is specified, @ARGV will
always be empty upon succesful return of GetOptions since all
options have been processed, except when -- is used:
-foo arg1 -bar arg2 -- arg3
will call the call-back routine for arg1 and arg2, and
terminate leaving arg2 in @ARGV.
If requireorder is set, options processing terminates when
the first non-option is encountered.
-foo arg1 -bar arg2 arg3
is equivalent to
-foo -- arg1 -bar arg2 arg3
bundling (default: reset)
Setting this variable to a non-zero value will allow single-
character options to be bundled. To distinguish bundles from
long option names, long options must be introduced with --
and single-character options (and bundles) with -. For
example,
ps -vax --vax
Page 7
Getopt::Long(3) Getopt::Long(3)
would be equivalent to
ps -v -a -x --vax
provided "vax", "v", "a" and "x" have been defined to be
valid options.
Bundled options can also include a value in the bundle; this
value has to be the last part of the bundle, e.g.
scale -h24 -w80
is equivalent to
scale -h 24 -w 80
Note: resetting bundling also resets bundlingoverride.
bundling_override (default: reset)
If bundlingoverride is set, bundling is enabled as with
bundling but now long option names override option bundles.
In the above example, -vax would be interpreted as the option
"vax", not the bundle "v", "a", "x".
Note: resetting bundlingoverride also resets bundling.
Note: Using option bundling can easily lead to unexpected
results, especially when mixing long options and bundles.
Caveat emptor.
ignore_case (default: set)
If set, case is ignored when matching options.
Note: resetting ignorecase also resets ignorecasealways.
ignore_case_always (default: reset)
When bundling is in effect, case is ignored on single-
character options also.
Note: resetting ignorecasealways also resets ignorecase.
pass_through (default: reset)
Unknown options are passed through in @ARGV instead of being
flagged as errors. This makes it possible to write wrapper
scripts that process only part of the user supplied options,
and passes the remaining options to some other program.
This can be very confusing, especially when permute is also
set.
Page 8
Getopt::Long(3) Getopt::Long(3)
debug (default: reset)
Enable copious debugging output.
OTHER USEFUL VARIABLES
$Getopt::Long::VERSION
The version number of this Getopt::Long implementation in the
format major.minor. This can be used to have Exporter check
the version, e.g.
use Getopt::Long 3.00;
You can inspect $Getopt::Long::major_version and
$Getopt::Long::minor_version for the individual components.
$Getopt::Long::error
Internal error flag. May be incremented from a call-back
routine to cause options parsing to fail.
Page 9
Getopt::Long(3) Getopt::Long(3)
Page 10