@node Getopt/Long, Getopt/Mixed, GDBM_File, Module List
@unnumbered extended processing of command line options


@unnumberedsec NAME

GetOptions - extended processing of command line options

@unnumberedsec SYNOPSIS

@example
use Getopt::Long;
$result = GetOptions (...option-descriptions...);
@end example

@unnumberedsec 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"

@example
-vax
@end example

which means the combination of -v, -a and -x. With the new
syntax @strong{--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:

@example
--size 24
--size=24
@end example

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:

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

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:

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

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:

@table @asis
@item <none>
Option does not take an argument. 
The option variable will be set to 1.

@item !
Option does not take an argument and may be negated, i.e. prefixed by
"no". E.g. "foo!" will allow @strong{--foo} (with value 1) and @strong{-nofoo}
(with value 0).
The option variable will be set to 1, or 0 if negated.

@item =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 @strong{--}, it
will not be considered an option on itself.

@item :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 @strong{--}, it
will be considered an option on itself.

@item =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. 

@item :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.

@item =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.

@item :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.

@end table
A lone dash - is considered an option, the corresponding option
name is the empty string.

A double dash on itself @strong{--} signals end of the options list.

@unnumberedsubsec 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:

@example
%optctl = ();
&GetOptions (\%optctl, "size=i");
@end example

will perform the equivalent of the assignment

@example
$optctl@{"size"@} = 24;
@end example

For array options, a reference to an array is used, e.g.:

@example
%optctl = ();
&GetOptions (\%optctl, "sizes=i@@");
@end example

with command line "-sizes 24 -sizes 48" will perform the equivalent of
the assignment

@example
$optctl@{"sizes"@} = [24, 48];
@end example

For hash options (an option whose argument looks like "name=value"),
a reference to a hash is used, e.g.:

@example
%optctl = ();
&GetOptions (\%optctl, "define=s%");
@end example

with command line "--define foo=hello --define bar=world" will perform the
equivalent of the assignment

@example
$optctl@{"define"@} = @{foo=>@'hello@', bar=>@'world@')
@end example

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 @strong{main}.
For example:

@example
&GetOptions ("size=i", "sizes=i@@");
@end example

with command line "-size 10 -sizes 24 -sizes 48" will perform the
equivalent of the assignments

@example
$opt_size = 10;
@@opt_sizes = (24, 48);
@end example

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.

@unnumberedsubsec 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
op 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 variable $Getopt::Long::autoabbrev.

@unnumberedsubsec 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 $Getopt::Long::order to have the value $PERMUTE.
See also the examples.

@unnumberedsubsec Option starters

On the command line, options can start with - (traditional), @strong{--}
(POSIX) and + (GNU, now being phased out). The latter is not
allowed if the environment variable @strong{POSIXLY_CORRECT} has been
defined.

Options that start with "--" may have an argument appended, separated
with an "=", e.g. "--foo=bar".

@unnumberedsubsec Return value

A return status of 0 (false) indicates that the function detected
one or more errors.

@unnumberedsec COMPATIBILITY

Getopt::Long::GetOptions() is the successor of
@strong{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 variable $Getopt::Long::getopt_compat is set to a
non-zero value, 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. @strong{Using a starter argument is
strongly deprecated.}

For convenience, option specifiers may have a leading - or @strong{--},
so it is possible to write:

@example
GetOptions qw(-foo=s --bar=i --ar=s);
@end example

@unnumberedsec EXAMPLES

If the option specifier is "one:i" (i.e. takes an optional integer
argument), then the following situations are handled:

@example
-one -two		-> $opt_one = @'@', -two is next option
-one -2		-> $opt_one = -2
@end example

Also, assume specifiers "foo=s" and "bar:s" :

@example
-bar -xxx		-> $opt_bar = @'@', @'-xxx@' is next option
-foo -bar		-> $opt_foo = @'-bar@'
-foo --		-> $opt_foo = @'--@'
@end example

In GNU or POSIX format, option names and values can be combined:

@example
+foo=blech		-> $opt_foo = @'blech@'
--bar=		-> $opt_bar = @'@'
--bar=--		-> $opt_bar = @'--@'
@end example

Example of using variable references:

@example
$ret = &GetOptions (@'foo=s@', \$foo, @'bar=i@', @'ar=s@', \@@ar);
@end example

With command line options "-foo blech -bar 24 -ar xx -ar yy" 
this will result in:

@example
$bar = @'blech@'
$opt_bar = 24
@@ar = (@'xx@',@'yy@')
@end example

Example of using the <> option specifier:

@example
@@ARGV = qw(-foo 1 bar -foo 2 blech);
&GetOptions("foo=i", \$myfoo, "<>", \&mysub);
@end example

Results:

@example
&mysub("bar") will be called (with $myfoo being 1)
&mysub("blech") will be called (with $myfoo being 2)
@end example

Compare this with:

@example
@@ARGV = qw(-foo 1 bar -foo 2 blech);
&GetOptions("foo=i", \$myfoo);
@end example

This will leave the non-options in @@ARGV:

@example
$myfoo -> 2
@@ARGV -> qw(bar blech)
@end example

@unnumberedsec CONFIGURATION VARIABLES

The following variables can be set to change the default behaviour of
GetOptions():

@table @asis
@item $Getopt::Long::autoabbrev      
Allow option names to be abbreviated to uniqueness.
Default is 1 unless environment variable
POSIXLY_CORRECT has been set.

@item $Getopt::Long::getopt_compat   
Allow @'+@' to start options.
Default is 1 unless environment variable
POSIXLY_CORRECT has been set.

@item $Getopt::Long::order           
Whether non-options are allowed to be mixed with
options.
Default is $REQUIRE_ORDER if environment variable
POSIXLY_CORRECT has been set, $PERMUTE otherwise.

$PERMUTE means that 

@example
-foo arg1 -bar arg2 arg3
@end example

is equivalent to

@example
-foo -bar arg1 arg2 arg3
@end example

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 @strong{--} is used:

@example
-foo arg1 -bar arg2 -- arg3
@end example

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.

@example
-foo arg1 -bar arg2 arg3
@end example

is equivalent to

@example
-foo -- arg1 -bar arg2 arg3
@end example

$RETURN_IN_ORDER is not supported by GetOptions().

@item $Getopt::Long::bundling
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 @strong{--} and single-character
options (and bundles) with -. For example,

@example
ps -vax --vax
@end example

would be equivalent to

@example
ps -v -a -x --vax
@end example

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.

@example
scale -h24 -w80
@end example

is equivalent to

@example
scale -h 24 -w 80
@end example

@strong{Note:} Using option bundling can easily lead to unexpected results,
especially when mixing long options and bundles. Caveat emptor.

@item $Getopt::Long::ignorecase
Ignore case when matching options. Default is 1. When bundling is in
effect, case is ignored on single-character options only if
$Getopt::Long::ignorecase is greater than 1.

@item $Getopt::Long::passthrough
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 $Getopt::Long::order is
set to $PERMUTE.

@item $Getopt::Long::VERSION
The version number of this Getopt::Long implementation in the format
@code{major}.@code{minor}. This can be used to have Exporter check the
version, e.g.

@example
use Getopt::Long 2.00;
@end example

You can inspect $Getopt::Long::major_version and
$Getopt::Long::minor_version for the individual components.

@item $Getopt::Long::error
Internal error flag. May be incremented from a call-back routine to
cause options parsing to fail.

@item $Getopt::Long::debug           
Enable copious debugging output. Default is 0.

@end table
