1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
== Tutorial
=== Why OptionParser?
When a Ruby program executes, it captures its command-line arguments
and options into variable ARGV.
This simple program just prints its \ARGV:
:include: ruby/argv.rb
Execution, with arguments and options:
$ ruby argv.rb foo --bar --baz bat bam
["foo", "--bar", "--baz", "bat", "bam"]
The executing program is responsible for parsing and handling
the command-line options.
OptionParser offers methods for parsing and handling those options.
With \OptionParser, you can define options so that for each option:
- The code that defines the option and code that handles that option
are in the same place.
- The option may take no argument, a required argument, or an optional argument.
- The argument may be automatically converted to a specified class.
- The argument may be restricted to specified _forms_.
- The argument may be restricted to specified _values_.
The class also has:
- Method #summarize: returns a text summary of the options.
- Method #help: displays automatically-generated help text.
=== Defining Options
A common way to define an option in \OptionParser
is with instance method OptionParser#on.
The method may be called with any number of arguments
(whose order does not matter),
and may also have a trailing optional keyword argument +into+.
The given arguments determine the characteristics of the new option.
These may include:
- One or more short option names.
- One or more long option names.
- Whether the option takes no argument, an optional argument, or a required argument.
- Acceptable _forms_ for the argument.
- Acceptable _values_ for the argument.
- A proc or method to be called when the parser encounters the option.
- String descriptions for the option.
=== Option Names
You can give an option one or more names of two types:
- Short (1-character) name, beginning with one hyphen (<tt>-</tt>).
- Long (multi-character) name, beginning with two hyphens (<tt>--</tt>).
==== Short Option Names
A short option name consists of a hyphen and a single character.
File +short_names.rb+
defines an option with a short name, <tt>-x</tt>,
and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</tt>.
:include: ruby/short_names.rb
Executions:
$ ruby short_names.rb -x
["x", true]
$ ruby short_names.rb -1
["-1 or -%", true]
$ ruby short_names.rb -%
["-1 or -%", true]
Multiple short names can "share" a hyphen:
$ ruby short_names.rb -x1%
["x", true]
["-1 or -%", true]
["-1 or -%", true]
This is a good time to note that giving an undefined option raises an exception:
$ ruby short_names.rb -z
short_names.rb:9:in `<main>': invalid option: -z (OptionParser::InvalidOption)
==== Long Option Names
A long option name consists of two hyphens and a one or more characters
(usually two or more characters).
File +long_names.rb+
defines an option with a long name, <tt>--xxx</tt>,
and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--z2#</tt>.
:include: ruby/long_names.rb
Executions:
$ ruby long_names.rb --xxx
["-xxx", true]
$ ruby long_names.rb --y1%
["--y1% or --z2#", true]
$ ruby long_names.rb --z2#
["--y1% or --z2#", true]
==== Mixing Option Names
Many developers like to mix short and long option names,
so that a short name is in effect an abbreviation of a long name.
File +mixed_names.rb+
defines options that each have both a short and a long name.
:include: ruby/mixed_names.rb
Executions:
$ ruby mixed_names.rb -x
["--xxx", true]
$ ruby mixed_names.rb --xxx
["--xxx", true]
$ ruby mixed_names.rb -y
["--y1%", true]
$ ruby mixed_names.rb --y1%
["--y1%", true]
=== Option Arguments
An option may take no argument, a required argument, or an optional argument.
==== Option with No Argument
All the examples above define options with no argument.
==== Option with Required Argument
Specify a required argument for an option by adding a dummy word
to its name definition.
File +required_argument.rb+ defines two options;
each has a required argument because the name definition has a following dummy word.
:include: ruby/required_argument.rb
When an option is found, the given argument is yielded.
Executions:
$ ruby required_argument.rb -x AAA
["--xxx", "AAA"]
$ ruby required_argument.rb -y BBB
["--yyy", "BBB"]
Omitting a required argument raises an error:
$ ruby required_argument.rb -x
required_argument.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
==== Option with Optional Argument
Specify an optional argument for an option by adding a dummy word
enclosed in square brackets to its name definition.
File +optional_argument.rb+ defines two options;
each has an optional argument because the name definition has a following dummy word
in square brackets.
:include: ruby/optional_argument.rb
When an option with an argument is found, the given argument yielded.
Executions:
$ ruby optional_argument.rb -x AAA
["--xxx", "AAA"]
$ ruby optional_argument.rb -y BBB
["--yyy", "BBB"]
Omitting an optional argument does not raise an error.
|
