Commit | Line | Data |
7d1b667f |
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 | |
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. |
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. |
72 | |
73 | * Options linkage |
74 | |
75 | Using Getopt::Long gives the programmer ultimate control over the |
76 | command line options and how they must be handled: |
77 | |
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 |
10933be5 |
83 | the value as arguments (for hash options: the name, key and value); |
7d1b667f |
84 | - combinations of the above. |
85 | |
86 | * Customization: |
87 | |
10933be5 |
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: |
91 | |
92 | use Getopt::Long qw(:config bundling no_ignore_case); |
93 | |
94 | and |
95 | |
96 | use Getopt::Long; |
97 | Getopt::Long::Configure qw(bundling no_ignore_case); |
98 | |
99 | Some of the possible customizations. Most of them take a "no_" prefix |
100 | to reverse the effect: |
7d1b667f |
101 | |
102 | - default |
103 | |
104 | Restore default settings. |
105 | |
106 | - auto_abbrev |
107 | |
108 | Allow option names to be abbreviated to uniqueness. |
109 | |
110 | - getopt_compat |
111 | |
112 | Allow '+' to start options. |
113 | |
114 | - gnu_compat |
115 | |
116 | Compatibility with GNU getopt_long(). |
117 | |
118 | - permute |
119 | - require_order |
120 | |
121 | Whether non-options are allowed to be mixed with options. |
122 | |
123 | permute means that |
124 | |
125 | -foo arg1 -bar arg2 arg3 |
126 | |
127 | is equivalent to |
128 | |
129 | -foo -bar arg1 arg2 arg3 |
130 | |
131 | (provided -foo does not take an argument value). |
132 | |
133 | require_order means that options processing |
134 | terminates when the first non-option is encountered. |
135 | |
136 | -foo arg1 -bar arg2 arg3 |
137 | |
138 | is equivalent to |
139 | |
140 | -foo -- arg1 -bar arg2 arg3 |
141 | |
142 | - bundling |
143 | |
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 "-". |
148 | |
149 | - ignore_case |
150 | |
151 | Ignore case when matching options. |
152 | |
153 | - pass_through |
154 | |
155 | Do not issue error messages for unknown options, but leave |
156 | them (pass-through) in @ARGV. |
157 | |
158 | - prefix |
159 | |
160 | The string that starts options. See also prefix_pattern. |
161 | |
162 | - prefix_pattern |
163 | |
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 (--|-). |
167 | |
168 | - debug |
169 | |
170 | Enable copious debugging output. |
171 | |
172 | * Object oriented interface: |
173 | |
174 | Using the object oriented interface, multiple parser objects can be |
175 | instantiated, each having their own configuration settings: |
176 | |
79d0183a |
177 | $p1 = new Getopt::Long::Parser (config => ["bundling"]); |
178 | $p2 = new Getopt::Long::Parser (config => ["posix"]); |
7d1b667f |
179 | if ($p1->getoptions(...options descriptions...)) ... |
180 | |
181 | AVAILABILITY |
182 | ============ |
183 | |
184 | The official version for module Getopt::Long comes with the Perl 5 |
185 | distribution. |
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 |
191 | |
192 | COPYRIGHT AND DISCLAIMER |
193 | ======================== |
194 | |
79d0183a |
195 | Module Getopt::Long is Copyright 2003,1990 by Johan Vromans. |
7d1b667f |
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 |
200 | later version. |
201 | |
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" -------------------- |