Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1343 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/Getopt::Long.3perl b/upstream/archlinux/man3/Getopt::Long.3perl
new file mode 100644
index 00000000..153dafd5
--- /dev/null
+++ b/upstream/archlinux/man3/Getopt::Long.3perl
@@ -0,0 +1,1343 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "Getopt::Long 3perl"
+.TH Getopt::Long 3perl 2024-02-11 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+Getopt::Long \- Extended processing of command line options
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 8
+\&  use Getopt::Long;
+\&  my $data   = "file.dat";
+\&  my $length = 24;
+\&  my $verbose;
+\&  GetOptions ("length=i" => \e$length,    # numeric
+\&              "file=s"   => \e$data,      # string
+\&              "verbose"  => \e$verbose)   # flag
+\&  or die("Error in command line arguments\en");
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The Getopt::Long module implements an extended getopt function called
+\&\fBGetOptions()\fR. It parses the command line from \f(CW@ARGV\fR, recognizing
+and removing specified options and their possible values.
+.PP
+This function adheres to the POSIX syntax for command
+line options, with GNU extensions. In general, this means that options
+have long names instead of single letters, and are introduced with a
+double dash "\-\-". Support for bundling of command line options, as was
+the case with the more traditional single-letter approach, is provided
+but not enabled by default.
+.SH "Command Line Options, an Introduction"
+.IX Header "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 \fIoptions\fR 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.
+.PP
+Command line options come in several flavours. Historically, they are
+preceded by a single dash \f(CW\*(C`\-\*(C'\fR, and consist of a single letter.
+.PP
+.Vb 1
+\&    \-l \-a \-c
+.Ve
+.PP
+Usually, these single-character options can be bundled:
+.PP
+.Vb 1
+\&    \-lac
+.Ve
+.PP
+Options can have values, the value is placed after the option
+character. Sometimes with whitespace in between, sometimes not:
+.PP
+.Vb 1
+\&    \-s 24 \-s24
+.Ve
+.PP
+Due to the very cryptic nature of these options, another style was
+developed that used long names. So instead of a cryptic \f(CW\*(C`\-l\*(C'\fR one
+could use the more descriptive \f(CW\*(C`\-\-long\*(C'\fR. 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 \f(CW\*(C`+\*(C'\fR instead. Also, option values could be specified either
+like
+.PP
+.Vb 1
+\&    \-\-size=24
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&    \-\-size 24
+.Ve
+.PP
+The \f(CW\*(C`+\*(C'\fR form is now obsolete and strongly deprecated.
+.SH "Getting Started with Getopt::Long"
+.IX Header "Getting Started with Getopt::Long"
+Getopt::Long is the Perl5 successor of \f(CW\*(C`newgetopt.pl\*(C'\fR. This was the
+first Perl module that provided support for handling the new style of
+command line options, in particular long option names, hence the Perl5
+name Getopt::Long. This module also supports single-character options
+and bundling.
+.PP
+To use Getopt::Long from a Perl program, you must include the
+following line in your Perl program:
+.PP
+.Vb 1
+\&    use Getopt::Long;
+.Ve
+.PP
+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.
+.PP
+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 "Configuring Getopt::Long" for more
+details on how to configure Getopt::Long.
+.SS "Simple options"
+.IX Subsection "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:
+.PP
+.Vb 1
+\&    \-\-all \-\-verbose \-\-quiet \-\-debug
+.Ve
+.PP
+Handling simple options is straightforward:
+.PP
+.Vb 3
+\&    my $verbose = \*(Aq\*(Aq;   # option variable with default value (false)
+\&    my $all = \*(Aq\*(Aq;       # option variable with default value (false)
+\&    GetOptions (\*(Aqverbose\*(Aq => \e$verbose, \*(Aqall\*(Aq => \e$all);
+.Ve
+.PP
+The call to \fBGetOptions()\fR parses the command line arguments that are
+present in \f(CW@ARGV\fR and sets the option variable to the value \f(CW1\fR 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 \fIenabling\fR the option.
+.PP
+The option name as specified to the \fBGetOptions()\fR function is called
+the option \fIspecification\fR. Later we'll see that this specification
+can contain more than just the option name. The reference to the
+variable is called the option \fIdestination\fR.
+.PP
+\&\fBGetOptions()\fR will return a true value if the command line could be
+processed successfully. Otherwise, it will write error messages using
+\&\fBdie()\fR and \fBwarn()\fR, and return a false result.
+.SS "A little bit less simple options"
+.IX Subsection "A little bit less simple options"
+Getopt::Long supports two useful variants of simple options:
+\&\fInegatable\fR options and \fIincremental\fR options.
+.PP
+A negatable option is specified with an exclamation mark \f(CW\*(C`!\*(C'\fR after the
+option name:
+.PP
+.Vb 2
+\&    my $verbose = \*(Aq\*(Aq;   # option variable with default value (false)
+\&    GetOptions (\*(Aqverbose!\*(Aq => \e$verbose);
+.Ve
+.PP
+Now, using \f(CW\*(C`\-\-verbose\*(C'\fR on the command line will enable \f(CW$verbose\fR,
+as expected. But it is also allowed to use \f(CW\*(C`\-\-noverbose\*(C'\fR, which will
+disable \f(CW$verbose\fR by setting its value to \f(CW0\fR. Using a suitable
+default value, the program can find out whether \f(CW$verbose\fR is false
+by default, or disabled by using \f(CW\*(C`\-\-noverbose\*(C'\fR.
+.PP
+(If both \f(CW\*(C`\-\-verbose\*(C'\fR and \f(CW\*(C`\-\-noverbose\*(C'\fR are given, whichever is given
+last takes precedence.)
+.PP
+An incremental option is specified with a plus \f(CW\*(C`+\*(C'\fR after the
+option name:
+.PP
+.Vb 2
+\&    my $verbose = \*(Aq\*(Aq;   # option variable with default value (false)
+\&    GetOptions (\*(Aqverbose+\*(Aq => \e$verbose);
+.Ve
+.PP
+Using \f(CW\*(C`\-\-verbose\*(C'\fR on the command line will increment the value of
+\&\f(CW$verbose\fR. This way the program can keep track of how many times the
+option occurred on the command line. For example, each occurrence of
+\&\f(CW\*(C`\-\-verbose\*(C'\fR could increase the verbosity level of the program.
+.SS "Mixing command line option with other arguments"
+.IX Subsection "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 \f(CW\*(C`\-\-\*(C'\fR on the command line:
+.PP
+.Vb 1
+\&    \-\-size 24 \-\- \-\-all
+.Ve
+.PP
+In this example, \f(CW\*(C`\-\-all\*(C'\fR will \fInot\fR be treated as an option, but
+passed to the program unharmed, in \f(CW@ARGV\fR.
+.SS "Options with values"
+.IX Subsection "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.
+.PP
+Three kinds of values are supported: integer numbers, floating point
+numbers, and strings.
+.PP
+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.
+.PP
+.Vb 2
+\&    my $tag = \*(Aq\*(Aq;       # option variable with default value
+\&    GetOptions (\*(Aqtag=s\*(Aq => \e$tag);
+.Ve
+.PP
+In the option specification, the option name is followed by an equals
+sign \f(CW\*(C`=\*(C'\fR and the letter \f(CW\*(C`s\*(C'\fR. The equals sign indicates that this
+option requires a value. The letter \f(CW\*(C`s\*(C'\fR indicates that this value is
+an arbitrary string. Other possible value types are \f(CW\*(C`i\*(C'\fR for integer
+values, and \f(CW\*(C`f\*(C'\fR for floating point values. Using a colon \f(CW\*(C`:\*(C'\fR 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 \f(CW\*(Aq\*(Aq\fR assigned, while numeric options are set to \f(CW0\fR.
+.PP
+(If the same option appears more than once on the command line, the
+last given value is used.  If you want to take all the values, see
+below.)
+.SS "Options with multiple values"
+.IX Subsection "Options with multiple values"
+Options sometimes take several values. For example, a program could
+use multiple directories to search for library files:
+.PP
+.Vb 1
+\&    \-\-library lib/stdlib \-\-library lib/extlib
+.Ve
+.PP
+To accomplish this behaviour, simply specify an array reference as the
+destination for the option:
+.PP
+.Vb 1
+\&    GetOptions ("library=s" => \e@libfiles);
+.Ve
+.PP
+Alternatively, you can specify that the option can have multiple
+values by adding a "@", and pass a reference to a scalar as the
+destination:
+.PP
+.Vb 1
+\&    GetOptions ("library=s@" => \e$libfiles);
+.Ve
+.PP
+Used with the example above, \f(CW@libfiles\fR c.q. \f(CW@$libfiles\fR would
+contain two strings upon completion: \f(CW"lib/stdlib"\fR and
+\&\f(CW"lib/extlib"\fR, in that order. It is also possible to specify that
+only integer or floating point numbers are acceptable values.
+.PP
+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 \fBsplit()\fR
+and \fBjoin()\fR operators:
+.PP
+.Vb 2
+\&    GetOptions ("library=s" => \e@libfiles);
+\&    @libfiles = split(/,/,join(\*(Aq,\*(Aq,@libfiles));
+.Ve
+.PP
+Of course, it is important to choose the right separator string for
+each purpose.
+.PP
+Warning: What follows is an experimental feature.
+.PP
+Options can take multiple values at once, for example
+.PP
+.Vb 1
+\&    \-\-coordinates 52.2 16.4 \-\-rgbcolor 255 255 149
+.Ve
+.PP
+This can be accomplished by adding a repeat specifier to the option
+specification. Repeat specifiers are very similar to the \f(CW\*(C`{...}\*(C'\fR
+repeat specifiers that can be used with regular expression patterns.
+For example, the above command line would be handled as follows:
+.PP
+.Vb 1
+\&    GetOptions(\*(Aqcoordinates=f{2}\*(Aq => \e@coor, \*(Aqrgbcolor=i{3}\*(Aq => \e@color);
+.Ve
+.PP
+The destination for the option must be an array or array reference.
+.PP
+It is also possible to specify the minimal and maximal number of
+arguments an option takes. \f(CW\*(C`foo=s{2,4}\*(C'\fR indicates an option that
+takes at least two and at most 4 arguments. \f(CW\*(C`foo=s{1,}\*(C'\fR indicates one
+or more values; \f(CW\*(C`foo:s{,}\*(C'\fR indicates zero or more option values.
+.SS "Options with hash values"
+.IX Subsection "Options with hash values"
+If the option destination is a reference to a hash, the option will
+take, as value, strings of the form \fIkey\fR\f(CW\*(C`=\*(C'\fR\fIvalue\fR. The value will
+be stored with the specified key in the hash.
+.PP
+.Vb 1
+\&    GetOptions ("define=s" => \e%defines);
+.Ve
+.PP
+Alternatively you can use:
+.PP
+.Vb 1
+\&    GetOptions ("define=s%" => \e$defines);
+.Ve
+.PP
+When used with command line options:
+.PP
+.Vb 1
+\&    \-\-define os=linux \-\-define vendor=redhat
+.Ve
+.PP
+the hash \f(CW%defines\fR (or \f(CW%$defines\fR) will contain two keys, \f(CW"os"\fR
+with value \f(CW"linux"\fR and \f(CW"vendor"\fR with value \f(CW"redhat"\fR. It is
+also possible to specify that only integer or floating point numbers
+are acceptable values. The keys are always taken to be strings.
+.SS "User-defined subroutines to handle options"
+.IX Subsection "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 \fBGetOptions()\fR encounters the option, it
+will call the subroutine with two or three arguments. The first
+argument is the name of the option. (Actually, it is an object that
+stringifies to the name of the option.) For a scalar or array destination,
+the second argument is the value to be stored. For a hash destination,
+the second argument is the key to the hash, and the third argument
+the value to be stored. It is up to the subroutine to store the value,
+or do whatever it thinks is appropriate.
+.PP
+A trivial application of this mechanism is to implement options that
+are related to each other. For example:
+.PP
+.Vb 3
+\&    my $verbose = \*(Aq\*(Aq;   # option variable with default value (false)
+\&    GetOptions (\*(Aqverbose\*(Aq => \e$verbose,
+\&                \*(Aqquiet\*(Aq   => sub { $verbose = 0 });
+.Ve
+.PP
+Here \f(CW\*(C`\-\-verbose\*(C'\fR and \f(CW\*(C`\-\-quiet\*(C'\fR control the same variable
+\&\f(CW$verbose\fR, but with opposite values.
+.PP
+If the subroutine needs to signal an error, it should call \fBdie()\fR with
+the desired error message as its argument. \fBGetOptions()\fR will catch the
+\&\fBdie()\fR, issue the error message, and record that an error result must
+be returned upon completion.
+.PP
+If the text of the error message starts with an exclamation mark \f(CW\*(C`!\*(C'\fR
+it is interpreted specially by \fBGetOptions()\fR. There is currently one
+special command implemented: \f(CWdie("!FINISH")\fR will cause \fBGetOptions()\fR
+to stop processing options, as if it encountered a double dash \f(CW\*(C`\-\-\*(C'\fR.
+.PP
+Here is an example of how to access the option name and value from within
+a subroutine:
+.PP
+.Vb 5
+\&    GetOptions (\*(Aqopt=i\*(Aq => \e&handler);
+\&    sub handler {
+\&        my ($opt_name, $opt_value) = @_;
+\&        print("Option name is $opt_name and value is $opt_value\en");
+\&    }
+.Ve
+.SS "Options with multiple names"
+.IX Subsection "Options with multiple names"
+Often it is user friendly to supply alternate mnemonic names for
+options. For example \f(CW\*(C`\-\-height\*(C'\fR could be an alternate name for
+\&\f(CW\*(C`\-\-length\*(C'\fR. Alternate names can be included in the option
+specification, separated by vertical bar \f(CW\*(C`|\*(C'\fR characters. To implement
+the above example:
+.PP
+.Vb 1
+\&    GetOptions (\*(Aqlength|height=f\*(Aq => \e$length);
+.Ve
+.PP
+The first name is called the \fIprimary\fR name, the other names are
+called \fIaliases\fR. When using a hash to store options, the key will
+always be the primary name.
+.PP
+Multiple alternate names are possible.
+.SS "Case and abbreviations"
+.IX Subsection "Case and abbreviations"
+Without additional configuration, \fBGetOptions()\fR will ignore the case of
+option names, and allow the options to be abbreviated to uniqueness.
+.PP
+.Vb 1
+\&    GetOptions (\*(Aqlength|height=f\*(Aq => \e$length, "head" => \e$head);
+.Ve
+.PP
+This call will allow \f(CW\*(C`\-\-l\*(C'\fR and \f(CW\*(C`\-\-L\*(C'\fR for the length option, but
+requires a least \f(CW\*(C`\-\-hea\*(C'\fR and \f(CW\*(C`\-\-hei\*(C'\fR for the head and height options.
+.SS "Summary of Option Specifications"
+.IX Subsection "Summary of Option Specifications"
+Each option specifier consists of two parts: the name specification
+and the argument specification.
+.PP
+The name specification contains the name of the option, optionally
+followed by a list of alternative names separated by vertical bar
+characters.
+.PP
+.Vb 2
+\&    length            option name is "length"
+\&    length|size|l     name is "length", aliases are "size" and "l"
+.Ve
+.PP
+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.
+.PP
+The argument specification can be
+.IP ! 4
+The option does not take an argument and may be negated by prefixing
+it with "no" or "no\-". E.g. \f(CW"foo!"\fR will allow \f(CW\*(C`\-\-foo\*(C'\fR (a value of
+1 will be assigned) as well as \f(CW\*(C`\-\-nofoo\*(C'\fR and \f(CW\*(C`\-\-no\-foo\*(C'\fR (a value of
+0 will be assigned). If the option has aliases, this applies to the
+aliases as well.
+.Sp
+Using negation on a single letter option when bundling is in effect is
+pointless and will result in a warning.
+.IP + 4
+The option does not take an argument and will be incremented by 1
+every time it appears on the command line. E.g. \f(CW"more+"\fR, when used
+with \f(CW\*(C`\-\-more \-\-more \-\-more\*(C'\fR, will increment the value three times,
+resulting in a value of 3 (provided it was 0 or undefined at first).
+.Sp
+The \f(CW\*(C`+\*(C'\fR specifier is ignored if the option destination is not a scalar.
+.IP "= \fItype\fR [ \fIdesttype\fR ] [ \fIrepeat\fR ]" 4
+.IX Item "= type [ desttype ] [ repeat ]"
+The option requires an argument of the given type. Supported types
+are:
+.RS 4
+.IP s 4
+.IX Item "s"
+String. An arbitrary sequence of characters. It is valid for the
+argument to start with \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`\-\-\*(C'\fR.
+.IP i 4
+.IX Item "i"
+Integer. An optional leading plus or minus sign, followed by a
+sequence of digits.
+.IP o 4
+.IX 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 (\f(CW\*(C`0x\*(C'\fR followed by '0' .. '9', 'a' .. 'f', case
+insensitive), or a binary string (\f(CW\*(C`0b\*(C'\fR followed by a series of '0'
+and '1').
+.IP f 4
+.IX Item "f"
+Real number. For example \f(CW3.14\fR, \f(CW\-6.23E24\fR and so on.
+.RE
+.RS 4
+.Sp
+The \fIdesttype\fR can be \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR 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.
+.Sp
+The \fIrepeat\fR specifies the number of values this option takes per
+occurrence on the command line. It has the format \f(CW\*(C`{\*(C'\fR [ \fImin\fR ] [ \f(CW\*(C`,\*(C'\fR [ \fImax\fR ] ] \f(CW\*(C`}\*(C'\fR.
+.Sp
+\&\fImin\fR denotes the minimal number of arguments. It defaults to 1 for
+options with \f(CW\*(C`=\*(C'\fR and to 0 for options with \f(CW\*(C`:\*(C'\fR, see below. Note that
+\&\fImin\fR overrules the \f(CW\*(C`=\*(C'\fR / \f(CW\*(C`:\*(C'\fR semantics.
+.Sp
+\&\fImax\fR denotes the maximum number of arguments. It must be at least
+\&\fImin\fR. If \fImax\fR is omitted, \fIbut the comma is not\fR, there is no
+upper bound to the number of argument values taken.
+.RE
+.IP ": \fItype\fR [ \fIdesttype\fR ]" 4
+.IX Item ": type [ desttype ]"
+Like \f(CW\*(C`=\*(C'\fR, 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.
+.Sp
+Note that if a string argument starts with \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`\-\-\*(C'\fR, it will be
+considered an option on itself.
+.IP ": \fInumber\fR [ \fIdesttype\fR ]" 4
+.IX Item ": number [ desttype ]"
+Like \f(CW\*(C`:i\*(C'\fR, but if the value is omitted, the \fInumber\fR will be assigned.
+.Sp
+If the \fInumber\fR is octal, hexadecimal or binary, behaves like \f(CW\*(C`:o\*(C'\fR.
+.IP ": + [ \fIdesttype\fR ]" 4
+.IX Item ": + [ desttype ]"
+Like \f(CW\*(C`:i\*(C'\fR, but if the value is omitted, the current value for the
+option will be incremented.
+.SH "Advanced Possibilities"
+.IX Header "Advanced Possibilities"
+.SS "Object oriented interface"
+.IX Subsection "Object oriented interface"
+Getopt::Long can be used in an object oriented way as well:
+.PP
+.Vb 5
+\&    use Getopt::Long;
+\&    $p = Getopt::Long::Parser\->new;
+\&    $p\->configure(...configuration options...);
+\&    if ($p\->getoptions(...options descriptions...)) ...
+\&    if ($p\->getoptionsfromarray( \e@array, ...options descriptions...)) ...
+.Ve
+.PP
+Configuration options can be passed to the constructor:
+.PP
+.Vb 2
+\&    $p = new Getopt::Long::Parser
+\&             config => [...configuration options...];
+.Ve
+.SS "Callback object"
+.IX Subsection "Callback object"
+In version 2.37 the first argument to the callback function was
+changed from string to object. This was done to make room for
+extensions and more detailed control. The object stringifies to the
+option name so this change should not introduce compatibility
+problems.
+.PP
+The callback object has the following methods:
+.IP name 4
+.IX Item "name"
+The name of the option, unabbreviated. For an option with multiple
+names it return the first (canonical) name.
+.IP given 4
+.IX Item "given"
+The name of the option as actually used, unabbreveated.
+.SS "Thread Safety"
+.IX Subsection "Thread Safety"
+Getopt::Long is thread safe when using ithreads as of Perl 5.8.  It is
+\&\fInot\fR thread safe when using the older (experimental and now
+obsolete) threads implementation that was added to Perl 5.005.
+.SS "Documentation and help texts"
+.IX Subsection "Documentation and help texts"
+Getopt::Long encourages the use of Pod::Usage to produce help
+messages. For example:
+.PP
+.Vb 2
+\&    use Getopt::Long;
+\&    use Pod::Usage;
+\&
+\&    my $man = 0;
+\&    my $help = 0;
+\&
+\&    GetOptions(\*(Aqhelp|?\*(Aq => \e$help, man => \e$man) or pod2usage(2);
+\&    pod2usage(1) if $help;
+\&    pod2usage(\-exitval => 0, \-verbose => 2) if $man;
+\&
+\&    _\|_END_\|_
+\&
+\&    =head1 NAME
+\&
+\&    sample \- Using Getopt::Long and Pod::Usage
+\&
+\&    =head1 SYNOPSIS
+\&
+\&    sample [options] [file ...]
+\&
+\&     Options:
+\&       \-help            brief help message
+\&       \-man             full documentation
+\&
+\&    =head1 OPTIONS
+\&
+\&    =over 8
+\&
+\&    =item B<\-help>
+\&
+\&    Print a brief help message and exits.
+\&
+\&    =item B<\-man>
+\&
+\&    Prints the manual page and exits.
+\&
+\&    =back
+\&
+\&    =head1 DESCRIPTION
+\&
+\&    B<This program> will read the given input file(s) and do something
+\&    useful with the contents thereof.
+\&
+\&    =cut
+.Ve
+.PP
+See Pod::Usage for details.
+.SS "Parsing options from an arbitrary array"
+.IX Subsection "Parsing options from an arbitrary array"
+By default, GetOptions parses the options that are present in the
+global array \f(CW@ARGV\fR. A special entry \f(CW\*(C`GetOptionsFromArray\*(C'\fR can be
+used to parse options from an arbitrary array.
+.PP
+.Vb 2
+\&    use Getopt::Long qw(GetOptionsFromArray);
+\&    $ret = GetOptionsFromArray(\e@myopts, ...);
+.Ve
+.PP
+When used like this, options and their possible values are removed
+from \f(CW@myopts\fR, the global \f(CW@ARGV\fR is not touched at all.
+.PP
+The following two calls behave identically:
+.PP
+.Vb 2
+\&    $ret = GetOptions( ... );
+\&    $ret = GetOptionsFromArray(\e@ARGV, ... );
+.Ve
+.PP
+This also means that a first argument hash reference now becomes the
+second argument:
+.PP
+.Vb 2
+\&    $ret = GetOptions(\e%opts, ... );
+\&    $ret = GetOptionsFromArray(\e@ARGV, \e%opts, ... );
+.Ve
+.SS "Parsing options from an arbitrary string"
+.IX Subsection "Parsing options from an arbitrary string"
+A special entry \f(CW\*(C`GetOptionsFromString\*(C'\fR can be used to parse options
+from an arbitrary string.
+.PP
+.Vb 2
+\&    use Getopt::Long qw(GetOptionsFromString);
+\&    $ret = GetOptionsFromString($string, ...);
+.Ve
+.PP
+The contents of the string are split into arguments using a call to
+\&\f(CW\*(C`Text::ParseWords::shellwords\*(C'\fR. As with \f(CW\*(C`GetOptionsFromArray\*(C'\fR, the
+global \f(CW@ARGV\fR is not touched.
+.PP
+It is possible that, upon completion, not all arguments in the string
+have been processed. \f(CW\*(C`GetOptionsFromString\*(C'\fR will, when called in list
+context, return both the return status and an array reference to any
+remaining arguments:
+.PP
+.Vb 1
+\&    ($ret, $args) = GetOptionsFromString($string, ... );
+.Ve
+.PP
+If any arguments remain, and \f(CW\*(C`GetOptionsFromString\*(C'\fR was not called in
+list context, a message will be given and \f(CW\*(C`GetOptionsFromString\*(C'\fR will
+return failure.
+.PP
+As with GetOptionsFromArray, a first argument hash reference now
+becomes the second argument. See the next section.
+.SS "Storing options values in a hash"
+.IX Subsection "Storing options values in a hash"
+Sometimes, for example when there are a lot of options, having a
+separate variable for each of them can be cumbersome. \fBGetOptions()\fR
+supports, as an alternative mechanism, storing options values in a
+hash.
+.PP
+To obtain this, a reference to a hash must be passed \fIas the first
+argument\fR to \fBGetOptions()\fR. 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,
+\&\f(CWexists($h{option})\fR (or \fBdefined()\fR) can be used to test if an option
+was used. The drawback is that warnings will be issued if the program
+runs under \f(CW\*(C`use strict\*(C'\fR and uses \f(CW$h{option}\fR without testing with
+\&\fBexists()\fR or \fBdefined()\fR first.
+.PP
+.Vb 2
+\&    my %h = ();
+\&    GetOptions (\e%h, \*(Aqlength=i\*(Aq);       # will store in $h{length}
+.Ve
+.PP
+For options that take list or hash values, it is necessary to indicate
+this by appending an \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR sign after the type:
+.PP
+.Vb 1
+\&    GetOptions (\e%h, \*(Aqcolours=s@\*(Aq);     # will push to @{$h{colours}}
+.Ve
+.PP
+To make things more complicated, the hash may contain references to
+the actual destinations, for example:
+.PP
+.Vb 3
+\&    my $len = 0;
+\&    my %h = (\*(Aqlength\*(Aq => \e$len);
+\&    GetOptions (\e%h, \*(Aqlength=i\*(Aq);       # will store in $len
+.Ve
+.PP
+This example is fully equivalent with:
+.PP
+.Vb 2
+\&    my $len = 0;
+\&    GetOptions (\*(Aqlength=i\*(Aq => \e$len);   # will store in $len
+.Ve
+.PP
+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:
+.PP
+.Vb 6
+\&    my $verbose = 0;                    # frequently referred
+\&    my $debug = 0;                      # frequently referred
+\&    my %h = (\*(Aqverbose\*(Aq => \e$verbose, \*(Aqdebug\*(Aq => \e$debug);
+\&    GetOptions (\e%h, \*(Aqverbose\*(Aq, \*(Aqdebug\*(Aq, \*(Aqfilter\*(Aq, \*(Aqsize=i\*(Aq);
+\&    if ( $verbose ) { ... }
+\&    if ( exists $h{filter} ) { ... option \*(Aqfilter\*(Aq was specified ... }
+.Ve
+.SS Bundling
+.IX Subsection "Bundling"
+With bundling it is possible to set several single-character options
+at once. For example if \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`x\*(C'\fR are all valid options,
+.PP
+.Vb 1
+\&    \-vax
+.Ve
+.PP
+will set all three.
+.PP
+Getopt::Long supports three styles of bundling. To enable bundling, a
+call to Getopt::Long::Configure is required.
+.PP
+The simplest style of bundling can be enabled with:
+.PP
+.Vb 1
+\&    Getopt::Long::Configure ("bundling");
+.Ve
+.PP
+Configured this way, single-character options can be bundled but long
+options (and any of their auto-abbreviated shortened forms) \fBmust\fR
+always start with a double dash \f(CW\*(C`\-\-\*(C'\fR to avoid ambiguity. For example,
+when \f(CW\*(C`vax\*(C'\fR, \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`x\*(C'\fR are all valid options,
+.PP
+.Vb 1
+\&    \-vax
+.Ve
+.PP
+will set \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`x\*(C'\fR, but
+.PP
+.Vb 1
+\&    \-\-vax
+.Ve
+.PP
+will set \f(CW\*(C`vax\*(C'\fR.
+.PP
+The second style of bundling lifts this restriction. It can be enabled
+with:
+.PP
+.Vb 1
+\&    Getopt::Long::Configure ("bundling_override");
+.Ve
+.PP
+Now, \f(CW\*(C`\-vax\*(C'\fR will set the option \f(CW\*(C`vax\*(C'\fR.
+.PP
+In all of the above cases, option values may be inserted in the
+bundle. For example:
+.PP
+.Vb 1
+\&    \-h24w80
+.Ve
+.PP
+is equivalent to
+.PP
+.Vb 1
+\&    \-h 24 \-w 80
+.Ve
+.PP
+A third style of bundling allows only values to be bundled with
+options. It can be enabled with:
+.PP
+.Vb 1
+\&    Getopt::Long::Configure ("bundling_values");
+.Ve
+.PP
+Now, \f(CW\*(C`\-h24\*(C'\fR will set the option \f(CW\*(C`h\*(C'\fR to \f(CW24\fR, but option bundles
+like \f(CW\*(C`\-vxa\*(C'\fR and \f(CW\*(C`\-h24w80\*(C'\fR are flagged as errors.
+.PP
+Enabling \f(CW\*(C`bundling_values\*(C'\fR will disable the other two styles of
+bundling.
+.PP
+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:
+.PP
+.Vb 1
+\&    Getopt::Long::Configure ("bundling", "ignorecase_always");
+.Ve
+.PP
+It goes without saying that bundling can be quite confusing.
+.SS "The lonesome dash"
+.IX Subsection "The lonesome dash"
+Normally, a lone dash \f(CW\*(C`\-\*(C'\fR on the command line will not be considered
+an option. Option processing will terminate (unless "permute" is
+configured) and the dash will be left in \f(CW@ARGV\fR.
+.PP
+It is possible to get special treatment for a lone dash. This can be
+achieved by adding an option specification with an empty name, for
+example:
+.PP
+.Vb 1
+\&    GetOptions (\*(Aq\*(Aq => \e$stdio);
+.Ve
+.PP
+A lone dash on the command line will now be a legal option, and using
+it will set variable \f(CW$stdio\fR.
+.SS "Argument callback"
+.IX Subsection "Argument callback"
+A special option 'name' \f(CW\*(C`<>\*(C'\fR can be used to designate a subroutine
+to handle non-option arguments. When \fBGetOptions()\fR encounters an
+argument that does not look like an option, it will immediately call this
+subroutine and passes it one parameter: the argument name.
+.PP
+For example:
+.PP
+.Vb 3
+\&    my $width = 80;
+\&    sub process { ... }
+\&    GetOptions (\*(Aqwidth=i\*(Aq => \e$width, \*(Aq<>\*(Aq => \e&process);
+.Ve
+.PP
+When applied to the following command line:
+.PP
+.Vb 1
+\&    arg1 \-\-width=72 arg2 \-\-width=60 arg3
+.Ve
+.PP
+This will call
+\&\f(CWprocess("arg1")\fR while \f(CW$width\fR is \f(CW80\fR,
+\&\f(CWprocess("arg2")\fR while \f(CW$width\fR is \f(CW72\fR, and
+\&\f(CWprocess("arg3")\fR while \f(CW$width\fR is \f(CW60\fR.
+.PP
+This feature requires configuration option \fBpermute\fR, see section
+"Configuring Getopt::Long".
+.SH "Configuring Getopt::Long"
+.IX Header "Configuring Getopt::Long"
+Getopt::Long can be configured by calling subroutine
+\&\fBGetopt::Long::Configure()\fR. This subroutine takes a list of quoted
+strings, each specifying a configuration option to be enabled, e.g.
+\&\f(CW\*(C`ignore_case\*(C'\fR. To disable, prefix with \f(CW\*(C`no\*(C'\fR or \f(CW\*(C`no_\*(C'\fR, e.g.
+\&\f(CW\*(C`no_ignore_case\*(C'\fR. Case does not matter. Multiple calls to \fBConfigure()\fR
+are possible.
+.PP
+Alternatively, as of version 2.24, the configuration options may be
+passed together with the \f(CW\*(C`use\*(C'\fR statement:
+.PP
+.Vb 1
+\&    use Getopt::Long qw(:config no_ignore_case bundling);
+.Ve
+.PP
+The following options are available:
+.IP default 12
+.IX Item "default"
+This option causes all configuration options to be reset to their
+default values.
+.IP posix_default 12
+.IX Item "posix_default"
+This option causes all configuration options to be reset to their
+default values as if the environment variable POSIXLY_CORRECT had
+been set.
+.IP auto_abbrev 12
+.IX Item "auto_abbrev"
+Allow option names to be abbreviated to uniqueness.
+Default is enabled unless environment variable
+POSIXLY_CORRECT has been set, in which case \f(CW\*(C`auto_abbrev\*(C'\fR is disabled.
+.IP getopt_compat 12
+.IX Item "getopt_compat"
+Allow \f(CW\*(C`+\*(C'\fR to start options.
+Default is enabled unless environment variable
+POSIXLY_CORRECT has been set, in which case \f(CW\*(C`getopt_compat\*(C'\fR is disabled.
+.IP gnu_compat 12
+.IX Item "gnu_compat"
+\&\f(CW\*(C`gnu_compat\*(C'\fR controls whether \f(CW\*(C`\-\-opt=\*(C'\fR is allowed, and what it should
+do. Without \f(CW\*(C`gnu_compat\*(C'\fR, \f(CW\*(C`\-\-opt=\*(C'\fR gives an error. With \f(CW\*(C`gnu_compat\*(C'\fR,
+\&\f(CW\*(C`\-\-opt=\*(C'\fR will give option \f(CW\*(C`opt\*(C'\fR and empty value.
+This is the way GNU \fBgetopt_long()\fR does it.
+.Sp
+Note that \f(CW\*(C`\-\-opt value\*(C'\fR is still accepted, even though GNU
+\&\fBgetopt_long()\fR doesn't.
+.IP gnu_getopt 12
+.IX Item "gnu_getopt"
+This is a short way of setting \f(CW\*(C`gnu_compat\*(C'\fR \f(CW\*(C`bundling\*(C'\fR \f(CW\*(C`permute\*(C'\fR
+\&\f(CW\*(C`no_getopt_compat\*(C'\fR. With \f(CW\*(C`gnu_getopt\*(C'\fR, command line handling should be
+reasonably compatible with GNU \fBgetopt_long()\fR.
+.IP require_order 12
+.IX Item "require_order"
+Whether command line arguments are allowed to be mixed with options.
+Default is disabled unless environment variable
+POSIXLY_CORRECT has been set, in which case \f(CW\*(C`require_order\*(C'\fR is enabled.
+.Sp
+See also \f(CW\*(C`permute\*(C'\fR, which is the opposite of \f(CW\*(C`require_order\*(C'\fR.
+.IP permute 12
+.IX Item "permute"
+Whether command line arguments are allowed to be mixed with options.
+Default is enabled unless environment variable
+POSIXLY_CORRECT has been set, in which case \f(CW\*(C`permute\*(C'\fR is disabled.
+Note that \f(CW\*(C`permute\*(C'\fR is the opposite of \f(CW\*(C`require_order\*(C'\fR.
+.Sp
+If \f(CW\*(C`permute\*(C'\fR is enabled, this means that
+.Sp
+.Vb 1
+\&    \-\-foo arg1 \-\-bar arg2 arg3
+.Ve
+.Sp
+is equivalent to
+.Sp
+.Vb 1
+\&    \-\-foo \-\-bar arg1 arg2 arg3
+.Ve
+.Sp
+If an argument callback routine is specified, \f(CW@ARGV\fR will always be
+empty upon successful return of \fBGetOptions()\fR since all options have been
+processed. The only exception is when \f(CW\*(C`\-\-\*(C'\fR is used:
+.Sp
+.Vb 1
+\&    \-\-foo arg1 \-\-bar arg2 \-\- arg3
+.Ve
+.Sp
+This will call the callback routine for arg1 and arg2, and then
+terminate \fBGetOptions()\fR leaving \f(CW"arg3"\fR in \f(CW@ARGV\fR.
+.Sp
+If \f(CW\*(C`require_order\*(C'\fR is enabled, options processing
+terminates when the first non-option is encountered.
+.Sp
+.Vb 1
+\&    \-\-foo arg1 \-\-bar arg2 arg3
+.Ve
+.Sp
+is equivalent to
+.Sp
+.Vb 1
+\&    \-\-foo \-\- arg1 \-\-bar arg2 arg3
+.Ve
+.Sp
+If \f(CW\*(C`pass_through\*(C'\fR is also enabled, options processing will terminate
+at the first unrecognized option, or non-option, whichever comes
+first.
+.IP "bundling (default: disabled)" 12
+.IX Item "bundling (default: disabled)"
+Enabling this option will allow single-character options to be
+bundled. To distinguish bundles from long option names, long options
+(and any of their auto-abbreviated shortened forms) \fImust\fR be
+introduced with \f(CW\*(C`\-\-\*(C'\fR and bundles with \f(CW\*(C`\-\*(C'\fR.
+.Sp
+Note that, if you have options \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`l\*(C'\fR and \f(CW\*(C`all\*(C'\fR, and
+auto_abbrev enabled, possible arguments and option settings are:
+.Sp
+.Vb 6
+\&    using argument               sets option(s)
+\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    \-a, \-\-a                      a
+\&    \-l, \-\-l                      l
+\&    \-al, \-la, \-ala, \-all,...     a, l
+\&    \-\-al, \-\-all                  all
+.Ve
+.Sp
+The surprising part is that \f(CW\*(C`\-\-a\*(C'\fR sets option \f(CW\*(C`a\*(C'\fR (due to auto
+completion), not \f(CW\*(C`all\*(C'\fR.
+.Sp
+Note: disabling \f(CW\*(C`bundling\*(C'\fR also disables \f(CW\*(C`bundling_override\*(C'\fR.
+.IP "bundling_override (default: disabled)" 12
+.IX Item "bundling_override (default: disabled)"
+If \f(CW\*(C`bundling_override\*(C'\fR is enabled, bundling is enabled as with
+\&\f(CW\*(C`bundling\*(C'\fR but now long option names override option bundles.
+.Sp
+Note: disabling \f(CW\*(C`bundling_override\*(C'\fR also disables \f(CW\*(C`bundling\*(C'\fR.
+.Sp
+\&\fBNote:\fR Using option bundling can easily lead to unexpected results,
+especially when mixing long options and bundles. Caveat emptor.
+.IP "ignore_case  (default: enabled)" 12
+.IX Item "ignore_case (default: enabled)"
+If enabled, case is ignored when matching option names. If, however,
+bundling is enabled as well, single character options will be treated
+case-sensitive.
+.Sp
+With \f(CW\*(C`ignore_case\*(C'\fR, option specifications for options that only
+differ in case, e.g., \f(CW"foo"\fR and \f(CW"Foo"\fR, will be flagged as
+duplicates.
+.Sp
+Note: disabling \f(CW\*(C`ignore_case\*(C'\fR also disables \f(CW\*(C`ignore_case_always\*(C'\fR.
+.IP "ignore_case_always (default: disabled)" 12
+.IX Item "ignore_case_always (default: disabled)"
+When bundling is in effect, case is ignored on single-character
+options also.
+.Sp
+Note: disabling \f(CW\*(C`ignore_case_always\*(C'\fR also disables \f(CW\*(C`ignore_case\*(C'\fR.
+.IP "auto_version (default:disabled)" 12
+.IX Item "auto_version (default:disabled)"
+Automatically provide support for the \fB\-\-version\fR option if
+the application did not specify a handler for this option itself.
+.Sp
+Getopt::Long will provide a standard version message that includes the
+program name, its version (if \f(CW$main::VERSION\fR is defined), and the
+versions of Getopt::Long and Perl. The message will be written to
+standard output and processing will terminate.
+.Sp
+\&\f(CW\*(C`auto_version\*(C'\fR will be enabled if the calling program explicitly
+specified a version number higher than 2.32 in the \f(CW\*(C`use\*(C'\fR or
+\&\f(CW\*(C`require\*(C'\fR statement.
+.IP "auto_help (default:disabled)" 12
+.IX Item "auto_help (default:disabled)"
+Automatically provide support for the \fB\-\-help\fR and \fB\-?\fR options if
+the application did not specify a handler for this option itself.
+.Sp
+Getopt::Long will provide a help message using module Pod::Usage. The
+message, derived from the SYNOPSIS POD section, will be written to
+standard output and processing will terminate.
+.Sp
+\&\f(CW\*(C`auto_help\*(C'\fR will be enabled if the calling program explicitly
+specified a version number higher than 2.32 in the \f(CW\*(C`use\*(C'\fR or
+\&\f(CW\*(C`require\*(C'\fR statement.
+.IP "pass_through (default: disabled)" 12
+.IX Item "pass_through (default: disabled)"
+With \f(CW\*(C`pass_through\*(C'\fR anything that is unknown, ambiguous or supplied with
+an invalid option will not be flagged as an error. Instead the unknown
+option(s) will be passed to the catchall \f(CW\*(C`<>\*(C'\fR if present, otherwise
+through to \f(CW@ARGV\fR. 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.
+.Sp
+If \f(CW\*(C`require_order\*(C'\fR is enabled, options processing will terminate at the
+first unrecognized option, or non-option, whichever comes first and all
+remaining arguments are passed to \f(CW@ARGV\fR instead of the catchall
+\&\f(CW\*(C`<>\*(C'\fR if present.  However, if \f(CW\*(C`permute\*(C'\fR is enabled instead, results
+can become confusing.
+.Sp
+Note that the options terminator (default \f(CW\*(C`\-\-\*(C'\fR), if present, will
+also be passed through in \f(CW@ARGV\fR.
+.IP prefix 12
+.IX Item "prefix"
+The string that starts options. If a constant string is not
+sufficient, see \f(CW\*(C`prefix_pattern\*(C'\fR.
+.IP prefix_pattern 12
+.IX Item "prefix_pattern"
+A Perl pattern that identifies the strings that introduce options.
+Default is \f(CW\*(C`\-\-|\-|\e+\*(C'\fR unless environment variable
+POSIXLY_CORRECT has been set, in which case it is \f(CW\*(C`\-\-|\-\*(C'\fR.
+.IP long_prefix_pattern 12
+.IX Item "long_prefix_pattern"
+A Perl pattern that allows the disambiguation of long and short
+prefixes. Default is \f(CW\*(C`\-\-\*(C'\fR.
+.Sp
+Typically you only need to set this if you are using nonstandard
+prefixes and want some or all of them to have the same semantics as
+\&'\-\-' does under normal circumstances.
+.Sp
+For example, setting prefix_pattern to \f(CW\*(C`\-\-|\-|\e+|\e/\*(C'\fR and
+long_prefix_pattern to \f(CW\*(C`\-\-|\e/\*(C'\fR would add Win32 style argument
+handling.
+.IP "debug (default: disabled)" 12
+.IX Item "debug (default: disabled)"
+Enable debugging output.
+.SH "Exportable Methods"
+.IX Header "Exportable Methods"
+.IP VersionMessage 4
+.IX Item "VersionMessage"
+This subroutine provides a standard version message. Its argument can be:
+.RS 4
+.IP \(bu 4
+A string containing the text of a message to print \fIbefore\fR printing
+the standard message.
+.IP \(bu 4
+A numeric value corresponding to the desired exit status.
+.IP \(bu 4
+A reference to a hash.
+.RE
+.RS 4
+.Sp
+If more than one argument is given then the entire argument list is
+assumed to be a hash.  If a hash is supplied (either as a reference or
+as a list) it should contain one or more elements with the following
+keys:
+.ie n .IP """\-message""" 4
+.el .IP \f(CW\-message\fR 4
+.IX Item "-message"
+.PD 0
+.ie n .IP """\-msg""" 4
+.el .IP \f(CW\-msg\fR 4
+.IX Item "-msg"
+.PD
+The text of a message to print immediately prior to printing the
+program's usage message.
+.ie n .IP """\-exitval""" 4
+.el .IP \f(CW\-exitval\fR 4
+.IX Item "-exitval"
+The desired exit status to pass to the \fBexit()\fR function.
+This should be an integer, or else the string "NOEXIT" to
+indicate that control should simply be returned without
+terminating the invoking process.
+.ie n .IP """\-output""" 4
+.el .IP \f(CW\-output\fR 4
+.IX Item "-output"
+A reference to a filehandle, or the pathname of a file to which the
+usage message should be written. The default is \f(CW\*(C`\e*STDERR\*(C'\fR unless the
+exit value is less than 2 (in which case the default is \f(CW\*(C`\e*STDOUT\*(C'\fR).
+.RE
+.RS 4
+.Sp
+You cannot tie this routine directly to an option, e.g.:
+.Sp
+.Vb 1
+\&    GetOptions("version" => \e&VersionMessage);
+.Ve
+.Sp
+Use this instead:
+.Sp
+.Vb 1
+\&    GetOptions("version" => sub { VersionMessage() });
+.Ve
+.RE
+.IP HelpMessage 4
+.IX Item "HelpMessage"
+This subroutine produces a standard help message, derived from the
+program's POD section SYNOPSIS using Pod::Usage. It takes the same
+arguments as \fBVersionMessage()\fR. In particular, you cannot tie it
+directly to an option, e.g.:
+.Sp
+.Vb 1
+\&    GetOptions("help" => \e&HelpMessage);
+.Ve
+.Sp
+Use this instead:
+.Sp
+.Vb 1
+\&    GetOptions("help" => sub { HelpMessage() });
+.Ve
+.SH "Return values and Errors"
+.IX Header "Return values and Errors"
+Configuration errors and errors in the option definitions are
+signalled using \fBdie()\fR and will terminate the calling program unless
+the call to \fBGetopt::Long::GetOptions()\fR was embedded in \f(CW\*(C`eval { ...
+}\*(C'\fR, or \fBdie()\fR was trapped using \f(CW$SIG{_\|_DIE_\|_}\fR.
+.PP
+GetOptions returns true to indicate success.
+It returns false when the function detected one or more errors during
+option parsing. These errors are signalled using \fBwarn()\fR and can be
+trapped with \f(CW$SIG{_\|_WARN_\|_}\fR.
+.SH Legacy
+.IX Header "Legacy"
+The earliest development of \f(CW\*(C`newgetopt.pl\*(C'\fR 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'.
+.SS "Default destinations"
+.IX Subsection "Default destinations"
+When no destination is specified for an option, GetOptions will store
+the resultant value in a global variable named \f(CW\*(C`opt_\*(C'\fR\fIXXX\fR, where
+\&\fIXXX\fR is the primary name of this option. When a program executes
+under \f(CW\*(C`use strict\*(C'\fR (recommended), these variables must be
+pre-declared with \fBour()\fR or \f(CW\*(C`use vars\*(C'\fR.
+.PP
+.Vb 2
+\&    our $opt_length = 0;
+\&    GetOptions (\*(Aqlength=i\*(Aq);    # will store in $opt_length
+.Ve
+.PP
+To yield a usable Perl variable, characters that are not part of the
+syntax for variables are translated to underscores. For example,
+\&\f(CW\*(C`\-\-fpp\-struct\-return\*(C'\fR will set the variable
+\&\f(CW$opt_fpp_struct_return\fR. Note that this variable resides in the
+namespace of the calling program, not necessarily \f(CW\*(C`main\*(C'\fR. For
+example:
+.PP
+.Vb 1
+\&    GetOptions ("size=i", "sizes=i@");
+.Ve
+.PP
+with command line "\-size 10 \-sizes 24 \-sizes 48" will perform the
+equivalent of the assignments
+.PP
+.Vb 2
+\&    $opt_size = 10;
+\&    @opt_sizes = (24, 48);
+.Ve
+.SS "Alternative option starters"
+.IX Subsection "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).
+.PP
+.Vb 2
+\&    my $len = 0;
+\&    GetOptions (\*(Aq/\*(Aq, \*(Aqlength=i\*(Aq => $len);
+.Ve
+.PP
+Now the command line may look like:
+.PP
+.Vb 1
+\&    /length 24 \-\- arg
+.Ve
+.PP
+Note that to terminate options processing still requires a double dash
+\&\f(CW\*(C`\-\-\*(C'\fR.
+.PP
+\&\fBGetOptions()\fR will not interpret a leading \f(CW"<>"\fR as option starters
+if the next argument is a reference. To force \f(CW"<"\fR and \f(CW">"\fR as
+option starters, use \f(CW"><"\fR. Confusing? Well, \fBusing a starter
+argument is strongly deprecated\fR anyway.
+.SS "Configuration variables"
+.IX Subsection "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 \f(CW\*(C`Configure\*(C'\fR routine that was introduced
+in version 2.17. Besides, it is much easier.
+.SH "Tips and Techniques"
+.IX Header "Tips and Techniques"
+.SS "Pushing multiple values in a hash option"
+.IX Subsection "Pushing multiple values in a hash option"
+Sometimes you want to combine the best of hashes and arrays. For
+example, the command line:
+.PP
+.Vb 1
+\&  \-\-list add=first \-\-list add=second \-\-list add=third
+.Ve
+.PP
+where each successive 'list add' option will push the value of add
+into array ref \f(CW$list\fR\->{'add'}. The result would be like
+.PP
+.Vb 1
+\&  $list\->{add} = [qw(first second third)];
+.Ve
+.PP
+This can be accomplished with a destination routine:
+.PP
+.Vb 2
+\&  GetOptions(\*(Aqlist=s%\*(Aq =>
+\&               sub { push(@{$list{$_[1]}}, $_[2]) });
+.Ve
+.SH Troubleshooting
+.IX Header "Troubleshooting"
+.SS "GetOptions does not return a false result when an option is not supplied"
+.IX Subsection "GetOptions does not return a false result when an option is not supplied"
+That's why they're called 'options'.
+.SS "GetOptions does not split the command line correctly"
+.IX Subsection "GetOptions does not split the command line correctly"
+The command line is not split by GetOptions, but by the command line
+interpreter (CLI). On Unix, this is the shell. On Windows, it is
+COMMAND.COM or CMD.EXE. Other operating systems have other CLIs.
+.PP
+It is important to know that these CLIs may behave different when the
+command line contains special characters, in particular quotes or
+backslashes. For example, with Unix shells you can use single quotes
+(\f(CW\*(C`\*(Aq\*(C'\fR) and double quotes (\f(CW\*(C`"\*(C'\fR) to group words together. The following
+alternatives are equivalent on Unix:
+.PP
+.Vb 3
+\&    "two words"
+\&    \*(Aqtwo words\*(Aq
+\&    two\e words
+.Ve
+.PP
+In case of doubt, insert the following statement in front of your Perl
+program:
+.PP
+.Vb 1
+\&    print STDERR (join("|",@ARGV),"\en");
+.Ve
+.PP
+to verify how your CLI passes the arguments to the program.
+.SS "Undefined subroutine &main::GetOptions called"
+.IX Subsection "Undefined subroutine &main::GetOptions called"
+Are you running Windows, and did you write
+.PP
+.Vb 1
+\&    use GetOpt::Long;
+.Ve
+.PP
+(note the capital 'O')?
+.SS "How do I put a ""\-?"" option into a Getopt::Long?"
+.IX Subsection "How do I put a ""-?"" option into a Getopt::Long?"
+You can only obtain this using an alias, and Getopt::Long of at least
+version 2.13.
+.PP
+.Vb 2
+\&    use Getopt::Long;
+\&    GetOptions ("help|?");    # \-help and \-? will both set $opt_help
+.Ve
+.PP
+Other characters that can't appear in Perl identifiers are also
+supported in aliases with Getopt::Long of at version 2.39. Note that
+the characters \f(CW\*(C`!\*(C'\fR, \f(CW\*(C`|\*(C'\fR, \f(CW\*(C`+\*(C'\fR, \f(CW\*(C`=\*(C'\fR, and \f(CW\*(C`:\*(C'\fR can only appear as the
+first (or only) character of an alias.
+.PP
+As of version 2.32 Getopt::Long provides auto-help, a quick and easy way
+to add the options \-\-help and \-? to your program, and handle them.
+.PP
+See \f(CW\*(C`auto_help\*(C'\fR in section "Configuring Getopt::Long".
+.SH AUTHOR
+.IX Header "AUTHOR"
+Johan Vromans <jvromans@squirrel.nl>
+.SH "COPYRIGHT AND DISCLAIMER"
+.IX Header "COPYRIGHT AND DISCLAIMER"
+This program is Copyright 1990,2015 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.
+.PP
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+.PP
+If you do not have a copy of the GNU General Public License write to
+the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
+MA 02139, USA.