Getopt::Long(3)
NNAAMMEE
GetOptions - extended processing of command line options
SSYYNNOOPPSSIISS
use Getopt::Long;
$result = GetOptions (...option-descriptions...);
DDEESSCCRRIIPPTTIIOONN
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 --vv, --aa and --xx. With the new
syntax ----vvaaxx 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.
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 ----ffoooo (with value 1) and --nnooffoooo (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.
LLiinnkkaaggee ssppeecciiffiiccaattiioonn
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:
%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
mmaaiinn. 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.
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.
AAlliiaasseess aanndd aabbbbrreevviiaattiioonnss
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 aauuttoo__aabbbbrreevv.
NNoonn--ooppttiioonn ccaallll--bbaacckk rroouuttiinnee
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 ppeerrmmuuttee, see section CONFIGURATION
OPTIONS.
See also the examples.
OOppttiioonn ssttaarrtteerrss
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 PPOOSSIIXXLLYY__CCOORRRREECCTT has been defined.
Options that start with "--" may have an argument
appended, separated with an "=", e.g. "--foo=bar".
RReettuurrnn vvaalluuee
A return status of 0 (false) indicates that the function
detected one or more errors.
CCOOMMPPAATTIIBBIILLIITTYY
Getopt::Long::GetOptions() is the successor of
nneewwggeettoopptt..ppll 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 ggeettoopptt__ccoommppaatt 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. UUssiinngg aa ssttaarrtteerr aarrgguummeenntt iiss ssttrroonnggllyy
ddeepprreeccaatteedd..
For convenience, option specifiers may have a leading -- or
----, so it is possible to write:
GetOptions qw(-foo=s --bar=i --ar=s);
EEXXAAMMPPLLEESS
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 = '--'
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)
CCOONNFFIIGGUURRAATTIIOONN OOPPTTIIOONNSS
GGeettOOppttiioonnss can be configured by calling subroutine
GGeettoopptt::::LLoonngg::::ccoonnffiigg. This subroutine takes a list of
quoted strings, each specifying a configuration option to
be set, e.g. iiggnnoorree__ccaassee. Options can be reset by
prefixing with nnoo__, e.g. nnoo__iiggnnoorree__ccaassee. Case does not
matter. Multiple calls to ccoonnffiigg 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 ccoonnffiigg 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 aauuttoo__aabbbbrreevv is reset.
getopt_compat
Allow '+' to start options. Default is set
unless environment variable POSIXLY_CORRECT
has been set, in which case ggeettoopptt__ccoommppaatt 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 ppeerrmmuuttee, which is the opposite of
rreeqquuiirree__oorrddeerr.
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 ppeerrmmuuttee is reset. Note
that ppeerrmmuuttee is the opposite of rreeqquuiirree__oorrddeerr.
If ppeerrmmuuttee 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 rreeqquuiirree__oorrddeerr 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
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 bbuunnddlliinngg also resets
bbuunnddlliinngg__oovveerrrriiddee.
bundling_override (default: reset)
If bbuunnddlliinngg__oovveerrrriiddee is set, bundling is
enabled as with bbuunnddlliinngg but now long option
names override option bundles. In the above
example, --vvaaxx would be interpreted as the
option "vax", not the bundle "v", "a", "x".
Note: resetting bbuunnddlliinngg__oovveerrrriiddee also resets
bbuunnddlliinngg.
NNoottee:: 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 iiggnnoorree__ccaassee also resets
iiggnnoorree__ccaassee__aallwwaayyss.
ignore_case_always (default: reset)
When bundling is in effect, case is ignored on
single-character options also.
Note: resetting iiggnnoorree__ccaassee__aallwwaayyss also resets
iiggnnoorree__ccaassee.
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
ppeerrmmuuttee is also set.
debug (default: reset)
Enable copious debugging output.
OOTTHHEERR UUSSEEFFUULL VVAARRIIAABBLLEESS
$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.