develooper Front page | perl.perl5.porters | Postings from May 2003

ANNOUNCE: Getopt::Long 2.33

Thread Next
May 20, 2003 01:51
ANNOUNCE: Getopt::Long 2.33
Message ID:
Version 2.33 of module Getopt::Long has been released to CPAN. It will
be standard part of Perl 5.8.1 and 5.9.

Module Getopt::Long implements an extended getopt function called
GetOptions(). This function implements the POSIX standard for command
line options, with GNU extensions, while still capable of handling
the traditional one-letter options (including option bundling).
It adds a lot of features like automatic abbreviation of option names,
aliases and callback functions.

The README document is attached to this message.

The easiest way to get it is by using the CPAN shell:

   perl -MCPAN -e 'install("Getopt::Long")'

Alternatively, use a Web browser and point it to the CPAN search engine:

Changes in this version

**************** WARNING -- EXPERIMENTAL CODE AHEAD ****************

The following new features are marked experimental. This means that if
you are going to use them you _must_ watch out for the next release of
Getopt::Long to see if the API has changed.

* Getopt::Long can automatically handle --version and --help options
  if the calling program did not specify a handler explicitly.

  Two configuration parameters have been added: 'auto_help' (or
  'help') and 'auto_version' (or 'version'). If set, Getopt::Long will
  itself take care of --help and --version options. Otherwise,
  everything is exactly as it was before.

  The new features will be enabled by default for programs that
  explicitly require version 2.3203 or later.

  Getopt::Long uses module Pod::Usage to produce the help message from
  the SYNOPSIS section of the program's POD.

  Using a --help (or -?) command line option will write the SYNOPSIS
  section of the program's POD to STDOUT, and exit with status 0.
  However, an illegal option will produce the help text to STDERR,
  and exit with status 2. This is in accordance with current

* Two subroutines can be exported on demand:

  - VersionMessage

    This subroutine prints the standard version message.

  - HelpMessage

    This subroutine prints the standard help message.

  Both subroutines take the same arguments as Pod::Usage::pod2usage,
  see its documentation for details.  


    use Getopt::Long 2.33 qw(GetOptions HelpMessage);
    GetOptions(...) or HelpMessage(2);

**************** END EXPERIMENTAL CODE ****************

* Subroutine Configure can now be exported on demand.

* Negatable options (with "!") now also support the "no-" prefix.
  On request of Ed Avis.

* Some fixes with hashes and bundling.
  Thanks to Anders Johnson and Andrei Gnepp.
  Mandatory/optional status for hash values is now effective.
  String valued options with no value now default to the empty string
  instead of 1 (one).
  NOTE: The hash options still remain more or less experimental.

* Fix a pass_through bug where the options terminator (normally "--")
  was not passed through in @ARGV.
  Thanks to Philippe Verdret.

* Add FAQ: I "use GetOpt::Long;" (Windows) and now it doesn't work.

Previous released version was 2.32.

---- README ----

Module Getopt::Long - extended processing of command line options

