use Getopt::Long; $result = GetOptions (...option-descriptions...);
-vaxwhich 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=24GetOptions 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. 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:
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.
%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];
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 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 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.
Option names may be abbreviated to uniqueness, depending on configuration variable $Getopt::Long::autoabbrev.
Options that start with ``--'' may have an argument appended, separated with an ``='', e.g. ``---foo=bar''.
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. This only applies if no linkage is supplied.
If configuration variable $Getopt::Long::getopt_compat is set to a non-zero value, options that start with ``+'' 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);
-one -two -> $opt_one = '', -two is next option -one -2 -> $opt_one = -2Also, 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 variabel 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:
$bar = '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)
$PERMUTE 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 $Getopt::Long::order is $REQUIRE_ORDER, options processing terminates when the first non-option is encountered.
-foo arg1 -bar arg2 arg3
is equivalent to
-foo -- arg1 -bar arg2 arg3
$RETURN_IN_ORDER is not supported by GetOptions().
use Getopt::Long 2.00;
You can inspect $Getopt::Long::major_version and
$Getopt::Long::minor_version for the individual components.