OptionParser 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/README +110 -0
- data/docs/index.html +846 -0
- data/lib/commandline/optionparser.rb +16 -0
- data/lib/commandline/optionparser/option.rb +183 -0
- data/lib/commandline/optionparser/optiondata.rb +54 -0
- data/lib/commandline/optionparser/optionparser.rb +511 -0
- data/lib/commandline/text/format.rb +1451 -0
- data/test/tc_option.rb +121 -0
- data/test/testall.rb +16 -0
- metadata +50 -0
data/README
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
|
|
3
|
+
This release is licensed under the RLL - Ruby Lovers License. If you don't
|
|
4
|
+
love Ruby, then you don't have permission to even think about using/reading/
|
|
5
|
+
opening any file in this project.
|
|
6
|
+
|
|
7
|
+
If you a lover of Ruby, then you may use this freely and pay for your use
|
|
8
|
+
by giving feedback to the author, Jim Freeze.
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
CommandLine::OptionParser
|
|
12
|
+
=========================
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
ABOUT
|
|
16
|
+
=====
|
|
17
|
+
|
|
18
|
+
CommandLine::OptionParser is part of the CommandLine suite of
|
|
19
|
+
tools and is used for command line parsing. The parser integrates
|
|
20
|
+
with CommandLine::Option, CommandLine::OptionData and
|
|
21
|
+
CommandLine::Application.
|
|
22
|
+
|
|
23
|
+
The parser supports POSIX, Gnu and XTools style parsing options.
|
|
24
|
+
It also gives you flexibility to provide <em>non standard</em>
|
|
25
|
+
options. For example:
|
|
26
|
+
|
|
27
|
+
POSIX
|
|
28
|
+
=====
|
|
29
|
+
OptionParser.new Option.new(:names => "-f")
|
|
30
|
+
|
|
31
|
+
Gnu
|
|
32
|
+
===
|
|
33
|
+
OptionParser.new Option.new(:names => %w[--file -f])
|
|
34
|
+
|
|
35
|
+
XTools
|
|
36
|
+
======
|
|
37
|
+
OptionParser.new Option.new(:names => "-file")
|
|
38
|
+
|
|
39
|
+
User
|
|
40
|
+
====
|
|
41
|
+
OptionParser.new(Option.new(
|
|
42
|
+
:names => %w(--file -file --files -files -f),
|
|
43
|
+
:arg_arity => [1,-1],
|
|
44
|
+
:arg_description => "file1 [file2, ...]"))
|
|
45
|
+
|
|
46
|
+
This option parser with a single option prints:
|
|
47
|
+
|
|
48
|
+
OPTIONS
|
|
49
|
+
|
|
50
|
+
--file,-file,--files,-files,-f file1 [file2, ...]
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
There is document describing the various usage scenarios
|
|
54
|
+
at its homepage.
|
|
55
|
+
|
|
56
|
+
After poking around in a few corporations, it was evident that
|
|
57
|
+
option parsing was not understood. Nevertheless, many tools
|
|
58
|
+
were built that did not conform to any of the POSIX, Gnu or XTools
|
|
59
|
+
option styles. CommandLine::OptionParser was developed so that
|
|
60
|
+
new application could be written that conformed to accepted standards,
|
|
61
|
+
but non-standard option configurations could be handled as well
|
|
62
|
+
to support legacy interfaces.
|
|
63
|
+
|
|
64
|
+
More information on OptionParser can be found on its homepage:
|
|
65
|
+
http://optionparser.rubyforge.org
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
Major Features - 06/07/2005
|
|
69
|
+
=============
|
|
70
|
+
* First public release 0.5.0
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
Thanks for all the feedback!
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
Download & Installation
|
|
77
|
+
=======================
|
|
78
|
+
|
|
79
|
+
Homepage: http://optionparser.rubyforge.org
|
|
80
|
+
Download: http://rubyforge.org/frs/?group_id=296
|
|
81
|
+
|
|
82
|
+
Dependencies:
|
|
83
|
+
* None
|
|
84
|
+
|
|
85
|
+
There are many ways to install optionparser. Choose the one you like best:
|
|
86
|
+
|
|
87
|
+
Via RubyGems
|
|
88
|
+
$ gem install optionparser
|
|
89
|
+
|
|
90
|
+
# not in RPA yet
|
|
91
|
+
Via RPA
|
|
92
|
+
$ rpa install optionparser
|
|
93
|
+
|
|
94
|
+
# this either
|
|
95
|
+
The do-it-yourself way
|
|
96
|
+
$ ruby setup.rb config
|
|
97
|
+
$ ruby setup.rb setup
|
|
98
|
+
$ ruby setup.rb install
|
|
99
|
+
|
|
100
|
+
# nor this
|
|
101
|
+
The simplified do-it-yourself way
|
|
102
|
+
$ rake install
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
Integration with Application
|
|
106
|
+
============================
|
|
107
|
+
|
|
108
|
+
class MyApp << CommandLine::Application
|
|
109
|
+
|
|
110
|
+
end
|
data/docs/index.html
ADDED
|
@@ -0,0 +1,846 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="utf-8"?>
|
|
2
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
|
3
|
+
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
4
|
+
<head>
|
|
5
|
+
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
|
|
6
|
+
<title>Notes of Dr. Freeze</title>
|
|
7
|
+
<link rel="alternate" type="text/xml" title="RSS"
|
|
8
|
+
href="http://localhost:8808/index.cgi/index.rss" />
|
|
9
|
+
|
|
10
|
+
<style type="text/css">
|
|
11
|
+
body,td {
|
|
12
|
+
font-size: small;
|
|
13
|
+
line-height: 130%;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
a {
|
|
17
|
+
text-decoration: none;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
a:link, a:visited {
|
|
21
|
+
color: #2050f0;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
h1, h2, h3, h4, h5, h6 {
|
|
25
|
+
color: #446060;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
pre {
|
|
29
|
+
border-left: 7px solid #e8d8d8;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
.sidebar {
|
|
33
|
+
font-size: smaller;
|
|
34
|
+
color: #70b0b0;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
.sidebar a:link {
|
|
38
|
+
color: #104020;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
.sidebar a:visited {
|
|
42
|
+
color: #104020;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
.sidebar a:hover {
|
|
46
|
+
color: #401020;
|
|
47
|
+
font-weight: bold;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
.Sidebarwarning {
|
|
51
|
+
color: #902020;
|
|
52
|
+
padding-left: 1em;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
.sidebarholder {
|
|
56
|
+
border-top: 2px solid #aaaaaa;
|
|
57
|
+
border-left: 2px solid #aaaaaa;
|
|
58
|
+
padding: 0px;
|
|
59
|
+
margin-bottom: 16px;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
.sidebartitle {
|
|
63
|
+
background: #c0e0e0;
|
|
64
|
+
padding-left: 8px;
|
|
65
|
+
color: #0000cc;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
.sidebarbody {
|
|
69
|
+
background: #f8ffff;
|
|
70
|
+
color: #a08080;
|
|
71
|
+
padding-left: 8px;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
.sidebartext {
|
|
75
|
+
color: #80a0a0;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
.sidebar TABLE TABLE, .sidebar TABLE TABLE TD {
|
|
79
|
+
color: #a08080;
|
|
80
|
+
padding-right: 0.5em;
|
|
81
|
+
padding-left: 0em;
|
|
82
|
+
padding-top: 0em;
|
|
83
|
+
padding-bottom: 0em;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
.sidebarsubhead {
|
|
87
|
+
color: #503030;
|
|
88
|
+
background: #f8d0d0;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
.indent {
|
|
92
|
+
margin-left: 1.5em;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
.catcount {
|
|
96
|
+
color: #807070;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
.entry {
|
|
100
|
+
border-top: 2px solid #aaaaaa;
|
|
101
|
+
border-left: 2px solid #aaaaaa;
|
|
102
|
+
padding: 0px;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
.entrytitlebar {
|
|
106
|
+
#background: #e0c0e0;
|
|
107
|
+
background: #aaaaff;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
.entrytitle {
|
|
111
|
+
font-family: Arial,Helvetica;
|
|
112
|
+
color: #111166;
|
|
113
|
+
padding-left: 12pt;
|
|
114
|
+
font-size: large;
|
|
115
|
+
font-variant: small-caps;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
.entrytitledetail {
|
|
119
|
+
text-align: right;
|
|
120
|
+
font-size: x-small;
|
|
121
|
+
padding-right: 12pt;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
.entrybody {
|
|
125
|
+
padding-left: 36pt;
|
|
126
|
+
padding-right: 12pt;
|
|
127
|
+
padding-bottom: 12pt;
|
|
128
|
+
line-height: 130%;
|
|
129
|
+
#background: #f8f0f0;
|
|
130
|
+
background: #eeeeff;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
.entrybody h1,h2,h3,h4 {
|
|
134
|
+
line-height: 100%;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
.pagetitle {
|
|
138
|
+
font-size: xx-large;
|
|
139
|
+
font-family: Arial,Helvetica;
|
|
140
|
+
#text-shadow: .18em .15em .2em #223366;
|
|
141
|
+
text-shadow: .18em .15em .2em #9999cc;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
.titlemenu {
|
|
145
|
+
font-size: x-small;
|
|
146
|
+
font-family: Arial,Helvetica;
|
|
147
|
+
text-align: right;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
.schedhead {
|
|
151
|
+
font-size: small;
|
|
152
|
+
font-family: Arial,Helvetica;
|
|
153
|
+
text-align: right;
|
|
154
|
+
font-weight: bold;
|
|
155
|
+
background: #403030;
|
|
156
|
+
color: #c0c0c0;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
.schedentry {
|
|
160
|
+
font-size: small;
|
|
161
|
+
font-family: Arial,Helvetica;
|
|
162
|
+
text-align: center;
|
|
163
|
+
background: #d0c0c0;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
.schedempty {
|
|
167
|
+
font-size: small;
|
|
168
|
+
background: #f0e0e0;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
.sidebartable {
|
|
172
|
+
color: #a08080;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
.c {
|
|
176
|
+
text-align: right;
|
|
177
|
+
padding-right: 0.5em;
|
|
178
|
+
padding-left: 0em;
|
|
179
|
+
padding-top: 0em;
|
|
180
|
+
padding-bottom: 0em;
|
|
181
|
+
}
|
|
182
|
+
.ctitle {
|
|
183
|
+
text-align: right;
|
|
184
|
+
padding-right: 0.5em;
|
|
185
|
+
padding-left: 0em;
|
|
186
|
+
padding-top: 0em;
|
|
187
|
+
padding-bottom: 0em;
|
|
188
|
+
border-bottom: 1px solid #d0d0d0;
|
|
189
|
+
}
|
|
190
|
+
.ctotal {
|
|
191
|
+
text-align: right;
|
|
192
|
+
padding-right: 0.5em;
|
|
193
|
+
padding-left: 0em;
|
|
194
|
+
padding-top: 0em;
|
|
195
|
+
padding-bottom: 0em;
|
|
196
|
+
border-top: 1px solid #d0d0d0;
|
|
197
|
+
border-bottom: 1px solid #d0d0d0;
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
.caltoday {
|
|
201
|
+
text-align: right;
|
|
202
|
+
background: #f8d0d0;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
</style>
|
|
206
|
+
|
|
207
|
+
</head>
|
|
208
|
+
<body>
|
|
209
|
+
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
|
210
|
+
<tr class="entrybody"><td colspan="3" class="entrybody">
|
|
211
|
+
<h1>Welcome to <a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a></h1>
|
|
212
|
+
<tt><a
|
|
213
|
+
href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a></tt> is
|
|
214
|
+
designed to be a flexible command line parser with a Ruby look and feel to
|
|
215
|
+
it. <a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a>
|
|
216
|
+
got its birth from the need for a parser that was flexible. One that
|
|
217
|
+
supported (or not) the standard command line styles of <tt>Unix</tt>,
|
|
218
|
+
<tt>Gnu</tt> and <tt>X Toolkit</tt>.
|
|
219
|
+
|
|
220
|
+
<p>
|
|
221
|
+
<a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> is not
|
|
222
|
+
a port of a traditional command line parser, but it is written to meet the
|
|
223
|
+
feature requirements of traditional command line parsers. When using it as
|
|
224
|
+
a library, you should notice that it is expressive, supports Ruby’s
|
|
225
|
+
blocks and lambda’s, and is sprinkled with a little bit of magic.
|
|
226
|
+
</p>
|
|
227
|
+
<p>
|
|
228
|
+
While the library can be used by itself, it is also designed to work with
|
|
229
|
+
the CommandLine::Application class. These tools work together to facilitate
|
|
230
|
+
the generation of a sophisticated (batch oriented) application user
|
|
231
|
+
interface in a matter of minutes.
|
|
232
|
+
</p>
|
|
233
|
+
<h1>Traditional Option Parsing Schemes</h1>
|
|
234
|
+
<p>
|
|
235
|
+
Command line options traditionally occur in three flavors:
|
|
236
|
+
</p>
|
|
237
|
+
<ul>
|
|
238
|
+
<li><em>Unix</em> (or POSIX.2)
|
|
239
|
+
|
|
240
|
+
</li>
|
|
241
|
+
<li><em>Gnu</em>
|
|
242
|
+
|
|
243
|
+
</li>
|
|
244
|
+
<li><em>X Toolkit</em>
|
|
245
|
+
|
|
246
|
+
</li>
|
|
247
|
+
</ul>
|
|
248
|
+
<p>
|
|
249
|
+
Below is a summary of these schemes. <em>(Note: I did not invent these
|
|
250
|
+
traditional parsing conventions. Most of the information contained below
|
|
251
|
+
was pulled from internet resources and I have quoted these resources where
|
|
252
|
+
possible.)</em>
|
|
253
|
+
</p>
|
|
254
|
+
<h2>Unix Style (POSIX)</h2>
|
|
255
|
+
<p>
|
|
256
|
+
The Unix style command line options are a single character preceded by a
|
|
257
|
+
single dash (hyphen character). In general, lowercase options are preferred
|
|
258
|
+
with their uppercase counterparts being the special case variant.
|
|
259
|
+
</p>
|
|
260
|
+
<h3>Mode Flag</h3>
|
|
261
|
+
<p>
|
|
262
|
+
If an option does not take an argument, then it is a mode-flag.
|
|
263
|
+
</p>
|
|
264
|
+
<h3>Optional Separation Between the Option Flag and Its Argument</h3>
|
|
265
|
+
<p>
|
|
266
|
+
If the option takes an argument, the argument follows it with optional
|
|
267
|
+
white space separating the two. For example, the following forms are both
|
|
268
|
+
valid:
|
|
269
|
+
</p>
|
|
270
|
+
<pre>
|
|
271
|
+
sort -k 5
|
|
272
|
+
sort -k5
|
|
273
|
+
</pre>
|
|
274
|
+
<h3>Grouping</h3>
|
|
275
|
+
<p>
|
|
276
|
+
A mode-flag can be grouped together with other mode-flags behind a single
|
|
277
|
+
dash. For example:
|
|
278
|
+
</p>
|
|
279
|
+
<pre>
|
|
280
|
+
tar -c -v -f
|
|
281
|
+
</pre>
|
|
282
|
+
<p>
|
|
283
|
+
is equivalent to:
|
|
284
|
+
</p>
|
|
285
|
+
<pre>
|
|
286
|
+
tar -cvf
|
|
287
|
+
</pre>
|
|
288
|
+
<p>
|
|
289
|
+
If grouping is done, the last option in a group can be an option that takes
|
|
290
|
+
an argument. For example
|
|
291
|
+
</p>
|
|
292
|
+
<pre>
|
|
293
|
+
sort -r -n -k 5
|
|
294
|
+
</pre>
|
|
295
|
+
<p>
|
|
296
|
+
can be written as
|
|
297
|
+
</p>
|
|
298
|
+
<pre>
|
|
299
|
+
sort -rnk 5
|
|
300
|
+
</pre>
|
|
301
|
+
<p>
|
|
302
|
+
but not
|
|
303
|
+
</p>
|
|
304
|
+
<pre>
|
|
305
|
+
sort -rkn 5
|
|
306
|
+
</pre>
|
|
307
|
+
<p>
|
|
308
|
+
because the ‘5’ argument belongs to the ‘k’ option
|
|
309
|
+
flag.
|
|
310
|
+
</p>
|
|
311
|
+
<h3>Option Parsing Termination</h3>
|
|
312
|
+
<p>
|
|
313
|
+
It is convention that a double hyphen is a signal to stop option
|
|
314
|
+
interpretation and to read the remaining statements on the command line
|
|
315
|
+
literally. So, a command such as:
|
|
316
|
+
</p>
|
|
317
|
+
<pre>
|
|
318
|
+
app -- -x -y -z
|
|
319
|
+
</pre>
|
|
320
|
+
<p>
|
|
321
|
+
will not ‘see’ the three mode-flags. Instead, they will be
|
|
322
|
+
treated as arguments to the application:
|
|
323
|
+
</p>
|
|
324
|
+
<pre>
|
|
325
|
+
#args = ["-x", "-y", "-z"]
|
|
326
|
+
</pre>
|
|
327
|
+
<h3>POSIX Summary</h3>
|
|
328
|
+
<ol>
|
|
329
|
+
<li>An option is a hyphen followed by a single alphanumeric character.
|
|
330
|
+
|
|
331
|
+
</li>
|
|
332
|
+
<li>An option may require an argument which must follow the option with an
|
|
333
|
+
optional space in between.
|
|
334
|
+
|
|
335
|
+
<pre>
|
|
336
|
+
-r ubygems
|
|
337
|
+
-rubygems
|
|
338
|
+
-r=ubygems # not ok. '=' is Gnu style
|
|
339
|
+
</pre>
|
|
340
|
+
</li>
|
|
341
|
+
<li>Options that do not require arguments can be grouped after a hyphen.
|
|
342
|
+
|
|
343
|
+
</li>
|
|
344
|
+
<li>Options can appear in any order.
|
|
345
|
+
|
|
346
|
+
</li>
|
|
347
|
+
<li>Options can appear multiple times.
|
|
348
|
+
|
|
349
|
+
</li>
|
|
350
|
+
<li>Options precede other nonoption arguments. TODO: Test for this
|
|
351
|
+
|
|
352
|
+
</li>
|
|
353
|
+
<li>The — argument terminates options.
|
|
354
|
+
|
|
355
|
+
</li>
|
|
356
|
+
<li>The - option is used to represent the standard input stream.
|
|
357
|
+
|
|
358
|
+
</li>
|
|
359
|
+
</ol>
|
|
360
|
+
<h3>References</h3>
|
|
361
|
+
<p>
|
|
362
|
+
<a
|
|
363
|
+
href="http://www.mkssoftware.com/docs/man1/getopts.1.asp">www.mkssoftware.com/docs/man1/getopts.1.asp</a>
|
|
364
|
+
</p>
|
|
365
|
+
<h2>Gnu Style</h2>
|
|
366
|
+
<p>
|
|
367
|
+
The Gnu style command line options provide support for option words (or
|
|
368
|
+
keywords), yet still maintain compatibility with the Unix style options.
|
|
369
|
+
The options in this style are sometimes referred to as
|
|
370
|
+
<em>long_options</em> and the Unix style options as <em>short_options</em>.
|
|
371
|
+
The compatibility is maintained by preceding the <em>long_options</em> with
|
|
372
|
+
two dashes. The option word must be two or more characters.
|
|
373
|
+
</p>
|
|
374
|
+
<pre>
|
|
375
|
+
:test
|
|
376
|
+
if gnu_style is slected, ensure only two options and that one
|
|
377
|
+
is Unix and one is Gnu style.
|
|
378
|
+
</pre>
|
|
379
|
+
<h3>Separation Between the Option Flag and Its Argument</h3>
|
|
380
|
+
<p>
|
|
381
|
+
Gnu style options cannot be grouped. For options that have an argument, the
|
|
382
|
+
argument follows the option with either whitespace or an ’=’.
|
|
383
|
+
For example, the following are equivalent:
|
|
384
|
+
</p>
|
|
385
|
+
<pre>
|
|
386
|
+
app --with-optimizer yes
|
|
387
|
+
app --with-optimizer=yes
|
|
388
|
+
</pre>
|
|
389
|
+
<h3>Option Parsing Termination</h3>
|
|
390
|
+
<p>
|
|
391
|
+
Similar to the <em>Unix</em> style double-hyphen ’- -’, the
|
|
392
|
+
<em>Gnu</em> style has a triple-hyphen ’- - -’ to signal that
|
|
393
|
+
option parsing be halted and to treat the remaining text as arguments (that
|
|
394
|
+
is, read literally from the command line)
|
|
395
|
+
</p>
|
|
396
|
+
<pre>
|
|
397
|
+
app --- -x -y -z
|
|
398
|
+
args = ["-x", "-y", "-z"]
|
|
399
|
+
</pre>
|
|
400
|
+
<h3>Mixing <em>Gnu</em> and <em>Unix</em> Styles</h3>
|
|
401
|
+
<p>
|
|
402
|
+
The <em>Gnu</em> and the <em>Unix</em> option types can be mixed on the
|
|
403
|
+
same commandline. The following are equivalent:
|
|
404
|
+
</p>
|
|
405
|
+
<pre>
|
|
406
|
+
app -a -b --with-c
|
|
407
|
+
app -ab --with-c
|
|
408
|
+
app -ba --with-c
|
|
409
|
+
app --with-c -ab
|
|
410
|
+
</pre>
|
|
411
|
+
<h2>X Toolkit Style</h2>
|
|
412
|
+
<p>
|
|
413
|
+
The X Toolkit style uses the single hyphen followed by a keyword option.
|
|
414
|
+
This style is not compatible with the <em>Unix</em> or the <em>Gnu</em>
|
|
415
|
+
option types. In most situations this is OK since these options will be
|
|
416
|
+
filtered from the command line before passing them to an application.
|
|
417
|
+
</p>
|
|
418
|
+
<h3>’-’ and STDIN</h3>
|
|
419
|
+
<p>
|
|
420
|
+
It is convention that a bare hypen indicates to read from stdin.
|
|
421
|
+
</p>
|
|
422
|
+
<h2>The <a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> Style</h2>
|
|
423
|
+
<p>
|
|
424
|
+
The CommandLine::<a
|
|
425
|
+
href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> does not
|
|
426
|
+
care what style you use. It is designed for maximum flexiblity so it may be
|
|
427
|
+
used within any organiziation to meet their standards.
|
|
428
|
+
</p>
|
|
429
|
+
<h3>Multiple Option Names</h3>
|
|
430
|
+
<p>
|
|
431
|
+
<a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> does
|
|
432
|
+
not place restrictions on the number of options. The only restriction is
|
|
433
|
+
that an option name begin with a hyphen ’-’. An definitely
|
|
434
|
+
conjured example of this freedom is:
|
|
435
|
+
</p>
|
|
436
|
+
<pre>
|
|
437
|
+
:names => %w(
|
|
438
|
+
--file --File --f --F -file -File -f -F
|
|
439
|
+
)
|
|
440
|
+
</pre>
|
|
441
|
+
<h2>Miscellaneous Option Styles</h2>
|
|
442
|
+
<h3>Prefix Matching</h3>
|
|
443
|
+
<p>
|
|
444
|
+
Although not encouraged, some prefer the ability to truncate option words
|
|
445
|
+
to their first unique match. For example, an application that support this
|
|
446
|
+
style and accepts the following two option words:
|
|
447
|
+
</p>
|
|
448
|
+
<pre>
|
|
449
|
+
["--foos", "--fbars"]
|
|
450
|
+
</pre>
|
|
451
|
+
<p>
|
|
452
|
+
will accept any of the following as valid options
|
|
453
|
+
</p>
|
|
454
|
+
<pre>
|
|
455
|
+
app --fo
|
|
456
|
+
app --foo
|
|
457
|
+
app --foos
|
|
458
|
+
</pre>
|
|
459
|
+
<p>
|
|
460
|
+
for the "—foos" option flag since it can be determined that
|
|
461
|
+
"—fo" will only match "—foos" and not
|
|
462
|
+
"—fbars".
|
|
463
|
+
</p>
|
|
464
|
+
<h3>Repeated Arguments</h3>
|
|
465
|
+
<p>
|
|
466
|
+
A common question is how an option parser should respond when an option is
|
|
467
|
+
specified on the command line multiple times. This is true for mode flags,
|
|
468
|
+
but especially true for options that require an argument, For example, what
|
|
469
|
+
should happen when the following is given:
|
|
470
|
+
</p>
|
|
471
|
+
<pre>
|
|
472
|
+
app -f file1 -f file2
|
|
473
|
+
</pre>
|
|
474
|
+
<p>
|
|
475
|
+
Should the parser flag this as an error or should it accept both arguments.
|
|
476
|
+
</p>
|
|
477
|
+
<p>
|
|
478
|
+
<a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> gives
|
|
479
|
+
you the choice of whether it raises an exception when an option is seen
|
|
480
|
+
more than once, or it just passes the data onto the user.
|
|
481
|
+
</p>
|
|
482
|
+
<p>
|
|
483
|
+
How the data is handled is up to the user, but it typically boils down to
|
|
484
|
+
either Append, Replace or Raise. This is described in more detail in the
|
|
485
|
+
usage section.
|
|
486
|
+
</p>
|
|
487
|
+
<h2>CVS Mode</h2>
|
|
488
|
+
<p>
|
|
489
|
+
CVS is a common application with a unique command line structure. The cvs
|
|
490
|
+
application commandline can be given options, but requires a command. This
|
|
491
|
+
command can also be given options. This means that there are two sets of
|
|
492
|
+
options, one set for the cvs application and one set for the cvs-command.
|
|
493
|
+
Some example formats are:
|
|
494
|
+
</p>
|
|
495
|
+
<pre>
|
|
496
|
+
cvs [cvs-options]
|
|
497
|
+
cvs [cvs-options] command [command-options-and-arguments]
|
|
498
|
+
|
|
499
|
+
cvs -r update
|
|
500
|
+
cvs -r update .
|
|
501
|
+
cvs edit -p file
|
|
502
|
+
</pre>
|
|
503
|
+
<p>
|
|
504
|
+
To handle this, the first unclaimed argument is treated as a command and
|
|
505
|
+
the options and option-arguments that follow belong to that command. More
|
|
506
|
+
on how this is handled in the usage section.
|
|
507
|
+
</p>
|
|
508
|
+
<h2>Option Grouping</h2>
|
|
509
|
+
<p>
|
|
510
|
+
A conflict can occur where a grouping of single letter Unix options has the
|
|
511
|
+
value as a word option preceded by a single dash. For this reason, it is
|
|
512
|
+
customary to use the double-dash notation for word options. Unless
|
|
513
|
+
double-dashes are enforced for word options, <a
|
|
514
|
+
href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> will
|
|
515
|
+
check for possible name conflicts and raise an exception if it finds one.
|
|
516
|
+
</p>
|
|
517
|
+
<p>
|
|
518
|
+
An individual Option. Why isnt’ a hash good enough? I think it is. An
|
|
519
|
+
option, is a hash. But, it can’t validate itself. <a
|
|
520
|
+
href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> should
|
|
521
|
+
worry about parsing using a collection of options
|
|
522
|
+
</p>
|
|
523
|
+
<h1><a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> Usage</h1>
|
|
524
|
+
<p>
|
|
525
|
+
The <a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a>
|
|
526
|
+
library consists of three classes, <tt>Option</tt>, <tt><a
|
|
527
|
+
href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a></tt> and
|
|
528
|
+
<tt>OptionData</tt>. For each option an <tt>Option</tt> object is created.
|
|
529
|
+
When you are ready to prepare for command line parsing, these options are
|
|
530
|
+
collected into an <tt><a
|
|
531
|
+
href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a></tt>
|
|
532
|
+
object. This object controls the type of option scheme that is to be
|
|
533
|
+
implemented. When it comes time to parse a command line, call the method
|
|
534
|
+
+Option#parse+. This will parse any array, but parses ARGV by default. The
|
|
535
|
+
result is an <tt>OptionData</tt> object. This object can be used from which
|
|
536
|
+
to extract values or it can be passed to another class as a fully
|
|
537
|
+
encapsulated data object.
|
|
538
|
+
</p>
|
|
539
|
+
<h2>Getting Started</h2>
|
|
540
|
+
<p>
|
|
541
|
+
An option is created with the following syntax:
|
|
542
|
+
</p>
|
|
543
|
+
<pre>
|
|
544
|
+
opt = Option.new([type], [options], <properties>)
|
|
545
|
+
</pre>
|
|
546
|
+
<p>
|
|
547
|
+
The optional type can be <tt>:flag</tt> or <tt>:default</tt>, with
|
|
548
|
+
<tt>:default</tt> naturally being the default.
|
|
549
|
+
</p>
|
|
550
|
+
<p>
|
|
551
|
+
The options supported are
|
|
552
|
+
</p>
|
|
553
|
+
<pre>
|
|
554
|
+
:posix => true | false
|
|
555
|
+
</pre>
|
|
556
|
+
<p>
|
|
557
|
+
with <tt>:posix => false</tt> being the default.
|
|
558
|
+
</p>
|
|
559
|
+
<p>
|
|
560
|
+
An option object has six properties. Four of these properties define
|
|
561
|
+
attributes of the object. The last two define <em>actions</em> that are
|
|
562
|
+
taken when a command line is parsed.
|
|
563
|
+
</p>
|
|
564
|
+
<ol>
|
|
565
|
+
<li>:names
|
|
566
|
+
|
|
567
|
+
</li>
|
|
568
|
+
<li>:arg_arity
|
|
569
|
+
|
|
570
|
+
</li>
|
|
571
|
+
<li>:opt_description
|
|
572
|
+
|
|
573
|
+
</li>
|
|
574
|
+
<li>:arg_description
|
|
575
|
+
|
|
576
|
+
</li>
|
|
577
|
+
<li>:opt_found
|
|
578
|
+
|
|
579
|
+
</li>
|
|
580
|
+
<li>:opt_not_found
|
|
581
|
+
|
|
582
|
+
</li>
|
|
583
|
+
</ol>
|
|
584
|
+
<h3>Mode-Flag</h3>
|
|
585
|
+
<p>
|
|
586
|
+
To create a mode flag, that is an option that is either true or false
|
|
587
|
+
depending if it is seen on the command line, we write:
|
|
588
|
+
</p>
|
|
589
|
+
<pre>
|
|
590
|
+
opt_debug = Option.new(
|
|
591
|
+
:names => %w(--debug -d),
|
|
592
|
+
:arg_arity => [0,0],
|
|
593
|
+
:opt_description => "Sets debug to true",
|
|
594
|
+
:arg_description => "",
|
|
595
|
+
:opt_found => true,
|
|
596
|
+
:opt_not_found => false
|
|
597
|
+
)
|
|
598
|
+
</pre>
|
|
599
|
+
<p>
|
|
600
|
+
Now, this is a lot of work just for a common mode-flag. However, there is a
|
|
601
|
+
shorter way:
|
|
602
|
+
</p>
|
|
603
|
+
<pre>
|
|
604
|
+
opt = Option.new(:flag,
|
|
605
|
+
:names => %w(--debug -d),
|
|
606
|
+
:opt_description => "Sets debug to true.")
|
|
607
|
+
</pre>
|
|
608
|
+
<p>
|
|
609
|
+
Or, even simpler yet,
|
|
610
|
+
</p>
|
|
611
|
+
<pre>
|
|
612
|
+
opt = Option.new(:flag, :names => %w(--debug -d))
|
|
613
|
+
</pre>
|
|
614
|
+
<p>
|
|
615
|
+
For a common option like a mode-flag, <tt>Option</tt> will use the first
|
|
616
|
+
option ‘word’ it finds in the :names list and use that in the
|
|
617
|
+
automatic option text. Of course, if you don’t want any text, just
|
|
618
|
+
set the option description to an empty string:
|
|
619
|
+
</p>
|
|
620
|
+
<pre>
|
|
621
|
+
:opt_description => "".
|
|
622
|
+
</pre>
|
|
623
|
+
<h3>POSIX</h3>
|
|
624
|
+
<p>
|
|
625
|
+
The default for is false, so the following are equivalent:
|
|
626
|
+
</p>
|
|
627
|
+
<pre>
|
|
628
|
+
op1 = OptionParser.new(opts, :posix => false)
|
|
629
|
+
op2 = OptionParser.new(opts)
|
|
630
|
+
op1.posix) #=> false
|
|
631
|
+
op2.posix) #=> false
|
|
632
|
+
</pre>
|
|
633
|
+
<h3>Actions</h3>
|
|
634
|
+
<p>
|
|
635
|
+
The option properties <tt>:opt_found</tt> and <tt>:opt_not_found</tt> are
|
|
636
|
+
the source of the value returned for an option when it is parsed. These
|
|
637
|
+
properties can be either an object or a proc/lambda. If they are an object,
|
|
638
|
+
then the stored object is simply returned. If they are lambdas, then the
|
|
639
|
+
stored value is the result of executing the lambda. So, the following will
|
|
640
|
+
have the same result:
|
|
641
|
+
</p>
|
|
642
|
+
<p>
|
|
643
|
+
object is the Options can perform actions
|
|
644
|
+
</p>
|
|
645
|
+
<pre>
|
|
646
|
+
opt_debug = Option.new(:flag
|
|
647
|
+
:names => %w(--debug -d),
|
|
648
|
+
:opt_found => true,
|
|
649
|
+
:opt_not_found => false
|
|
650
|
+
)
|
|
651
|
+
|
|
652
|
+
opt_debug = Option.new(:flag
|
|
653
|
+
:names => %w(--debug -d),
|
|
654
|
+
:opt_found => lambda { true },
|
|
655
|
+
:opt_not_found => lambda { false }
|
|
656
|
+
)
|
|
657
|
+
</pre>
|
|
658
|
+
<p>
|
|
659
|
+
The key to notice here is that there is never a need to set an instance
|
|
660
|
+
variable to a default value. Normally one does:
|
|
661
|
+
</p>
|
|
662
|
+
<pre>
|
|
663
|
+
@debug = false
|
|
664
|
+
# option setup
|
|
665
|
+
... parse the commandline
|
|
666
|
+
@debug = true if parse_results[:debug]
|
|
667
|
+
</pre>
|
|
668
|
+
<p>
|
|
669
|
+
Here, one has the option of doing the following:
|
|
670
|
+
</p>
|
|
671
|
+
<pre>
|
|
672
|
+
opt_debug = Option.new(:flag :names => %w(--debug -d),)
|
|
673
|
+
... parse the commandline
|
|
674
|
+
@debug = option_data[:debug]
|
|
675
|
+
|
|
676
|
+
# or
|
|
677
|
+
|
|
678
|
+
opt_debug = Option.new(:flag
|
|
679
|
+
:names => %w(--debug -d),
|
|
680
|
+
:opt_found => lambda { @debug = true },
|
|
681
|
+
:opt_not_found => lambda { @debug = false }
|
|
682
|
+
)
|
|
683
|
+
# do nothing, variable already set.
|
|
684
|
+
</pre>
|
|
685
|
+
<p>
|
|
686
|
+
I find this much easier to manage that having to worry about setting
|
|
687
|
+
default behaviour.
|
|
688
|
+
</p>
|
|
689
|
+
<h2><a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a></h2>
|
|
690
|
+
<p>
|
|
691
|
+
Once the options are defined, we load them into and <a
|
|
692
|
+
href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> and parse
|
|
693
|
+
the command line. The syntax for creating an <a
|
|
694
|
+
href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> object
|
|
695
|
+
is:
|
|
696
|
+
</p>
|
|
697
|
+
<pre>
|
|
698
|
+
OptionParser.new(opt_or_array_of_opts[, options])
|
|
699
|
+
</pre>
|
|
700
|
+
<p>
|
|
701
|
+
where the only option is for parsing posix:
|
|
702
|
+
</p>
|
|
703
|
+
<pre>
|
|
704
|
+
:posix => true | false (default is false)
|
|
705
|
+
</pre>
|
|
706
|
+
<p>
|
|
707
|
+
If you want to parse posix, you must specify so. <a
|
|
708
|
+
href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> will not
|
|
709
|
+
assume posix mode just because all of the options are posix options. This
|
|
710
|
+
allows you to use posix only options but not require the strict parsing
|
|
711
|
+
rules.
|
|
712
|
+
</p>
|
|
713
|
+
<p>
|
|
714
|
+
Some examples of creating an <a
|
|
715
|
+
href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> object:
|
|
716
|
+
</p>
|
|
717
|
+
<pre>
|
|
718
|
+
opt = Option.new(:flag, :names => %w(-h))
|
|
719
|
+
|
|
720
|
+
op = OptionParser.new(opt, :posix => false)
|
|
721
|
+
op = OptionParser.new(opt)
|
|
722
|
+
|
|
723
|
+
opts = []
|
|
724
|
+
opts << Option.new(:flag, :names => %w(--help h))
|
|
725
|
+
opts << Option.new(:flag, :names => %w(--debug d))
|
|
726
|
+
op = OptionParser.new(opts)
|
|
727
|
+
|
|
728
|
+
op = OptionParser.new
|
|
729
|
+
op << opt
|
|
730
|
+
op << opts
|
|
731
|
+
|
|
732
|
+
# block constructor
|
|
733
|
+
op = OptionParser.new { |o|
|
|
734
|
+
o << Option.new(:flag, :names => %w(--debug d))
|
|
735
|
+
}
|
|
736
|
+
</pre>
|
|
737
|
+
<h2>Parsing the Command Line</h2>
|
|
738
|
+
<p>
|
|
739
|
+
Parsing the command line is as simple as calling #parse:
|
|
740
|
+
</p>
|
|
741
|
+
<pre>
|
|
742
|
+
opt = Option.new(:flag, :names => %w(-h))
|
|
743
|
+
op = OptionParser.new(opt)
|
|
744
|
+
option_data = op.parse
|
|
745
|
+
</pre>
|
|
746
|
+
<h2>Option Data</h2>
|
|
747
|
+
<p>
|
|
748
|
+
The OptionData is the return value of <a
|
|
749
|
+
href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a>#parse.
|
|
750
|
+
The parsing results for each option are accessed with the bracket notation
|
|
751
|
+
#[].
|
|
752
|
+
</p>
|
|
753
|
+
<pre>
|
|
754
|
+
opt = Option.new(:posix => true,
|
|
755
|
+
:names => %w(-r),
|
|
756
|
+
:opt_found => OptionParser::GET_ARGS)
|
|
757
|
+
od = OptionParser.new(opt, :posix => true).parse(["-rubygems"])
|
|
758
|
+
od["-r"] #=> "ubygems"
|
|
759
|
+
|
|
760
|
+
od = OptionParser.new(opt, :posix => true).parse(["-r", "ubygems"])
|
|
761
|
+
od["-r"] #=> "ubygems"
|
|
762
|
+
</pre>
|
|
763
|
+
<p>
|
|
764
|
+
But, OptionData is not liberal in that it only stores a reference to an
|
|
765
|
+
options first name. An option cannot access its parsed values using just
|
|
766
|
+
any of its names.
|
|
767
|
+
</p>
|
|
768
|
+
<pre>
|
|
769
|
+
od = OptionParser.new { |o|
|
|
770
|
+
o << Option.new(:flag, :names => %w(--valid --notvalid))
|
|
771
|
+
o << Option.new(:flag, :names => %w(--first --second))
|
|
772
|
+
}.parse(%w(--notvalid --second))
|
|
773
|
+
od["--valid"] #=> true
|
|
774
|
+
od["--first"] #=> true
|
|
775
|
+
od["--notvalid"] #=> CommandLine::OptionData::UnknownOptionError
|
|
776
|
+
od["--second"] #=> CommandLine::OptionData::UnknownOptionError
|
|
777
|
+
</pre>
|
|
778
|
+
<h3>Built-in Data Handlers</h3>
|
|
779
|
+
<p>
|
|
780
|
+
<a href="/index.cgi/OptionParser/OptionParser.rdoc">OptionParser</a> has
|
|
781
|
+
built-in data handlers for handling common scenarios. These lambas can save
|
|
782
|
+
a lot of typing.
|
|
783
|
+
</p>
|
|
784
|
+
<p>
|
|
785
|
+
The first is GET_ARG_ARRAY. This is useful for options that take a variable
|
|
786
|
+
number of arguments. It returns all the arguments in an array.
|
|
787
|
+
</p>
|
|
788
|
+
<pre>
|
|
789
|
+
# GET_ARG_ARRAY returns all arguments in an array, even if no
|
|
790
|
+
# arguments are present. This is not to be confused with the option
|
|
791
|
+
# occuring multiple times on the command line.
|
|
792
|
+
opt = Option.new(:names => %w(--file),
|
|
793
|
+
:argument_arity => [0-1],
|
|
794
|
+
:opt_found => OptionParser::GET_ARG_ARRAY)
|
|
795
|
+
od = OptionParser.new(opt).parse(%w(--file))
|
|
796
|
+
od["--file"] #=> []
|
|
797
|
+
od = OptionParser.new(opt).parse(%w(--file=file))
|
|
798
|
+
od["--file"] #=> ["file"]
|
|
799
|
+
od = OptionParser.new(opt).parse(%w(--file=file1 --file file2))
|
|
800
|
+
od["--file"] #=> ["file2"]
|
|
801
|
+
od = OptionParser.new(opt).parse(%w(--file=file1 file2))
|
|
802
|
+
od["--file"] #=> ["file1", "file2"]
|
|
803
|
+
od = OptionParser.new(opt).parse(%w(--file file1 file2))
|
|
804
|
+
od["--file"] #=> ["file1", "file2"]
|
|
805
|
+
</pre>
|
|
806
|
+
<p>
|
|
807
|
+
The next is GET_ARGS. This is a ‘smart’ option getter. If no
|
|
808
|
+
arguments are found, it returns true. If a single argument is found, it
|
|
809
|
+
returns that argument. If more than one argument is found, it returns an
|
|
810
|
+
array of those arguments.
|
|
811
|
+
</p>
|
|
812
|
+
<pre>
|
|
813
|
+
opt = Option.new(:names => %w(--file),
|
|
814
|
+
:argument_arity => [0-1],
|
|
815
|
+
:opt_found => OptionParser::GET_ARGS)
|
|
816
|
+
od = OptionParser.new(opt).parse(%w(--file))
|
|
817
|
+
od["--file"] #=> true
|
|
818
|
+
od = OptionParser.new(opt).parse(%w(--file=file))
|
|
819
|
+
od["--file"] #=> "file"
|
|
820
|
+
od = OptionParser.new(opt).parse(%w(--file=file1 --file file2))
|
|
821
|
+
od["--file"] #=> "file2"
|
|
822
|
+
od = OptionParser.new(opt).parse(%w(--file=file1 file2))
|
|
823
|
+
od["--file"] #=> ["file1", "file2"]
|
|
824
|
+
od = OptionParser.new(opt).parse(%w(--file file1 file2))
|
|
825
|
+
od["--file"] #=> ["file1", "file2"]
|
|
826
|
+
</pre>
|
|
827
|
+
<p>
|
|
828
|
+
And, for those oxymoronic non-optional options:
|
|
829
|
+
</p>
|
|
830
|
+
<pre>
|
|
831
|
+
opt = Option.new(:names => %w(--not-really-an-option),
|
|
832
|
+
:opt_not_found => OptionParser::OPT_NOT_FOUND_BUT_REQUIRED
|
|
833
|
+
)
|
|
834
|
+
OptionParser.new(opt).parse([]) #=> OptionParser::MissingRequiredOptionError
|
|
835
|
+
</pre>
|
|
836
|
+
<h3>OptionData</h3>
|
|
837
|
+
<p>
|
|
838
|
+
We have just shown that after parsing a command line, the result of each
|
|
839
|
+
option is found from OptionData. The vaues that are left are assigned to
|
|
840
|
+
<tt>args</tt>. And, the first argument can be a command if so desired.
|
|
841
|
+
</p>
|
|
842
|
+
|
|
843
|
+
</td></tr>
|
|
844
|
+
</table>
|
|
845
|
+
</body>
|
|
846
|
+
</html>
|