This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Getopt-Long to CPAN version 2.42
[perl5.git] / cpan / Getopt-Long / README
CommitLineData
7d1b667f
JH
1Module Getopt::Long - extended processing of command line options
2=================================================================
3
4Module Getopt::Long implements an extended getopt function called
5GetOptions(). This function implements the POSIX standard for command
6line options, with GNU extensions, while still capable of handling
7the traditional one-letter options.
8In general, this means that command line options can have long names
9instead of single letters, and are introduced with a double dash `--'.
10
11Optionally, Getopt::Long can support the traditional bundling of
12single-letter command line options.
13
8de02997
RGS
14Getopt::Long is part of the Perl 5 distribution. It is the successor
15of newgetopt.pl that came with Perl 4. It is fully upward compatible.
16In fact, the Perl 5 version of newgetopt.pl is just a wrapper around
17the module.
7d1b667f
JH
18
19For complete documentation, see the Getopt::Long POD document or use
20the command
21
22 perldoc Getopt::Long
23
24FEATURES
25========
26
27* Long option names
28
29Major advantage of using long option names is that it is much easier
30to memorize the option names. Using single-letter names one quickly
31runs into the problem that there is no logical relationship between
32the semantics of the selected option and its option letter.
33Disadvantage is that it requires more typing. Getopt::Long provides
34for option name abbreviation, so option names may be abbreviated to
35uniqueness. Also, modern shells like Cornell's tcsh support option
36name completion. As a rule of thumb, you can use abbreviations freely
37while running commands interactively but always use the full names in
38scripts.
39
40Examples (POSIX):
41
42 --long --width=80 --height=24
43
44Extensions:
45
46 -long (convenience) +width=80 (deprecated) -height 24 (traditional)
47
48By default, long option names are case insensitive.
49
50* Single-letter options and bundling
51
52When single-letter options are requested, Getopt::Long allows the
53option names to be bundled, e.g. "-abc" is equivalent to "-a -b -c".
54In this case, long option names must be introduced with the POSIX "--"
55introducer.
56
57Examples:
58
59 -lgAd (bundle) -xw 80 (bundle, w takes a value) -xw80 (same)
60 even -l24w80 (l = 24 and w = 80)
61
62By default, single-letter option names are case sensitive.
63
64* Flexibility:
65
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.
554627f6 72 - options can have multiple values, e.g., "--position 25 624".
7d1b667f
JH
73
74* Options linkage
75
76Using Getopt::Long gives the programmer ultimate control over the
77command line options and how they must be handled:
78
79 - by setting a global variable in the calling program;
80 - by setting a specified variable;
81 - by entering the option name and the value in an associative array
82 (hash) or object (if it is a blessed hash);
83 - by calling a user-specified subroutine with the option name and
10933be5 84 the value as arguments (for hash options: the name, key and value);
7d1b667f
JH
85 - combinations of the above.
86
87* Customization:
88
10933be5
RGS
89The module can be customized by specifying settings in the 'use'
90directive, or by calling a special method, Getopt::Long::Configure.
91For example, the following two cases are functionally equal:
92
93 use Getopt::Long qw(:config bundling no_ignore_case);
94
95and
96
97 use Getopt::Long;
98 Getopt::Long::Configure qw(bundling no_ignore_case);
99
100Some of the possible customizations. Most of them take a "no_" prefix
101to reverse the effect:
7d1b667f
JH
102
103 - default
104
105 Restore default settings.
106
107 - auto_abbrev
108
109 Allow option names to be abbreviated to uniqueness.
110
111 - getopt_compat
112
113 Allow '+' to start options.
114
115 - gnu_compat
116
117 Compatibility with GNU getopt_long().
118
119 - permute
120 - require_order
121
122 Whether non-options are allowed to be mixed with options.
123
124 permute means that
125
126 -foo arg1 -bar arg2 arg3
127
128 is equivalent to
129
130 -foo -bar arg1 arg2 arg3
131
132 (provided -foo does not take an argument value).
133
134 require_order means that options processing
135 terminates when the first non-option is encountered.
136
137 -foo arg1 -bar arg2 arg3
138
139 is equivalent to
140
141 -foo -- arg1 -bar arg2 arg3
142
143 - bundling
144
145 Setting this variable to a non-zero value will allow
146 single-character options to be bundled. To distinguish bundles
147 from long option names, long options must be introduced with
148 "--" and single-character options (and bundles) with "-".
149
150 - ignore_case
151
152 Ignore case when matching options.
153
154 - pass_through
155
156 Do not issue error messages for unknown options, but leave
157 them (pass-through) in @ARGV.
158
159 - prefix
160
161 The string that starts options. See also prefix_pattern.
162
163 - prefix_pattern
164
165 A Perl pattern that identifies the strings that introduce
554627f6
RGS
166 options. Default is --|-|\+ unless environment variable
167 POSIXLY_CORRECT has been set, in which case it is --|-.
168
169 - long_prefix_pattern
170
171 A perl pattern that is used to identify which prefixes
172 should be treated as long style. Any prefixes that don't
173 match this pattern will have short option semantics.
174 Defaults to --.
7d1b667f
JH
175
176 - debug
177
178 Enable copious debugging output.
179
180* Object oriented interface:
181
182Using the object oriented interface, multiple parser objects can be
183instantiated, each having their own configuration settings:
184
79d0183a
RGS
185 $p1 = new Getopt::Long::Parser (config => ["bundling"]);
186 $p2 = new Getopt::Long::Parser (config => ["posix"]);
7d1b667f
JH
187 if ($p1->getoptions(...options descriptions...)) ...
188
189AVAILABILITY
190============
191
192The official version for module Getopt::Long comes with the Perl 5
193distribution.
194Newer versions will be made available on the Comprehensive Perl Archive
195Network (CPAN), see "http://www.perl.com/CPAN/authors/Johan_Vromans".
196Or use the CPAN search engine:
197 http://search.cpan.org/search?mode=module&query=Getopt::Long
198 http://search.cpan.org/search?module=Getopt::Long
199
200COPYRIGHT AND DISCLAIMER
201========================
202
654bf526 203Module Getopt::Long is Copyright 2013,1990 by Johan Vromans.
7d1b667f
JH
204This program is free software; you can redistribute it and/or
205modify it under the terms of the Perl Artistic License or the
206GNU General Public License as published by the Free Software
207Foundation; either version 2 of the License, or (at your option) any
208later version.
209
210-------------------------------------------------------------------
211Johan Vromans jvromans@squirrel.nl
554627f6 212Squirrel Consultancy Exloo, the Netherlands
7d1b667f
JH
213http://www.squirrel.nl http://www.squirrel.nl/people/jvromans
214------------------ "Arms are made for hugging" --------------------