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. |
554627f6 |
72 | - options can have multiple values, e.g., "--position 25 624". |
7d1b667f |
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 |
85 | - combinations of the above. |
86 | |
87 | * Customization: |
88 | |
10933be5 |
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 |
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 |
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 |
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 |
185 | $p1 = new Getopt::Long::Parser (config => ["bundling"]); |
186 | $p2 = new Getopt::Long::Parser (config => ["posix"]); |
7d1b667f |
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 | |
554627f6 |
203 | Module Getopt::Long is Copyright 2005,1990 by Johan Vromans. |
7d1b667f |
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 |
213 | http://www.squirrel.nl http://www.squirrel.nl/people/jvromans |
214 | ------------------ "Arms are made for hugging" -------------------- |