Welcome to the Monastery | |
PerlMonks |
perlman:Getopt::Longby root (Monk) |
on Dec 23, 1999 at 00:51 UTC ( [id://1211]=perlfunc: print w/replies, xml ) | Need Help?? |
Getopt::LongSee the current Perl documentation for Getopt::Long. Here is our local, out-dated (pre-5.6) version: GetOptions - extended processing of command line options
use Getopt::Long; $result = GetOptions (...option-descriptions...);
The Getopt::Long module implements an extended getopt function called
-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
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,
Options that do not take arguments will have no argument specifier. The option variable will be set to 1 if the option is used. For the other options, the 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.
Linkage specificationThe 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 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
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.
Note that, if your code is running under the recommended
use vars qw/ $opt_size @opt_sizes $opt_bar /; 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 abbreviationsThe 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. For convenience, the single character ``?'' is allowed as an alias, e.g. ``help|?''. Option names may be abbreviated to uniqueness, depending on configuration option auto_abbrev.
Non-option call-back routineA 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 startersOn 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, separated with an ``='', e.g. ``--foo=bar''.
Return values and Errors
Configuration errors and errors in the option definitions are signalled
using die and will terminate the calling program unless the call to A return value of 1 (true) indicates success.
A return status of 0 (false) indicates that the
function detected one or more errors during option parsing. These errors
are signalled using
perlguts and can be trapped with
Errors that can't happen are signalled using
COMPATIBILITYGetopt::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.
If an ``%'' sign is appended to the argument specifier, the option is treated as a hash.
If configuration option getopt_compat 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);
EXAMPLESIf 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)
CONFIGURATION OPTIONSGetOptions can be configured by calling subroutine Getopt::Long::Configure. This subroutine takes a list of quoted strings, each specifying a configuration option to be set, e.g. ignore_case. Options can be reset by prefixing with no_, e.g. no_ignore_case. 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:
OTHER USEFUL VARIABLES
AUTHORJohan Vromans <jvromans@squirrel.nl>
COPYRIGHT AND DISCLAIMERThis program is Copyright 1990,1998 by Johan Vromans. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. If you do not have a copy of the GNU General Public License write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. |
|