--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.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
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Getopt::Long 3"
+.TH Getopt::Long 3 "2009-03-30" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Getopt::Long \- Extended processing of command line options
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 7
+\& use Getopt::Long;
+\& my $data = "file.dat";
+\& my $length = 24;
+\& my $verbose;
+\& $result = GetOptions ("length=i" => \e$length, # numeric
+\& "file=s" => \e$data, # string
+\& "verbose" => \e$verbose); # flag
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The Getopt::Long module implements an extended getopt function called
+\&\fIGetOptions()\fR. This function adheres to the \s-1POSIX\s0 syntax for command
+line options, with \s-1GNU\s0 extensions. In general, this means that options
+have long names instead of single letters, and are introduced with a
+double dash \*(L"\-\-\*(R". 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, hence the name Getopt::Long. This module also
+supports single-character options and bundling. Single character
+options may be any alphabetic character, a question mark, and a dash.
+Long options may consist of a series of letters, digits, and dashes.
+Although this is currently not enforced by Getopt::Long, multiple
+consecutive dashes are not allowed, and the option name must not end
+with a dash.
+.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 \*(L"Configuring Getopt::Long\*(R" for more
+details on how to configure Getopt::Long.
+.Sh "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 = ''; # option variable with default value (false)
+\& my $all = ''; # option variable with default value (false)
+\& GetOptions ('verbose' => \e$verbose, 'all' => \e$all);
+.Ve
+.PP
+The call to \fIGetOptions()\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 \fIGetOptions()\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
+\&\fIGetOptions()\fR will return a true value if the command line could be
+processed successfully. Otherwise, it will write error messages to
+\&\s-1STDERR\s0, and return a false result.
+.Sh "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 = ''; # option variable with default value (false)
+\& GetOptions ('verbose!' => \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
+An incremental option is specified with a plus \f(CW\*(C`+\*(C'\fR after the
+option name:
+.PP
+.Vb 2
+\& my $verbose = ''; # option variable with default value (false)
+\& GetOptions ('verbose+' => \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.
+.Sh "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.
+.Sh "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 = ''; # option variable with default value
+\& GetOptions ('tag=s' => \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''\fR assigned, while numeric options are set to \f(CW0\fR.
+.Sh "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 \*(L"@\*(R", and pass a scalar reference as the
+destination:
+.PP
+.Vb 1
+\& GetOptions ("library=s@" => \e$libfiles);
+.Ve
+.PP
+Used with the example above, \f(CW@libfiles\fR (or \f(CW@$libfiles\fR) would
+contain two strings upon completion: \f(CW"lib/srdlib"\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 \fIsplit()\fR
+and \fIjoin()\fR operators:
+.PP
+.Vb 2
+\& GetOptions ("library=s" => \e@libfiles);
+\& @libfiles = split(/,/,join(',',@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('coordinates=f{2}' => \e@coor, 'rgbcolor=i{3}' => \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{,}\*(C'\fR indicates one
+or more values; \f(CW\*(C`foo:s{,}\*(C'\fR indicates zero or more option values.
+.Sh "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.
+.Sh "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 \fIGetOptions()\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 arguments 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 = ''; # option variable with default value (false)
+\& GetOptions ('verbose' => \e$verbose,
+\& 'quiet' => 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 \fIdie()\fR with
+the desired error message as its argument. \fIGetOptions()\fR will catch the
+\&\fIdie()\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 \fIGetOptions()\fR. There is currently one
+special command implemented: \f(CW\*(C`die("!FINISH")\*(C'\fR will cause \fIGetOptions()\fR
+to stop processing options, as if it encountered a double dash \f(CW\*(C`\-\-\*(C'\fR.
+.PP
+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.
+.Sh "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 ('length|height=f' => \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.
+.Sh "Case and abbreviations"
+.IX Subsection "Case and abbreviations"
+Without additional configuration, \fIGetOptions()\fR will ignore the case of
+option names, and allow the options to be abbreviated to uniqueness.
+.PP
+.Vb 1
+\& GetOptions ('length|height=f' => \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.
+.Sh "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 \*(L"no\*(R" or \*(L"no\-\*(R". 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
+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\*(C`\-6.23E24\*(C'\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.
+.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"
+.Sh "Object oriented interface"
+.IX Subsection "Object oriented interface"
+Getopt::Long can be used in an object oriented way as well:
+.PP
+.Vb 4
+\& use Getopt::Long;
+\& $p = new Getopt::Long::Parser;
+\& $p\->configure(...configuration options...);
+\& if ($p\->getoptions(...options descriptions...)) ...
+.Ve
+.PP
+Configuration options can be passed to the constructor:
+.PP
+.Vb 2
+\& $p = new Getopt::Long::Parser
+\& config => [...configuration options...];
+.Ve
+.Sh "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.
+.Sh "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;
+.Ve
+.PP
+.Vb 2
+\& my $man = 0;
+\& my $help = 0;
+.Ve
+.PP
+.Vb 3
+\& GetOptions('help|?' => \e$help, man => \e$man) or pod2usage(2);
+\& pod2usage(1) if $help;
+\& pod2usage(\-exitstatus => 0, \-verbose => 2) if $man;
+.Ve
+.PP
+.Vb 1
+\& __END__
+.Ve
+.PP
+.Vb 1
+\& =head1 NAME
+.Ve
+.PP
+.Vb 1
+\& sample \- Using Getopt::Long and Pod::Usage
+.Ve
+.PP
+.Vb 1
+\& =head1 SYNOPSIS
+.Ve
+.PP
+.Vb 1
+\& sample [options] [file ...]
+.Ve
+.PP
+.Vb 3
+\& Options:
+\& \-help brief help message
+\& \-man full documentation
+.Ve
+.PP
+.Vb 1
+\& =head1 OPTIONS
+.Ve
+.PP
+.Vb 1
+\& =over 8
+.Ve
+.PP
+.Vb 1
+\& =item B<\-help>
+.Ve
+.PP
+.Vb 1
+\& Print a brief help message and exits.
+.Ve
+.PP
+.Vb 1
+\& =item B<\-man>
+.Ve
+.PP
+.Vb 1
+\& Prints the manual page and exits.
+.Ve
+.PP
+.Vb 1
+\& =back
+.Ve
+.PP
+.Vb 1
+\& =head1 DESCRIPTION
+.Ve
+.PP
+.Vb 2
+\& B<This program> will read the given input file(s) and do something
+\& useful with the contents thereof.
+.Ve
+.PP
+.Vb 1
+\& =cut
+.Ve
+.PP
+See Pod::Usage for details.
+.Sh "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, 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
+.Sh "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.
+.Sh "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. \fIGetOptions()\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 \fIGetOptions()\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(CW\*(C`exists($h{option})\*(C'\fR (or \fIdefined()\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
+\&\fIexists()\fR or \fIdefined()\fR first.
+.PP
+.Vb 2
+\& my %h = ();
+\& GetOptions (\e%h, 'length=i'); # 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, 'colours=s@'); # 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 = ('length' => \e$len);
+\& GetOptions (\e%h, 'length=i'); # will store in $len
+.Ve
+.PP
+This example is fully equivalent with:
+.PP
+.Vb 2
+\& my $len = 0;
+\& GetOptions ('length=i' => \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 = ('verbose' => \e$verbose, 'debug' => \e$debug);
+\& GetOptions (\e%h, 'verbose', 'debug', 'filter', 'size=i');
+\& if ( $verbose ) { ... }
+\& if ( exists $h{filter} ) { ... option 'filter' was specified ... }
+.Ve
+.Sh "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
+would set all three.
+.PP
+Getopt::Long supports two levels of bundling. To enable bundling, a
+call to Getopt::Long::Configure is required.
+.PP
+The first level 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 \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
+would 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
+would set \f(CW\*(C`vax\*(C'\fR.
+.PP
+The second level 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 would set the option \f(CW\*(C`vax\*(C'\fR.
+.PP
+When any level of bundling is enabled, 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
+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.
+.Sh "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 \*(L"permute\*(R" 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 ('' => \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.
+.Sh "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 \fIGetOptions()\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. Well, actually
+it is an object that stringifies to the argument name.
+.PP
+For example:
+.PP
+.Vb 3
+\& my $width = 80;
+\& sub process { ... }
+\& GetOptions ('width=i' => \e$width, '<>' => \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(CW\*(C`process("arg1")\*(C'\fR while \f(CW$width\fR is \f(CW80\fR,
+\&\f(CW\*(C`process("arg2")\*(C'\fR while \f(CW$width\fR is \f(CW72\fR, and
+\&\f(CW\*(C`process("arg3")\*(C'\fR while \f(CW$width\fR is \f(CW60\fR.
+.PP
+This feature requires configuration option \fBpermute\fR, see section
+\&\*(L"Configuring Getopt::Long\*(R".
+.SH "Configuring Getopt::Long"
+.IX Header "Configuring Getopt::Long"
+Getopt::Long can be configured by calling subroutine
+\&\fIGetopt::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, or disabled, e.g. \f(CW\*(C`no_ignore_case\*(C'\fR. Case does not
+matter. Multiple calls to \fIConfigure()\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 \s-1POSIXLY_CORRECT\s0 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
+\&\s-1POSIXLY_CORRECT\s0 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
+\&\s-1POSIXLY_CORRECT\s0 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 \s-1GNU\s0 \fIgetopt_long()\fR does it.
+.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
+fully compatible with \s-1GNU\s0 \fIgetopt_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
+\&\s-1POSIXLY_CORRECT\s0 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
+\&\s-1POSIXLY_CORRECT\s0 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 \fIGetOptions()\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 \fIGetOptions()\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
+\&\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 long 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 \s-1SYNOPSIS\s0 \s-1POD\s0 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)"
+Options that are unknown, ambiguous or supplied with an invalid option
+value are passed through in \f(CW@ARGV\fR instead of being flagged as
+errors. This makes it possible to write wrapper scripts that process
+only part of the user supplied command line arguments, and pass the
+remaining options to some other program.
+.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.
+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
+\&\s-1POSIXLY_CORRECT\s0 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 "*" 4
+A string containing the text of a message to print \fIbefore\fR printing
+the standard message.
+.IP "*" 4
+A numeric value corresponding to the desired exit status.
+.IP "*" 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 \fB\f(BIexit()\fB\fR function.
+This should be an integer, or else the string \*(L"\s-1NOEXIT\s0\*(R" 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 \s-1POD\s0 section \s-1SYNOPSIS\s0 using Pod::Usage. It takes the same
+arguments as \fIVersionMessage()\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 \fIdie()\fR and will terminate the calling program unless
+the call to \fIGetopt::Long::GetOptions()\fR was embedded in \f(CW\*(C`eval { ...
+}\*(C'\fR, or \fIdie()\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 \fIwarn()\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'.
+.Sh "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\fI\s-1XXX\s0\fR, where
+\&\fI\s-1XXX\s0\fR is the primary name of this option. When a progam executes
+under \f(CW\*(C`use strict\*(C'\fR (recommended), these variables must be
+pre-declared with \fIour()\fR or \f(CW\*(C`use vars\*(C'\fR.
+.PP
+.Vb 2
+\& our $opt_length = 0;
+\& GetOptions ('length=i'); # 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 \*(L"\-size 10 \-sizes 24 \-sizes 48\*(R" will perform the
+equivalent of the assignments
+.PP
+.Vb 2
+\& $opt_size = 10;
+\& @opt_sizes = (24, 48);
+.Ve
+.Sh "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 ('/', 'length=i' => $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
+\&\fIGetOptions()\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.
+.Sh "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"
+.Sh "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('list=s%' =>
+\& sub { push(@{$list{$_[1]}}, $_[2]) });
+.Ve
+.SH "Troubleshooting"
+.IX Header "Troubleshooting"
+.Sh "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'.
+.Sh "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 (\s-1CLI\s0). On Unix, this is the shell. On Windows, it is
+\&\s-1COMMAND\s0.COM or \s-1CMD\s0.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`'\*(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"
+\& 'two words'
+\& 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 \s-1CLI\s0 passes the arguments to the program.
+.Sh "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')?
+.ie n .Sh "How do I put a ""\-?"" option into a Getopt::Long?"
+.el .Sh "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
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Johan Vromans <jvromans@squirrel.nl>
+.SH "COPYRIGHT AND DISCLAIMER"
+.IX Header "COPYRIGHT AND DISCLAIMER"
+This program is Copyright 1990,2009 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
+\&\s-1GNU\s0 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 \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
+\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. See the
+\&\s-1GNU\s0 General Public License for more details.
+.PP
+If you do not have a copy of the \s-1GNU\s0 General Public License write to
+the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
+\&\s-1MA\s0 02139, \s-1USA\s0.
projects / catagits/Gitalist.git / blobdiff