1 Module Getopt::Long - extended processing of command line options
2 =================================================================
4 Module Getopt::Long implements an extended getopt function called
5 GetOptions(). This function implements the POSIX standard for command
6 line options, with GNU extensions, while still capable of handling
7 the traditional one-letter options.
8 In general, this means that command line options can have long names
9 instead of single letters, and are introduced with a double dash `--'.
11 Optionally, Getopt::Long can support the traditional bundling of
12 single-letter command line options.
14 Getopt::Long::GetOptions() is part of the Perl 5 distribution. It is
15 the successor of newgetopt.pl that came with Perl 4. It is fully
16 upward compatible. In fact, the Perl 5 version of newgetopt.pl is just
17 a wrapper around the module.
19 For complete documentation, see the Getopt::Long POD document or use
29 Major advantage of using long option names is that it is much easier
30 to memorize the option names. Using single-letter names one quickly
31 runs into the problem that there is no logical relationship between
32 the semantics of the selected option and its option letter.
33 Disadvantage is that it requires more typing. Getopt::Long provides
34 for option name abbreviation, so option names may be abbreviated to
35 uniqueness. Also, modern shells like Cornell's tcsh support option
36 name completion. As a rule of thumb, you can use abbreviations freely
37 while running commands interactively but always use the full names in
42 --long --width=80 --height=24
46 -long (convenience) +width=80 (deprecated) -height 24 (traditional)
48 By default, long option names are case insensitive.
50 * Single-letter options and bundling
52 When single-letter options are requested, Getopt::Long allows the
53 option names to be bundled, e.g. "-abc" is equivalent to "-a -b -c".
54 In this case, long option names must be introduced with the POSIX "--"
59 -lgAd (bundle) -xw 80 (bundle, w takes a value) -xw80 (same)
60 even -l24w80 (l = 24 and w = 80)
62 By default, single-letter option names are case sensitive.
66 - options can have alternative names, using an alternative name
67 will behave as if the primary name was used;
68 - options can be negatable, e.g. "debug" will switch it on, while
69 "nodebug" will switch it off.
70 - options can set values, but also add values producing an array
71 of values instead of a single scalar value, or set values in a hash.
75 Using Getopt::Long gives the programmer ultimate control over the
76 command line options and how they must be handled:
78 - by setting a global variable in the calling program;
79 - by setting a specified variable;
80 - by entering the option name and the value in an associative array
81 (hash) or object (if it is a blessed hash);
82 - by calling a user-specified subroutine with the option name and
83 the value as arguments (for hash options: the name, key and value);
84 - combinations of the above.
88 The module can be customized by specifying settings in the 'use'
89 directive, or by calling a special method, Getopt::Long::Configure.
90 For example, the following two cases are functionally equal:
92 use Getopt::Long qw(:config bundling no_ignore_case);
97 Getopt::Long::Configure qw(bundling no_ignore_case);
99 Some of the possible customizations. Most of them take a "no_" prefix
100 to reverse the effect:
104 Restore default settings.
108 Allow option names to be abbreviated to uniqueness.
112 Allow '+' to start options.
116 Compatibility with GNU getopt_long().
121 Whether non-options are allowed to be mixed with options.
125 -foo arg1 -bar arg2 arg3
129 -foo -bar arg1 arg2 arg3
131 (provided -foo does not take an argument value).
133 require_order means that options processing
134 terminates when the first non-option is encountered.
136 -foo arg1 -bar arg2 arg3
140 -foo -- arg1 -bar arg2 arg3
144 Setting this variable to a non-zero value will allow
145 single-character options to be bundled. To distinguish bundles
146 from long option names, long options must be introduced with
147 "--" and single-character options (and bundles) with "-".
151 Ignore case when matching options.
155 Do not issue error messages for unknown options, but leave
156 them (pass-through) in @ARGV.
160 The string that starts options. See also prefix_pattern.
164 A Perl pattern that identifies the strings that introduce
165 options. Default is (--|-|\+) unless environment variable
166 POSIXLY_CORRECT has been set, in which case it is (--|-).
170 Enable copious debugging output.
172 * Object oriented interface:
174 Using the object oriented interface, multiple parser objects can be
175 instantiated, each having their own configuration settings:
177 $p1 = new Getopt::Long::Parser (config => ["bundling"]);
178 $p2 = new Getopt::Long::Parser (config => ["posix"]);
179 if ($p1->getoptions(...options descriptions...)) ...
184 The official version for module Getopt::Long comes with the Perl 5
186 Newer versions will be made available on the Comprehensive Perl Archive
187 Network (CPAN), see "http://www.perl.com/CPAN/authors/Johan_Vromans".
188 Or use the CPAN search engine:
189 http://search.cpan.org/search?mode=module&query=Getopt::Long
190 http://search.cpan.org/search?module=Getopt::Long
192 COPYRIGHT AND DISCLAIMER
193 ========================
195 Module Getopt::Long is Copyright 2003,1990 by Johan Vromans.
196 This program is free software; you can redistribute it and/or
197 modify it under the terms of the Perl Artistic License or the
198 GNU General Public License as published by the Free Software
199 Foundation; either version 2 of the License, or (at your option) any
202 -------------------------------------------------------------------
203 Johan Vromans jvromans@squirrel.nl
204 Squirrel Consultancy Haarlem, the Netherlands
205 http://www.squirrel.nl http://www.squirrel.nl/people/jvromans
206 ------------------ "Arms are made for hugging" --------------------