From 7d1b667fcedc08204a73c6220a32905ed1833ea6 Mon Sep 17 00:00:00 2001 From: Jarkko Hietaniemi Date: Sun, 5 Aug 2001 19:38:07 +0000 Subject: [PATCH] Upgrade to Getopt::Long 2.26. p4raw-id: //depot/perl@11587 --- MANIFEST | 2 + lib/Getopt/Long.pm | 78 +++++++++----- lib/Getopt/Long/CHANGES | 277 ++++++++++++++++++++++++++++++++++++++++++++++++ lib/Getopt/Long/README | 196 ++++++++++++++++++++++++++++++++++ 4 files changed, 529 insertions(+), 24 deletions(-) create mode 100644 lib/Getopt/Long/CHANGES create mode 100644 lib/Getopt/Long/README diff --git a/MANIFEST b/MANIFEST index 19bd6a2..7174859 100644 --- a/MANIFEST +++ b/MANIFEST @@ -923,6 +923,8 @@ lib/ftp.pl FTP code (obsolete, use Net::FTP instead) 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 diff --git a/lib/Getopt/Long.pm b/lib/Getopt/Long.pm index ff0475b..01e0e91 100644 --- a/lib/Getopt/Long.pm +++ b/lib/Getopt/Long.pm @@ -2,12 +2,12 @@ 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 ################ @@ -35,8 +35,9 @@ use 5.004; 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); @@ -215,12 +216,16 @@ __END__ ################ 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 { @@ -244,7 +249,7 @@ 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 ", @@ -264,7 +269,7 @@ sub GetOptions { # 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; @@ -273,7 +278,7 @@ sub GetOptions { # 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])) ) { @@ -286,7 +291,7 @@ sub GetOptions { # 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. @@ -309,7 +314,7 @@ sub GetOptions { } # 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; } @@ -346,7 +351,7 @@ sub GetOptions { $_ = 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 { @@ -677,8 +682,10 @@ sub FindOption ($$$$$$$) { 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, @@ -850,13 +857,23 @@ sub FindOption ($$$$$$$) { } } - 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) @@ -864,7 +881,9 @@ sub FindOption ($$$$$$$) { 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. @@ -1032,7 +1051,12 @@ Getopt::Long - Extended processing of command line options =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 @@ -1364,6 +1388,15 @@ argument to start with C<-> or C<-->. 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. @@ -1885,6 +1918,3 @@ MA 02139, USA. =cut -# Local Variables: -# eval: (load-file "pod.el") -# End: diff --git a/lib/Getopt/Long/CHANGES b/lib/Getopt/Long/CHANGES new file mode 100644 index 0000000..b43606a --- /dev/null +++ b/lib/Getopt/Long/CHANGES @@ -0,0 +1,277 @@ +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. + diff --git a/lib/Getopt/Long/README b/lib/Getopt/Long/README new file mode 100644 index 0000000..1a2dc10 --- /dev/null +++ b/lib/Getopt/Long/README @@ -0,0 +1,196 @@ +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" -------------------- -- 2.7.4