lib/getcwd.pl A getcwd() emulator
lib/getopt.pl Perl library supporting option parsing
lib/Getopt/Long.pm Fetch command options (GetOptions)
+lib/Getopt/Long/CHANGES Getopt::Long changes
+lib/Getopt/Long/README Getopt::Long README
lib/Getopt/Long/t/basic.t See if Getopt::Long works
lib/Getopt/Long/t/compat.t See if Getopt::Long works
lib/Getopt/Long/t/linkage.t See if Getopt::Long works
package Getopt::Long;
-# RCS Status : $Id: GetoptLong.pl,v 2.26 2001-01-31 10:20:29+01 jv Exp $
+# RCS Status : $Id: GetoptLong.pl,v 2.28 2001-08-05 18:41:09+02 jv Exp $
# Author : Johan Vromans
# Created On : Tue Sep 11 15:00:12 1990
# Last Modified By: Johan Vromans
-# Last Modified On: Sat Jan 6 17:12:27 2001
-# Update Count : 748
+# Last Modified On: Sun Aug 5 18:41:06 2001
+# Update Count : 751
# Status : Released
################ Copyright ################
use strict;
use vars qw($VERSION $VERSION_STRING);
-$VERSION = 2.25;
-$VERSION_STRING = "2.25";
+$VERSION = 2.26;
+# For testing versions only.
+#$VERSION_STRING = "2.25_13";
use Exporter;
use AutoLoader qw(AUTOLOAD);
################ AutoLoading subroutines ################
-# RCS Status : $Id: GetoptLongAl.pl,v 2.30 2001-01-31 10:21:11+01 jv Exp $
+package Getopt::Long;
+
+use strict;
+
+# RCS Status : $Id: GetoptLongAl.pl,v 2.34 2001-08-05 18:42:45+02 jv Exp $
# Author : Johan Vromans
# Created On : Fri Mar 27 11:50:30 1998
# Last Modified By: Johan Vromans
-# Last Modified On: Tue Dec 26 18:01:16 2000
-# Update Count : 98
+# Last Modified On: Sat Aug 4 17:32:13 2001
+# Update Count : 128
# Status : Released
sub GetOptions {
print STDERR ("GetOpt::Long $Getopt::Long::VERSION ",
"called from package \"$pkg\".",
"\n ",
- 'GetOptionsAl $Revision: 2.30 $ ',
+ 'GetOptionsAl $Revision: 2.34 $ ',
"\n ",
"ARGV: (@ARGV)",
"\n ",
# First argument may be an object. It's OK to use this as long
# as it is really a hash underneath.
$userlinkage = undef;
- if ( ref($optionlist[0]) and
+ if ( @optionlist && ref($optionlist[0]) and
"$optionlist[0]" =~ /^(?:.*\=)?HASH\([^\(]*\)$/ ) {
$userlinkage = shift (@optionlist);
print STDERR ("=> user linkage: $userlinkage\n") if $debug;
# See if the first element of the optionlist contains option
# starter characters.
# Be careful not to interpret '<>' as option starters.
- if ( $optionlist[0] =~ /^\W+$/
+ if ( @optionlist && $optionlist[0] =~ /^\W+$/
&& !($optionlist[0] eq '<>'
&& @optionlist > 0
&& ref($optionlist[1])) ) {
# Verify correctness of optionlist.
%opctl = ();
%bopctl = ();
- while ( @optionlist > 0 ) {
+ while ( @optionlist ) {
my $opt = shift (@optionlist);
# Strip leading prefix so people can specify "--foo=i" if they like.
}
# Match option spec. Allow '?' as an alias only.
- if ( $opt !~ /^((\w+[-\w]*)(\|(\?|\w[-\w]*)?)*)?([!~+]|[=:][infse][@%]?)?$/ ) {
+ if ( $opt !~ /^((\w+[-\w]*)(\|(\?|\w[-\w]*)?)*)?([!~+]|[=:][ionfse][@%]?)?$/ ) {
$error .= "Error in option spec: \"$opt\"\n";
next;
}
$_ = lc ($_) if $ignorecase > 1;
if ( $c eq '!' ) {
$opctl{"no$_"} = $c;
- warn ("Ignoring '!' modifier for short option $_\n");
+ # warn ("Ignoring '!' modifier for short option $_\n");
$opctl{$_} = $bopctl{$_} = '';
}
else {
my $rest = undef; # remainder from unbundling
# If it is a long option, it may include the value.
- if (($starter eq "--" || ($getopt_compat && !$bundling))
- && $opt =~ /^([^=]+)=(.*)$/s ) {
+ # With getopt_compat, not if bundling.
+ if ( ($starter eq "--"
+ || ($getopt_compat && ($bundling == 0 || $bundling == 2)))
+ && $opt =~ /^([^=]+)=(.*)$/s ) {
$opt = $1;
$optarg = $2;
print STDERR ("=> option \"", $opt,
}
}
- elsif ( $type eq "n" || $type eq "i" ) { # numeric/integer
- if ( $bundling && defined $rest && $rest =~ /^([-+]?[0-9]+)(.*)$/s ) {
+ elsif ( $type eq "n" || $type eq "i" # numeric/integer
+ || $type eq "o" ) { # dec/oct/hex/bin value
+
+ my $o_valid =
+ $type eq "o" ? "[-+]?[1-9][0-9]*|0x[0-9a-f]+|0b[01]+|0[0-7]*"
+ : "[-+]?[0-9]+";
+
+ if ( $bundling && defined $rest && $rest =~ /^($o_valid)(.*)$/si ) {
$arg = $1;
$rest = $2;
+ $arg = ($type eq "o" && $arg =~ /^0/) ? oct($arg) : 0+$arg;
unshift (@ARGV, $starter.$rest) if defined $rest && $rest ne '';
}
- elsif ( $arg !~ /^[-+]?[0-9]+$/ ) {
+ elsif ( $arg =~ /^($o_valid)$/si ) {
+ $arg = ($type eq "o" && $arg =~ /^0/) ? oct($arg) : 0+$arg;
+ }
+ else {
if ( defined $optarg || $mand eq "=" ) {
if ( $passthrough ) {
unshift (@ARGV, defined $rest ? $starter.$rest : $arg)
return (0);
}
warn ("Value \"", $arg, "\" invalid for option ",
- $opt, " (number expected)\n");
+ $opt, " (",
+ $type eq "o" ? "extended " : "",
+ "number expected)\n");
$error++;
undef $opt;
# Push back.
=head1 SYNOPSIS
use Getopt::Long;
- $result = GetOptions (...option-descriptions...);
+ my $data = "file.dat";
+ my $length = 24;
+ my $verbose;
+ $result = GetOptions ("length=i" => \$length, # numeric
+ "file=s" => \$data, # string
+ "verbose" => \$verbose); # flag
=head1 DESCRIPTION
Integer. An optional leading plus or minus sign, followed by a
sequence of digits.
+=item o
+
+Extended integer, Perl style. This can be either an optional leading
+plus or minus sign, followed by a sequence of digits, or an octal
+string (a zero, optionally followed by '0', '1', .. '7'), or a
+hexadecimal string (C<0x> followed by '0' .. '9', 'a' .. 'f', case
+insensitive), or a binary string (C<0b> followed by a series of '0'
+and '1').
+
=item f
Real number. For example C<3.14>, C<-6.23E24> and so on.
=cut
-# Local Variables:
-# eval: (load-file "pod.el")
-# End:
--- /dev/null
+Changes in version 2.26
+-----------------------
+
+* New option type: 'o'. It accepts all kinds of integral numbers in
+ Perl style, including decimal (24), octal (012), hexadecimal (0x2f)
+ and binary (0b1001).
+
+* Fix problem with getopt_compat not matching +foo=bar.
+
+* Remove $VERSION_STRING for production versions.
+
+Changes in version 2.26
+-----------------------
+
+* New option type: 'o'. It accepts all kinds of integral numbers in
+ Perl style, including decimal (24), octal (012), hexadecimal (0x2f)
+ and binary (0b1001).
+
+* Fix problem with getopt_compat not matching +foo=bar.
+
+* Remove $VERSION_STRING for production versions.
+
+Changes in version 2.25
+-----------------------
+
+* Change handling of a lone "-" on the command line. It will now be
+ treated as a non-option unless an explicit specification was passed
+ to GetOptions. See the manual.
+ In the old implementation an error was signalled, so no
+ compatibility breaks are expected from this change.
+
+* Add $VERSION_STRING. This is the string form of $VERSION. Usually
+ they are identical, unless it is a pre-release in which case
+ $VERSION will be (e.g.) 2.2403 and $VERSION_STRING will be "2.24_03".
+
+Changes in version 2.24
+-----------------------
+
+* Add object oriented interface:
+
+ use Getopt::Long;
+ $p = new Getopt::Long::Parser;
+ $p->configure(...configuration options...);
+ if ($p->getoptions(...options descriptions...)) ...
+
+* Add configuration at 'use' time:
+
+ use Getopt::Long qw(:config no_ignore_case bundling);
+
+* Add configuration options "gnu_getopt" and "gnu_compat".
+
+ "gnu_compat" controls whether --opt= is allowed, and what it should
+ do. Without "gnu_compat", --opt= gives an error. With "gnu_compat",
+ --opt= will give option "opt" and empty value.
+ This is the way GNU getopt_long does it.
+
+ "gnu_getopt" is a short way of setting "gnu_compat bundling permute
+ no_getopt_compat. With "gnu_getopt", command line handling should be
+ fully compatible with GNU getopt_long.
+
+* Correct warnings when the user specified an array or hash
+ destination using a non-lowercase option, e.g. "I=s@".
+
+* Correct ambiguous use of 'set' and 'reset' in the Configuration
+ section of the documentation.
+
+* Add configuration option "posix_default" to reset to defaults as if
+ POSIXLY_CORRECT were set.
+
+* Disallow "no" prefix on configuration options "default", "prefix" and
+ "prefix_pattern".
+
+* Add a section "Trouble Shooting" to the documentation, with
+ frequently asked questions.
+
+Changes in version 2.23
+-----------------------
+
+* When a call-back routine issues 'die', messages starting with "!"
+ are treated specially. Currently, only "!FINISH" is recognised (see
+ the next bullet point). Other messages that start with "!" are
+ ignored.
+
+* Change 'die("FINISH") (see changes in 2.21) to die("!FINISH"). This
+ is an incompatible change, but I guess noone is using this yet.
+
+Changes in version 2.22
+-----------------------
+
+* Fixes a bug in the combination of aliases and negation.
+
+ Old: "foo|bar!" allowed negation on foo, but not on bar.
+ New: "foo|bar!" allows negation on foo and bar.
+
+ Caveat: "foo|f!", with bundling, issues the warning that negation on
+ a short option is ignored. To obtain the desired behaviour, use
+
+ "foo!" => \$opt_foo, "f" => \$opt_foo
+ or
+ "foo|f" => \$opt_foo, "nofoo" => sub { $opt_foo = 0 }
+
+ Remember that this is _only_ required when bundling is in effect.
+
+Changes in version 2.21
+-----------------------
+
+* New documentation.
+
+* User defined subroutines should use 'die' to signal errors.
+
+* User defined subroutines can preliminary terminate options
+ processing by calling die("FINISH");
+
+* Correct erroneous install of Getopt::Long manpage.
+ Previous versions seem to install Getopt::GetoptLong instead of
+ Getopt::Long.
+
+Changes in version 2.20
+-----------------------
+
+* Prevent the magic argument "<>" from being interpreted as option
+ starter characters if it is the first argument passed.
+ To use the characters "<>" as option starters, pass "><" instead.
+
+* Changed license: Getopt::Long may now also be used under the Perl
+ Artistic License.
+
+* Changed the file name of the distribution kit from "GetoptLong..."
+ to "Getopt-Long-..." to match the standards.
+
+Changes in version 2.19
+-----------------------
+
+* Fix a warning bug with bundling_override.
+
+There's no version 2.18
+-----------------------
+
+Changes in version 2.17
+-----------------------
+
+* Getopt::Long::config is renamed Getopt::Long::Configure. The old
+ name will remain supported without being documented.
+
+* Options can have the specifier '+' to denote that the option value
+ must be incremented each time the option occurs on the command line.
+ For example:
+
+ my $more = 2;
+ Getopt::Long::Configure("bundling");
+ GetOptions ("v+" => \$more);
+ print STDOUT ("more = $more\n");
+
+ will print "more = 3" when called with "-v", "more = 4" when called
+ with "-vv" (or "-v -v"), and so on.
+
+* Getopt::Long now uses autoloading. This substantially reduces the
+ resources required to 'use Getopt::Long' (about 100 lines of over
+ 1300 total).
+
+* It is now documented that global option variables like $opt_foo
+ need to be declared using 'use vars ...' when running under 'use
+ strict'.
+
+* To install, it is now required to use the official procedure:
+
+ perl Makefile.PL
+ make
+ make test
+ make install
+
+Changes in version 2.16
+-----------------------
+
+* A couple of small additional fixes to the $` $& $' fixes.
+
+* The option prefix can be set using config("prefix=...") or, more
+ powerful, with config("prefix_pattern=..."); see the documentation
+ for details.
+
+* More 'perl -w' warnings eliminated for obscure cases of bundling.
+
+This version is identical to 2.15, which was not released.
+
+There's no version 2.14
+-----------------------
+
+Changes in version 2.13
+-----------------------
+
+* All regexps are changed to avoid the use of $`, $& and $'. Using one
+ of these causes all pattern matches in the program to be much slower
+ than necessary.
+
+* Configuration errors are signalled using die() and will cause the
+ program to be terminated (unless eval{...} or $SIG{__DIE__} is
+ used).
+
+* Option parsing errors are now signalled with calls to warn().
+
+* In option bundles, numeric values may be embedded in the bundle
+ (e.g. -al24w80).
+
+* More 'perl -w' warnings eliminated for obscure cases of bundling.
+
+* Removed non-standard version number matching. Version 1.121 is now
+ more than 1.12 but less than 1.13.
+
+Changes in version 2.12
+-----------------------
+
+* A single question mark is allowed as an alias to an option, e.g.
+
+ GetOptions ("help|?", ...)
+
+Changes in version 2.11
+-----------------------
+
+* User linkage may be an object, provided the object is really a hash.
+
+ For example:
+
+ { package Foo;
+ sub new () { return bless {}; }
+ }
+
+ my $linkage = Foo->new();
+
+ GetOptions ($linkage, ... );
+
+* Some bug fixes in handling obscure cases of pass-through.
+
+Changes in version 2.9
+----------------------
+
+* A new way to configure Getopt::Long. Instead of setting module local
+ variables, routine Getopt::Long::config can be called with the names
+ of options to be set or reset, e.g.
+
+ Getopt::Long::config ("no_auto_abbrev", "ignore_case");
+
+ Configuring by using the module local variables is deprecated, but
+ it will continue to work for backwark compatibility.
+
+Changes in version 2.6
+----------------------
+
+* Handle ignorecase even if autoabbrev is off.
+
+* POD corrections.
+
+Changes in version 2.4
+----------------------
+
+* Pass-through of unrecognized options. Makes it easy to write wrapper
+ programs that process some of the command line options but pass the
+ others to another program.
+
+* Options can be of type HASH, now you can say
+
+ --define foo=bar
+
+ and have $opt_define{"foo"} set to "bar".
+
+* An enhanced skeleton program, skel2.pl, that combines the power of
+ Getopt::Long with Pod::Usage.
+ Module Pod::Usage can be obtained from CPAN,
+ http://www.perl.com/CPAN/authors/Brad_Appleton.
+
+Possible incompatibility in version 2.4
+---------------------------------------
+
+Previous versions of Getopt::Long always downcased the option variable
+names when ignorecase was in effect. This bug has been corrected. As a
+consequence, &GetOptions ("Foo") will now set variable $opt_Foo
+instead of $opt_foo.
+
--- /dev/null
+Module Getopt::Long - extended processing of command line options
+=================================================================
+
+Module Getopt::Long implements an extended getopt function called
+GetOptions(). This function implements the POSIX standard for command
+line options, with GNU extensions, while still capable of handling
+the traditional one-letter options.
+In general, this means that command line options can have long names
+instead of single letters, and are introduced with a double dash `--'.
+
+Optionally, Getopt::Long can support the traditional bundling of
+single-letter command line options.
+
+Getopt::Long::GetOptions() is part of the Perl 5 distribution. It 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.
+
+For complete documentation, see the Getopt::Long POD document or use
+the command
+
+ perldoc Getopt::Long
+
+FEATURES
+========
+
+* Long option names
+
+Major advantage of using long option names is that it is much easier
+to memorize the option names. Using single-letter names one quickly
+runs into the problem that there is no logical relationship between
+the semantics of the selected option and its option letter.
+Disadvantage is that it requires more typing. Getopt::Long provides
+for option name abbreviation, so option names may be abbreviated to
+uniqueness. Also, modern shells like Cornell's tcsh support option
+name completion. As a rule of thumb, you can use abbreviations freely
+while running commands interactively but always use the full names in
+scripts.
+
+Examples (POSIX):
+
+ --long --width=80 --height=24
+
+Extensions:
+
+ -long (convenience) +width=80 (deprecated) -height 24 (traditional)
+
+By default, long option names are case insensitive.
+
+* Single-letter options and bundling
+
+When single-letter options are requested, Getopt::Long allows the
+option names to be bundled, e.g. "-abc" is equivalent to "-a -b -c".
+In this case, long option names must be introduced with the POSIX "--"
+introducer.
+
+Examples:
+
+ -lgAd (bundle) -xw 80 (bundle, w takes a value) -xw80 (same)
+ even -l24w80 (l = 24 and w = 80)
+
+By default, single-letter option names are case sensitive.
+
+* Flexibility:
+
+ - options can have alternative names, using an alternative name
+ will behave as if the primary name was used;
+ - options can be negatable, e.g. "debug" will switch it on, while
+ "nodebug" will switch it off.
+ - options can set values, but also add values producing an array
+ of values instead of a single scalar value, or set values in a hash.
+
+* Options linkage
+
+Using Getopt::Long gives the programmer ultimate control over the
+command line options and how they must be handled:
+
+ - by setting a global variable in the calling program;
+ - by setting a specified variable;
+ - by entering the option name and the value in an associative array
+ (hash) or object (if it is a blessed hash);
+ - by calling a user-specified subroutine with the option name and
+ the value as arguments;
+ - combinations of the above.
+
+* Customization:
+
+The module contains a special method, Getopt::Long::Configure, to
+control configuration variables to activate (or de-activate) specific
+behavior. It can be called with one or more names of options:
+
+ - default
+
+ Restore default settings.
+
+ - auto_abbrev
+
+ Allow option names to be abbreviated to uniqueness.
+
+ - getopt_compat
+
+ Allow '+' to start options.
+
+ - gnu_compat
+
+ Compatibility with GNU getopt_long().
+
+ - permute
+ - require_order
+
+ Whether non-options are allowed to be mixed with options.
+
+ permute means that
+
+ -foo arg1 -bar arg2 arg3
+
+ is equivalent to
+
+ -foo -bar arg1 arg2 arg3
+
+ (provided -foo does not take an argument value).
+
+ require_order means that options processing
+ terminates when the first non-option is encountered.
+
+ -foo arg1 -bar arg2 arg3
+
+ is equivalent to
+
+ -foo -- arg1 -bar arg2 arg3
+
+ - 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
+ "--" and single-character options (and bundles) with "-".
+
+ - ignore_case
+
+ Ignore case when matching options.
+
+ - pass_through
+
+ Do not issue error messages for unknown options, but leave
+ them (pass-through) in @ARGV.
+
+ - prefix
+
+ The string that starts options. See also prefix_pattern.
+
+ - prefix_pattern
+
+ A Perl pattern that identifies the strings that introduce
+ options. Default is (--|-|\+) unless environment variable
+ POSIXLY_CORRECT has been set, in which case it is (--|-).
+
+ - debug
+
+ Enable copious debugging output.
+
+* Object oriented interface:
+
+Using the object oriented interface, multiple parser objects can be
+instantiated, each having their own configuration settings:
+
+ $p1 = new Getopt::Long::Parser (config => ["posix"]);
+ $p2 = new Getopt::Long::Parser (config => ["no_posix"]);
+ if ($p1->getoptions(...options descriptions...)) ...
+
+AVAILABILITY
+============
+
+The official version for module Getopt::Long comes with the Perl 5
+distribution.
+Newer versions will be made available on the Comprehensive Perl Archive
+Network (CPAN), see "http://www.perl.com/CPAN/authors/Johan_Vromans".
+Or use the CPAN search engine:
+ http://search.cpan.org/search?mode=module&query=Getopt::Long
+ http://search.cpan.org/search?module=Getopt::Long
+
+COPYRIGHT AND DISCLAIMER
+========================
+
+Module Getopt::Long is Copyright 2001,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
+Foundation; either version 2 of the License, or (at your option) any
+later version.
+
+-------------------------------------------------------------------
+Johan Vromans jvromans@squirrel.nl
+Squirrel Consultancy Haarlem, the Netherlands
+http://www.squirrel.nl http://www.squirrel.nl/people/jvromans
+------------------ "Arms are made for hugging" --------------------
https://perl5.git.perl.org / perl5.git / commitdiff