Skip to content

Commit fe72cff

Browse files
BurdetteLamarnobu
BurdetteLamar
authored and
nobu
committed
[ruby/optparse] More on tutorial (#9)
* More on tutorial: clearer example output ruby/optparse@84dfd92d2a
1 parent 2b66b22 commit fe72cff

10 files changed

+133
-54
lines changed

‎doc/ruby/long_names.rb

-9
This file was deleted.

‎doc/ruby/mixed_names.rb

-9
This file was deleted.

‎doc/ruby/short_names.rb

-9
This file was deleted.

‎doc/ruby/argv.rb renamed to ‎doc/tutorial/argv.rb

File renamed without changes.

‎doc/tutorial/long_names.rb

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('--xxx') do |value|
4+
p ['-xxx', value]
5+
end
6+
parser.on('--y1%', '--z2#') do |value|
7+
p ['--y1% or --z2#', value]
8+
end
9+
parser.parse!

‎doc/tutorial/mixed_names.rb

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-x', '--xxx') do |value|
4+
p ['--xxx', value]
5+
end
6+
parser.on('-y', '--y1%') do |value|
7+
p ['--y1%', value]
8+
end
9+
parser.parse!

‎doc/tutorial/optional_argument.rb

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-x [XXX]', '--xxx') do |value|
4+
p ['--xxx', value]
5+
end
6+
parser.on('-y', '--yyy [YYY]') do |value|
7+
p ['--yyy', value]
8+
end
9+
parser.parse!

‎doc/tutorial/required_argument.rb

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-x XXX', '--xxx') do |value|
4+
p ['--xxx', value]
5+
end
6+
parser.on('-y', '--y YYY') do |value|
7+
p ['--yyy', value]
8+
end
9+
parser.parse!

‎doc/tutorial/short_names.rb

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-x') do |value|
4+
p ['x', value]
5+
end
6+
parser.on('-1', '-%') do |value|
7+
p ['-1 or -%', value]
8+
end
9+
parser.parse!

‎doc/tutorial.rdoc renamed to ‎doc/tutorial/tutorial.rdoc

+88-27
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ When a Ruby program executes, it captures its command-line arguments
66
and options into variable ARGV.
77
This simple program just prints its \ARGV:
88

9-
:include: ruby/argv.rb
9+
:include: argv.rb
1010

1111
Execution, with arguments and options:
1212

13-
$ ruby doc/ruby/argv.rb foo --bar --baz bat bam
13+
$ ruby argv.rb foo --bar --baz bat bam
1414
["foo", "--bar", "--baz", "bat", "bam"]
1515

1616
The executing program is responsible for parsing and handling
@@ -27,8 +27,10 @@ With \OptionParser, you can define options so that for each option:
2727
- The argument may be restricted to specified _forms_.
2828
- The argument may be restricted to specified _values_.
2929

30-
The class also has a method #summarize that returns a string summary
31-
of all defined options.
30+
The class also has:
31+
32+
- Method #summarize: returns a text summary of the options.
33+
- Method #help: displays automatically-generated help text.
3234

3335
=== Defining Options
3436

@@ -65,23 +67,28 @@ File +short_names.rb+
6567
defines an option with a short name, <tt>-x</tt>,
6668
and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</tt>.
6769

68-
:include: ruby/short_names.rb
70+
:include: short_names.rb
6971

7072
Executions:
7173

72-
$ ruby doc/ruby/short_names.rb -x
73-
"-x true"
74-
$ ruby doc/ruby/short_names.rb -1
75-
"-1 or -% true"
76-
$ ruby doc/ruby/short_names.rb -%
77-
"-1 or -% true"
74+
$ ruby short_names.rb -x
75+
["x", true]
76+
$ ruby short_names.rb -1
77+
["-1 or -%", true]
78+
$ ruby short_names.rb -%
79+
["-1 or -%", true]
7880

7981
Multiple short names can "share" a hyphen:
8082

8183
$ ruby short_names.rb -x1%
82-
"-x true"
83-
"-1 or -% true"
84-
"-1 or -% true"
84+
["x", true]
85+
["-1 or -%", true]
86+
["-1 or -%", true]
87+
88+
This is a good time to note that giving an undefined option raises an exception:
89+
90+
$ ruby short_names.rb -z
91+
short_names.rb:9:in `<main>': invalid option: -z (OptionParser::InvalidOption)
8592

8693
==== Long Option Names
8794

@@ -92,16 +99,16 @@ File +long_names.rb+
9299
defines an option with a long name, <tt>--xxx</tt>,
93100
and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--z2#</tt>.
94101

95-
:include: ruby/long_names.rb
102+
:include: long_names.rb
96103

97104
Executions:
98105

99106
$ ruby long_names.rb --xxx
100-
"--xxx true"
107+
["-xxx", true]
101108
$ ruby long_names.rb --y1%
102-
"--y1% or -z2# true"
109+
["--y1% or --z2#", true]
103110
$ ruby long_names.rb --z2#
104-
"--y1% or -z2# true"
111+
["--y1% or --z2#", true]
105112

106113
==== Mixing Option Names
107114

@@ -111,15 +118,69 @@ so that a short name is in effect an abbreviation of a long name.
111118
File +mixed_names.rb+
112119
defines options that each have both a short and a long name.
113120

114-
:include: ruby/mixed_names.rb
121+
:include: mixed_names.rb
122+
123+
Executions:
124+
125+
$ ruby mixed_names.rb -x
126+
["--xxx", true]
127+
$ ruby mixed_names.rb --xxx
128+
["--xxx", true]
129+
$ ruby mixed_names.rb -y
130+
["--y1%", true]
131+
$ ruby mixed_names.rb --y1%
132+
["--y1%", true]
133+
134+
=== Option Arguments
135+
136+
An option may take no argument, a required argument, or an optional argument.
137+
138+
==== Option with No Argument
139+
140+
All the examples above define options with no argument.
141+
142+
==== Option with Required Argument
143+
144+
Specify a required argument for an option by adding a dummy word
145+
to its name definition.
146+
147+
File +required_argument.rb+ defines two options;
148+
each has a required argument because the name definition has a following dummy word.
149+
150+
:include: required_argument.rb
151+
152+
When an option is found, the given argument is yielded.
115153

116154
Executions:
117155

118-
$ ruby doc/ruby/mixed_names.rb -x
119-
"--xxx true"
120-
$ ruby doc/ruby/mixed_names.rb --xxx
121-
"--xxx true"
122-
$ ruby doc/ruby/mixed_names.rb -y
123-
"--y1% true"
124-
$ ruby doc/ruby/mixed_names.rb --y1%
125-
"--y1% true"
156+
$ ruby required_argument.rb -x AAA
157+
["--xxx", "AAA"]
158+
$ ruby required_argument.rb -y BBB
159+
["--yyy", "BBB"]
160+
161+
Omitting a required argument raises an error:
162+
163+
$ ruby required_argument.rb -x
164+
required_argument.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
165+
166+
==== Option with Optional Argument
167+
168+
Specify an optional argument for an option by adding a dummy word
169+
enclosed in square brackets to its name definition.
170+
171+
File +optional_argument.rb+ defines two options;
172+
each has an optional argument because the name definition has a following dummy word
173+
in square brackets.
174+
175+
:include: optional_argument.rb
176+
177+
When an option with an argument is found, the given argument yielded.
178+
179+
Executions:
180+
181+
$ ruby optional_argument.rb -x AAA
182+
["--xxx", "AAA"]
183+
$ ruby optional_argument.rb -y BBB
184+
["--yyy", "BBB"]
185+
186+
Omitting an optional argument does not raise an error.

0 commit comments

Comments
 (0)