lib/Getopt/Long.pm

3 # Getopt::Long.pm -- Universal options parsing
82 	$autoabbrev = 0;		# no automatic abbrev of options
84 	$getopt_compat = 0;		# disallow '+' to start options
89 	$autoabbrev = 1;		# automatic abbrev of options
91 	$getopt_compat = 1;		# allow '+' to start options
97     $ignorecase = 1;		# ignore case when matching options
98     $passthrough = 0;		# leave unrecognized options alone
296     my @ret = ();		# accum for non-options
500     # Show the options tables if debugging.
731 	    # Try non-options call-back.
984 	# If bundling == 2, long options can override bundles.
1043 	    # Remove auto-supplied options (version, help).
1354     my (@options) = @_;
1362     if ( ref($options[0]) eq 'ARRAY' ) {
1366 	  $longprefix, $bundling_values ) = @{shift(@options)};
1370     foreach $opt ( @options ) {
1484 #  - a hash with options. See Pod::Usage for details.
1513 #  - a hash with options. See Pod::Usage for details.
1545     # (message) or hash with options.
1600 Getopt::Long - Extended processing of command line options
1617 and removing specified options and their possible values.
1620 line options, with GNU extensions. In general, this means that options
1622 double dash "--". Support for bundling of command line options, as was
1631 command line I<options> as well. Options are not necessary for the
1637 Command line options come in several flavours. Historically, they are
1642 Usually, these single-character options can be bundled:
1651 Due to the very cryptic nature of these options, another style was
1654 bundle of single-character options and a long one, two dashes are used
1655 to precede the option name. Early implementations of long options used
1671 command line options, in particular long option names, hence the Perl5
1672 name Getopt::Long. This module also supports single-character options
1684 In the default configuration, options names may be abbreviated to
1686 even for long option names. Also, options may be placed between
1690 =head2 Simple options
1692 The most simple options are the ones that take no values. Their mere
1697 Handling simple options is straightforward:
1718 =head2 A little bit less simple options
1720 Getopt::Long supports two useful variants of simple options:
1721 I<negatable> options and I<incremental> options.
1751 Usually programs take command line options as well as other arguments,
1753 options first, and the other arguments last. Getopt::Long will,
1754 however, allow the options and arguments to be mixed and 'filter out'
1755 all the options before passing the rest of the arguments to the
1766 For options that take values it must be specified whether the option
1787 this case, if no suitable value is supplied, string valued options get
1788 an empty string C<''> assigned, while numeric options are set to C<0>.
1818 multiple occurrences of the options. This is easy using Perl's split()
1859 When used with command line options:
1868 =head2 User-defined subroutines to handle options
1882 A trivial application of this mechanism is to implement options that
1900 to stop processing options, as if it encountered a double dash C<-->.
1914 options. For example C<--height> could be an alternate name for
1922 called I<aliases>. When using a hash to store options, the key will
1930 option names, and allow the options to be abbreviated to uniqueness.
1935 requires a least C<--hea> and C<--hei> for the head and height options.
2018 options with C<=> and to 0 for options with C<:>, see below. Note that
2028 If omitted, an empty string will be assigned to string values options,
2029 and the value zero to numeric options.
2055     $p->configure(...configuration options...);
2056     if ($p->getoptions(...options descriptions...)) ...
2057     if ($p->getoptionsfromarray( \@array, ...options descriptions...)) ...
2059 Configuration options can be passed to the constructor:
2062              config => [...configuration options...];
2116     sample [options] [file ...]
2145 =head2 Parsing options from an arbitrary array
2147 By default, GetOptions parses the options that are present in the
2149 used to parse options from an arbitrary array.
2154 When used like this, options and their possible values are removed
2168 =head2 Parsing options from an arbitrary string
2170 A special entry C<GetOptionsFromString> can be used to parse options
2194 =head2 Storing options values in a hash
2196 Sometimes, for example when there are a lot of options, having a
2198 supports, as an alternative mechanism, storing options values in a
2214 For options that take list or hash values, it is necessary to indicate
2231 Any mixture is possible. For example, the most frequently used options
2232 could be stored in variables while all other options get stored in the
2244 With bundling it is possible to set several single-character options
2245 at once. For example if C<a>, C<v> and C<x> are all valid options,
2258 Configured this way, single-character options can be bundled but long
2259 options (and any of their auto-abbreviated shortened forms) B<must>
2261 when C<vax>, C<a>, C<v> and C<x> are all valid options,
2288 options. It can be enabled with:
2298 When configured for bundling, single-character options are matched
2299 case sensitive while long options are matched case insensitive. To
2300 have the single-character options matched case insensitive as well,
2356 Alternatively, as of version 2.24, the configuration options may be
2361 The following options are available:
2367 This option causes all configuration options to be reset to their
2372 This option causes all configuration options to be reset to their
2384 Allow C<+> to start options.
2406 Whether command line arguments are allowed to be mixed with options.
2414 Whether command line arguments are allowed to be mixed with options.
2428 empty upon successful return of GetOptions() since all options have been
2436 If C<require_order> is enabled, options processing
2445 If C<pass_through> is also enabled, options processing will terminate
2451 Enabling this option will allow single-character options to be
2452 bundled. To distinguish bundles from long option names, long options
2456 Note that, if you have options C<a>, C<l> and C<all>, and
2479 especially when mixing long options and bundles. Caveat emptor.
2484 bundling is enabled as well, single character options will be treated
2487 With C<ignore_case>, option specifications for options that only
2496 options also.
2516 Automatically provide support for the B<--help> and B<-?> options if
2534 remaining options to some other program.
2536 If C<require_order> is enabled, options processing will terminate at the
2542 Note that the options terminator (default C<-->), if present, will
2547 The string that starts options. If a constant string is not
2552 A Perl pattern that identifies the strings that introduce options.
2713 Note that to terminate options processing still requires a double dash
2751 That's why they're called 'options'.
2798 to add the options --help and -? to your program, and handle them.