From: Gurusamy Sarathy Date: Sun, 5 Mar 2000 20:35:13 +0000 (+0000) Subject: Getopt-Long v2.21 update (from Johan Vromans) X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=0b7031a26bc1dac055a802438072e3a031175a8d;p=p5sagit%2Fp5-mst-13.2.git Getopt-Long v2.21 update (from Johan Vromans) p4raw-id: //depot/perl@5557 --- diff --git a/lib/Getopt/Long.pm b/lib/Getopt/Long.pm index 06fb196..4e9ef8b 100644 --- a/lib/Getopt/Long.pm +++ b/lib/Getopt/Long.pm @@ -2,17 +2,17 @@ package Getopt::Long; -# RCS Status : $Id: GetoptLong.pl,v 2.21 1999-08-04 10:33:07+02 jv Exp $ +# RCS Status : $Id: GetoptLong.pl,v 2.22 2000-03-05 21:08:03+01 jv Exp $ # Author : Johan Vromans # Created On : Tue Sep 11 15:00:12 1990 # Last Modified By: Johan Vromans -# Last Modified On: Wed Aug 4 10:08:50 1999 -# Update Count : 709 +# Last Modified On: Sun Mar 5 21:08:55 2000 +# Update Count : 720 # Status : Released ################ Copyright ################ -# This program is Copyright 1990,1999 by Johan Vromans. +# This program is Copyright 1990,2000 by Johan Vromans. # This program is free software; you can redistribute it and/or # modify it under the terms of the Perl Artistic License or the # GNU General Public License as published by the Free Software @@ -23,9 +23,9 @@ package Getopt::Long; # 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, +# the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, # MA 02139, USA. ################ Module Preamble ################ @@ -36,7 +36,7 @@ BEGIN { require 5.004; use Exporter (); use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS); - $VERSION = "2.20"; + $VERSION = "2.21"; @ISA = qw(Exporter); @EXPORT = qw(&GetOptions $REQUIRE_ORDER $PERMUTE $RETURN_IN_ORDER); @@ -52,14 +52,14 @@ use vars qw($error $debug $major_version $minor_version); use vars qw($autoabbrev $getopt_compat $ignorecase $bundling $order $passthrough); # Official invisible variables. -use vars qw($genprefix); +use vars qw($genprefix $caller); -# Public subroutines. +# Public subroutines. sub Configure (@); sub config (@); # deprecated name sub GetOptions; -# Private subroutines. +# Private subroutines. sub ConfigDefaults (); sub FindOption ($$$$$$$); sub Croak (@); # demand loading the real Croak @@ -98,8 +98,76 @@ sub ConfigDefaults () { # Version major/minor numbers. ($major_version, $minor_version) = $VERSION =~ /^(\d+)\.(\d+)/; -# Set defaults. -ConfigDefaults (); +ConfigDefaults(); + +################ Object Oriented routines ################ + +=experimental + +# NOTE: The object oriented routines use $error for thread locking. +eval "sub lock{}" if $] < 5.005; + +# Store a copy of the default configuration. Since ConfigDefaults has +# just been called, what we get from Configure is the default. +my $default_config = do { lock ($error); Configure () }; + +sub new { + my $that = shift; + my $class = ref($that) || $that; + + # Register the callers package. + my $self = { caller => (caller)[0] }; + + bless ($self, $class); + + # Process construct time configuration. + if ( @_ > 0 ) { + lock ($error); + my $save = Configure ($default_config, @_); + $self->{settings} = Configure ($save); + } + # Else use default config. + else { + $self->{settings} = $default_config; + } + + $self; +} + +sub configure { + my ($self) = shift; + + lock ($error); + + # Restore settings, merge new settings in. + my $save = Configure ($self->{settings}, @_); + + # Restore orig config and save the new config. + $self->{settings} = Configure ($save); +} + +sub getoptions { + my ($self) = shift; + + lock ($error); + + # Restore config settings. + my $save = Configure ($self->{settings}); + + # Call main routine. + my $ret = 0; + $caller = $self->{caller}; + eval { $ret = GetOptions (@_); }; + + # Restore saved settings. + Configure ($save); + + # Handle errors and return value. + die ($@) if $@; + return $ret; +} + +=cut ################ Package return ################ @@ -109,12 +177,12 @@ __END__ ################ AutoLoading subroutines ################ -# RCS Status : $Id: GetoptLongAl.pl,v 2.22 1999-07-07 12:57:05+02 jv Exp $ +# RCS Status : $Id: GetoptLongAl.pl,v 2.25 2000-03-05 21:08:03+01 jv Exp $ # Author : Johan Vromans # Created On : Fri Mar 27 11:50:30 1998 # Last Modified By: Johan Vromans -# Last Modified On: Wed Jul 7 12:47:57 1999 -# Update Count : 28 +# Last Modified On: Sat Mar 4 16:33:02 2000 +# Update Count : 49 # Status : Released sub GetOptions { @@ -123,7 +191,7 @@ sub GetOptions { my $argend = '--'; # option list terminator my %opctl = (); # table of arg.specs (long and abbrevs) my %bopctl = (); # table of arg.specs (bundles) - my $pkg = (caller)[0]; # current context + my $pkg = $caller || (caller)[0]; # current context # Needed if linkage is omitted. my %aliases= (); # alias table my @ret = (); # accum for non-options @@ -138,7 +206,7 @@ sub GetOptions { print STDERR ("GetOpt::Long $Getopt::Long::VERSION ", "called from package \"$pkg\".", "\n ", - 'GetOptionsAl $Revision: 2.22 $ ', + 'GetOptionsAl $Revision: 2.25 $ ', "\n ", "ARGV: (@ARGV)", "\n ", @@ -153,9 +221,9 @@ sub GetOptions { "\n") if $debug; - # Check for ref HASH as first argument. + # Check for ref HASH as first argument. # First argument may be an object. It's OK to use this as long - # as it is really a hash underneath. + # as it is really a hash underneath. $userlinkage = undef; if ( ref($optionlist[0]) and "$optionlist[0]" =~ /^(?:.*\=)?HASH\([^\(]*\)$/ ) { @@ -192,7 +260,7 @@ sub GetOptions { && ref($userlinkage->{$opt}) ) { unshift (@optionlist, $userlinkage->{$opt}); } - unless ( @optionlist > 0 + unless ( @optionlist > 0 && ref($optionlist[0]) && ref($optionlist[0]) eq 'CODE' ) { $error .= "Option spec <> requires a reference to a subroutine\n"; next; @@ -220,7 +288,7 @@ sub GetOptions { # Force an alias if the option name is not locase. $a = $o unless $o eq lc($o); $o = lc ($o) - if $ignorecase > 1 + if $ignorecase > 1 || ($ignorecase && ($bundling ? length($o) > 1 : 1)); @@ -283,7 +351,7 @@ sub GetOptions { $opctl{$o} .= '@' if $opctl{$o} ne '' and $opctl{$o} !~ /\@$/; $bopctl{$o} .= '@' - if $bundling and defined $bopctl{$o} and + if $bundling and defined $bopctl{$o} and $bopctl{$o} ne '' and $bopctl{$o} !~ /\@$/; } elsif ( ref($optionlist[0]) =~ /^(HASH)$/ ) { @@ -291,7 +359,7 @@ sub GetOptions { $opctl{$o} .= '%' if $opctl{$o} ne '' and $opctl{$o} !~ /\%$/; $bopctl{$o} .= '%' - if $bundling and defined $bopctl{$o} and + if $bundling and defined $bopctl{$o} and $bopctl{$o} ne '' and $bopctl{$o} !~ /\%$/; } else { @@ -344,7 +412,8 @@ sub GetOptions { } # Process argument list - while ( @ARGV > 0 ) { + my $goon = 1; + while ( $goon && @ARGV > 0 ) { #### Get next argument #### @@ -356,7 +425,7 @@ sub GetOptions { # Double dash is option list terminator. if ( $opt eq $argend ) { # Finish. Push back accumulated arguments and return. - unshift (@ARGV, @ret) + unshift (@ARGV, @ret) if $order == $PERMUTE; return ($error == 0); } @@ -364,16 +433,16 @@ sub GetOptions { my $tryopt = $opt; my $found; # success status my $dsttype; # destination type ('@' or '%') - my $incr; # destination increment + my $incr; # destination increment my $key; # key (if hash type) my $arg; # option argument - ($found, $opt, $arg, $dsttype, $incr, $key) = - FindOption ($genprefix, $argend, $opt, + ($found, $opt, $arg, $dsttype, $incr, $key) = + FindOption ($genprefix, $argend, $opt, \%opctl, \%bopctl, \@opctl, \%aliases); if ( $found ) { - + # FindOption undefines $opt in case of errors. next unless defined $opt; @@ -414,7 +483,18 @@ sub GetOptions { elsif ( ref($linkage{$opt}) eq 'CODE' ) { print STDERR ("=> &L{$opt}(\"$opt\", \"$arg\")\n") if $debug; - &{$linkage{$opt}}($opt, $arg); + local ($@); + eval { + &{$linkage{$opt}}($opt, $arg); + }; + print STDERR ("=> die($@)\n") if $debug && $@ ne ''; + if ( $@ =~ /^FINISH\b/ ) { + $goon = 0; + } + elsif ( $@ ne '' ) { + warn ($@); + $error++; + } } else { print STDERR ("Invalid REF type \"", ref($linkage{$opt}), @@ -471,7 +551,18 @@ sub GetOptions { # Try non-options call-back. my $cb; if ( (defined ($cb = $linkage{'<>'})) ) { - &$cb ($tryopt); + local ($@); + eval { + &$cb ($tryopt); + }; + print STDERR ("=> die($@)\n") if $debug && $@ ne ''; + if ( $@ =~ /^FINISH\b/ ) { + $goon = 0; + } + elsif ( $@ ne '' ) { + warn ($@); + $error++; + } } else { print STDERR ("=> saving \"$tryopt\" ", @@ -528,7 +619,7 @@ sub FindOption ($$$$$$$) { && $opt =~ /^([^=]+)=(.*)$/s ) { $opt = $1; $optarg = $2; - print STDERR ("=> option \"", $opt, + print STDERR ("=> option \"", $opt, "\", optarg = \"$optarg\"\n") if $debug; } @@ -559,7 +650,7 @@ sub FindOption ($$$$$$$) { $tryopt .= $rest; undef $rest; } - } + } # Try auto-abbreviation. elsif ( $autoabbrev ) { @@ -645,7 +736,7 @@ sub FindOption ($$$$$$$) { ($mand, $type, $dsttype, $key) = $type =~ /^(.)(.)([@%]?)$/; # Check if there is an option argument available. - if ( defined $optarg ? ($optarg eq '') + if ( defined $optarg ? ($optarg eq '') : !(defined $rest || @ARGV > 0) ) { # Complain if this option needs an argument. if ( $mand eq "=" ) { @@ -667,17 +758,17 @@ sub FindOption ($$$$$$$) { # Get key if this is a "name=value" pair for a hash option. $key = undef; if ($dsttype eq '%' && defined $arg) { - ($key, $arg) = ($arg =~ /^(.*)=(.*)$/s) ? ($1, $2) : ($arg, 1); + ($key, $arg) = ($arg =~ /^([^=]*)=(.*)$/s) ? ($1, $2) : ($arg, 1); } #### Check if the argument is valid for this option #### if ( $type eq "s" ) { # string - # A mandatory string takes anything. + # A mandatory string takes anything. return (1, $opt,$arg,$dsttype,$incr,$key) if $mand eq "="; - # An optional string takes almost anything. - return (1, $opt,$arg,$dsttype,$incr,$key) + # An optional string takes almost anything. + return (1, $opt,$arg,$dsttype,$incr,$key) if defined $optarg || defined $rest; return (1, $opt,$arg,$dsttype,$incr,$key) if $arg eq "-"; # ?? @@ -692,12 +783,12 @@ sub FindOption ($$$$$$$) { } elsif ( $type eq "n" || $type eq "i" ) { # numeric/integer - if ( $bundling && defined $rest && $rest =~ /^(-?[0-9]+)(.*)$/s ) { + if ( $bundling && defined $rest && $rest =~ /^([-+]?[0-9]+)(.*)$/s ) { $arg = $1; $rest = $2; unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne ''; } - elsif ( $arg !~ /^-?[0-9]+$/ ) { + elsif ( $arg !~ /^[-+]?[0-9]+$/ ) { if ( defined $optarg || $mand eq "=" ) { if ( $passthrough ) { unshift (@ARGV, defined $rest ? $starter.$rest : $arg) @@ -725,12 +816,12 @@ sub FindOption ($$$$$$$) { # and at least one digit following the point and 'e'. # [-]NN[.NN][eNN] if ( $bundling && defined $rest && - $rest =~ /^(-?[0-9]+(\.[0-9]+)?([eE]-?[0-9]+)?)(.*)$/s ) { + $rest =~ /^([-+]?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?)(.*)$/s ) { $arg = $1; $rest = $+; unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne ''; } - elsif ( $arg !~ /^-?[0-9.]+(\.[0-9]+)?([eE]-?[0-9]+)?$/ ) { + elsif ( $arg !~ /^[-+]?[0-9.]+(\.[0-9]+)?([eE][-+]?[0-9]+)?$/ ) { if ( defined $optarg || $mand eq "=" ) { if ( $passthrough ) { unshift (@ARGV, defined $rest ? $starter.$rest : $arg) @@ -761,6 +852,18 @@ sub FindOption ($$$$$$$) { # Getopt::Long Configuration. sub Configure (@) { my (@options) = @_; + + my $prevconfig = + [ $error, $debug, $major_version, $minor_version, + $autoabbrev, $getopt_compat, $ignorecase, $bundling, $order, + $passthrough, $genprefix ]; + + if ( ref($options[0]) eq 'ARRAY' ) { + ( $error, $debug, $major_version, $minor_version, + $autoabbrev, $getopt_compat, $ignorecase, $bundling, $order, + $passthrough, $genprefix ) = @{shift(@options)}; + } + my $opt; foreach $opt ( @options ) { my $try = lc ($opt); @@ -809,7 +912,7 @@ sub Configure (@) { elsif ( $try =~ /^prefix_pattern=(.+)$/ ) { $genprefix = $1; # Parenthesize if needed. - $genprefix = "(" . $genprefix . ")" + $genprefix = "(" . $genprefix . ")" unless $genprefix =~ /^\(.*\)$/; eval { '' =~ /$genprefix/; }; Croak ("Getopt::Long: invalid pattern \"$genprefix\"") if $@; @@ -821,6 +924,7 @@ sub Configure (@) { Croak ("Getopt::Long: unknown config parameter \"$opt\"") } } + $prevconfig; } # Deprecated name. @@ -839,7 +943,7 @@ sub Croak (@) { =head1 NAME -GetOptions - extended processing of command line options +Getopt::Long - Extended processing of command line options =head1 SYNOPSIS @@ -854,353 +958,544 @@ 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" +but not enabled by default. + +=head1 Command Line Options, an Introduction + +Command line operated programs traditionally take their arguments from +the command line, for example filenames or other information that the +program needs to know. Besides arguments, these programs often take +command line I as well. Options are not necessary for the +program to work, hence the name 'option', but are used to modify its +default behaviour. For example, a program could do its job quietly, +but with a suitable option it could provide verbose information about +what it did. + +Command line options come in several flavours. Historically, they are +preceded by a single dash C<->, and consist of a single letter. + + -l -a -c + +Usually, these single-character options can be bundled: + + -lac + +Options can have values, the value is placed after the option +character. Sometimes with whitespace in between, sometimes not: + + -s 24 -s24 + +Due to the very cryptic nature of these options, another style was +developed that used long names. So instead of a cryptic C<-l> one +could use the more descriptive C<--long>. To distinguish between a +bundle of single-character options and a long one, two dashes are used +to precede the option name. Early implementations of long options used +a plus C<+> instead. Also, option values could be specified either +like + + --size=24 + +or + + --size 24 + +The C<+> form is now obsolete and strongly deprecated. + +=head1 Getting Started with Getopt::Long + +Getopt::Long is the Perl5 successor of C. This was +the firs Perl module that provided support for handling the new style +of command line options, hence the name Getopt::Long. This module +also supports single-character options and bundling. In this case, the +options are restricted to alphabetic characters only, and the +characters C and C<->. + +To use Getopt::Long from a Perl program, you must include the +following line in your Perl program: + + use Getopt::Long; + +This will load the core of the Getopt::Long module and prepare your +program for using it. Most of the actual Getopt::Long code is not +loaded until you really call one of its functions. + +In the default configuration, options names may be abbreviated to +uniqueness, case does not matter, and a single dash is sufficient, +even for long option names. Also, options may be placed between +non-option arguments. See L for more +details on how to configure Getopt::Long. + +=head2 Simple options + +The most simple options are the ones that take no values. Their mere +presence on the command line enables the option. Popular examples are: + + --all --verbose --quiet --debug + +Handling simple options is straightforward: + + my $verbose = ''; # option variable with default value (false) + my $all = ''; # option variable with default value (false) + GetOptions ('verbose' => \$verbose, 'all' => \$all); + +The call to GetOptions() parses the command line arguments that are +present in C<@ARGV> and sets the option variable to the value C<1> if +the option did occur on the command line. Otherwise, the option +variable is not touched. Setting the option value to true is often +called I the option. + +The option name as specified to the GetOptions() function is called +the option I. Later we'll see that this specification +can contain more than just the option name. The reference to the +variable is called the option I. + +GetOptions() will return a true value if the command line could be +processed successfully. Otherwise, it will write error messages to +STDERR, and return a false result. + +=head2 A little bit less simple options + +Getopt::Long supports two useful variants of simple options: +I options and I options. + +A negatable option is specified with a exclamation mark C after the +option name: + + my $verbose = ''; # option variable with default value (false) + GetOptions ('verbose!' => \$verbose); + +Now, using C<--verbose> on the command line will enable C<$verbose>, +as expected. But it is also allowed to use C<--noverbose>, which will +disable C<$verbose> by setting its value to C<0>. Using a suitable +default value, the program can find out whether C<$verbose> is false +by default, or disabled by using C<--noverbose>. + +An incremental option is specified with a plus C<+> after the +option name: + + my $verbose = ''; # option variable with default value (false) + GetOptions ('verbose+' => \$verbose); + +Using C<--verbose> on the command line will increment the value of +C<$verbose>. This way the program can keep track of how many times the +option occurred on the command line. For example, each occurrence of +C<--verbose> could increase the verbosity level of the program. + +=head2 Mixing command line option with other arguments + +Usually programs take command line options as well as other arguments, +for example, file names. It is good practice to always specify the +options first, and the other arguments last. Getopt::Long will, +however, allow the options and arguments to be mixed and 'filter out' +all the options before passing the rest of the arguments to the +program. To stop Getopt::Long from processing further arguments, +insert a double dash C<--> on the command line: + + --size 24 -- --all + +In this example, C<--all> will I be treated as an option, but +passed to the program unharmed, in C<@ARGV>. + +=head2 Options with values + +For options that take values it must be specified whether the option +value is required or not, and what kind of value the option expects. + +Three kinds of values are supported: integer numbers, floating point +numbers, and strings. + +If the option value is required, Getopt::Long will take the +command line argument that follows the option and assign this to the +option variable. If, however, the option value is specified as +optional, this will only be done if that value does not look like a +valid command line option itself. - -vax + my $tag = ''; # option variable with default value + GetOptions ('tag=s' => \$tag); -which means the combination of B<-v>, B<-a> and B<-x>. With the new -syntax B<--vax> would be a single option, probably indicating a -computer architecture. +In the option specification, the option name is followed by an equals +sign C<=> and the letter C. The equals sign indicates that this +option requires a value. The letter C indicates that this value is +an arbitrary string. Other possible value types are C for integer +values, and C for floating point values. Using a colon C<:> instead +of the equals sign indicates that the option value is optional. In +this case, if no suitable value is supplied, string valued options get +an empty string C<''> assigned, while numeric options are set to C<0>. -Command line options can be used to set values. These values can be -specified in one of two ways: +=head2 Options with multiple values - --size 24 - --size=24 +Options sometimes take several values. For example, a program could +use multiple directories to search for library files: -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: + --library lib/stdlib --library lib/extlib - GetOptions("size=i" => \$offset); +To accomplish this behaviour, simply specify an array reference as the +destination for the option: -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. + my @libfiles = (); + GetOptions ("library=s" => \@libfiles); -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: +Used with the example above, C<@libfiles> would contain two strings +upon completion: C<"lib/srdlib"> and C<"lib/extlib">, in that order. +It is also possible to specify that only integer or floating point +numbers are acceptible values. - %optctl = ("size" => \$offset); - GetOptions(\%optctl, "size=i"); +Often it is useful to allow comma-separated lists of values as well as +multiple occurrences of the options. This is easy using Perl's split() +and join() operators: -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. + my @libfiles = (); + GetOptions ("library=s" => \@libfiles); + @libfiles = split(/,/,join(',',@libfiles)); -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. +Of course, it is important to choose the right separator string for +each purpose. -Each option specifier designates the name of the option, optionally -followed by an argument specifier. +=head2 Options with hash values -Options that do not take arguments will have no argument specifier. -The option variable will be set to 1 if the option is used. +If the option destination is a reference to a hash, the option will +take, as value, strings of the form IC<=>I. The value will +be stored with the specified key in the hash. -For the other options, the values for argument specifiers are: + my %defines = (); + GetOptions ("define=s" => \%defines); -=over 8 +When used with command line options: + + --define os=linux --define vendor=redhat + +the hash C<%defines> will contain two keys, C<"os"> with value +C<"linux> and C<"vendor"> with value C<"redhat">. +It is also possible to specify that only integer or floating point +numbers are acceptible values. The keys are always taken to be strings. + +=head2 User-defined subroutines to handle options + +Ultimate control over what should be done when (actually: each time) +an option is encountered on the command line can be achieved by +designating a reference to a subroutine (or an anonymous subroutine) +as the option destination. When GetOptions() encounters the option, it +will call the subroutine with two arguments: the name of the option, +and the value to be assigned. It is up to the subroutine to store the +value, or do whatever it thinks is appropriate. + +A trivial application of this mechanism is to implement options that +are related to each other. For example: + + my $verbose = ''; # option variable with default value (false) + GetOptions ('verbose' => \$verbose, + 'quiet' => sub { $verbose = 0 }); + +Here C<--verbose> and C<--quiet> control the same variable +C<$verbose>, but with opposite values. + +If the subroutine needs to signal an error, it should call die() with +the desired error message as its argument. GetOptions() will catch the +die(), issue the error message, and record that an error result must +be returned upon completion. + +It is also possible for a user-defined subroutine to preliminary +terminate options processing by calling die() with argument +C<"FINISH">. GetOptions will react as if it encountered a double dash +C<-->. + +=head2 Options with multiple names + +Often it is user friendly to supply alternate mnemonic names for +options. For example C<--height> could be an alternate name for +C<--length>. Alternate names can be included in the option +specification, separated by vertical bar C<|> characters. To implement +the above example: + + GetOptions ('length|height=f' => \$length); + +The first name is called the I name, the other names are +called I. + +Multiple alternate names are possible. + +=head2 Case and abbreviations + +Without additional configuration, GetOptions() will ignore the case of +option names, and allow the options to be abbreviated to uniqueness. + + GetOptions ('length|height=f' => \$length, "head" => \$head); + +This call will allow C<--l> and C<--L> for the length option, but +requires a least C<--hea> and C<--hei> for the head and height options. + +=head2 Summary of Option Specifications + +Each option specifier consists of two parts: the name specification +and the argument specification. + +The name specification contains the name of the option, optionally +followed by a list of alternative names separated by vertical bar +characters. + + length option name is "length" + length|size|l name is "length", aliases are "size" and "l" + +The argument specification is optional. If omitted, the option is +considered boolean, a value of 1 will be assigned when the option is +used on the command line. + +The argument specification can be + +=over =item ! -Option does not take an argument and may be negated, i.e. prefixed by -"no". E.g. "foo!" will allow B<--foo> (with value 1) and B<-nofoo> -(with value 0). -The option variable will be set to 1, or 0 if negated. +The option does not take an argument and may be negated, i.e. prefixed +by "no". E.g. C<"foo!"> will allow C<--foo> (a value of 1 will be +assigned) and C<--nofoo> (a value of 0 will be assigned). =item + -Option does not take an argument and will be incremented by 1 every -time it appears on the command line. E.g. "more+", when used with -B<--more --more --more>, will set the option variable to 3 (provided -it was 0 or undefined at first). +The option does not take an argument and will be incremented by 1 +every time it appears on the command line. E.g. C<"more+">, when used +with C<--more --more --more>, will increment the value three times, +resulting in a value of 3 (provided it was 0 or undefined at first). -The B<+> specifier is ignored if the option destination is not a SCALAR. +The C<+> specifier is ignored if the option destination is not a scalar. -=item =s +=item = I [ I ] -Option takes a mandatory string argument. -This string will be assigned to the option variable. -Note that even if the string argument starts with B<-> or B<-->, it -will not be considered an option on itself. +The option requires an argument of the given type. Supported types +are: -=item :s +=over -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 B<-> or B<-->, it -will be considered an option on itself. +=item s -=item =i +String. An arbitrary sequence of characters. It is valid for the +argument to start with C<-> or C<-->. -Option takes a mandatory integer argument. -This value will be assigned to the option variable. -Note that the value may start with B<-> to indicate a negative -value. +=item i -=item :i +Integer. An optional leading plus or minus sign, followed by a +sequence of digits. -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 B<-> to indicate a negative -value. +=item f -=item =f +Real number. For example C<3.14>, C<-6.23E24> and so on. -Option takes a mandatory real number argument. -This value will be assigned to the option variable. -Note that the value may start with B<-> to indicate a negative -value. +=back + +The I can be C<@> or C<%> to specify that the option is +list or a hash valued. This is only needed when the destination for +the option value is not otherwise specified. It should be omitted when +not needed. + +=item : I [ I ] -=item :f +Like C<=>, but designates the argument as optional. +If omitted, an empty string will be assigned to string values options, +and the value zero to numeric options. -Option takes an optional real number argument. -This value will be assigned to the option variable. -If omitted, the value 0 will be assigned. +Note that if a string argument starts with C<-> or C<-->, it will be +considered an option on itself. =back -A lone dash B<-> is considered an option, the corresponding option -name is the empty string. +=head1 Advanced Possibilities -A double dash on itself B<--> signals end of the options list. +=head2 Documentation and help texts -=head2 Linkage specification +Getopt::Long encourages the use of Pod::Usage to produce help +messages. For example: -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: + use Getopt::Long; + use Pod::Usage; - %optctl = (); - GetOptions (\%optctl, "size=i"); + my $man = 0; + my $help = 0; -will perform the equivalent of the assignment + GetOptions('help|?' => \$help, man => \$man) or pod2usage(2); + pod2usage(1) if $help; + pod2usage(-exitstatus => 0, -verbose => 2) if $man; - $optctl{"size"} = 24; + __END__ -For array options, a reference to an array is used, e.g.: + =head1 NAME - %optctl = (); - GetOptions (\%optctl, "sizes=i@"); + sample - Using GetOpt::Long and Pod::Usage -with command line "-sizes 24 -sizes 48" will perform the equivalent of -the assignment + =head1 SYNOPSIS - $optctl{"sizes"} = [24, 48]; + sample [options] [file ...] -For hash options (an option whose argument looks like "name=value"), -a reference to a hash is used, e.g.: + Options: + -help brief help message + -man full documentation - %optctl = (); - GetOptions (\%optctl, "define=s%"); + =head1 OPTIONS -with command line "--define foo=hello --define bar=world" will perform the -equivalent of the assignment + =over 8 - $optctl{"define"} = {foo=>'hello', bar=>'world') + =item B<-help> -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 B
. -For example: + Print a brief help message and exits. - GetOptions ("size=i", "sizes=i@"); + =item B<-man> -with command line "-size 10 -sizes 24 -sizes 48" will perform the -equivalent of the assignments + Prints the manual page and exits. - $opt_size = 10; - @opt_sizes = (24, 48); + =back -A lone dash B<-> is considered an option, the corresponding Perl -identifier is $opt_ . + =head1 DESCRIPTION -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. + B will read the given input file(s) and do someting + useful with the contents thereof. -Note that, if your code is running under the recommended C pragma, it may be helpful to declare these package variables -via C perhaps something like this: + =cut - use vars qw/ $opt_size @opt_sizes $opt_bar /; +See L for details. -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. +=head2 Storing options in a hash -If a REF ARRAY is supplied, the new value is appended (pushed) to the -referenced array. +Sometimes, for example when there are a lot of options, having a +separate variable for each of them can be cumbersome. GetOptions() +supports, as an alternative mechanism, storing options in a hash. -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". +To obtain this, a reference to a hash must be passed I to GetOptions(). For each option that is specified on the +command line, the option value will be stored in the hash with the +option name as key. Options that are not actually used on the command +line will not be put in the hash, on other words, +C (or defined()) can be used to test if an option +was used. The drawback is that warnings will be issued if the program +runs under C and uses C<$h{option}> without testing with +exists() or defined() first. -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. + my %h = (); + GetOptions (\%h, 'length=i'); # will store in $h{length} -=head2 Aliases and abbreviations +For options that take list or hash values, it is necessary to indicate +this by appending an C<@> or C<%> sign after the type: -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. For convenience, the single character -"?" is allowed as an alias, e.g. "help|?". + GetOptions (\%h, 'colours=s@'); # will push to @{$h{colours}} -Option names may be abbreviated to uniqueness, depending on -configuration option B. +To make things more complicated, the hash may contain references to +the actual destinations, for example: -=head2 Non-option call-back routine + my $len = 0; + my %h = ('length' => \$len); + GetOptions (\%h, 'length=i'); # will store in $len -A special option specifier, EE, 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 B, see section -CONFIGURATION OPTIONS. +This example is fully equivalent with: -See also the examples. + my $len = 0; + GetOptions ('length=i' => \$len); # will store in $len -=head2 Option starters +Any mixture is possible. For example, the most frequently used options +could be stored in variables while all other options get stored in the +hash: -On the command line, options can start with B<-> (traditional), B<--> -(POSIX) and B<+> (GNU, now being phased out). The latter is not -allowed if the environment variable B has been -defined. + my $verbose = 0; # frequently referred + my $debug = 0; # frequently referred + my %h = ('verbose' => \$verbose, 'debug' => \$debug); + GetOptions (\%h, 'verbose', 'debug', 'filter', 'size=i'); + if ( $verbose ) { ... } + if ( exists $h{filter} ) { ... option 'filter' was specified ... } -Options that start with "--" may have an argument appended, separated -with an "=", e.g. "--foo=bar". +=head2 Bundling -=head2 Return values and Errors +With bundling it is possible to set several single-character options +at once. For example if C, C and C are all valid options, -Configuration errors and errors in the option definitions are -signalled using C and will terminate the calling -program unless the call to C was embedded -in C or C was trapped using C<$SIG{__DIE__}>. + -vax -A return value of 1 (true) indicates success. +would set all three. -A return status of 0 (false) indicates that the function detected one -or more errors during option parsing. These errors are signalled using -C and can be trapped with C<$SIG{__WARN__}>. +Getopt::Long supports two levels of bundling. To enable bundling, a +call to Getopt::Long::Configure is required. -Errors that can't happen are signalled using C. +The first level of bundling can be enabled with: -=head1 COMPATIBILITY + Getopt::Long::Configure ("bundling"); -Getopt::Long::GetOptions() is the successor of -B 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. +Configured this way, single-character options can be bundled but long +options B always start with a double dash C<--> to avoid +abiguity. For example, when C, C, C and C are all valid +options, -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. + -vax -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. +would set C, C and C, but -If configuration option B 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. + --vax -If the first argument to GetOptions (after the optional linkage -specification) 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. GetOptions will not interpret a leading -"<>" as option starters if the next argument is a reference. To -force "<" and ">" as option starters, use "><". Confusing? Well, -B +would set C. -For convenience, option specifiers may have a leading B<-> or B<-->, -so it is possible to write: +The second level of bundling lifts this restriction. It can be enabled +with: - GetOptions qw(-foo=s --bar=i --ar=s); + Getopt::Long::Configure ("bundling_override"); -=head1 EXAMPLES +Now, C<-vax> would set the option C. -If the option specifier is "one:i" (i.e. takes an optional integer -argument), then the following situations are handled: +When any level of bundling is enabled, option values may be inserted +in the bundle. For example: - -one -two -> $opt_one = '', -two is next option - -one -2 -> $opt_one = -2 + -h24w80 -Also, assume specifiers "foo=s" and "bar:s" : +is equivalent to - -bar -xxx -> $opt_bar = '', '-xxx' is next option - -foo -bar -> $opt_foo = '-bar' - -foo -- -> $opt_foo = '--' + -h 24 -w 80 -In GNU or POSIX format, option names and values can be combined: +When configured for bundling, single-character options are matched +case sensitive while long options are matched case insensitive. To +have the single-character options matched case insensitive as well, +use: - +foo=blech -> $opt_foo = 'blech' - --bar= -> $opt_bar = '' - --bar=-- -> $opt_bar = '--' + Getopt::Long::Configure ("bundling", "ignorecase_always"); -Example of using variable references: +It goes without saying that bundling can be quite confusing. - $ret = GetOptions ('foo=s', \$foo, 'bar=i', 'ar=s', \@ar); +=head2 The lonesome dash -With command line options "-foo blech -bar 24 -ar xx -ar yy" -this will result in: +Some applications require the option C<-> (that's a lone dash). This +can be achieved by adding an option specification with an empty name: - $foo = 'blech' - $opt_bar = 24 - @ar = ('xx','yy') + GetOptions ('' => \$stdio); -Example of using the EE option specifier: +A lone dash on the command line will now be legal, and set options +variable C<$stdio>. - @ARGV = qw(-foo 1 bar -foo 2 blech); - GetOptions("foo=i", \$myfoo, "<>", \&mysub); +=head2 Argument call-back -Results: +A special option 'name' C<<>> can be used to designate a subroutine +to handle non-option arguments. When GetOptions() encounters an +argument that does not look like an option, it will immediately call this +subroutine and passes it the argument as a parameter. - mysub("bar") will be called (with $myfoo being 1) - mysub("blech") will be called (with $myfoo being 2) +For example: -Compare this with: + my $width = 80; + sub process { ... } + GetOptions ('width=i' => \$width, '<>' => \&process); - @ARGV = qw(-foo 1 bar -foo 2 blech); - GetOptions("foo=i", \$myfoo); +When applied to the following command line: -This will leave the non-options in @ARGV: + arg1 --width=72 arg2 --width=60 arg3 - $myfoo -> 2 - @ARGV -> qw(bar blech) +This will call +C while C<$width> is C<80>, +C while C<$width> is C<72>, and +C while C<$width> is C<60>. -=head1 CONFIGURATION OPTIONS +This feature requires configuration option B, see section +L. -B can be configured by calling subroutine -B. This subroutine takes a list of quoted -strings, each specifying a configuration option to be set, e.g. -B. Options can be reset by prefixing with B, e.g. -B. Case does not matter. Multiple calls to B -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 B routine. Besides, it -is much easier. +=head1 Configuring Getopt::Long + +Getopt::Long 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. +C, or reset, e.g. C. Case does not +matter. Multiple calls to Configure() are possible. The following options are available: @@ -1215,122 +1510,102 @@ default values. Allow option names to be abbreviated to uniqueness. Default is set unless environment variable -POSIXLY_CORRECT has been set, in which case B is reset. +POSIXLY_CORRECT has been set, in which case C is reset. -=item getopt_compat +=item getopt_compat -Allow '+' to start options. +Allow C<+> to start options. Default is set unless environment variable -POSIXLY_CORRECT has been set, in which case B is reset. +POSIXLY_CORRECT has been set, in which case C is reset. =item require_order -Whether non-options are allowed to be mixed with -options. +Whether command line arguments are allowed to be mixed with options. Default is set unless environment variable -POSIXLY_CORRECT has been set, in which case b is reset. +POSIXLY_CORRECT has been set, in which case C is reset. -See also B, which is the opposite of B. +See also C, which is the opposite of C. =item permute -Whether non-options are allowed to be mixed with -options. +Whether command line arguments are allowed to be mixed with options. Default is set unless environment variable -POSIXLY_CORRECT has been set, in which case B is reset. -Note that B is the opposite of B. +POSIXLY_CORRECT has been set, in which case C is reset. +Note that C is the opposite of C. -If B is set, this means that +If C is set, this means that - -foo arg1 -bar arg2 arg3 + --foo arg1 --bar arg2 arg3 is equivalent to - -foo -bar arg1 arg2 arg3 + --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 B<--> is used: +If an argument call-back routine is specified, C<@ARGV> will always be +empty upon succesful return of GetOptions() since all options have been +processed. The only exception is when C<--> is used: - -foo arg1 -bar arg2 -- arg3 + --foo arg1 --bar arg2 -- arg3 will call the call-back routine for arg1 and arg2, and terminate -leaving arg2 in @ARGV. +GetOptions() leaving C<"arg2"> in C<@ARGV>. -If B is set, options processing +If C is set, options processing terminates when the first non-option is encountered. - -foo arg1 -bar arg2 arg3 + --foo arg1 --bar arg2 arg3 is equivalent to - -foo -- arg1 -bar arg2 arg3 + --foo -- arg1 --bar arg2 arg3 =item 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 B<--> and single-character -options (and bundles) with B<->. 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; for strings -this value is the rest of the bundle, but integer and floating values -may be combined in the bundle, e.g. +Setting this option will allow single-character options to be bundled. +To distinguish bundles from long option names, long options I be +introduced with C<--> and single-character options (and bundles) with +C<->. - scale -h24w80 - -is equivalent to - - scale -h 24 -w 80 - -Note: resetting B also resets B. +Note: resetting C also resets C. =item bundling_override (default: reset) -If B is set, bundling is enabled as with -B but now long option names override option bundles. In the -above example, B<-vax> would be interpreted as the option "vax", not -the bundle "v", "a", "x". +If C is set, bundling is enabled as with +C but now long option names override option bundles. -Note: resetting B also resets B. +Note: resetting C also resets C. B Using option bundling can easily lead to unexpected results, especially when mixing long options and bundles. Caveat emptor. =item ignore_case (default: set) -If set, case is ignored when matching options. +If set, case is ignored when matching long option names. Single +character options will be treated case-sensitive. -Note: resetting B also resets B. +Note: resetting C also resets C. =item ignore_case_always (default: reset) When bundling is in effect, case is ignored on single-character options also. -Note: resetting B also resets B. +Note: resetting C also resets C. =item 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 +Options that are unknown, ambiguous or supplied with an invalid option +value are passed through in C<@ARGV> instead of being flagged as +errors. This makes it possible to write wrapper scripts that process +only part of the user supplied command line arguments, and pass the remaining options to some other program. -This can be very confusing, especially when B is also set. +This can be very confusing, especially when C is also set. =item prefix -The string that starts options. See also B. +The string that starts options. If a constant string is not +sufficient, see C. =item prefix_pattern @@ -1344,27 +1619,84 @@ Enable copious debugging output. =back -=head1 OTHER USEFUL VARIABLES +=head1 Return values and Errors -=over 12 +Configuration errors and errors in the option definitions are +signalled using die() and will terminate the calling program unless +the call to Getopt::Long::GetOptions() was embedded in C, or die() was trapped using C<$SIG{__DIE__}>. -=item $Getopt::Long::VERSION +A return value of 1 (true) indicates success. -The version number of this Getopt::Long implementation in the format -C.C. This can be used to have Exporter check the -version, e.g. +A return status of 0 (false) indicates that the function detected one +or more errors during option parsing. These errors are signalled using +warn() and can be trapped with C<$SIG{__WARN__}>. - use Getopt::Long 3.00; +Errors that can't happen are signalled using Carp::croak(). -You can inspect $Getopt::Long::major_version and -$Getopt::Long::minor_version for the individual components. +=head1 Legacy -=item $Getopt::Long::error +The earliest development of C started in 1990, with Perl +version 4. As a result, its development, and the development of +Getopt::Long, has gone through several stages. Since backward +compatibility has always been extremely important, the current version +of Getopt::Long still supports a lot of constructs that nowadays are +no longer necessary or otherwise unwanted. This section describes +briefly some of these 'features'. -Internal error flag. May be incremented from a call-back routine to -cause options parsing to fail. +=head2 Default destinations -=back +When no destination is specified for an option, GetOptions will store +the resultant value in a global variable named CI, where +I is the primary name of this option. When a progam executes +under C (recommended), these variables must be +pre-declared with our() or C. + + our $opt_length = 0; + GetOptions ('length=i'); # will store in $opt_length + +To yield a usable Perl variable, characters that are not part of the +syntax for variables are translated to underscores. For example, +C<--fpp-struct-return> will set the variable +C<$opt_fpp_struct_return>. Note that this variable resides in the +namespace of the calling program, not necessarily C
. 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); + +=head2 Alternative option starters + +A string of alternative option starter characters may be passed as the +first argument (or the first argument after a leading hash reference +argument). + + my $len = 0; + GetOptions ('/', 'length=i' => $len); + +Now the command line may look like: + + /length 24 -- arg + +Note that to terminate options processing still requires a double dash +C<-->. + +GetOptions() will not interpret a leading C<"<>"> as option starters +if the next argument is a reference. To force C<"<"> and C<">"> as +option starters, use C<"><">. Confusing? Well, B anyway. + +=head2 Configuration variables + +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 C routine. Besides, it +is much easier. =head1 AUTHOR @@ -1372,7 +1704,7 @@ Johan Vromans Ejvromans@squirrel.nlE =head1 COPYRIGHT AND DISCLAIMER -This program is Copyright 1990,1999 by Johan Vromans. +This program is Copyright 2000,1990 by Johan Vromans. This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License or the GNU General Public License as published by the Free Software @@ -1389,3 +1721,8 @@ the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. =cut + +# Local Variables: +# mode: perl +# eval: (load-file "pod.el") +# End: