<H2><A NAME="documentation and help texts">Documentation and help texts</A></H2>
<P>Getopt::Long encourages the use of Pod::Usage to produce help
messages. For example:</P>
<PRE>
use Getopt::Long;
use Pod::Usage;</PRE>
<PRE>
my $man = 0;
my $help = 0;</PRE>
<PRE>
GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
pod2usage(1) if $help;
pod2usage(-exitstatus => 0, -verbose => 2) if $man;</PRE>
<PRE>
__END__</PRE>
<PRE>
=head1 NAME</PRE>
<PRE>
sample - Using GetOpt::Long and Pod::Usage</PRE>
<PRE>
=head1 SYNOPSIS</PRE>
<PRE>
sample [options] [file ...]</PRE>
<PRE>
Options:
-help brief help message
-man full documentation</PRE>
<PRE>
=head1 OPTIONS</PRE>
<PRE>
=over 8</PRE>
<PRE>
=item B<-help></PRE>
<PRE>
Print a brief help message and exits.</PRE>
<PRE>
=item B<-man></PRE>
<PRE>
Prints the manual page and exits.</PRE>
<PRE>
=back</PRE>
<PRE>
=head1 DESCRIPTION</PRE>
<PRE>
B<This program> will read the given input file(s) and do someting
useful with the contents thereof.</PRE>
<PRE>
=cut</PRE>
<P>See <A HREF="../../lib/Pod/Usage.html">the Pod::Usage manpage</A> for details.</P>
<P>
<H2><A NAME="storing options in a hash">Storing options in a hash</A></H2>
<P>Sometimes, for example when there are a lot of options, having a
separate variable for each of them can be cumbersome. <CODE>GetOptions()</CODE>
supports, as an alternative mechanism, storing options in a hash.</P>
<P>To obtain this, a reference to a hash must be passed <EM>as the first
argument</EM> to GetOptions(). For each option that is specified on the
command line, the option value will be stored in the hash with the
option name as key. Options that are not actually used on the command
line will not be put in the hash, on other words,
<A HREF="../../lib/Pod/perlfunc.html#item_exists"><CODE>exists($h{option})</CODE></A> (or <A HREF="../../lib/Pod/perlfunc.html#item_defined"><CODE>defined())</CODE></A> can be used to test if an option
was used. The drawback is that warnings will be issued if the program
runs under <CODE>use strict</CODE> and uses <CODE>$h{option}</CODE> without testing with
<A HREF="../../lib/Pod/perlfunc.html#item_exists"><CODE>exists()</CODE></A> or <A HREF="../../lib/Pod/perlfunc.html#item_defined"><CODE>defined()</CODE></A> first.</P>
<PRE>
my %h = ();
GetOptions (\%h, 'length=i'); # will store in $h{length}</PRE>
<P>For options that take list or hash values, it is necessary to indicate
this by appending an <CODE>@</CODE> or <CODE>%</CODE> sign after the type:</P>
<PRE>
GetOptions (\%h, 'colours=s@'); # will push to @{$h{colours}}</PRE>
<P>To make things more complicated, the hash may contain references to
the actual destinations, for example:</P>
<PRE>
my $len = 0;
my %h = ('length' => \$len);
GetOptions (\%h, 'length=i'); # will store in $len</PRE>
<P>This example is fully equivalent with:</P>
<PRE>
my $len = 0;
GetOptions ('length=i' => \$len); # will store in $len</PRE>
<P>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:</P>
<PRE>
my $verbose = 0; # frequently referred
my $debug = 0; # frequently referred
my %h = ('verbose' => \$verbose, 'debug' => \$debug);
Whether command line arguments are allowed to be mixed with options.
Default is set unless environment variable
POSIXLY_CORRECT has been set, in which case <A HREF="#item_require_order"><CODE>require_order</CODE></A> is reset.
<P>See also <A HREF="#item_permute"><CODE>permute</CODE></A>, which is the opposite of <A HREF="#item_require_order"><CODE>require_order</CODE></A>.</P>
