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 |
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 | |
bd444ebb |
185 | Module Getopt::Long is Copyright 2002,1990 by Johan Vromans. |
7d1b667f |
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" -------------------- |