Module Getopt::Long implements an extended getopt function called
GetOptions(). This function implements the POSIX standard for command
line options, with GNU extensions, while still capable of handling
the traditional one-letter options.
In general, this means that command line options can have long names
instead of single letters, and are introduced with a double dash `--'.

Optionally, Getopt::Long can support the traditional bundling of
single-letter command line options.

Getopt::Long::GetOptions() is part of the Perl 5 distribution. It is
the successor of that came with Perl 4. It is fully
upward compatible. In fact, the Perl 5 version of is just
a wrapper around the module.

For complete documentation, see the Getopt::Long POD document or use
the command

    perldoc Getopt::Long


* Long option names

Major advantage of using long option names is that it is much easier
to memorize the option names. Using single-letter names one quickly
runs into the problem that there is no logical relationship between
the semantics of the selected option and its option letter.
Disadvantage is that it requires more typing. Getopt::Long provides
for option name abbreviation, so option names may be abbreviated to
uniqueness. Also, modern shells like Cornell's tcsh support option
name completion. As a rule of thumb, you can use abbreviations freely
while running commands interactively but always use the full names in

Examples (POSIX):

    --long --width=80 --height=24


    -long (convenience) +width=80 (deprecated) -height 24 (traditional)

By default, long option names are case insensitive.

* Single-letter options and bundling

When single-letter options are requested, Getopt::Long allows the
option names to be bundled, e.g. "-abc" is equivalent to "-a -b -c".
In this case, long option names must be introduced with the POSIX "--"


    -lgAd (bundle) -xw 80 (bundle, w takes a value) -xw80 (same)
    even -l24w80 (l = 24 and w = 80)

By default, single-letter option names are case sensitive.

* Flexibility:

  - options can have alternative names, using an alternative name
    will behave as if the primary name was used;
  - options can be negatable, e.g. "debug" will switch it on, while
    "nodebug" will switch it off.    
  - options can set values, but also add values producing an array
    of values instead of a single scalar value, or set values in a hash.

* Options linkage

Using Getopt::Long gives the programmer ultimate control over the
command line options and how they must be handled:

  - by setting a global variable in the calling program;
  - by setting a specified variable;
  - by entering the option name and the value in an associative array
    (hash) or object (if it is a blessed hash);
  - by calling a user-specified subroutine with the option name and
    the value as arguments (for hash options: the name, key and value);
  - combinations of the above.

* Customization:

The module can be customized by specifying settings in the 'use'
directive, or by calling a special method, Getopt::Long::Configure.
For example, the following two cases are functionally equal:

    use Getopt::Long qw(:config bundling no_ignore_case);


    use Getopt::Long;
    Getopt::Long::Configure qw(bundling no_ignore_case);
Some of the possible customizations. Most of them take a "no_" prefix
to reverse the effect:

  - default

	Restore default settings.

  - auto_abbrev      

	Allow option names to be abbreviated to uniqueness. 

  - getopt_compat   

	Allow '+' to start options.

  - gnu_compat

	Compatibility with GNU getopt_long().

  - permute
  - require_order           

	Whether non-options are allowed to be mixed with options.

	permute means that 

	    -foo arg1 -bar arg2 arg3

	is equivalent to

	    -foo -bar arg1 arg2 arg3

	(provided -foo does not take an argument value).

	require_order means that options processing
	terminates when the first non-option is encountered.

	    -foo arg1 -bar arg2 arg3

	is equivalent to

	    -foo -- arg1 -bar arg2 arg3

  - bundling

	Setting this variable to a non-zero value will allow 
	single-character options to be bundled. To distinguish bundles
	from long option names, long options must be introduced with 
	"--" and single-character options (and bundles) with "-".

  - ignore_case      

	Ignore case when matching options.

  - pass_through

	Do not issue error messages for unknown options, but leave
	them (pass-through) in @ARGV.

  - prefix

	The string that starts options. See also prefix_pattern.

  - prefix_pattern

	A Perl pattern that identifies the strings that introduce
	options. Default is (--|-|\+) unless environment variable
	POSIXLY_CORRECT has been set, in which case it is (--|-).

  - debug

	Enable copious debugging output.

* Object oriented interface:

Using the object oriented interface, multiple parser objects can be
instantiated, each having their own configuration settings:

    $p1 = new Getopt::Long::Parser (config => ["bundling"]);
    $p2 = new Getopt::Long::Parser (config => ["posix"]);
    if ($p1->getoptions(...options descriptions...)) ...


The official version for module Getopt::Long comes with the Perl 5
Newer versions will be made available on the Comprehensive Perl Archive
Network (CPAN), see "".
Or use the CPAN search engine:


Module Getopt::Long is Copyright 2003,1990 by Johan Vromans.
This program is free software; you can redistribute it and/or
modify it under the terms of the Perl Artistic License or the
GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any
later version.

Johan Vromans                        
Squirrel Consultancy                       Haarlem, the Netherlands
------------------ "Arms are made for hugging" --------------------

Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About