Commit | Line | Data |
---|---|---|
7d1b667f JH |
1 | Module Getopt::Long - extended processing of command line options |
2 | ================================================================= | |
3 | ||
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 `--'. | |
10 | ||
11 | Optionally, Getopt::Long can support the traditional bundling of | |
12 | single-letter command line options. | |
13 | ||
8de02997 RGS |
14 | Getopt::Long is part of the Perl 5 distribution. It is the successor |
15 | of newgetopt.pl that came with Perl 4. It is fully upward compatible. | |
16 | In fact, the Perl 5 version of newgetopt.pl is just a wrapper around | |
17 | the module. | |
7d1b667f JH |
18 | |
19 | For complete documentation, see the Getopt::Long POD document or use | |
20 | the command | |
21 | ||
22 | perldoc Getopt::Long | |
23 | ||
24 | FEATURES | |
25 | ======== | |
26 | ||
27 | * Long option names | |
28 | ||
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 | |
38 | scripts. | |
39 | ||
40 | Examples (POSIX): | |
41 | ||
42 | --long --width=80 --height=24 | |
43 | ||
44 | Extensions: | |
45 | ||
46 | -long (convenience) +width=80 (deprecated) -height 24 (traditional) | |
47 | ||
48 | By default, long option names are case insensitive. | |
49 | ||
50 | * Single-letter options and bundling | |
51 | ||
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 "--" | |
55 | introducer. | |
56 | ||
57 | Examples: | |
58 | ||
59 | -lgAd (bundle) -xw 80 (bundle, w takes a value) -xw80 (same) | |
60 | even -l24w80 (l = 24 and w = 80) | |
61 | ||
62 | By 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 | ||
76 | Using Getopt::Long gives the programmer ultimate control over the | |
77 | command 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 |
89 | The module can be customized by specifying settings in the 'use' |
90 | directive, or by calling a special method, Getopt::Long::Configure. | |
91 | For example, the following two cases are functionally equal: | |
92 | ||
93 | use Getopt::Long qw(:config bundling no_ignore_case); | |
94 | ||
95 | and | |
96 | ||
97 | use Getopt::Long; | |
98 | Getopt::Long::Configure qw(bundling no_ignore_case); | |
99 | ||
100 | Some of the possible customizations. Most of them take a "no_" prefix | |
101 | to 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 | ||
182 | Using the object oriented interface, multiple parser objects can be | |
183 | instantiated, 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 | ||
189 | AVAILABILITY | |
190 | ============ | |
191 | ||
192 | The official version for module Getopt::Long comes with the Perl 5 | |
193 | distribution. | |
194 | Newer versions will be made available on the Comprehensive Perl Archive | |
195 | Network (CPAN), see "http://www.perl.com/CPAN/authors/Johan_Vromans". | |
196 | Or 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 | ||
200 | COPYRIGHT AND DISCLAIMER | |
201 | ======================== | |
202 | ||
8de02997 | 203 | Module Getopt::Long is Copyright 2006,1990 by Johan Vromans. |
7d1b667f JH |
204 | This program is free software; you can redistribute it and/or |
205 | modify it under the terms of the Perl Artistic License or the | |
206 | GNU General Public License as published by the Free Software | |
207 | Foundation; either version 2 of the License, or (at your option) any | |
208 | later version. | |
209 | ||
210 | ------------------------------------------------------------------- | |
211 | Johan Vromans jvromans@squirrel.nl | |
554627f6 | 212 | Squirrel Consultancy Exloo, the Netherlands |
7d1b667f JH |
213 | http://www.squirrel.nl http://www.squirrel.nl/people/jvromans |
214 | ------------------ "Arms are made for hugging" -------------------- |