Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
3 | getopt - Process single-character switches with switch clustering |
4 | |
5 | getopts - Process single-character switches with switch clustering |
6 | |
7 | GetOptions - extended getopt processing |
8 | |
9 | =head1 SYNOPSIS |
10 | |
11 | use Getopt::Std; |
12 | getopt('oDI'); # -o, -D & -I take arg. Sets opt_* as a side effect. |
748a9306 |
13 | getopts('oif:'); # -o & -i are boolean flags, -f takes an argument |
14 | # Sets opt_* as a side effect. |
a0d0e21e |
15 | |
16 | use Getopt::Long; |
17 | $result = GetOptions (...option-descriptions...); |
18 | |
19 | =head1 DESCRIPTION |
20 | |
21 | The getopt() functions processes single-character switches with switch |
22 | clustering. Pass one argument which is a string containing all switches |
23 | that take an argument. For each switch found, sets $opt_x (where x is the |
24 | switch name) to the value of the argument, or 1 if no argument. Switches |
25 | which take an argument don't care whether there is a space between the |
26 | switch and the argument. |
27 | |
28 | The Getopt::Long module implements an extended getopt function called |
29 | GetOptions(). This function adheres to the new syntax (long option names, |
30 | no bundling). It tries to implement the better functionality of |
31 | traditional, GNU and POSIX getopt() functions. |
32 | |
33 | Each description should designate a valid Perl identifier, optionally |
34 | followed by an argument specifier. |
35 | |
36 | Values for argument specifiers are: |
37 | |
38 | <none> option does not take an argument |
39 | ! option does not take an argument and may be negated |
40 | =s :s option takes a mandatory (=) or optional (:) string argument |
41 | =i :i option takes a mandatory (=) or optional (:) integer argument |
42 | =f :f option takes a mandatory (=) or optional (:) real number argument |
43 | |
44 | If option "name" is set, it will cause the Perl variable $opt_name to |
45 | be set to the specified value. The calling program can use this |
46 | variable to detect whether the option has been set. Options that do |
47 | not take an argument will be set to 1 (one). |
48 | |
49 | Options that take an optional argument will be defined, but set to '' |
50 | if no actual argument has been supplied. |
51 | |
52 | If an "@" sign is appended to the argument specifier, the option is |
53 | treated as an array. Value(s) are not set, but pushed into array |
54 | @opt_name. |
55 | |
56 | Options that do not take a value may have an "!" argument specifier to |
57 | indicate that they may be negated. E.g. "foo!" will allow B<-foo> (which |
58 | sets $opt_foo to 1) and B<-nofoo> (which will set $opt_foo to 0). |
59 | |
60 | The option name may actually be a list of option names, separated by |
61 | '|'s, e.g. B<"foo|bar|blech=s". In this example, options 'bar' and |
62 | 'blech' will set $opt_foo instead. |
63 | |
64 | Option names may be abbreviated to uniqueness, depending on |
65 | configuration variable $autoabbrev. |
66 | |
67 | Dashes in option names are allowed (e.g. pcc-struct-return) and will |
68 | be translated to underscores in the corresponding Perl variable (e.g. |
69 | $opt_pcc_struct_return). Note that a lone dash "-" is considered an |
70 | option, corresponding Perl identifier is $opt_ . |
71 | |
72 | A double dash "--" signals end of the options list. |
73 | |
74 | If the first option of the list consists of non-alphanumeric |
75 | characters only, it is interpreted as a generic option starter. |
76 | Everything starting with one of the characters from the starter will |
77 | be considered an option. |
78 | |
79 | The default values for the option starters are "-" (traditional), "--" |
80 | (POSIX) and "+" (GNU, being phased out). |
81 | |
82 | Options that start with "--" may have an argument appended, separated |
83 | with an "=", e.g. "--foo=bar". |
84 | |
85 | If configuration variable $getopt_compat is set to a non-zero value, |
86 | options that start with "+" may also include their arguments, |
87 | e.g. "+foo=bar". |
88 | |
89 | A return status of 0 (false) indicates that the function detected |
90 | one or more errors. |
91 | |
92 | =head1 EXAMPLES |
93 | |
94 | If option "one:i" (i.e. takes an optional integer argument), then |
95 | the following situations are handled: |
96 | |
97 | -one -two -> $opt_one = '', -two is next option |
98 | -one -2 -> $opt_one = -2 |
99 | |
100 | Also, assume "foo=s" and "bar:s" : |
101 | |
102 | -bar -xxx -> $opt_bar = '', '-xxx' is next option |
103 | -foo -bar -> $opt_foo = '-bar' |
104 | -foo -- -> $opt_foo = '--' |
105 | |
106 | In GNU or POSIX format, option names and values can be combined: |
107 | |
108 | +foo=blech -> $opt_foo = 'blech' |
109 | --bar= -> $opt_bar = '' |
110 | --bar=-- -> $opt_bar = '--' |
111 | |
112 | =over 12 |
113 | |
114 | =item $autoabbrev |
115 | |
116 | Allow option names to be abbreviated to uniqueness. |
117 | Default is 1 unless environment variable |
118 | POSIXLY_CORRECT has been set. |
119 | |
120 | =item $getopt_compat |
121 | |
122 | Allow '+' to start options. |
123 | Default is 1 unless environment variable |
124 | POSIXLY_CORRECT has been set. |
125 | |
126 | =item $option_start |
127 | |
128 | Regexp with option starters. |
129 | Default is (--|-) if environment variable |
130 | POSIXLY_CORRECT has been set, (--|-|\+) otherwise. |
131 | |
132 | =item $order |
133 | |
134 | Whether non-options are allowed to be mixed with |
135 | options. |
136 | Default is $REQUIRE_ORDER if environment variable |
137 | POSIXLY_CORRECT has been set, $PERMUTE otherwise. |
138 | |
139 | =item $ignorecase |
140 | |
141 | Ignore case when matching options. Default is 1. |
142 | |
143 | =item $debug |
144 | |
145 | Enable debugging output. Default is 0. |
146 | |
147 | =back |
148 | |
149 | =head1 NOTE |
150 | |
151 | Does not yet use the Exporter--or even packages!! |
152 | Thus, it's not a real module. |
153 | |