Commit | Line | Data |
---|---|---|
86530b38 AT |
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 | |
83 | the value as arguments; | |
84 | - combinations of the above. | |
85 | ||
86 | * Customization: | |
87 | ||
88 | The module contains a special method, Getopt::Long::Configure, to | |
89 | control configuration variables to activate (or de-activate) specific | |
90 | behavior. It can be called with one or more names of options: | |
91 | ||
92 | - default | |
93 | ||
94 | Restore default settings. | |
95 | ||
96 | - auto_abbrev | |
97 | ||
98 | Allow option names to be abbreviated to uniqueness. | |
99 | ||
100 | - getopt_compat | |
101 | ||
102 | Allow '+' to start options. | |
103 | ||
104 | - gnu_compat | |
105 | ||
106 | Compatibility with GNU getopt_long(). | |
107 | ||
108 | - permute | |
109 | - require_order | |
110 | ||
111 | Whether non-options are allowed to be mixed with options. | |
112 | ||
113 | permute means that | |
114 | ||
115 | -foo arg1 -bar arg2 arg3 | |
116 | ||
117 | is equivalent to | |
118 | ||
119 | -foo -bar arg1 arg2 arg3 | |
120 | ||
121 | (provided -foo does not take an argument value). | |
122 | ||
123 | require_order means that options processing | |
124 | terminates when the first non-option is encountered. | |
125 | ||
126 | -foo arg1 -bar arg2 arg3 | |
127 | ||
128 | is equivalent to | |
129 | ||
130 | -foo -- arg1 -bar arg2 arg3 | |
131 | ||
132 | - bundling | |
133 | ||
134 | Setting this variable to a non-zero value will allow | |
135 | single-character options to be bundled. To distinguish bundles | |
136 | from long option names, long options must be introduced with | |
137 | "--" and single-character options (and bundles) with "-". | |
138 | ||
139 | - ignore_case | |
140 | ||
141 | Ignore case when matching options. | |
142 | ||
143 | - pass_through | |
144 | ||
145 | Do not issue error messages for unknown options, but leave | |
146 | them (pass-through) in @ARGV. | |
147 | ||
148 | - prefix | |
149 | ||
150 | The string that starts options. See also prefix_pattern. | |
151 | ||
152 | - prefix_pattern | |
153 | ||
154 | A Perl pattern that identifies the strings that introduce | |
155 | options. Default is (--|-|\+) unless environment variable | |
156 | POSIXLY_CORRECT has been set, in which case it is (--|-). | |
157 | ||
158 | - debug | |
159 | ||
160 | Enable copious debugging output. | |
161 | ||
162 | * Object oriented interface: | |
163 | ||
164 | Using the object oriented interface, multiple parser objects can be | |
165 | instantiated, each having their own configuration settings: | |
166 | ||
167 | $p1 = new Getopt::Long::Parser (config => ["posix"]); | |
168 | $p2 = new Getopt::Long::Parser (config => ["no_posix"]); | |
169 | if ($p1->getoptions(...options descriptions...)) ... | |
170 | ||
171 | AVAILABILITY | |
172 | ============ | |
173 | ||
174 | The official version for module Getopt::Long comes with the Perl 5 | |
175 | distribution. | |
176 | Newer versions will be made available on the Comprehensive Perl Archive | |
177 | Network (CPAN), see "http://www.perl.com/CPAN/authors/Johan_Vromans". | |
178 | Or use the CPAN search engine: | |
179 | http://search.cpan.org/search?mode=module&query=Getopt::Long | |
180 | http://search.cpan.org/search?module=Getopt::Long | |
181 | ||
182 | COPYRIGHT AND DISCLAIMER | |
183 | ======================== | |
184 | ||
185 | Module Getopt::Long is Copyright 2002,1990 by Johan Vromans. | |
186 | This program is free software; you can redistribute it and/or | |
187 | modify it under the terms of the Perl Artistic License or the | |
188 | GNU General Public License as published by the Free Software | |
189 | Foundation; either version 2 of the License, or (at your option) any | |
190 | later version. | |
191 | ||
192 | ------------------------------------------------------------------- | |
193 | Johan Vromans jvromans@squirrel.nl | |
194 | Squirrel Consultancy Haarlem, the Netherlands | |
195 | http://www.squirrel.nl http://www.squirrel.nl/people/jvromans | |
196 | ------------------ "Arms are made for hugging" -------------------- |